Cloning and merging - DarthJDG/Mangler.js GitHub Wiki

The .clone() and .merge() functions can be used to create deep or shallow copies of objects, respectively. .merge() can also copy object properties from one object to another.

Deep copy

Sometimes you have to do destructive operations on your data, such as adding/removing properties, wrapping/unwrapping objects, etc. Most Mangler.js transformation functions operate on the objects and arrays themselves, but what if you need to keep the original data structure as well?

To solve this problem, you can use .clone() to create a deep copy of your nested data and do all operations on the cloned objects without touching the originals:

object = {
	array: [
		{ foo: 'bar' }
	]
};

copy = Mangler.clone(object);

copy.array[0].foo = 'new value';

// The following will output the original 'bar' value
console.log(object.array[0].foo);

By default, Mangler.js knows how to clone object literals, arrays, mangler objects and Date objects with unlimited levels of nesting. If however it encounters an object instance of an unknown type, it will copy its reference directly, pointing to the original object. To learn how to make Mangler.js clone other object types, read the advanced topic of Type handling.

To add support for less common native types, such as typed arrays, look at the Mangler-natives module.

Shallow copy

To make a shallow copy of object literals, simply call the .merge() function with an empty object as the first parameter:

object = {
	foo: 'bar',
	o: { b: 1 },
	a: [1, 2, 3],
};

copy = Mangler.merge({}, object);

You can freely add/remove and re-assign properties of the copy object without touching the original, but going any deeper will affect object:

// Re-assign property without changing the original
copy.foo = 'baz';

// Add/remove properties without changing the original
copy.newprop = 'foobar';
delete copy.foo;

// Going deeper WILL change the original data
copy.o.b = 2;
copy.a.push(4);

Merging object properties

The .merge() function can also be used to copy object properties from one object to another:

Mangler.merge(destination, source);

Both the destination and source parameters can be either an object or an array of objects. Depending on the type of the parameters, it will do one of the following:

• merge(object, object) will copy object properties from source to destination.
• merge(object, array) will copy object properties from all source objects to destination in order.
• merge(array, object) will copy object properties from source into all destination objects
• merge(array, array) will copy object properties from all source objects into destination objects with matching array indices. If source has more items, extra items will be ignored. If destination has more items, extra items are unchanged.

object = {
	one: 1
};

// Add extra property
Mangler.merge(object, { two: 2 });

// Merge multiple objects
Mangler.merge(object, [{ one: -1 }, { three: 3 }]);

/*
object = {
	one: -1,
	two: 2,
	three: 3
}
*/

The source parameter always takes priority, existing properties in destination will be overwritten. In all cases, the function returns the destination parameter.