merge-trackby

A small JavaScript library to recursively merge object and array hierarchies without replacing original objects, with support for reordering of objects in arrays tracking their identity according to a callback function. It is useful when you want to import new JSON data into already existing objects, keeping their classes and references to them. It is also useful when you have setters and you don’t want to redefine them and want them to be triggered for the changes.

Installation

npm i merge-trackby

or

<script src="merge-trackby.js"></script>

Usage

Merge b into a recursively tracking arrays by index:

merge(a, b);

And this will track objects on the first level by property, (in this case id), and on more deep levels by index:

merge(a, b, {trackBy: trackBy('id')});

Maximum depth, on which tracking by property should be used, can be specified using the second parameter, null means “any depth”:

merge(a, b, {trackBy: trackBy('id', 2)});
merge(a, b, {trackBy: trackBy('id', null)});

Custom tracking function can also be defined depending on depth, key, a, and b values:

merge(a, b, {trackBy: function (depth, key, a, b) {
	return function (obj) {
		return obj.id;
	};
}});

Caveats

• Any excessive target array elements are removed
• All excessive target object properties are retained
• Because it is mainly focused on merging JSON data, it doesn’t support circular references

Browser support

Requires Map if you specify trackBy function, but it can be polyfilled.

License

MIT.