Deep Copy TS

Common errors

• TypeError: (0 , deep_copy_ts__WEBPACK_IMPORTED_MODULE_0__.deepCopy) is not a function

  cause This error often occurs in bundler environments (e.g., Webpack, Rollup) when there's a mismatch between CommonJS `require` and ES Module `import` syntax, or if the bundler struggles to resolve the named export `deepCopy`.
  fix Ensure you are using `import { deepCopy } from 'deep-copy-ts';` for ES Modules. If in a CommonJS-only environment, use `const { deepCopy } = require('deep-copy-ts');`. Verify your bundler configuration correctly handles ES Modules.

• Maximum call stack size exceeded

  cause This error typically indicates an infinite recursion. While not explicitly stated in the documentation, it can occur in deep copying libraries when processing objects with circular references (e.g., `obj.a = obj`).
  fix Inspect the object you are attempting to copy for circular references. If they exist, either restructure your data to avoid them or use a deep cloning utility that explicitly supports and handles circular references, often by tracking visited objects.

Warnings

• gotcha The library's support for `BigInt64Array` and `BigUint64Array` is noted as 'not supported in Safari yet' in the README. Use caution or polyfills if targeting Safari and these types are critical.
  Fix: Ensure browser compatibility requirements are met, potentially by avoiding these specific TypedArray types or implementing environment-specific fallbacks.
• gotcha Functions and Promises are copied by reference, not deeply cloned. If a function contains internal state or references that need to be duplicated, deep-copy-ts will not handle this, and the copied object will share the same function instance as the original.
  Fix: Be aware of this behavior and manually handle custom logic for duplicating functions or Promises if deep cloning their internal state is required.
• gotcha While the library handles many common types, objects with circular references are not explicitly documented. Attempting to deep copy an object with a direct or indirect circular reference might lead to an infinite loop and a 'Maximum call stack size exceeded' error if not properly handled by the library internally.
  Fix: Test the library's behavior with objects containing circular references in your specific environment. If an error occurs, consider pre-processing your objects to break circular references or using a different library that explicitly guarantees circular reference handling.
• breaking As a pre-1.0.0 package (current version 0.5.4), deep-copy-ts may introduce breaking changes in minor version updates without adhering to strict semver major-version increments. Review release notes carefully when upgrading minor versions.
  Fix: Pin to exact versions for production environments or conduct thorough regression testing when updating to new minor versions.

Install

• npm install deep-copy-ts npm
• yarn add deep-copy-ts yarn
• pnpm add deep-copy-ts pnpm

Imports

• deepCopy
  wrong:

  const deepCopy = require('deep-copy-ts');

  correct:

  import { deepCopy } from 'deep-copy-ts';

  The library primarily uses named exports. Prefer ESM imports for modern TypeScript/JavaScript projects.
• deepCopy (CommonJS)
  wrong:

  import deepCopy from 'deep-copy-ts';

  correct:

  const { deepCopy } = require('deep-copy-ts');

  For CommonJS environments, destructure the named export. A default import will not work.
• Type definitions

  import type { DeepCopy } from 'deep-copy-ts';

  While `deepCopy` is a function, you might import types for advanced scenarios or extending its behavior, though direct type imports for the function itself are less common.

Quickstart

This quickstart demonstrates how to use `deepCopy` to duplicate an object containing various primitive and complex data types, including nested structures, dates, regexps, functions, and typed arrays. It then verifies that modifications to the copied object's nested properties do not affect the original object, illustrating the deep cloning behavior. It also shows that functions are copied by reference.

import { deepCopy } from 'deep-copy-ts';

const originalObject = {
  primitive: 123,
  text: 'hello world',
  nested: {
    array: [1, 2, { sub: 'item' }],
    date: new Date('2023-01-01T12:00:00Z'),
    regex: /test/gi,
  },
  func: () => console.log('This is a function'),
  nullValue: null,
  undefinedValue: undefined,
  typedArray: new Uint8Array([10, 20, 30]),
  buffer: new ArrayBuffer(8),
  dataView: new DataView(new ArrayBuffer(16))
};

const copiedObject = deepCopy(originalObject);

console.log('Original object:', originalObject);
console.log('Copied object:', copiedObject);

// Verify deep copy by modifying a nested property
copiedObject.nested.array[0] = 999;
copiedObject.nested.date.setFullYear(2050);

console.log('\nAfter modifying copiedObject:');
console.log('Original array element:', originalObject.nested.array[0]); // Should be 1
console.log('Copied array element:', copiedObject.nested.array[0]);     // Should be 999
console.log('Original date year:', originalObject.nested.date.getFullYear()); // Should be 2023
console.log('Copied date year:', copiedObject.nested.date.getFullYear());     // Should be 2050

// Functions are copied by reference
console.log('Are functions strictly equal?', originalObject.func === copiedObject.func); // true