@homer0/object-utils 4.0.0 → 5.0.0

package/dist/index.d.mts

@@ -1,406 +0,0 @@
-/**
- * Creates a deep copy of a given object.
- *
- * @param target  The object to copy.
- * @template T  The type of the input object, which will be the same as the one
- *              returned.
- */
-declare const copy: <T>(target: T) => T;
-
-/**
- * The callback that will be used to replace a key.
- *
- * @param substring  The captured string to replace.
- * @param args       The list of groups captured by the expression.
- */
-type FormatKeysReplaceFn = (substring: string, ...args: string[]) => string;
-type FormatKeysOptions = {
-    /**
-     * The object to transform.
-     */
-    target: unknown;
-    /**
-     * A regular expression to match the keys to transform.
-     */
-    search: RegExp;
-    /**
-     * The callback that will be used to replace the matched substring. Think of `search` and
-     * `replace` as the parameters of `String.replace`.
-     */
-    replace: FormatKeysReplaceFn;
-    /**
-     * A list of keys or paths where the transformation will be made. If not specified, the
-     * function will use all the keys from the object.
-     */
-    include?: string[];
-    /**
-     * A list of keys or paths where the transformation won't be made.
-     */
-    exclude?: string[];
-    /**
-     * The delimiter that will separate the path components for both `include` and `exclude`.
-     */
-    pathDelimiter?: string;
-};
-type FormatKeysExtensionOptions = Omit<FormatKeysOptions, 'search' | 'replace'>;
-/**
- * Formats all the keys on an object using a way similar to `.replace(regexp, ...)` but
- * that also works recursively and with _"object paths"_.
- *
- * @param options  The set of options to customize the transformation.
- * @template T  The type of the returned object.
- * @example
- *
- *   const target = {
- *     prop_one: 'Charito!',
- *   };
- *   console.log(
- *     formatKeys({
- *       target,
- *       // Find all the keys with snake case.
- *       search: /([a-z])_([a-z])/g,
- *       // Using the same .replace style callback, replace it with lower camel case.
- *       replace: (_, firstLetter, secondLetter) => {
- *         const newSecondLetter = secondLetter.toUpperCase();
- *         return `${firstLetter}${newSecondLetter}`;
- *       },
- *     }),
- *   );
- *   // Will output { propOne: 'Charito!}.
- *
- */
-declare const formatKeys: <T = Record<string, unknown>>(options: FormatKeysOptions) => T;
-
-/**
- * A shorthand method for {@link formatKeys} that transforms the keys from `dash-case`
- * to `lowerCamelCase`.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- */
-declare const dashToLowerCamelKeys: <T>(options: FormatKeysExtensionOptions) => T;
-
-/**
- * A shorthand method for {@link formatKeys} that transforms the keys from `dash-case`
- * to `snake_case`.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- */
-declare const dashToSnakeKeys: <T>(options: FormatKeysExtensionOptions) => T;
-
-/**
- * Used in the {@link extract} function to specify a path for a property, or an "origin path"
- * and an "extraction path".
- */
-type extractionPath = string | Record<string, string>;
-type ExtractOptions = {
-    /**
-     * The object from where the property/properties will be extracted.
-     */
-    target: unknown;
-    /**
-     * This can be a single path or a list of them. And for this method, the paths are not
-     * only strings but can also be an object with a single key, that would be the path to
-     * where to "do the extraction", and the value the path on the target object.
-     */
-    paths: extractionPath | extractionPath[];
-    /**
-     * The delimiter that will separate the path components.
-     */
-    pathDelimiter?: string;
-    /**
-     * Whether or not to throw an error when the path is invalid. If this is `false`, the
-     * method will silently fail an empty object.
-     */
-    failWithError?: boolean;
-};
-/**
- * Extracts a property or properties from an object in order to create a new one.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- * @example
- *
- *   const target = {
- *     name: {
- *       first: 'Pilar',
- *     },
- *     age: 3,
- *     address: {
- *       planet: 'earth',
- *       something: 'else',
- *     },
- *   };
- *   console.log(
- *     extract({
- *       target: obj,
- *       paths: [{ name: 'name.first' }, 'age', 'address.planet'],
- *     }),
- *   );
- *   // Will output { name: 'Pilar', age: 3, address: { planet: 'earth' } }
- *
- */
-declare const extract: <T = Record<string, unknown>>(options: ExtractOptions) => T | undefined;
-
-/**
- * Checks whether a key for an array or an Object should be flattened.
- *
- * @param key    The key to check inside its parent.
- * @param value  The value of the key.
- */
-type ShouldFlattenFn = (key: string, value: unknown) => boolean;
-type FlatOptions = {
-    /**
-     * The object to transform.
-     */
-    target: unknown;
-    /**
-     * A custom prefix to be added before the name of the properties. This can be used on
-     * custom cases and it's also used when the method calls itself in order to flatten a
-     * sub object.
-     */
-    prefix?: string;
-    /**
-     * The delimiter that will separate the path components.
-     */
-    pathDelimiter?: string;
-    /**
-     * A custom function that can be used in order to tell the function whether an Object or
-     * an Array property should be flatten or not.
-     */
-    shouldFlatten?: ShouldFlattenFn;
-};
-/**
- * Flattens an object properties into a single level dictionary.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- * @example
- *
- * const target = {
- * propOne: {
- * propOneSub: 'Charito!',
- * },
- * propTwo: '!!!',
- * };
- * console.log(flat({ target });
- * // Will output { 'propOne.propOneSub': 'Charito!', propTwo: '!!!' }
- *
- */
-declare const flat: <T = Record<string, unknown>>(options: FlatOptions) => T;
-
-type GetOptions = {
-    /**
-     * The object from where the property will be read.
-     */
-    target: unknown;
-    /**
-     * The path to the property.
-     */
-    path: string;
-    /**
-     * The delimiter that will separate the path components.
-     */
-    pathDelimiter?: string;
-    /**
-     * Whether or not to throw an error when the path is invalid. If this is `false`,
-     *  the method will silently fail and return `undefined`.
-     */
-    failWithError?: boolean;
-};
-/**
- * Returns the value of an object property using a path.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- * @throws {Error} If the path is invalid and `failWithError` is set to `true`.
- * @example
- *
- *   const obj = {
- *     propOne: {
- *       propOneSub: 'Charito!',
- *     },
- *     propTwo: '!!!',
- *   };
- *   console.log(get({ target: obj, path: 'propOne.propOneSub' }));
- *   // Will output 'Charito!'
- *
- */
-declare function get<T>(options: GetOptions): T | undefined;
-declare function get<T>(options: unknown, path: string): T | undefined;
-
-/**
- * A shorthand method for {@link formatKeys} that transforms the keys from
- * `lowerCamelCase` to `dash-case`.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- */
-declare const lowerCamelToDashKeys: <T>(options: FormatKeysExtensionOptions) => T;
-
-/**
- * A shorthand method for {@link formatKeys} that transforms the keys from
- * `lowerCamelCase` to `snake_case`.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- */
-declare const lowerCamelToSnakeKeys: <T>(options: FormatKeysExtensionOptions) => T;
-
-/**
- * This method makes a deep merge of a list of objects into a new one. The method also
- * supports arrays: if the first element is an array, it will be merged into an array,
- * otherwise, it will be an object.
- *
- * @param targets  The list of objects to merge.
- * @template T  The type of the merged object that will be returned.
- * @example
- *
- *   const objA = { a: 'first' };
- *   const objB = { b: 'second' };
- *   console.log(merge(objA, objB));
- *   // Will output { a: 'first', b: 'second' }
- *
- * @example
- *
- *   const arrA = [{ a: 'first' }];
- *   const arrB = [{ b: 'second' }];
- *   console.log(merge(objA, objB));
- *   // Will output [{ a: 'first', b: 'second' }]
- *
- */
-declare const merge: <T = unknown>(...targets: unknown[]) => T;
-
-type RemoveOptions = {
-    /**
-     * The object from where the property will be removed.
-     */
-    target: unknown;
-    /**
-     * The path to the property.
-     */
-    path: string;
-    /**
-     * The delimiter that will separate the path components.
-     */
-    pathDelimiter?: string;
-    /**
-     * Whether or not to throw an error when the path is invalid. If this is `false`, the
-     * function will silently fail.
-     */
-    failWithError?: boolean;
-    /**
-     * If this flag is `true` and after removing the property the parent object is empty,
-     * it will remove it recursively until a non empty parent object is found.
-     */
-    cleanEmptyProperties?: boolean;
-};
-/**
- * Deletes a property of an object using a path.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- * @example
- *
- *   const target = {
- *     propOne: {
- *       propOneSub: 'Charito!',
- *     },
- *     propTwo: '!!!',
- *   };
- *   console.log(remove({ target, path: 'propOne.propOneSub' }));
- *   // Will output { propTwo: '!!!' }
- *
- */
-declare function remove<T = unknown>(options: RemoveOptions): T | undefined;
-declare function remove<T = unknown>(options: unknown, path: string): T | undefined;
-
-type SetOptions = {
-    /**
-     * The object where the property will be set.
-     */
-    target: unknown;
-    /**
-     * The path for the property.
-     */
-    path: string;
-    /**
-     * The value to set on the property.
-     */
-    value: unknown;
-    /**
-     * The delimiter that will separate the path components.
-     */
-    pathDelimiter?: string;
-    /**
-     * Whether or not to throw an error when the path is invalid. If this is `false`, the method
-     * will silently fail and return `undefined`.
-     */
-    failWithError?: boolean;
-};
-/**
- * Sets a property on an object using a path. If the path doesn't exist, it will be
- * created.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- * @throws {Error} If one of the path components is for a non-object property and
- *                 `failWithError` is set to `true`.
- * @example
- *
- *   const target = {};
- *   console.log(set({ target, path: 'some.prop.path', value: 'some-value' }));
- *   // Will output { some: { prop: { path: 'some-value' } } }
- *
- */
-declare function set<T = Record<string, unknown>>(options: SetOptions): T | undefined;
-declare function set<T = Record<string, unknown>>(options: SetOptions | unknown, path: string, value: unknown): T | undefined;
-
-/**
- * A shorthand method for {@link formatKeys} that transforms the keys from `snake_case` to
- * `dash-case`.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- */
-declare const snakeToDashKeys: <T>(options: FormatKeysExtensionOptions) => T;
-
-/**
- * A shorthand method for {@link formatKeys} that transforms the keys from `snake_case` to
- * `lowerCamelCase`.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- */
-declare const snakeToLowerCamelKeys: <T>(options: FormatKeysExtensionOptions) => T;
-
-type UnflatOptions = {
-    /**
-     * The object to transform.
-     */
-    target: unknown;
-    /**
-     * The delimiter that will separate the path components.
-     */
-    pathDelimiter?: string;
-};
-/**
- * This method does the exact opposite from `flat`: It takes an already flatten object and
- * restores it structure.
- *
- * @param options  The options to use.
- * @template T  The type of the returned object.
- * @example
- *
- *   const target = {
- *     'propOne.propOneSub': 'Charito!',
- *     propTwo: '!!!',
- *   };
- *   console.log(unflat({ target }));
- *   // Will output { propOne: { propOneSub: 'Charito!' }, 'propTwo': '!!!' }
- *
- */
-declare const unflat: <T = Record<string, unknown>>(options: UnflatOptions) => T;
-
-export { type ExtractOptions, type FlatOptions, type FormatKeysExtensionOptions, type FormatKeysOptions, type FormatKeysReplaceFn, type GetOptions, type RemoveOptions, type SetOptions, type ShouldFlattenFn, type UnflatOptions, copy, dashToLowerCamelKeys, dashToSnakeKeys, extract, type extractionPath, flat, formatKeys, get, lowerCamelToDashKeys, lowerCamelToSnakeKeys, merge, remove, set, snakeToDashKeys, snakeToLowerCamelKeys, unflat };