Clone Deep

Clone Deep provides recursive (deep) cloning functionality for JavaScript native types, including Object, Array, RegExp, Date, and all primitive values. It offers a simple, focused API for creating independent copies of complex nested data structures while preserving type information and object relationships.

Package Information

• Package Name: clone-deep
• Package Type: npm
• Language: JavaScript
• Installation: npm install clone-deep
• Node.js Compatibility: >=8

Core Imports

const cloneDeep = require('clone-deep');

For ES modules:

import cloneDeep from 'clone-deep';

Basic Usage

const cloneDeep = require('clone-deep');

// Clone nested objects
const original = {
  user: { name: 'Alice', preferences: { theme: 'dark' } },
  items: [{ id: 1, active: true }, { id: 2, active: false }]
};

const copy = cloneDeep(original);

// Modifications to copy don't affect original
copy.user.name = 'Bob';
copy.items[0].active = false;

console.log(original.user.name); // 'Alice'
console.log(original.items[0].active); // true

Architecture

Clone Deep is built around type-aware recursive cloning:

• Type Detection: Uses kind-of library to identify value types (object, array, primitive, etc.)
• Plain Object Focus: Uses is-plain-object to identify objects suitable for deep cloning
• Shallow Clone Fallback: Leverages shallow-clone for primitives and non-cloneable objects
• Configurable Instance Handling: Optional instanceClone parameter for custom object cloning behavior
• Recursive Processing: Handles arbitrarily nested structures while maintaining object relationships

Capabilities

Deep Cloning

Recursively clones JavaScript native types with optional custom instance handling.

/**
 * Recursively clone JavaScript native types
 * @param {any} value - The value to clone (objects, arrays, primitives, etc.)
 * @param {boolean|function} [instanceClone] - Controls cloning of non-plain objects
 * @returns {any} - Deep clone of the input value
 */
function cloneDeep(value, instanceClone);

Parameters:

• value (any): The value to clone. Supports all JavaScript types including:

  • Objects (plain objects, instances, nested structures)
  • Arrays (including nested arrays with mixed types)
  • Primitives (string, number, boolean, null, undefined)
  • Native types (RegExp, Date, Map, Set)
  • Functions (copied by reference)

• instanceClone (boolean|function, optional): Controls how non-plain objects are handled:

  • undefined or false: Copy object references for non-plain objects (default behavior)
  • true: Deep clone all objects including constructor instances
  • function: Custom cloning function called for non-plain objects

Returns: Deep clone of the input value with the same type and structure

Usage Examples:

const cloneDeep = require('clone-deep');

// Basic object cloning
const obj = { a: 'b', nested: { x: 1, y: 2 } };
const cloned = cloneDeep(obj);
// obj and cloned are completely independent

// Array cloning with nested objects
const arr = [{ name: 'Alice' }, { name: 'Bob' }];
const clonedArr = cloneDeep(arr);
// Modifying clonedArr[0].name won't affect arr[0].name

// Primitive values
const str = cloneDeep('hello'); // 'hello'
const num = cloneDeep(42); // 42
const bool = cloneDeep(true); // true

// RegExp and Date objects
const regex = cloneDeep(/pattern/gi); // Independent RegExp copy
const date = cloneDeep(new Date()); // Independent Date copy

// Custom instance cloning
function CustomClass(value) {
  this.value = value;
}

const instance = new CustomClass({ data: 'test' });

// Default: copy reference
const refCopy = cloneDeep(instance);

// Clone instances: deep clone the instance
const instanceCopy = cloneDeep(instance, true);

// Custom cloning function
const customCopy = cloneDeep(instance, function(obj) {
  if (obj instanceof CustomClass) {
    return new CustomClass(cloneDeep(obj.value));
  }
  return obj;
});

Supported Data Types:

• Objects: Plain objects are deeply cloned; non-plain objects follow instanceClone behavior
• Arrays: All elements are recursively cloned
• Primitives: Returned as-is (string, number, boolean, null, undefined)
• RegExp: Creates independent copy with same pattern and flags
• Date: Creates independent copy with same timestamp
• Map: Creates independent copy with cloned entries
• Set: Creates independent copy with cloned values
• Functions: Copied by reference (not cloned)

Type Safety:

The function preserves the type and structure of the input while ensuring complete independence between the original and cloned values. Circular references are not explicitly handled and may cause stack overflow errors.