@ayogohealth/object-assign-deep

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.