copy-anything

What is copy-anything?

The 'copy-anything' npm package is a utility for deep cloning JavaScript objects, arrays, and other data types. It ensures that the copied data is a completely new instance, preventing unintended mutations in the original data.

What are copy-anything's main functionalities?

Deep Cloning Objects

This feature allows you to create a deep clone of an object, ensuring that nested objects are also cloned and not just referenced.

const copy = require('copy-anything');
const original = { a: 1, b: { c: 2 } };
const cloned = copy(original);
console.log(cloned); // { a: 1, b: { c: 2 } }

Deep Cloning Arrays

This feature allows you to create a deep clone of an array, ensuring that nested arrays and objects within the array are also cloned.

const copy = require('copy-anything');
const originalArray = [1, [2, 3], { a: 4 }];
const clonedArray = copy(originalArray);
console.log(clonedArray); // [1, [2, 3], { a: 4 }]

Handling Special Data Types

This feature ensures that special data types like Date objects are properly cloned, creating new instances with the same values.

const copy = require('copy-anything');
const original = new Date();
const cloned = copy(original);
console.log(cloned); // A new Date instance with the same value as original

Other packages similar to copy-anything

lodash

Lodash is a popular utility library that provides a wide range of functions for manipulating arrays, objects, and other data types. It includes a deep cloning function (`_.cloneDeep`) that offers similar functionality to 'copy-anything'. However, Lodash is a much larger library with many additional features beyond cloning.

clone-deep

The 'clone-deep' package is specifically designed for deep cloning objects and arrays. It offers similar functionality to 'copy-anything' but focuses solely on deep cloning without additional utilities.

rfdc

The 'rfdc' (Really Fast Deep Clone) package is a lightweight and fast deep cloning library. It provides similar deep cloning capabilities as 'copy-anything' but is optimized for performance, making it a good choice for performance-critical applications.

README

Copy anything 🎭

An optimised way to copy'ing (cloning) an object or array. A small and simple integration.

Motivation

I created this package because I tried a lot of similar packages that do copy'ing/cloning. But all had its quirks, and all of them break things they are not supposed to break... 😞

I was looking for:

• a simple copy/clone function
• has to be fast!
• props must lose any reference to original object
• works with arrays and objects in arrays!
• does not break special class instances　‼️

This last one is crucial! So many libraries use custom classes that create objects with special prototypes, and such objects all break when trying to copy them inproperly. So we gotta be careful!

copy-anything will copy objects and nested properties, but only as long as they're "plain objects". As soon as a sub-prop is not a "plain object" and has a special prototype, it will copy that instance over "as is". ♻️

Meet the family

• copy-anything 🎭
• merge-anything 🥡
• filter-anything ⚔️
• find-and-replace-anything 🎣
• compare-anything 🛰
• flatten-anything 🏏
• is-what 🙉

Usage

import copy from 'copy-anything'

const original = {name: 'Ditto', type: {water: true}}
const copy = copy(original)

// now if we change a nested prop like the type:
copy.type.water = false
copy.type.fire = true // new prop

// then the original object will still be the same:
(original.type.water === true)
(original.type.fire === undefined)

Works with arrays

It will also clone arrays, as well as objects inside arrays! 😉

import copy from 'copy-anything'

const original = [{name: 'Squirtle'}]
const copy = copy(original)

// now if we change a prop in the array like so:
copy[0].name = 'Wartortle'
copy.push({name: 'Charmander'}) // new item

// then the original array will still be the same:
(original[0].name === 'Squirtle')
(original[1] === undefined)

Source code

The source code is literally just these lines. Most of the magic comes from the isPlainObject function from the is-what library.

import { isPlainObject } from 'is-what'

export default function copy (target) {
  if (isArray(target)) return target.map(i => copy(i))
  if (!isPlainObject(target)) return target
  return Object.keys(target)
    .reduce((carry, key) => {
      const val = target[key]
      carry[key] = copy(val)
      return carry
    }, {})
}