fast-copy

What is fast-copy?

The fast-copy npm package is a deep copying utility designed to be faster than other deep copy alternatives. It can handle various JavaScript data types and structures, including objects, arrays, dates, and more, providing a deep clone without the performance overhead of other libraries.

What are fast-copy's main functionalities?

Deep copying objects

This feature allows you to create a deep copy of an object, ensuring that nested objects are also cloned rather than just their references.

const copy = require('fast-copy').default;
const original = { a: 1, b: { c: 2 } };
const cloned = copy(original);

Deep copying arrays

Similar to objects, this feature enables deep copying of arrays, including nested arrays.

const copy = require('fast-copy').default;
const original = [1, 2, [3, 4]];
const cloned = copy(original);

Copying other types

fast-copy can also clone other JavaScript types such as Date objects and regular expressions.

const copy = require('fast-copy').default;
const date = new Date();
const regex = new RegExp('ab+c', 'i');
const clonedDate = copy(date);
const clonedRegex = copy(regex);

Other packages similar to fast-copy

lodash.clonedeep

Lodash's clonedeep method provides deep cloning functionality. It is part of the larger Lodash library, which is a general utility library. Compared to fast-copy, lodash.clonedeep may be slower but is part of a well-established utility library with a wide range of functions.

clone

The clone package offers deep cloning of objects and arrays. It is less focused on performance compared to fast-copy and does not handle some of the more complex data types that fast-copy can.

deep-copy

Deep-copy is another package that provides deep cloning capabilities. It is similar to fast-copy in its purpose but may not have the same performance optimizations.

rfdc

The rfdc (Really Fast Deep Clone) package is a competitor to fast-copy, focusing on performance for deep cloning. It claims to be faster than other deep cloning libraries for certain use cases and is a good alternative to consider when performance is critical.

README

fast-copy

A blazing fast deep object copier

Table of contents

• Usage
  • Multiple realms
• Types supported
• Benchmarks
  • Simple objects
  • Complex objects
  • 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

Multiple realms

Under the hood, fast-copy uses instanceof to determine object types, which can cause false negatives when used in combination with iframe-based objects. To handle this edge case, you can pass the optional second parameter of realm to the copy method, which identifies which realm the object comes from and will use that realm to drive both comparisons and constructors for the copies.

<iframe srcdoc="<script>var arr = ['foo', 'bar'];</script>"></iframe>

const iframe = document.querySelector("iframe");
const arr = iframe.contentWindow.arr;

console.log(copy(arr, iframe.contentWindow)); // ['foo', 'bar']

Types supported

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

• Array
• ArrayBuffer
• Buffer
• DataView
• Date
• Float32Array
• Float64Array
• Int8Array
• Int16Array
• Int32Array
• Map
• Object
• RegExp
• Set
• 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
• Error
• Function
• GeneratorFunction
• Number
• Null
• Promise
• String
• Symbol
• Undefined
• WeakMap
• WeakSet

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

Benchmarks

Simple objects

Small number of properties, all values are primitives

	Operations / second	Relative margin of error
fast-copy	1,536,378	0.90%
clone	1,146,433	0.76%
lodash.cloneDeep	955,818	0.59%
fast-deepclone	746,497	0.75%
fast-clone	515,248	0.94%
deepclone	444,649	0.73%

Complex objects

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

	Operations / second	Relative margin of error
fast-copy	110,295	0.75%
fast-deepclone	102,497	0.81%
deepclone	57,582	0.75%
clone	51,563	1.01%
fast-clone	43,956	0.74%
lodash.cloneDeep	40,257	0.79%

Circular objects

Objects that deeply reference themselves

	Operations / second	Relative margin of error
fast-copy	921,656	0.72%
clone	651,385	0.69%
lodash.cloneDeep	621,131	0.60%
fast-deepclone	385,925	0.84%
deepclone	377,517	0.65%
fast-clone (not supported)	0	0.00%

Special objects

Custom constructors, React components, etc

	Operations / second	Relative margin of error
fast-copy	50,839	0.61%
clone	44,504	0.78%
lodash.cloneDeep	38,210	0.62%
fast-deepclone	26,635	0.85%
fast-clone	22,422	0.67%
deepclone	13,753	0.84%

Development

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

• benchmark => run benchmark tests against other equality libraries
• build => build dist files with rollup
• clean => run clean:dist, clean:es, and clean:lib scripts
• clean:dist => run rimraf on the dist folder
• clean:es => run rimraf on the es folder
• clean:lib => run rimraf on the lib folder
• dev => start webpack playground App
• dist => run build and build:minified scripts
• lint => run ESLint on all files in src folder (also runs on dev script)
• lint:fix => run lint script, but with auto-fixer
• prepublish:compile => run lint, test:coverage, transpile:lib, transpile:es, 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
• transpile:es => run Babel on all files in src folder (transpiled to es folder without transpilation of ES2015 export syntax)
• transpile:lib => run Babel on all files in src folder (transpiled to lib folder)

Changelog

1.2.0

• Add support for multiple realms