JavaScript Deep Utility Functions

Common errors

• RangeError: Maximum call stack size exceeded

  cause An object with circular references was passed to a recursive function like `recursiveOmit` or `deepExtend`.
  fix Inspect the object structure for circular references. Refactor your object to avoid them, or preprocess the object to break cycles (e.g., by setting circular references to `null`) before passing it to `js-utils-deep` functions.

• TypeError: Cannot convert undefined or null to object

  cause Attempting to call a deep utility function (e.g., `deepExtend`, `recursiveOmit`) with `null` or `undefined` as a primary object argument.
  fix Ensure all arguments passed to `js-utils-deep` functions, especially the target or source objects, are valid JavaScript objects (non-null, non-undefined).

• TypeError: Cannot set properties of undefined (setting 'propertyName')

  cause This error can occur within `deepExtend` if a nested property path in the source object points to an `undefined` or `null` path in the target object where it's attempting to create a new object or set a value.
  fix Ensure that intermediate objects exist in the target where `deepExtend` is expected to merge. For example, if `source.a.b` exists, but `target.a` is `undefined`, `deepExtend` might fail. Pre-initialize empty objects for paths if necessary, or ensure your target object's structure is compatible with the source.

Warnings

• gotcha Both `deepExtend` and `recursiveOmit` functions mutate their first argument (the target object) in place. If you need to preserve the original object, ensure you pass a deep clone of it as the first argument.
  Fix: Before calling `deepExtend(obj1, obj2)` or `recursiveOmit(obj)`, create a deep clone of `obj1` or `obj` (e.g., `const clonedObj = JSON.parse(JSON.stringify(obj));`) and pass the clone to the function.
• gotcha Functions that perform deep object traversal, such as `recursiveOmit`, `deepExtend`, and `diffObject`, may encounter infinite loops and throw a 'Maximum call stack size exceeded' error if presented with objects containing circular references.
  Fix: Ensure objects passed to deep utility functions do not contain circular references. Pre-process objects to remove or break cycles if necessary, or use a library designed to handle circular references explicitly.
• gotcha The `recursiveOmit` function treats empty strings `''` as values to be omitted, similar to `null` and `undefined`. Be aware of this behavior if empty strings have semantic meaning in your data and should be preserved.
  Fix: If empty strings need to be preserved, consider pre-processing your object to replace empty strings with a placeholder or use a custom recursive function for omission.

Install

• npm install js-utils-deep npm
• yarn add js-utils-deep yarn
• pnpm add js-utils-deep pnpm

Imports

• recursiveOmit
  wrong:

  const { recursiveOmit } = require('js-utils-deep');

  correct:

  import { recursiveOmit } from 'js-utils-deep';

  Use named import for ESM environments. CommonJS users should use `require` with destructuring.
• deepExtend
  wrong:

  import * as deepUtils from 'js-utils-deep'; deepUtils.deepExtend(...);

  correct:

  import { deepExtend } from 'js-utils-deep';

  Functions are exported as named exports. Avoid importing the entire module as a namespace unless specifically needed for multiple calls.
• All functions (CommonJS)
  wrong:

  const deepExtend = require('js-utils-deep/deepExtend');

  correct:

  const { recursiveOmit, deepExtend, diffObject } = require('js-utils-deep');

  For CommonJS environments, destructure specific functions from the main module export. The library does not support direct subpath imports for individual functions.

Quickstart

Demonstrates the core functionalities of `js-utils-deep`: `recursiveOmit` to clean deeply nested objects, `deepExtend` to merge objects recursively, and `diffObject` to find differences, highlighting their usage and mutation behavior.

import { recursiveOmit, deepExtend, diffObject } from 'js-utils-deep';

// Example for recursiveOmit: Removes null, '', undefined from deeply nested objects
let objToOmit = {
  x: {
    y: {
      z: ''
    },
    a: {
      b: null,
      c: undefined
    },
    d: null
  },
  e: 0,
  f: 'hello',
  g: []
};
console.log('Original object for omit:', JSON.stringify(objToOmit));
const omitted = recursiveOmit(objToOmit); // Mutates objToOmit
console.log('Object after recursiveOmit:', JSON.stringify(omitted));
// Expected: {"e":0,"f":"hello","g":[]}

// Example for deepExtend: Deeply merges source into target object
let targetObj = {
  x: {
    y: { z: '' },
    a: { b: null, c: undefined }
  },
  existing: 'value'
};
let sourceObj = {
  x: {
    y: { z: 'new_z' },
    a: { b: 'new_b', c: 'new_c' },
    d: 'new_d'
  },
  newProp: 'added'
};
console.log('Target object before extend:', JSON.stringify(targetObj));
deepExtend(targetObj, sourceObj); // Mutates targetObj
console.log('Target object after deepExtend:', JSON.stringify(targetObj));
// Expected: {"x":{"y":{"z":"new_z"},"a":{"b":"new_b","c":"new_c"},"d":"new_d"},"existing":"value","newProp":"added"}

// Example for diffObject: Compares two objects and returns differing key-value pairs
let obj1 = {
  id: 1,
  name: 'Alpha',
  details: { version: '1.0', status: 'active' }
};
let obj2 = {
  id: 1,
  name: 'Beta',
  details: { version: '1.1', owner: 'Org' },
  tags: ['new']
};
console.log('Object 1 for diff:', JSON.stringify(obj1));
console.log('Object 2 for diff:', JSON.stringify(obj2));
const differences = diffObject(obj1, obj2);
console.log('Differences between objects:', JSON.stringify(differences));
// Expected: {"name":"Beta","details":{"version":"1.1","status":"active","owner":"Org"},"tags":["new"]}