fast-copy

A blazing fast deep object copier

Table of contents

• fast-copy
  • Table of contents
  • Usage
  • API
    • copy
    • copyStrict
    • createCopier
      • createCache
      • 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
    • Generator objects are copied, but still reference the original generator's state
  • Benchmarks
    • Simple objects
    • Complex objects
    • Big data
    • Circular objects
    • Special objects
  • Development

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 / maps / sets) are copied

import { copyStrict } from 'fast-copy';

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

const copied = copy(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(),
  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.

methods

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

• array => Array
• arrayBuffer=> ArrayBuffer, Float32Array, Float64Array, Int8Array, Int16Array, Int32Array, Uint8Array, Uint8ClampedArray, Uint16Array, Uint32Array, Uint64Array
• blob => Blob
• dataView => DataView
• date => Date
• error => Error, AggregateError, EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError
• map => Map
• object => Object, or any custom constructor
• regExp => RegExp
• set => Set

Each method has the following contract:

type InternalCopier<Value> = (value: Value, state: State) => Value;

interface State {
  Constructor: any;
  cache: WeakMap;
  copier: InternalCopier<any>;
  prototype: any;
}

Copier state

cache

If you want to maintain circular reference handling, then you'll need the methods to handle cache population for future lookups:

function shallowlyCloneArray<Value extends any[]>(
  value: Value,
  state: State
): Value {
  const clone = [...value];

  state.cache.set(value, clone);

  return clone;
}

copier

copier is provided for recursive calls with deeply-nested objects.

function deeplyCloneArray<Value extends any[]>(
  value: Value,
  state: State
): Value {
  const clone = [];

  state.cache.set(value, clone);

  value.forEach((item) => state.copier(item, state));

  return clone;
}

Note above I am using forEach instead of a simple map. This is because it is highly recommended to store the clone in cache eagerly when deeply copying, so that nested circular references are handled correctly.

Constructor / prototype

Both Constructor and prototype properties are only populated with complex objects that are not standard objects or arrays. This is mainly useful for custom subclasses of these globals, or maintaining custom prototypes of objects.

function deeplyCloneSubclassArray<Value extends CustomArray>(
  value: Value,
  state: State
): Value {
  const clone = new state.Constructor();

  state.cache.set(value, clone);

  value.forEach((item) => clone.push(item));

  return clone;
}

function deeplyCloneCustomObject<Value extends CustomObject>(
  value: Value,
  state: State
): Value {
  const clone = Object.create(state.prototype);

  state.cache.set(value, clone);

  Object.entries(value).forEach(([k, v]) => (clone[k] = v));

  return clone;
}

strict

Enforces strict copying of properties, which includes properties that are not standard for that object. An example would be a named key on an array.

NOTE: This creates a copier that is significantly slower than "loose" mode, so it is recommended to only use this when you have specific use-cases that require it.

Types supported

The following object types are deeply cloned when they are either properties on the object passed, or the object itself:

• Array
• ArrayBuffer
• Boolean primitive wrappers (e.g., new Boolean(true))
• Blob
• Buffer
• DataView
• Date
• Float32Array
• Float64Array
• Int8Array
• Int16Array
• Int32Array
• Map
• Number primitive wrappers (e.g., new Number(123))
• Object
• RegExp
• Set
• String primitive wrappers (e.g., new String('foo'))
• Uint8Array
• Uint8ClampedArray
• Uint16Array
• Uint32Array
• React components
• Custom constructors

The following object types are copied directly, as they are either primitives, cannot be cloned, or the common use-case implementation does not expect cloning:

• AsyncFunction
• Boolean primitives
• Error
• Function
• GeneratorFunction
• Number primitives
• Null
• Promise
• String primitives
• Symbol
• Undefined
• WeakMap
• WeakSet

Circular objects are supported out of the box. By default, a cache based on WeakSet is used, but if WeakSet is not available then a fallback is used. The benchmarks quoted below are based on use of WeakSet.

Aspects of default copiers

Inherently, what is considered a valid copy is subjective because of different requirements and use-cases. For this library, some decisions were explicitly made for the default copiers of specific object types, and those decisions are detailed below. If your use-cases require different handling, you can always create your own custom copier with createCopier.

Error references are copied directly, instead of creating a new *Error object

While it would be relatively trivial to copy over the message and stack to a new object of the same Error subclass, it is a common practice to "override" the message or stack, and copies would not retain this mutation. As such, the original reference is copied.

The constructor of the original object is used, instead of using known globals

Starting in ES2015, native globals can be subclassed like any custom class. When copying, we explicitly reuse the constructor of the original object. However, the expectation is that these subclasses would have the same constructur signature as their native base class. This is a common community practice, but there is the possibility of inaccuracy if the contract differs.

Generator objects are copied, but still reference the original generator's state

Generator objects are specific types of iterators, but appear like standard objects that just have a few methods (next, throw, return). These methods are bound to the internal state of the generator, which cannot be copied effectively. Normally this would be treated like other "uncopiable" objects and simply pass the reference through, however the "validation" of whether it is a generator object or a standard object is not guaranteed (duck-typing) and there is a runtime cost associated with. Therefore, the simplest path of treating it like a standard object (copying methods to a new object) was taken.

Benchmarks

Simple objects

Small number of properties, all values are primitives

Complex objects

Large number of properties, values are a combination of primitives and complex objects

Big data

Very large number of properties with high amount of nesting, mainly objects and arrays

Circular objects

Objects that deeply reference themselves

Special objects

Custom constructors, React components, etc

Development

Standard practice, clone the repo and yarn (or npm i) to get the dependencies. The following npm scripts are available:

• benchmark => run benchmark tests against other equality libraries
• build => run build:esm, build:cjs, build:umd, and build:min scripts
• build:cjs => build CJS files and types
• build:esm => build ESM files and types
• build:min => build minified files and types
• build:umd => build UMD files and types
• clean => remove the dist folder and all its contents
• clean:cjs => remove the dist/cjs folder and all its contents
• clean:esm => remove the dist/esm folder and all its contents
• clean:min => remove the dist/min folder and all its contents
• clean:umd => remove the dist/umd folder and all its contents
• dev => start webpack playground App
• lint => run eslint
• lint:fix => run lint script, but with auto-fixer
• release => run prepublishOnly and release with new version
• release:beta => run prepublishOnly and release with new beta version
• release:dry => run prepublishOnly and simulate a new release
• release:scripts => run lint, test:coverage, and dist scripts
• start => run dev
• test => run AVA with NODE_ENV=test on all files in test folder
• test:coverage => run same script as test with code coverage calculation via nyc
• test:watch => run same script as test but keep persistent watcher
• typecheck => run tsc on the codebase

fast-copy CHANGELOG

4.0.0

BREAKING CHANGES

• Legacy environment support has been removed; Symbol, WeakMap, and RegExp.prototype.flags are now expected to be present.
• createCopier now receives an object of options. The methods passed previously are namespaced under the methods key in that options object.
• createStrictCopier has been removed; please use the strict option passed to createCopier

3.0.2

• #95 - Add support for objects that have a prototype with no constructor

3.0.1

• #78 - Work when running Node process with --disable-proto=throw (thanks @castarco)

3.0.0

Breaking changes

• Exports are now always named, so the .default suffix is required when accessing
  • CommonJS in Node => const copy = require('fast-copy').default;
  • UMD global via CDN => const copy = globalThis['fast-copy'].default;
• copy.strict is no longer available; it is now available as the explicit copyStrict named import
• Options have been removed
  • isStrict option has been replaced with importing the separate copyStrict method
  • realm has been removed entirely, as instanceof is no longer used internally
• The FastCopy namespace in typings has been removed in favor of explicit import of available types

Enhancements

• Support exports option, to have bettern handling for different environments (ESM vs CJS vs UMD) and improve tree-shaking when supported
• Can now create a custom copier (either standard or strict), allowing maximum performance for specific use-cases
• Small speed improvements when handling certain object types

Bug fixes

• Correctly handle primitive wrappers, e.g. new String('foo')

2.1.7

• Republish of 2.1.6, as the release process failed mid-publish

2.1.6

• Revert #69 and #71, as they broke the package for NodeJS consumption (will be reintroduced in v3, as breaking changes are required)

2.1.5 - DO NOT USE

• Ensure "type": "module" is set to allow ESM in NodeJS to work #71

2.1.4 - DO NOT USE

• Provide "exports" definition in package.json #69 (thanks @liteoood)

2.1.3

• Fix source maps not referencing source code #65

2.1.2

• Support constructor property override on object #60
• Provide better support for constructor override on non-plain object types #61
• Remove tslint in favor of @typescript-eslint #62

2.1.1

• Fix ESM-to-CommonJS issue when using TSC to consume #37
• Modify Blob cloning to use blob.slice() instead of new Blob() for speed

2.1.0

• Support cloning Blob #31 (thanks @fratzigner)
• Fix cloning descriptors that only are getters / setters in strict mode
• Handle errors when defining properties in strict mode

2.0.5

• Fix issue copying objects referenced multiple times in source #28 (thanks @darkowic)

2.0.4

• Cache length of arrays for faster iteration #22
• Update dev dependencies and types

2.0.3

• Add safety to constructing native objects (fixes #19)

2.0.2

• Manually coalesce options instead of use destructuring (performance)

2.0.1

• Fix typings declarations - #17

2.0.0

• Rewrite in TypeScript
• Add strict mode (for more accurate and thorough copying, at the expense of less performance)

BREAKING CHANGES

• Second parameter is now an object of options

1.2.4

• Ensure Date copy uses realm-specific constructor

1.2.3

• Support custom prototype applied to plain object via Object.create()

1.2.2

• Support copy of extensions of native Array with alternative push() method

1.2.1

• Under-the-hood optimizations per recommendations from #7

1.2.0

• Add support for multiple realms

1.1.2

• Optimize order of operations for common use cases

1.1.1

• Fix cache using WeakSet when there was support for WeakMaps instead of WeakSets (in case one was polyfilled but not the other)

1.1.0

• Add TypeScript and FlowType bindings

1.0.1

• Activate tree-shaking

1.0.0

• Initial release