Configurable circular reference handling in lodash _.cloneDeep

Direct Answer

No. _.cloneDeep in lodash 4.17.21 has no configuration options for circular reference handling. It unconditionally throws a TypeError when a cycle is detected, exposes no replacer, ignore list, or error callback, and the error message does not include the property path where the cycle occurs.

Why lodash Cannot Be Configured

• The internal implementation tracks visited objects with a basic Set/WeakSet but exposes zero extension points.
• Monkey-patching lodash internals is fragile — internal structure is not covered by semver and may change in patch releases.
• JSON.stringify with a custom replacer can detect cycles, but it only works for JSON-serializable data (loses functions, symbols, Date, RegExp, Map, Set, typed arrays, etc.).

Recommended Approach: Custom Recursive Clone with WeakMap

A custom clone using a WeakMap to track visited objects is the standard pattern when circular structures are expected. It allows replacement with a placeholder, skipping, or recording the path.

function cloneDeepCircular(obj, options = {}) {
  const {
    placeholder = '[Circular]',
    onCycle = null // (path, original) => any
  } = options;

  const seen = new WeakMap(); // original -> clone
  const path = [];

  function clone(value) {
    if (value === null || typeof value !== 'object') return value;

    if (seen.has(value)) {
      const existing = seen.get(value);
      if (onCycle) return onCycle([...path], value);
      return placeholder;
    }

    // Handle Array
    if (Array.isArray(value)) {
      const cloneArr = [];
      seen.set(value, cloneArr);
      value.forEach((item, i) => {
        path.push(i);
        cloneArr[i] = clone(item);
        path.pop();
      });
      return cloneArr;
    }

    // Handle Date, RegExp, etc.
    if (value instanceof Date) return new Date(value);
    if (value instanceof RegExp) return new RegExp(value);

    // Handle plain object
    const cloneObj = {};
    seen.set(value, cloneObj);
    for (const key of Object.keys(value)) {
      path.push(key);
      cloneObj[key] = clone(value[key]);
      path.pop();
    }
    return cloneObj;
  }

  return clone(obj);
}

Usage Examples

const a = { foo: 1 };
a.self = a;

// Replace with placeholder
cloneDeepCircular(a);
// { foo: 1, self: '[Circular]' }

// Capture path
cloneDeepCircular(a, {
  onCycle: (path) => ({ __circularRef: path.join('.') })
});
// { foo: 1, self: { __circularRef: 'self' } }

// Skip the property entirely
cloneDeepCircular(a, {
  onCycle: () => undefined // property omitted
});
// { foo: 1 }

Alternative Libraries

If you prefer a maintained dependency over a custom implementation:

• rfdc (Really Fast Deep Clone) — supports circles: true option to preserve circular references.
• clone-deep (npm) — offers circular handling options.

These are separate dependencies, not lodash configuration.

Verification Step

Confirm lodash behavior in your environment:

const _ = require('lodash');
const obj = { a: 1 };
obj.b = obj;
try { _.cloneDeep(obj); } catch (e) { console.log(e.message); }
// Expected: "Converting circular structure to JSON" (or similar)

One Diagnostic Question

Do you need to preserve object identity for the circular reference (i.e., the cloned graph should have the same circular structure), or is a placeholder/skip sufficient? This determines whether rfdc (preserves cycles) or the custom clone above (replaces/skips) is the better fit.