klona - Deep Cloning Utility

Common errors

• TypeError: klona is not a function

  cause Attempting to use `klona` as a default import/require after the v2.0.0 breaking change to named exports.
  fix For ESM, change `import klona from 'klona'` to `import { klona } from 'klona'`. For CommonJS, change `const klona = require('klona')` to `const { klona } = require('klona')`.

• Type error: Module ''klona'' has no exported member 'klona'. Did you mean to use 'import klona from 'klona'' instead?

  cause Using an older TypeScript version or configuration with a `klona` version >=2.0.0, where the type definitions might be misinterpreted, or the editor cache is stale.
  fix Ensure your TypeScript version and configuration (`moduleResolution`) are compatible. Clear your editor's TypeScript cache if using VSCode. The correct import for v2+ is `import { klona } from 'klona'`.

Warnings

• breaking Starting with v2.0.0, `klona` migrated from a default export to a named export. This affects both ESM `import` statements and CommonJS `require` calls.
  Fix: Update your imports: For ESM, change `import klona from 'klona'` to `import { klona } from 'klona'`. For CommonJS, change `const klona = require('klona')` to `const { klona } = require('klona')`. This applies to all `klona` modes (e.g., `klona/json`, `klona/lite`).
• gotcha Prior to v2.0.5, `klona` and `klona/lite` had an issue where `Object.assign` within class constructors was not handled correctly during cloning, potentially leading to incorrect copies for custom class instances.
  Fix: Upgrade to `klona@2.0.5` or newer to ensure correct handling of `Object.assign` in class constructors.
• gotcha In `klona/full`, prototype methods were not consistently copied prior to v2.0.4, which could lead to incomplete deep clones for objects with prototype chains.
  Fix: Upgrade to `klona@2.0.4` or newer to ensure that prototype methods are correctly copied when using the `klona/full` module.
• gotcha Versions prior to v1.1.1 had issues correctly handling `Set` and `Map` instances during cloning, and lacked explicit protection against `__proto__` pollution attacks.
  Fix: Upgrade to `klona@1.1.1` or newer to resolve issues with `Set` and `Map` cloning and benefit from improved prototype pollution protection.
• gotcha TypeScript users leveraging `moduleResolution: 'nodenext'` in their `tsconfig.json` might encounter type resolution issues with `klona` in versions prior to v2.0.6 due to missing 'types' condition in the package's `exports` map.
  Fix: Upgrade to `klona@2.0.6` or newer to gain proper TypeScript `nodenext` support.

Install

• npm install klona npm
• yarn add klona yarn
• pnpm add klona pnpm

Imports

• klona
  wrong:

  import klona from 'klona';

  correct:

  import { klona } from 'klona';

  Since v2.0.0, `klona` uses named exports for ESM. For CommonJS, use `const { klona } = require('klona');`
• klona (JSON mode)
  wrong:

  import klona from 'klona/json';

  correct:

  import { klona } from 'klona/json';

  The `klona/json` entry point provides a smaller bundle for cloning only JSON-serializable types. Uses named exports since v2.0.0.
• klona (Full mode)
  wrong:

  import klona from 'klona/full';

  correct:

  import { klona } from 'klona/full';

  The `klona/full` entry point provides the most comprehensive cloning, including Symbol and non-enumerable properties. Uses named exports since v2.0.0.
• klona (CommonJS)
  wrong:

  const klona = require('klona');

  correct:

  const { klona } = require('klona');

  Since v2.0.0, `klona` uses named exports for CommonJS.

Quickstart

Demonstrates how to import and use the `klona` function to perform a deep clone of a complex object, including nested objects, dates, regexps, sets, and maps, and verifies that modifications to the clone do not affect the original source object.

import { klona } from 'klona';

const input = {
  foo: 1,
  bar: {
    baz: 2,
    bat: {
      hello: 'world'
    }
  },
  date: new Date(),
  regex: /test/g,
  items: new Set([1, 2, 3]),
  mapData: new Map([['a', 1], ['b', 2]])
};

const output = klona(input);

// Verify deep equality (requires an assertion library like Node's assert.deepStrictEqual)
// import * as assert from 'assert';
// assert.deepStrictEqual(input, output);

// Modifying the clone does not affect the original
output.bar.bat.hola = 'mundo';
output.bar.baz = 99;
output.items.add(4);
output.date.setFullYear(2030);

console.log('Original Input:', JSON.stringify(input, null, 2));
console.log('Cloned Output (modified):', JSON.stringify(output, null, 2));

// You would see 'hola' and 'mundo' only in the output, and 'baz' will be 99.
// The date and set will also reflect the changes only in the output.