CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-lodash-clonedeepwith

Creates a deep clone of a value with customizable cloning behavior through a user-provided customizer function

Overview
Eval results
Files

lodash.clonedeepwith

Creates a deep clone of a value with customizable cloning behavior through a user-provided customizer function. This method is like _.cloneWith except that it recursively clones the value, providing complete control over how different types of values are cloned.

Package Information

  • Package Name: lodash.clonedeepwith
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install lodash.clonedeepwith

Core Imports

const cloneDeepWith = require('lodash.clonedeepwith');

Or when using the full lodash library:

const _ = require('lodash');
// Use as _.cloneDeepWith(value, customizer)

Basic Usage

const cloneDeepWith = require('lodash.clonedeepwith');

// Basic deep cloning with custom DOM element handling
function customizer(value) {
  if (value && value.nodeType) {
    return value.cloneNode(true);
  }
}

const originalElement = document.body;
const clonedElement = cloneDeepWith(originalElement, customizer);

console.log(clonedElement === originalElement); // => false
console.log(clonedElement.nodeName); // => 'BODY'
console.log(clonedElement.childNodes.length); // => 20

Capabilities

Deep Clone with Customizer

Creates a deep clone of a value with customizable cloning behavior through a user-provided customizer function.

/**
 * This method is like `_.cloneWith` except that it recursively clones `value`.
 * 
 * @param {*} value The value to recursively clone.
 * @param {Function} [customizer] The function to customize cloning.
 * @returns {*} Returns the deep cloned value.
 */
function cloneDeepWith(value, customizer);

Parameters:

  • value ()* - The value to recursively clone. Can be any JavaScript value including objects, arrays, primitives, functions, etc.
  • customizer (Function) [optional] - The function to customize cloning behavior

Returns:

  • ()* - Returns the deep cloned value

Customizer Function:

The customizer function is invoked with different arguments depending on the context:

  • For root-level cloning: customizer(value)
  • For object properties: customizer(value, key, object, stack)

Where:

  • value - The current value being cloned
  • key - The key of the property being cloned (when cloning object properties)
  • object - The parent object containing the property (when cloning object properties)
  • stack - Internal stack object used for circular reference handling

Customizer Return Behavior:

  • Return undefined to use default cloning behavior
  • Return any other value to use that value as the clone
  • The customizer is called recursively for nested values

Usage Examples:

const cloneDeepWith = require('lodash.clonedeepwith');

// Example 1: Custom DOM element cloning
function domCustomizer(value) {
  if (value && value.nodeType) {
    return value.cloneNode(true);
  }
}

const element = document.createElement('div');
element.innerHTML = '<span>Hello</span>';
const clonedElement = cloneDeepWith(element, domCustomizer);

// Example 2: Custom class instance handling
class MyClass {
  constructor(data) {
    this.data = data;
  }
}

function classCustomizer(value) {
  if (value instanceof MyClass) {
    return new MyClass(value.data);
  }
}

const original = { 
  items: [new MyClass('test'), new MyClass('data')] 
};
const cloned = cloneDeepWith(original, classCustomizer);

// Example 3: Selective property handling
function selectiveCustomizer(value, key) {
  if (key === 'password') {
    return '[REDACTED]';
  }
  if (key === 'timestamp') {
    return new Date();
  }
}

const userData = {
  name: 'John',
  password: 'secret123',
  timestamp: new Date('2020-01-01'),
  profile: {
    email: 'john@example.com',
    password: 'another-secret'
  }
};
const sanitized = cloneDeepWith(userData, selectiveCustomizer);

// Example 4: Type-based customization
function typeCustomizer(value) {
  if (value instanceof Date) {
    return new Date(value.getTime() + 86400000); // Add one day
  }
  if (typeof value === 'function') {
    return function() { return 'wrapped'; };
  }
}

const complex = {
  date: new Date(),
  fn: function() { return 'original'; },
  nested: {
    date: new Date('2020-01-01'),
    fn: () => 'arrow'
  }
};
const customized = cloneDeepWith(complex, typeCustomizer);

Supported Clone Types

The function can clone the following types:

  • Primitives: strings, numbers, booleans, symbols, null, undefined
  • Objects: plain objects, with recursive property cloning
  • Arrays: including nested arrays and typed arrays (Float32Array, etc.)
  • Built-in Objects: Date, RegExp, Map, Set, ArrayBuffer, DataView
  • Circular References: automatically detected and handled
  • Custom Objects: through customizer function

Error Handling

The function handles circular references automatically using an internal stack. If the customizer function throws an error, the error will propagate up to the caller.

Performance Notes

  • Deep cloning is a recursive operation that can be expensive for large, deeply nested objects
  • The function is optimized for arrays larger than 200 elements
  • Circular reference detection adds overhead but prevents infinite loops
  • Custom cloning logic in the customizer can impact performance depending on complexity

Install with Tessl CLI

npx tessl i tessl/npm-lodash-clonedeepwith
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/lodash.clonedeepwith@4.5.x