cmpstr/dist/types/utils/DeepMerge.d.ts

CmpStr is a lightweight, fast and well performing package for calculating string similarity

/**
 * Deep Merge Utility
 * src/utils/DeepMerge.ts
 *
 * This module provides utility functions for deep merging objects, getting values by path,
 * and setting values by path in a deeply nested object structure.
 *
 * It supports dot and bracket notation (e.g. `a.b[0].c`) as well as escaped keys.
 *
 * Included functions:
 *  - `get`:   Retrieve a deeply nested value by path
 *  - `set`:   Assign a value to a nested path
 *  - `merge`: Deeply merge two objects
 *  - `has`:   Check whether a path exists
 *  - `rmv`:   Delete a value at a path
 *
 * @module Utils/DeepMerge
 * @author Paul Köhler
 * @license MIT
 */
/**
 * Deeply get a value from an object by a path string.
 *
 * @template T - The type of the object to get the value from
 * @param {T} t - The object to get the value from
 * @param {string} path - The path string, e.g. `a.b.c`
 * @param {any} fallback - The default value to return if the path does not exist
 * @returns {T|R|undefined} - The value at the specified path, otherwise the default value
 */
export declare function get<T extends Record<string, any>, R = any>(t: T, path: string, fallback?: any): T | R | undefined;
/**
 * Check if a path exists in an object.
 *
 * @template T - The type of the object to get the value from
 * @param {T} t - The object to check
 * @param {string} path - The path string, e.g. `a.b.c`
 * @returns {boolean} - True if the path exists, otherwise false
 */
export declare function has<T extends Record<string, any>>(t: T, path: string): boolean;
/**
 * Deeply set a value in an object by a path string.
 *
 * @template T - The type of the object to get the value from
 * @param {T} t - The object to set the value in
 * @param {string} path - The path string, e.g. `a.b.c`
 * @param {any} value - The value to set at the specified path
 * @returns {T} - The modified object with the value set at the specified path
 * @throws {Error} - Throws an error if the key is not a valid identifier
 */
export declare function set<T extends Record<string, any>>(t: T, path: string, value: any): T;
/**
 * Deeply merge two objects, where the second object overrides the first.
 *
 * @template T - The type of the object to get the value from
 * @param {T} t - The target object to merge into
 * @param {T} o - The source object to merge from
 * @param {boolean} [mergeUndefined=false] - Whether to merge undefined values
 * @returns {T} - The merged object
 */
export declare function merge<T extends Record<string, any>>(t?: T | undefined, o?: T | undefined, mergeUndefined?: boolean): T;
/**
 * Delete a value at a specified path in an object.
 *
 * @template T - The type of the object to get the value from
 * @param {T} t - The object to delete the value from
 * @param {string} path - The path string, e.g. `a.b.c`
 * @param {boolean} [preserveEmpty=false] - Whether to preserve empty objects/arrays
 * @returns {T} - The modified object with the value deleted at the specified path
 */
export declare function rmv<T extends Record<string, any>>(t: T, path: string, preserveEmpty?: boolean): T;