Home

Awesome

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!

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:

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:

OptionDefault ValueDescription
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.