nanoclone

Common errors

• Maximum call stack size exceeded

  cause Attempting to clone an extremely deep object structure or a very complex, recursive object graph that exhausts the JavaScript engine's call stack during the recursive cloning process.
  fix Reduce the depth of the object being cloned, or consider custom cloning logic to manage recursion. While `nanoclone` handles circular structures, extreme depth can still be problematic.

• Cloned object of type X does not behave as expected or is empty

  cause `nanoclone` does not provide full deep cloning support for all possible JavaScript object types beyond its explicitly listed supported types (e.g., WeakMap, Promises, custom class instances). For these types, it might perform a shallow copy, return an empty object, or fail to preserve their internal state.
  fix Review the 'Supported' list in `nanoclone`'s documentation. If you need to clone unsupported types, you may need to implement custom serialization/deserialization for those specific parts of your object or use a different cloning library that offers broader type support.

Warnings

• gotcha nanoclone provides deep cloning for primitives, arrays, plain objects, Date, RegExp, Map, Set, and DOM Nodes. However, it does not explicitly support or correctly clone all complex built-in JavaScript objects (e.g., WeakMap, WeakSet, ArrayBuffer, TypedArrays, Promise, Error instances) or instances of user-defined classes. These types may be shallow copied, return an empty object, or not preserve internal state.
  Fix: For unsupported complex types, consider manually handling cloning for those specific parts (e.g., using `JSON.parse(JSON.stringify(obj))` for JSON-safe data) or using a more feature-rich (and larger) deep cloning library if comprehensive type support is critical.
• gotcha While nanoclone handles circular references, deep cloning can be computationally intensive for extremely large, deeply nested, or highly interconnected objects. This can impact performance or potentially lead to 'Maximum call stack size exceeded' errors in environments with limited stack sizes.
  Fix: Profile application performance when cloning large datasets. Consider optimizing object structures, shallow cloning less critical parts, or implementing custom cloning logic for specific performance bottlenecks.
• gotcha Functions and Symbols are copied by reference, not deeply cloned. This is standard behavior for deep cloning libraries as cloning executable code or unique symbols is complex and rarely desired. Any functions or symbols within the object will point to the same original reference.
  Fix: Be aware that modifying properties of a function or a Symbol object in the original would reflect in the cloned object. This is generally the expected and desired behavior, but it's crucial to understand for mutable function properties.

Install

• npm install nanoclone npm
• yarn add nanoclone yarn
• pnpm add nanoclone pnpm

Imports

• clone
  wrong:

  import { clone } from 'nanoclone'

  correct:

  import clone from 'nanoclone'

  The `clone` function is exported as the default export for ESM environments.
• clone
  wrong:

  const { clone } = require('nanoclone')

  correct:

  const clone = require('nanoclone')

  For CommonJS environments, `nanoclone` exports the `clone` function as the `module.exports` default.
• clone (TypeScript type)

  import type clone from 'nanoclone'

  When using TypeScript, the type of the `clone` function can be imported for type declarations.

Quickstart

This quickstart demonstrates how to import and use `nanoclone` to perform a deep copy of a complex JavaScript object, including nested structures and a Date instance, verifying that the cloned object is independent of the original.

import clone from 'nanoclone';

interface DeepObject {
  num: number;
  arr: number[];
  nested: {
    obj: {
      a: number;
    };
  };
  d?: Date;
}

let a: DeepObject = {
  num: 2,
  arr: [1, 2, 3],
  nested: {
    obj: {
      a: 0
    }
  },
  d: new Date()
};

let b: DeepObject = clone(a);

// Verify independence
a.num = 10; // Change original
b.nested.obj.a = 5; // Change clone
a.d?.setFullYear(2000); // Change original Date

console.log('Original object:', a); 
// Expected: { num: 10, arr: [1, 2, 3], nested: { obj: { a: 0 } }, d: Date(2000...) }
console.log('Cloned object:', b);  
// Expected: { num: 2, arr: [1, 2, 3], nested: { obj: { a: 5 } }, d: Date(current year...) }