import { SetRequired, EmptyObject, Merge } from 'type-fest';

/**
 * This type is used to allow any type and bypass restrictions used in
 * typechecking and linting. Provides a CLEAR warning this is NOT the desired
 * behavior and is a dangerous practice.
 */
type DangerouslyAllowAny = any;
/**
 * A plain object is an object that has no special properties or methods,
 * and just has properties that are strings, numbers, or symbols.
 */
type PlainObject = Record<string | number | symbol, unknown>;
/**
 * A nil value is a value that is not defined or is undefined.
 */
type Nil = null | undefined;
/**
 * A type that represents any async function.
 */
type AnyAsyncFunction = (...args: unknown[]) => Promise<unknown>;
/**
 * A type that represents any synchronous function.
 */
type AnySyncFunction = (...args: unknown[]) => unknown;
/**
 * A type that represents any function.
 */
type AnyFunction = AnyAsyncFunction | AnySyncFunction;

/**
 * Deep clone an object
 *
 * @param obj - The object to clone
 * @returns A deep copy of the object (fallback to shallow clone for failures)
 */
declare function deepClone<T>(obj: T): T;
/**
 * Check if an object has a key
 *
 * @param obj - The object to check
 * @param key - The key to check
 * @returns True if the object has the key, false otherwise
 */
declare function hasKey<T extends PlainObject, K extends string>(obj: T, key: K): obj is T & SetRequired<T, K>;

/**
 * Check if a value is nil
 *
 * @param obj - The value to check
 * @returns True if the value is nil, false otherwise
 */
declare function isNil(obj: unknown): obj is Nil;
/**
 * Check if an object is a JS object
 *
 * @param obj - The object to check
 * @returns True if the object is a JS object}
 */
declare function isObject<T extends object>(obj: unknown): obj is T;
/**
 * Check if a value is a function
 *
 * @param obj - The value to check
 * @returns True if the value is a function, false otherwise
 */
declare function isFunction<T extends AnyFunction>(obj: unknown): obj is T;
/**
 * Check if an object is a plain object (i.e. a JS object but not including arrays or functions)
 *
 * @param obj - The object to check
 * @returns True if the object is a plain object, false otherwise.
 */
declare function isPlainObject<T extends PlainObject>(obj: unknown): obj is T;
/**
 * Check if an object is an empty object
 *
 * @param obj - The object to check
 * @returns True if the object is an empty object, false otherwise
 */
declare function isEmptyObject(obj: unknown): obj is EmptyObject;

/**
 * An async iterable stream that can be read from.
 * @example
 * ```typescript
 * const stream: AsyncIterableStream<string> = getStream();
 * for await (const chunk of stream) {
 *   console.log(chunk);
 * }
 * ```
 */
type AsyncIterableStream<T> = Merge<AsyncIterable<T>, ReadableStream<T>>;
/**
 * Create an async iterable stream from a readable stream.
 *
 * This is useful for creating an async iterable stream from a readable stream.
 *
 * @example
 * ```typescript
 * const stream: AsyncIterableStream<string> = createAsyncIterableStream(new ReadableStream({
 *   start(controller) {
 *     controller.enqueue("Hello");
 *     controller.close();
 *   },
 * }));
 * ```
 * @param source The readable stream to create an async iterable stream from.
 * @returns The async iterable stream.
 */
declare function createAsyncIterableStream<T>(source: ReadableStream<T>): AsyncIterableStream<T>;

type SafeStringifyOptions = {
    /**
     * The indentation to use for the output.
     */
    indentation?: string | number;
};
/**
 * Stringifies an object, handling circular references and ensuring the output is safe to use in a JSON string.
 * @param input - The object to stringify.
 * @param options.indentation - The indentation to use for the output.
 * @returns The stringified object.
 */
declare function safeStringify(input: DangerouslyAllowAny, { indentation }?: SafeStringifyOptions): string;

export { type AsyncIterableStream, type SafeStringifyOptions, createAsyncIterableStream, deepClone, hasKey, isEmptyObject, isFunction, isNil, isObject, isPlainObject, safeStringify };