funtool/dist/object/index.d.ts

A modern, efficient, and modular JavaScript utility library designed to enhance developer productivity.

/**
 * Check if an object has a specific property
 * @param obj - The object to check
 * @param key - The key to check
 * @returns True if the object has the property, false otherwise
 * @example
 * const obj = { a: 1, b: 2 };
 * hasOwn(obj, 'a'); // ✅ true
 * hasOwn(obj, 'c'); // ❌ false
 */
declare function hasOwn<T extends object>(obj: T, key: keyof T | (string & {}) | symbol | number): boolean;

/**
 * Retrieves the own property keys of an object, filtered by an optional predicate.
 *
 * This function supports both string and symbol keys, and by default only includes
 * enumerable properties. You can provide a custom predicate to filter keys based on
 * their name and property descriptor.
 *
 * If the input is a primitive value (non-object), it returns an empty array.
 *
 * @template T - The type of the input object.
 * @param {T} obj - The object whose keys are to be retrieved.
 * @param {(key?: string | symbol, descriptor?: PropertyDescriptor) => boolean} [predicate] -
 *        An optional function to filter keys. It receives each key and its descriptor.
 *        If not provided, only enumerable keys are returned.
 * @returns {(keyof T)[]} An array of the object's own keys filtered by the predicate.
 *
 * @example
 * const obj = {
 *   a: 1,
 *   b: 2,
 *   get c() { return 3; }
 * };
 * Object.defineProperty(obj, 'd', {
 *   value: 4,
 *   enumerable: false
 * });
 * const sym = Symbol('e');
 * obj[sym] = 5;
 *
 * // Get only enumerable keys (default)
 * keys(obj); // ['a', 'b', 'c', Symbol(e)]
 *
 * // Get all keys, including non-enumerable
 * keys(obj, () => true); // ['a', 'b', 'c', 'd', Symbol(e)]
 *
 * // Get only non-enumerable keys
 * keys(obj, (key, desc) => !desc.enumerable); // ['d']
 *
 * // Get only symbol keys
 * keys(obj, (key) => typeof key === 'symbol'); // [Symbol(e)]
 */
declare function keys<T extends object>(obj: T, predicate?: (key?: string | symbol, descriptor?: PropertyDescriptor) => boolean): (keyof T)[];

/**
 * Merges two objects into one. Properties from the second object
 * will overwrite those from the first object in case of conflicts.
 * Symbol keys are also supported.
 *
 * @template T - The type of the first object
 * @template U - The type of the second object
 * @param target - The target object to receive properties
 * @param source - The source object to copy properties from
 * @returns A new object with merged properties
 *
 * @example
 * ```ts
 * const sym = Symbol('id');
 * const a = { name: 'Alice', age: 25 };
 * const b = { age: 30, [sym]: 123 };
 * const result = merge(a, b);
 * // result: { name: 'Alice', age: 30, [sym]: 123 }
 * ```
 */
declare function merge<T extends object, U extends object>(target: T, source: U): T & U;
/**
 * Recursively deep merges two objects. Properties from the source object
 * will overwrite those in the target. Arrays are overwritten by default.
 * Symbol keys are also supported.
 *
 * @template T - The type of the first object
 * @template U - The type of the second object
 * @param target - The target object to receive properties
 * @param source - The source object to merge from
 * @returns A new object deeply merged from target and source
 *
 * @example
 * ```ts
 * const a = { user: { name: 'Alice', hobbies: [{ sport: 'tennis' }] } };
 * const b = { user: { age: 30, hobbies: [{ level: 'pro' }] } };
 * const result = mergeDeep(a, b);
 * // result: { user: { name: 'Alice', age: 30, hobbies: [{ sport: 'tennis', level: 'pro' }] } }
 * ```
 */
declare function mergeDeep<T extends object, U extends object>(target: T, source: U): T & U;

type ExistingKeys$1<T> = keyof T & string;
/**
 * @description Creates a new object by omitting the specified keys from the original object.
 * @param obj The source object
 * @param keysToOmit An array of keys to omit
 * @returns A new object without the specified keys
 *
 * @example
 * const user = { name: 'Alice', age: 25, password: 'secret' };
 * const safeUser = omit(user, ['password']);
 * console.log(safeUser); // ✅ { name: 'Alice', age: 25 }
 */
declare function omit<T extends object, K extends string>(obj: T, keysToOmit: K[]): Omit<T, Extract<K, ExistingKeys$1<T>>>;
/**
 * @description Creates a new object by omitting properties that match the predicate function.
 * @param obj The source object
 * @param predicate A function that returns `true` if the property should be omitted
 * @returns A new object without the properties that match the predicate
 *
 * @example
 * const user = { name: 'Alice', age: null, isActive: true };
 * const cleaned = omitBy(user, (value) => value === null);
 * console.log(cleaned); // ✅ { name: 'Alice', isActive: true }
 */
declare function omitBy<T extends object>(obj: T, predicate: (value: T[keyof T], key: keyof T) => boolean): Partial<T>;

type ExistingKeys<T> = keyof T & string;
/**
 * @description Creates a new object composed of the picked properties.
 * @param obj The source object
 * @param keysToPick An array of keys to pick from the source object
 * @returns A new object containing only the picked keys
 *
 * @example
 * const user = { name: 'Alice', age: 25, password: 'secret' };
 * const partialUser = pick(user, ['name', 'age']);
 * console.log(partialUser); // ✅ { name: 'Alice', age: 25 }
 */
declare function pick<T extends object, K extends string>(obj: T, keysToPick: readonly K[]): Pick<T, Extract<K, ExistingKeys<T>>>;
/**
 * @description Creates a new object composed of properties that satisfy the predicate function.
 * @param obj The source object
 * @param predicate A function invoked with (value, key) that returns `true` to keep the property
 * @returns A new object with properties that satisfy the predicate
 *
 * @example
 * const user = { name: 'Alice', age: 25, isActive: false };
 * const activeProps = pickBy(user, (value) => Boolean(value));
 * console.log(activeProps); // ✅ { name: 'Alice', age: 25 }
 */
declare function pickBy<T extends object>(obj: T, predicate: (value: T[keyof T], key: keyof T) => boolean): Partial<T>;

/**
 * Retrieves the values of an object's own properties, filtered by an optional predicate.
 *
 * Supports both string and symbol keys. By default, only enumerable properties are included.
 * A custom predicate can be provided to control which values are returned based on the key
 * and property descriptor.
 *
 * If the input is a primitive (non-object), an empty array is returned.
 *
 * @template T - The type of the input object.
 * @param {T} obj - The object whose values are to be retrieved.
 * @param {(key?: string | symbol, descriptor?: PropertyDescriptor) => boolean} [predicate] -
 *        Optional predicate function to filter properties. Receives the key and descriptor.
 *        If omitted, only enumerable values are returned.
 * @returns {T[keyof T][]} An array of the object's own property values, filtered by the predicate.
 *
 * @example
 * const obj = {
 *   a: 1,
 *   b: 2,
 *   get c() { return 3; }
 * };
 * Object.defineProperty(obj, 'd', {
 *   value: 4,
 *   enumerable: false
 * });
 * const sym = Symbol('e');
 * obj[sym] = 5;
 *
 * // Get only enumerable values (default)
 * values(obj); // [1, 2, 3, 5]
 *
 * // Get all values, including non-enumerable
 * values(obj, () => true); // [1, 2, 3, 4, 5]
 *
 * // Get only non-enumerable values
 * values(obj, (key, desc) => !desc.enumerable); // [4]
 *
 * // Get only symbol values
 * values(obj, (key) => typeof key === 'symbol'); // [5]
 */
declare function values<T extends object>(obj: T, predicate?: (key?: string | symbol, descriptor?: PropertyDescriptor) => boolean): T[keyof T][];

export { hasOwn, keys, merge, mergeDeep, omit, omitBy, pick, pickBy, values };