fast-copy

A blazing fast deep object copier

Table of contents

• fast-copy
  • Table of contents
  • Usage
  • API
    • copy
    • copyStrict
    • createCopier
      • createCache
      • maxDepth
      • methods
        • Copier state
          • cache
          • copier
          • Constructor / prototype
      • strict
  • Types supported
  • Aspects of default copiers
    • Error references are copied directly, instead of creating a new *Error object
    • The constructor of the original object is used, instead of using known globals
    • Sparse arrays are copied densely, unless using copyStrict
    • References are shared when circular references are possible
    • Typed arrays copy only the memory they view
  • Benchmarks
    • Simple objects
    • Complex objects
    • Big data
    • Circular objects
    • Special objects

Usage

import { copy } from 'fast-copy';
import { deepEqual } from 'fast-equals';

const object = {
  array: [123, { deep: 'value' }],
  map: new Map([
    ['foo', {}],
    [{ bar: 'baz' }, 'quz'],
  ]),
};

const copiedObject = copy(object);

console.log(copiedObject === object); // false
console.log(deepEqual(copiedObject, object)); // true

API

copy

Deeply copy the object passed.

import { copy } from 'fast-copy';

const copied = copy({ foo: 'bar' });

copyStrict

Deeply copy the object passed, but with additional strictness when replicating the original object:

• Properties retain their original property descriptor
• Non-enumerable keys are copied
• Non-standard properties (e.g., keys on arrays / dates / maps / sets) are copied
• Holes in sparse arrays are preserved

import { copyStrict } from 'fast-copy';

const object = { foo: 'bar' };
Object.defineProperty(object, 'bar', {
  enumerable: false,
  value: 'baz',
});

const copied = copyStrict(object);

NOTE: This method is significantly slower than copy, so it is recommended to only use this when you have specific use-cases that require it.

createCopier

Create a custom copier based on the type-specific method overrides passed, as well as configuration options for how copies should be performed. This is useful if you want to squeeze out maximum performance, or perform something other than a standard deep copy.

import { createCopier } from 'fast-copy';
import { LRUCache } from 'lru-cache';

const copyShallowStrict = createCopier({
  createCache: () => new LRUCache(),
  maxDepth: 32,
  methods: {
    array: (array) => [...array],
    map: (map) => new Map(map.entries()),
    object: (object) => ({ ...object }),
    set: (set) => new Set(set.values()),
  },
  strict: true,
});

createCache

Method that creates the internal cache in the Copier state. Defaults to creating a new WeakMap instance.

maxDepth

The maximum number of nested objects traversed before a MaxDepthExceededError is thrown. Defaults to 1000.

Because copying is recursive, a value nested more deeply than the JavaScript engine's call stack allows will exhaust the stack. The default limit sits below that threshold, so deeply-nested values fail with a descriptive, catchable error instead of a raw RangeError:

import { copy, MaxDepthExceededError } from 'fast-copy';

try {
  copy(untrustedPayload);
} catch (error) {
  if (error instanceof MaxDepthExceededError) {
    // `error.maxDepth` is the limit that was exceeded
  }
}

MaxDepthExceededError extends RangeError, so existing handling of the native stack-exhaustion error continues to work.

The limit is configured when the copier is created, so copy and copyStrict always use the default. If you copy values that are legitimately nested more deeply, create a copier with the limit you need and use it in their place; pass Infinity to remove the limit entirely, in which case sufficiently-deep values will again throw a native RangeError.

import { createCopier } from 'fast-copy';

export const copy = createCopier({ maxDepth: 5000 });
export const copyStrict = createCopier({ maxDepth: 5000, strict: true });

The default of 1000 assumes the stack available to a standard Node.js or browser main thread, where the native limit falls somewhere between roughly 1,800 and 4,000 levels depending on the copier used and the JIT's state. Environments configured with a smaller stack, such as a worker started with a reduced stackSizeMb, can exhaust it sooner, so lower the limit to suit the environment if you copy deeply-nested values in one.

const copyInWorker = createCopier({ maxDepth: 250 });

The failure when the limit is set too high for the environment is the same native RangeError thrown prior to this option existing, so too high a limit is never worse than having none.

NOTE: The depth counts nested objects only, including the buffer viewed by a DataView. Primitives and values already present in the cache (circular references) do not contribute to it.

methods

Methods used for copying specific object types. A list of the methods and which object types they handle:

This is the beginning of the README. Read the rest at the original. Read the full README ↗