deep-clone-map

Deep Clone Map

Install | API | Usage | Tests | TypeScript

Deep Clone Map maps any object or array and transforms its primitive values, always returning a new instance, it can map deeply nested values in complex objects and arrays. Think of it as Array.prototype.map() on steriods, capable to map objects and deeply nested structure.

Differences between other deep map libraries

Most existing libraries do not map values in arrays, and in nested complex structures combining both objects and arrays. Typescript support is also one of the lacking features of most existing libraries.

Size

Deep Clone Map size is really tiny only 242 bytes minified and gzipped.

Performance

Deep Clone Map has a performance on par with other popular alternatives, but it offers more: TypeScript support and mapping complex structures with nested arrays.

Some benchmarks running on MacOS Catalina and Node v12.13.0 using benchmark library:

deep-clone-map	1,433,245 ops/sec ±0.53% (92 runs sampled)
deep-map	1,131,833 ops/sec ±0.66% (88 runs sampled)
map-obj	1,344,719 ops/sec ±1.25% (87 runs sampled)

Install

npm:

npm install --save deep-clone-map

yarn:

yarn add deep-clone-map

API

deepCloneMap(any, mapFn?)

Argument	Type	Description
arg0	any	Any object, array or primitive whose values should be resolved.
arg1?	(arg0: any, key: string) => any	Callback used to transform primitive values, this parameter is optional if skipped, the object/array will be just deeply cloned instead. Arguments: value The existing primitive value to be transformed. key The key of the value that will be transformed, it will always be a string, in case of nested arrays and objects expect something like: key1.key2.0.1.key3 The return value is the maped value at the exact position determined by the key.

Returns

Returns a new deeply cloned version of the input argument value, it will maintain the exact same structure as the original object or array. In case if a primitive is provided as the first argument it will map its value to a new one, based on the callback function.

Usage

Import Deep Clone Map package

import deepCloneMap from 'deep-clone-map'

For es5 support:

import deepCloneMap from 'deep-clone-map/es5'

Deeply clone an object:

const obj = {
  a: 1,
  b: 2,
  c: {
    a: 1,
    b: 2,
    c: [1, 2, 3],
  },
}

const newObj = deepCloneMap(obj)
// newObj !== obj && newObj.c !== obj.c && newObj.c.c !== obj.c.c

Deeply clone an array:

const arr = [
  [1, 2, 3],
  [
    {
      a: 1,
      b: 2,
      c: [1, 2, 3],
    },
  ],
]

const newArr = deepCloneMap(arr)
// newArr !== arr && newArr[1] !== arr[1] && newArr[1].c !== arr[1].c

Deeply map an object

const obj = {
  a: 1,
  b: 2,
  c: {
    a: 1,
    b: 2,
    c: [1, 2, 3],
  },
}

const newObj = deepCloneMap(obj, val => val + 1)
/*
    newObj => {
      a: 2,
      b: 3,
      c: {
        a: 2,
        b: 3,
        c: [2, 4, 4]
      }
    }
  */

Deeply custom map an object based on the key

const obj = {
  a: 1,
  b: 2,
  c: {
    a: 1,
    b: 2,
    c: [1, 2, 3],
  },
}

const newObj = deepCloneMap(obj, (val, key) => {
  switch (key) {
    case 'a':
      return 10
    case 'c.b':
      return 20
    case 'c.c[1]':
      return 20
    default:
      return val
  }
})
/*
    newObj => {
      a: 10,
      b: 2,
      c: {
        a: 1,
        b: 20,
        c: [1, 20, 3]
      }
    }
  */

Deeply map a nested array

const arr = [
  [1, 2, 3],
  [
    {
      a: 1,
      b: [1, 2, 3],
      c: [
        {
          a: 1,
          b: [1, 2, 3],
        },
      ],
    },
  ],
]

const newArr = deepCloneMap(arr, val => val + 1)
/*
    newArr => [
      [2, 3, 4],
      [
        {
          a: 2,
          b: [2, 3, 4],
          c: [
            {
              a: 2,
              b: [2, 3, 4]
            }
          ]
        }
      ]
    ]
  */

Tests

In order to run the provided unit tests:

  # yarn
  yarn test

  # npm
  npm test

Typescript

The packages comes with typescript declarations included in the package, you only need to import the module normally.

By default the types are infered from the input argument:

const obj = {
  a: 1,
  b: 2,
}

const newObj = deepCloneMap(obj)
/*
    newObj => {
      a: number
      b: number
    }
  */

In some cases you will need to provide a different type to the deepCloneMap function, for example in instances when you map the primitive values to a different type:

  const obj = {
    a: 1,
    b: 2
  }

  const newObj = deepCloneMap<{ a: string; b: string }>(obj, val => String(val))