@homer0/object-utils 5.0.3 → 5.0.4

package/src/fns/formatKeys.ts

@@ -1,270 +0,0 @@
-/**
- * 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.
- */
-export type FormatKeysReplaceFn = (substring: string, ...args: string[]) => string;
-
-export 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;
-};
-
-export 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!}.
- *
- */
-export const formatKeys = <T = Record<string, unknown>>(
-  options: FormatKeysOptions,
-): T => {
-  const {
-    target,
-    search,
-    replace,
-    include = [],
-    exclude = [],
-    pathDelimiter = '.',
-  } = options;
-  // Re-case target.
-  const useTarget = target as Record<string, unknown>;
-  // First of all, get all the keys from the target.
-  const keys = Object.keys(target as Record<string, unknown>);
-  /**
-   * Then, check which keys are parent to other objects.
-   * This is saved on a dictionary not only because it makes it easier to check if the
-   * method should make a recursive call for a key, but also because when parsing the
-   * `exclude`
-   * parameter, if one of items is a key (and not an specific path), the method won't make
-   * the recursive call.
-   *
-   * @ignore
-   */
-  const hasChildrenByKey: Record<string, unknown> = {};
-  keys.forEach((key) => {
-    const value = useTarget[key];
-    hasChildrenByKey[key] = !!(
-      value &&
-      typeof value === 'object' &&
-      value !== null &&
-      !Array.isArray(value) &&
-      Object.keys(value)
-    );
-  });
-  /**
-   * Escape the path delimiter and create two regular expression: One that removes the path
-   * delimiter from the start of a path and one that removes it from the end.
-   * They are later used to normalize paths in order to avoid "incomplete paths" (paths that
-   * end or start with the delimiter).
-   */
-  const escapedPathDelimiter = pathDelimiter.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&');
-  const cleanPathStartExpression = new RegExp(`^${escapedPathDelimiter}`, 'i');
-  const cleanPathEndExpression = new RegExp(`${escapedPathDelimiter}$`, 'i');
-  /**
-   * This dictionary will be used to save the `include` parameter that will be sent for specific
-   * keys on recursive calls.
-   * If `include` has a path like `myKey.mySubKey`, `myKey` is not transformed, but `mySubKey`
-   * is saved on this dictionary (`{ myKey: ['mySubKey']}`) and when the method applies the
-   * formatting to the object, if `myKey` has an object, it will make a recursive all and
-   * send `['mySubKey]` as its `include` parameter.
-   */
-  const subIncludeByKey: Record<string, string[]> = {};
-  /**
-   * This will be an array containing the final list of `keys` that should be tranformed.
-   * To be clear, these keys will be from the top level, so, they won't be paths.
-   * Thd following blocks will parse `include` and `exclude` in order to extract the real keys,
-   * prepare the `include` and `exclude` for recursive calls, and save the actual keys
-   * from the object "at the current level of this call" (no, it's not thinking about the
-   * children :P).
-   */
-  let keysToFormat: string[];
-  // If the `include` parameter has paths/keys...
-  if (include.length) {
-    keysToFormat = include
-      .map((includePath) => {
-        // Normalize the path/key.
-        const useIncludePath = includePath
-          .replace(cleanPathStartExpression, '')
-          .replace(cleanPathEndExpression, '');
-        // Define the variable that will, eventually, have the real key.
-        let key;
-        // If the value is a path...
-        if (useIncludePath.includes(pathDelimiter)) {
-          // Split all its components.
-          const pathParts = useIncludePath.split(pathDelimiter);
-          // Get the first component, a.k.a. the real key.
-          const pathKey = pathParts.shift()!;
-          /**
-           * This is very important: Since the path was specified with sub components
-           * (like `myProp.mySubProp`), the method won't format the key, but the sub
-           * key(s)
-           * (`mySubProp`).
-           * The `key` is set to `''` so it will be later removed using `.filter`.
-           *
-           * @ignore
-           */
-          key = '';
-          /**
-           * If there's no array for the key on the "`include` dictionary for recursive calls",
-           * create an empty one.
-           */
-          if (!subIncludeByKey[pathKey]) {
-            subIncludeByKey[pathKey] = [];
-          }
-          // Save the rest of the path to be sent on the recursive call as `include`.
-          subIncludeByKey[pathKey]!.push(pathParts.join(pathDelimiter));
-        } else {
-          // If the value wasn't a path, assume it's a key, and set it to be returned.
-          key = useIncludePath;
-        }
-
-        return key;
-      })
-      // Remove any _empty keys_.
-      .filter((key) => key);
-  } else {
-    // There's nothing on the `include` parameter, so use all the keys.
-    keysToFormat = keys;
-  }
-  /**
-   * Similar to `subIncludeByKey`, this dictionary will be used to save the `exclude` parameter
-   * that will be sent for specific keys on recursive calls.
-   * If `exclude` has a path like `myKey.mySubKey`, `myKey` will be transformed, but `mySubKey`
-   * is saved on this dictionary (`{ myKey: ['mySubKey']}`) and when the method applies the
-   * formatting to the object, if `myKey` has an object, it will make a recursive all and
-   * send `['mySubKey]` as its `exclude` parameter.
-   */
-  const subExcludeByKey: Record<string, string[]> = {};
-  // If the `include` parameter has paths/keys...
-  if (exclude.length) {
-    /**
-     * Create a dictionary of keys that should be removed from `keysToFormat`.
-     * It's easier to have them on a list and use `.filter` than actually call `.splice` for
-     * every key that should be removed.
-     */
-    const keysToRemove: string[] = [];
-    exclude.forEach((excludePath) => {
-      // Normalize the path/key.
-      const useExcludePath = excludePath
-        .replace(cleanPathStartExpression, '')
-        .replace(cleanPathEndExpression, '');
-      // If the value is a path...
-      if (useExcludePath.includes(pathDelimiter)) {
-        // Split all its components.
-        const pathParts = useExcludePath.split(pathDelimiter);
-        // Get the first component, a.k.a. the real key.
-        const pathKey = pathParts.shift()!;
-        /**
-         * If there's no array for the key on the "`exclude` dictionary for recursive calls",
-         * create an empty one.
-         */
-        if (!subExcludeByKey[pathKey]) {
-          subExcludeByKey[pathKey] = [];
-        }
-        // Save the rest of the path to be sent on the recursive call as `exclude`.
-        subExcludeByKey[pathKey]!.push(pathParts.join(pathDelimiter));
-      } else {
-        /**
-         * If the value wasn't a path, assume it's a key, turn the flag on the "children
-         * dictionary" to `false`, to prevent recursive calls, and add the key to the list
-         * of keys that will be removed from `keysToFormat`.
-         * Basically: If it's a key, don't format it and don't make recursive calls for
-         * it.
-         *
-         * @ignore
-         */
-        hasChildrenByKey[useExcludePath] = false;
-        keysToRemove.push(useExcludePath);
-      }
-    });
-    // Remove keys that should be excluded.
-    keysToFormat = keysToFormat.filter((key) => key && !keysToRemove.includes(key));
-  }
-  // "Finally", reduce all the keys from the object and create the new one...
-  return keys.reduce<Record<string, unknown>>((newObj, key) => {
-    /**
-     * Define the new key and value for the object property. Depending on the validations,
-     * they may be replaced with formatted ones.
-     */
-    let newKey;
-    let newValue;
-    /**
-     * Get the current value for the key, in case it's needed for a recursive call or just
-     * to send it back because it didn't need any change.
-     */
-    const value = useTarget[key];
-    // If the key should be formatted, apply the formatting; otherwise, keep the original.
-    if (keysToFormat.includes(key)) {
-      newKey = key.replace(search, replace);
-    } else {
-      newKey = key;
-    }
-    /**
-     * If the paths/keys on `exclude` didn't modify the "children dictionary" for the key and
-     * the value is another object, make a recursive call; otherwise, just use the original
-     * value.
-     */
-    if (hasChildrenByKey[key]) {
-      newValue = formatKeys({
-        target: value,
-        search,
-        replace,
-        include: subIncludeByKey[key] || [],
-        exclude: subExcludeByKey[key] || [],
-        pathDelimiter,
-      });
-    } else {
-      newValue = value;
-    }
-    // "Done", return the new object with the "new key" and the "new value".
-    return { ...newObj, [newKey]: newValue };
-  }, {}) as T;
-};

package/src/fns/get.ts

@@ -1,93 +0,0 @@
-export 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!'
- *
- */
-function get<T>(options: GetOptions): T | undefined;
-function get<T>(options: unknown, path: string): T | undefined;
-function get<T>(options: GetOptions | unknown, path?: string): T | undefined {
-  let useOptions: GetOptions;
-  if (typeof path === 'string') {
-    useOptions = {
-      target: options,
-      path,
-    };
-  } else {
-    useOptions = options as GetOptions;
-  }
-
-  const {
-    target,
-    path: usePath,
-    pathDelimiter = '.',
-    failWithError = false,
-  } = useOptions;
-  const useTarget = target as Record<string, unknown>;
-  const parts = usePath.split(pathDelimiter);
-  const first = parts.shift()!;
-  let currentElement = useTarget[first] as Record<string, unknown>;
-  if (typeof currentElement === 'undefined') {
-    if (failWithError) {
-      throw new Error(`There's nothing on '${usePath}'`);
-    }
-
-    return undefined;
-  }
-
-  if (!parts.length) {
-    return currentElement as T;
-  }
-
-  let currentPath = first;
-  parts.some((currentPart) => {
-    let breakLoop = false;
-    currentPath += `${pathDelimiter}${currentPart}`;
-    currentElement = currentElement[currentPart] as Record<string, unknown>;
-    if (typeof currentElement === 'undefined') {
-      if (failWithError) {
-        throw new Error(`There's nothing on '${currentPath}'`);
-      } else {
-        breakLoop = true;
-      }
-    }
-
-    return breakLoop;
-  });
-
-  return currentElement as T;
-}
-
-export { get };

package/src/fns/lowerCamelToDashKeys.ts

@@ -1,18 +0,0 @@
-import { formatKeys, type FormatKeysExtensionOptions } from './formatKeys.js';
-
-/**
- * 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.
- */
-export const lowerCamelToDashKeys = <T>(options: FormatKeysExtensionOptions): T =>
-  formatKeys<T>({
-    ...options,
-    search: /([a-z])([A-Z])/g,
-    replace: (_, firstLetter, secondLetter) => {
-      const newSecondLetter = secondLetter.toLowerCase();
-      return `${firstLetter}-${newSecondLetter}`;
-    },
-  });

package/src/fns/lowerCamelToSnakeKeys.ts

@@ -1,18 +0,0 @@
-import { formatKeys, type FormatKeysExtensionOptions } from './formatKeys.js';
-
-/**
- * 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.
- */
-export const lowerCamelToSnakeKeys = <T>(options: FormatKeysExtensionOptions): T =>
-  formatKeys<T>({
-    ...options,
-    search: /([a-z])([A-Z])/g,
-    replace: (_, firstLetter, secondLetter) => {
-      const newSecondLetter = secondLetter.toLowerCase();
-      return `${firstLetter}_${newSecondLetter}`;
-    },
-  });

package/src/fns/merge.ts

@@ -1,29 +0,0 @@
-import extend from 'extend';
-
-/**
- * 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' }]
- *
- */
-export const merge = <T = unknown>(...targets: unknown[]): T => {
-  const [firstTarget] = targets;
-  const base = Array.isArray(firstTarget) ? [] : {};
-  return extend(true, base, ...targets) as T;
-};

package/src/fns/remove.ts

@@ -1,102 +0,0 @@
-import { copy } from './copy.js';
-import { get } from './get.js';
-
-export 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: '!!!' }
- *
- */
-function remove<T = unknown>(options: RemoveOptions): T | undefined;
-function remove<T = unknown>(options: unknown, path: string): T | undefined;
-function remove<T = unknown>(
-  options: RemoveOptions | unknown,
-  path?: string,
-): T | undefined {
-  let useOptions: RemoveOptions;
-  if (typeof path === 'string') {
-    useOptions = {
-      target: options,
-      path,
-    };
-  } else {
-    useOptions = options as RemoveOptions;
-  }
-
-  const {
-    target,
-    path: usePath,
-    pathDelimiter = '.',
-    cleanEmptyProperties = true,
-    failWithError = false,
-  } = useOptions;
-
-  const parts = usePath.split(pathDelimiter);
-  const last = parts.pop()!;
-  const result = copy(target) as Record<string, unknown>;
-  if (!parts.length) {
-    delete result[last];
-    return result as T;
-  }
-  const parentPath = parts.join(pathDelimiter);
-  const parentObj = get<Record<string, unknown>>({
-    target: result,
-    path: parentPath,
-    pathDelimiter,
-    failWithError,
-  });
-
-  if (typeof parentObj === 'undefined') {
-    return undefined;
-  }
-
-  delete parentObj[last];
-  if (cleanEmptyProperties && !Object.keys(parentObj).length) {
-    return remove({
-      target: result,
-      path: parentPath,
-      pathDelimiter,
-      failWithError,
-      cleanEmptyProperties,
-    }) as T;
-  }
-
-  return result as T;
-}
-
-export { remove };

package/src/fns/set.ts

@@ -1,131 +0,0 @@
-import { copy } from './copy.js';
-
-/**
- * List of paths that are forbidden to use on the `set` function, as they could lead to
- * security issues.
- *
- * @access protected
- */
-const FORBIDDEN_PATHS = ['__proto__', 'prototype', 'constructor'];
-
-export 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' } } }
- *
- */
-function set<T = Record<string, unknown>>(options: SetOptions): T | undefined;
-function set<T = Record<string, unknown>>(
-  options: SetOptions | unknown,
-  path: string,
-  value: unknown,
-): T | undefined;
-function set<T = Record<string, unknown>>(
-  options: SetOptions | unknown,
-  path?: string,
-  value?: unknown,
-): T | undefined {
-  let useOptions: SetOptions;
-  if (typeof path === 'string') {
-    useOptions = {
-      target: options,
-      path,
-      value,
-    };
-  } else {
-    useOptions = options as SetOptions;
-  }
-
-  const {
-    target,
-    path: usePath,
-    value: useValue,
-    pathDelimiter = '.',
-    failWithError = false,
-  } = useOptions;
-  const result = copy(target) as Record<string, unknown>;
-  if (!usePath.includes(pathDelimiter)) {
-    if (!usePath || FORBIDDEN_PATHS.includes(usePath.toLowerCase())) {
-      return undefined;
-    }
-
-    result[usePath] = useValue;
-    return result as T;
-  }
-
-  const parts = usePath.split(pathDelimiter);
-  const isInvalid = parts.some(
-    (part) => !part || FORBIDDEN_PATHS.includes(part.toLowerCase()),
-  );
-
-  if (isInvalid) {
-    return undefined;
-  }
-
-  const last = parts.pop();
-  let currentElement = result;
-  let currentPath = '';
-  let foundInvalid = false;
-  parts.forEach((part) => {
-    currentPath += `${pathDelimiter}${part}`;
-    const element = currentElement[part];
-    const elementType = typeof element;
-    if (elementType === 'undefined') {
-      currentElement[part] = {};
-      currentElement = currentElement[part] as Record<string, unknown>;
-    } else if (elementType === 'object') {
-      currentElement = currentElement[part] as Record<string, unknown>;
-    } else {
-      const errorPath = currentPath.substring(pathDelimiter.length);
-      if (failWithError) {
-        throw new Error(
-          `There's already an element of type '${elementType}' on '${errorPath}'`,
-        );
-      } else {
-        foundInvalid = true;
-      }
-    }
-  });
-
-  if (foundInvalid) return undefined;
-
-  if (result && last) {
-    currentElement[last] = useValue;
-  }
-
-  return result as T | undefined;
-}
-
-export { set };

package/src/fns/snakeToDashKeys.ts

@@ -1,15 +0,0 @@
-import { formatKeys, type FormatKeysExtensionOptions } from './formatKeys.js';
-
-/**
- * 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.
- */
-export const snakeToDashKeys = <T>(options: FormatKeysExtensionOptions): T =>
-  formatKeys<T>({
-    ...options,
-    search: /([a-z])_([a-z])/g,
-    replace: (_, firstLetter, secondLetter) => `${firstLetter}-${secondLetter}`,
-  });

package/src/fns/snakeToLowerCamelKeys.ts

@@ -1,18 +0,0 @@
-import { formatKeys, type FormatKeysExtensionOptions } from './formatKeys.js';
-
-/**
- * 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.
- */
-export const snakeToLowerCamelKeys = <T>(options: FormatKeysExtensionOptions): T =>
-  formatKeys<T>({
-    ...options,
-    search: /([a-z])_([a-z])/g,
-    replace: (_, firstLetter, secondLetter) => {
-      const newSecondLetter = secondLetter.toUpperCase();
-      return `${firstLetter}${newSecondLetter}`;
-    },
-  });