This contains a set of custom mergers for the seamless-immutable library. It's mainly a showcase for what can be done with custom mergers, but the mergers are hopefully useful on their own.
Any of the following:
npm install seamless-immutable-mergers
bower install seamless-immutable-mergers
- download seamless-immutable-mergers.js
Make sure that you have seamless-immutable loaded and in scope before using seamless-immutable-mergers.
Note: If you are using requirejs or similar then make sure that seamless-immutable is exported as seamless-immutable
so seamless-immutable-mergers can require the dependency.
If you have an immutable object that you want to merge with another object then you do the following in seamless-immutable:
var result = immutableObject.merge(otherObject);
All properties in otherObject
will be added to immutableObject
overwriting any duplicates. Properties in
immutableObject
that aren't in otherObject
will be left as is.
You can also pass in configuration to the merge process. For example using the deep option:
var result = immutableObject.merge(otherObject, {deep: true});
This will recursively merge all properties that are objects and exists in both the source and target instead of replacing them.
You can also pass in a custom merger that overrides the normal merge process. For example:
var result = immutableObject.merge(otherObject, {merger: myCustomMerger});
A merger is a function that takes the property for the current object, the property for the other object and optionally the config object. Example:
function myCustomMerger(current, other, config) {
return undefined;
}
If the merge returns undefined
then the merge continues like normal. If the merger returns something else then that result is used instead. So checks can be added so a custom merger only operates on specific input, like arrays.
This is a simple merger that instead of replacing an array with another concats them together. Example:
var immutable = require("seamless-immutable");
var mergers = reuqire("seamless-immutable-mergers");
var immutableObject = immutable({
title: "one",
items: [1, 2]
});
var otherObject = {
title: "two",
items: [3, 4]
};
var result = immutableObject.merge(otherObject, {merger: mergers.concatArrayMerger});
The result will be:
{
title: "two",
items: [1, 2, 3, 4]
}
This is a merger that operates on arrays and compares the contents of the arrays. If both arrays contain the same elements (it checks each element using ===
) it will not replace the current array with the update and thus not flag that as a change. This means that if there are no other changes and the arrays contain the same elements the result of the merge will be the same object as original. Example:
var data = {a: [1, 2]};
var immutableObject = immutable(data);
var data2 = {a: [1, 2]};
var result = immutableObject.merge(data2, {merger: mergers.equalityArrayMerger});
result === immutableObject
// true
This can be useful for change detection, like in React's shouldComponentUpdate
.
This is a simple merger that instead of replacing an array with another keeps the original one. Example:
var immutable = require("seamless-immutable");
var mergers = reuqire("seamless-immutable-mergers");
var immutableObject = immutable({
title: "one",
items: [1, 2]
});
var otherObject = {
title: "two",
items: [3, 4]
};
var result = immutableObject.merge(otherObject, {merger: mergers.ignoreArrayMerger});
The result will be:
{
title: "two",
items: [1, 2]
}
This is a merger that operates on arrays that contains objects with specified ids. It tries to merge each object in the target array with the object with the same id from the source array. Example:
var immutable = require("seamless-immutable");
var mergers = reuqire("seamless-immutable-mergers");
var immutableObject = immutable({
array: [
{
id: 10,
status: "ok",
content: "text"
}
]
});
var otherObject = {
array: [
{
id: 10,
status: "fail"
},
{
id: 11,
status: "ok",
content: "media"
}
]
};
var mergeConfig = {
merger: mergers.updatingByIdArrayMerger,
mergerObjectIdentifier: "id"
};
var result = immutableObject.merge(otherObject, mergeConfig);
The result will be:
{
array: [
{
id: 10,
status: "fail",
content: "text"
},
{
id: 11,
status: "ok",
content: "media"
}
]
}
This merger requires that mergerObjectIdentifier
is set in the config with the name of the property that identifies the object.
It can be used to update and add to arrays using for example push from the server with only the updated data.
This merger will check both arrays and only do anything if both of them has an object with the specified identifier at position 0. It will then assume that the rest of the arrays only contains such objects.
It can also be used with the deep
configuration to do this recursively.
Updated to seamless-immutable 7.0.0 and bumped the major version to be in sync.
Updated to seamless-immutable 6.0.0 and bumped the major version to be in sync.
Updated to seamless-immutable 5.2.0.
Updated to seamless-immutable 5.0.0 and bumped the major version to be in sync. Also updated chai and mocha test dependencies to the latest versions.
Added ignoreArrayMerger, updated to seamless-immutable 4.0.2 and bumped the major version to be in sync.
Fixed a bug in updatingByIdArrayMerger where a merge with an empty array would wipe the content of the current array.
Updated to seamless-immutable 3.0.0 and bumped the major version to be in sync.
Started using the UMD pattern so the library will be easy to consume as a global or with requirejs (and not only node/browserify).
Added new merger: equalityArrayMerger.
Initial release.