Skip to content
Like Object.assign(), but deeper.
Branch: master
Clone or download
Latest commit 2f9608d Apr 4, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
.eslintrc.js
.gitignore
README.md
objectAssignDeep.js
package-lock.json
package.json

README.md

Object-Assign-Deep

Like Object.assign() but deeper. This module is the holy grail of simple object manipulation in JavaScript and it does not resort to using the JSON functions. If you need more power or fine-grained control please take a look at the Object-Extender module.

Breaking Changes in v0.3!

  • objectAssignDeep() now mutates the first argument in the same way Object.assign() does.
  • By default, arrays are now replaced instead of merged to preserve backwards compatibility with older versions of this module.

Caution! Danger of Death!

This module is to be used with PLAIN objects that contain primitive values ONLY. Every time you misuse this module a kitten dies.. yes you're a kitten killer.

Do not use this module if:

  • Your objects are (or contain) native objects such as Date (nested Array is fine).
  • Your objects contain circular references (you'll cause a stack overflow).
  • Your objects are instances of some class you've written.
  • You are concerned with prototype chains, property descriptors, unenumerable properties, and any other advanced uses.

If you need to do something fancy like the above you'll need to write a custom solution for your use case.

Quick Start

You can merge plain objects or clone them:

const objectAssignDeep = require(`object-assign-deep`);

const mergedObjects = objectAssignDeep(target, object1, object2, ...objectN);

const clonedObject = objectAssignDeep({}, originalObject);

Simples!

Full Example

See the ./examples directory for a few examples, including one example case that demonstrates why you can't get clever with object cloning.

const objectAssignDeep = require(`object-assign-deep`);

const objectA = {
	prop1: `Hello`,
	prop2: `World`,
	nested: {
		bool: true,
		super: 123,
		still: `here!`,
	},
	array1: [1, 2, 3],
	array2: [4, 5, 6],
};

const objectB = {
	prop2: `Universe`,
	name: `Josh`,
	nested: {
		bool: false,
	},
	array1: null,
};

const objectC = {
	location: `United Kingdom`,
	name: `Bob`,
	nested: {
		super: 999,
	},
	array2: [100, 101, 102],
};

const result = objectAssignDeep(objectA, objectB, objectC);

console.log(`Result:`, result);

/*
*   {
*     prop1: 'Hello',
*     prop2: 'Universe',
*     nested: { bool: false, super: 999, still: 'here!' },
*     array1: null,
*     array2: [100, 101, 102],
*     name: 'Bob',
*     location: 'United Kingdom'
*   }
*/

API Overview

objectAssignDeep(target, object1, object2, ...objectN);

Merges all the objects together mutating the target in the process and returning the result.

objectAssignDeep.noMutate(object1, object2, ...objectN);

Merges all the objects together without mutating any of them and returning the entirely new object.

objectAssignDeep.withOptions(target, objects, options);

Takes a target, an array of objects to merge in, and an options object which can be used to change the behaviour of the function. The available options are:

Option Default Value Description
arrayBehaviour "replace" By default arrays in later objects will overwrite earlier values, but you can set this to "merge" if you want to concatenate the arrays instead.

If you need more customisation options please take a look at the Object-Extender module which builds upon Object-Assign-Deep.

You can’t perform that action at this time.