xuxi/lib/object.d.ts

Dynamically utility for combining different types of values ​​into a single value.

/** A type alias representing an object with string keys and values of any type. */
export type ObjectKey = {
    [key: string]: any;
};
/** A generic type that extends `T` with `ObjectKey`, allowing `T` to have arbitrary key-value pairs. */
export type ObjectAcc<T> = T & ObjectKey;
/**
 * A flexible mapping type that can be an:
 * - plain object (`ObjectKey`)
 * - array of objects (`ObjectKey[]`)
 * - recursive mapping (`ObjectMap[]`)
 * - primitive value (`string`, `number`, `null`, `boolean`, `undefined`)
 * - function that takes an optional object (`ObjectKey`) and returns an `ObjectMap`. */
export type ObjectMap = ObjectKey | ObjectKey[] | ObjectMap[] | string | number | null | boolean | undefined | ((key?: ObjectKey) => ObjectMap);
/** An object that can be processed by `object`. */
export type ObjectObj<T> = T | ObjectMap | ObjectAcc<T>;
/**
 * Checks if a given value is a plain object (i.e., not an array or null).
 * @param value - The value to check.
 * @returns True if the value is a plain object, otherwise false.
 */
export declare function isPlainObject(value: unknown): value is ObjectKey;
/**
 * Merges multiple objects deeply, handling arrays and functions gracefully.
 * @template T - The base object type.
 * @param obj - One or more objects to merge.
 * @returns The deeply merged object.
 */
declare function baseObject<T extends ObjectKey>(...obj: ObjectObj<T>[]): ObjectAcc<T>;
/**
 * Merges multiple objects deeply, handling arrays and functions gracefully **without overwriting**.
 * @template T - The base object type.
 * @param obj - One or more objects to merge.
 * @returns The deeply merged object **without overwriting** the value at the first key, only change the value if it does not exist.
 */
declare function preserveRoot<T extends ObjectKey>(...obj: ObjectObj<T>[]): ObjectAcc<T>;
/**
 * Recursively removes falsy values from an object, except those specified in `exclude`.
 * @template T - The object type.
 * @param obj - The object to clean.
 * @param exclude - An array of values to be preserved even if they are falsy (default: `[]`).
 * @param seen - To detect cyclic references (default: `new WeakSet<object>()`).
 * @returns A new object without the falsy values.
 * @example
 * @see {@link https://ilkhoeri.github.io/xuxi/clean Docs}
 */
export declare function clean<T extends ObjectKey>(obj: T, exclude?: unknown[], seen?: WeakSet<object>): T;
interface ObjectFunction {
    /**
     * Merges multiple objects and removes falsy values by default.
     * @template T - The base object type.
     * @param obj - One or more objects to merge.
     * @returns The deeply merged object with falsy values removed.
     */
    <T extends ObjectKey>(...obj: ObjectObj<T>[]): ObjectAcc<T>;
    /** A version of `object` that performs deep merging **without** removing falsy values. */
    raw: typeof baseObject;
    /** A version of `object` that performs a deep join **without overwriting** the value at the first key, only change the value if it does not exist. */
    preserve: typeof preserveRoot;
}
/**
 * Recursively merge objects with support for arrays, dynamic functions, and non falsy properties into a single object.
 *
 * Provides a chaining:
 * - {@link baseObject raw} method to **get falsy values** from the result.
 * - {@link preserveRoot preserve} method to join **without overwriting** first value.
 * @example
 * @see {@link https://ilkhoeri.github.io/xuxi/?id=object Docs}
 */
export declare const object: ObjectFunction;
export {};