obby/dist/index.d.cts

Manipulate, clone, merge, and compare Javascript objects with ease.

import * as wwp from 'wild-wild-path';
export * from 'emptier';
export { emptyDeep } from 'empty-deep';
export { deepmerge as merge } from 'deepmerge-ts';
import * as wwpr from 'wild-wild-parser';

/**
 * Deep clone an Object, Array or Primitive value.
 *
 * @remarks
 *
 * All JSON types (Object, Array, Number, String, and null) are supported, as
 * well as a few other more complex structures (Date, Buffer, TypedArray, Map,
 * Set, and undefined).
 *
 * @see {@link https://github.com/planttheidea/fast-copy}
 */
declare const clone: <Value>(value: Value) => Value;

/**
 * Copy a property from a source object to a target object.
 *
 * @remarks
 * Note that this function mutates the target object rather than returning a copy of it.
 *
 * @param source - The object whose property should be copied
 * @param sourcePath - The dot-notation path of the property to copy
 * @param target - The object the property should be copied to
 * @param [targetPath] - An alternative target path, if it differs from the source path.
 */
declare function copy(source: object, sourcePath: string, target: object, targetPath?: string): void;

declare const defaultPathOptions: wwp.Options;
/** {@inheritDoc wild-wild-paths#has} */
declare function has(target: wwp.Target, query: wwp.Query, options?: wwp.Options): boolean;
/** {@inheritDoc wild-wild-paths#get} */
declare function get(target: wwp.Target, query: wwp.Query, options?: wwp.Options): unknown;
/** {@inheritDoc wild-wild-paths#list} */
declare function getAll(target: wwp.Target, query: wwp.Query, options?: wwp.Options): unknown[];
/** {@inheritDoc wild-wild-paths#set} */
declare function set(target: wwp.Target, query: wwp.Query, value: unknown, options?: wwp.Options): wwp.Target;
/** {@inheritDoc wild-wild-paths#remove} */
declare function unset(target: wwp.Target, query: wwp.Query, options?: wwp.Options): wwp.Target;

declare const equals: <A, B>(a: A, b: B) => boolean;

/**
 * Returns a copy of the input object with all nested properties flattened
 * to dot notation.
 *
 * @example
 * ```js
 * const obj = {
 *   bool: true,
 *   prop: { number: 1, string: 'text' }
 * }
 * flatten(obj); // { bool: true, 'prop.number': 1, 'prop.string': 'text' }
 * ```
 *
 * @argument target - Any array or object
 * @argument query - An optional path query with wildcards; only matching properties will be included in the flattened output.
 */
declare function flatten(target: wwp.Target, query?: string, options?: wwp.Options): object;
/**
 * Returns a copy of the input object with all dot-notation property keys
 * expanded to their full path.
 *
 * @example
 * ```js
 * const obj = {
 *   bool: true,
 *   'prop.number': 1,
 *   'prop.string': 'text'
 * }
 * unflatten(obj); // { bool: true, prop: { number: 1, string: 'text' } }
 * ```
 */
declare function unflatten(target: wwp.Target, options?: wwp.Options): {};

/**
 * Copy a property from one object to another, and remove it from the original object.
 *
 * @remarks
 * Note that this function mutates the target object rather than returning a copy of it.
 *
 * @param source - The object whose property should be copied
 * @param sourcePath - The dot-notation path of the property to copy
 * @param target - The object the property should be copied to
 * @param [targetPath] - An alternative target path, if it differs from the source path.
 */
declare const move: (source: object, sourcePath: string, target: object, targetPath?: string) => void;

/**
 * Returns `true` if the input is a valid dot-notation query. Queries may
 * include wildcard characters and array index notation, like `2:5`.
 *
 * @example
 * ```js
 * isQuery('users.0.*')       // true
 * parseQuery('users admins') // true
 * parseQuery('users./[/')    // false: invalid RegExp
 * ```
 *
 * @remarks
 * When used with the `get()` function, wildcard queries will still only
 * return a single result.
 */
declare function isQuery(input: unknown): input is wwpr.QueryString;
/**
 * Returns `true` if the input is a valid dot-notation property path
 * with no wildcard characters or special array index notation.
 *
 * @example
 * ```js
 * parsePath('users.0')   // true
 * parsePath('*')         // false: this is a valid query but not a path
 * ```
 *
 */
declare function isPath(input: unknown): input is wwpr.PathString;

export { clone, copy, defaultPathOptions, equals, flatten, get, getAll, has, isPath, isQuery, move, set, unflatten, unset };