arr-mutations
v0.1.2
Published
Calculate all mutation operations between two arrays. Supports a generic equals predicate function.
Downloads
4
Maintainers
Readme
Array mutations
Calculate all mutation operations between two arrays. Supports a generic equals predicate function.
Install
npm install arr-mutations
Usage
var mutations = require('arr-mutations');
mutations([1, 2], [2, 3]);
//=> [{type: 'add', item: 3}, {type: 'remove', item: 1}]
mutations([2, 2, 2], [2, 2]);
//=> [{type: 'remove', item: 2}]
mutations([2, 2, 3, 2], [2, 3, 3, 2]);
//=> [{type: 'add', item: 3}, {type: 'remove', item: 2}]
// Items are matched in order from the new array, consider this example:
var first = [{id: 1, name: 'a'}, {id: 1, name: 'b'}, {id: 1, name: 'c'}];
var second = [{id: 1, name: 'aa'}, {id: 1, text: 'bb'}];
mutations(first, second, {
equals: function(a, b) { return a.id === b.id; }
});
//=> [
// {type: 'change', old: {id: 1, name: 'a'}, item: {id: 1, name: 'aa'}},
// {type: 'change', old: {id: 1, name: 'b'}, item: {id: 1, text: 'bb'}},
// {type: 'remove', item: {id: 1, name: 'c'}}
// ]
var first = [{id: 1, text: 'one'}, {id: 2, text: 'two'}];
var second = [{id: 2, text: 'another'}, {id: 3, text: 'three'}];
mutations(first, second, {
equals: function(a, b) { return a.id === b.id; }
});
//=> [
// {type: 'add', item: {id: 3, text: 'three'}},
// {type: 'change', old: {id: 2, text: 'two'}, item: {id: 2, text: 'another'}},
// {type: 'remove', item: {id: 1, text: 'one'}}
// ]
API
mutations(old, new, [options])
Returns an array of mutation operations which are needed to convert array old
to new
.
When detecting if an item has changed, the items from new array are scanned
from left to right and the first item passing options.equals
check, will be
considered as the new version of the original item. If that new item also
matches options.deepEquals
, it will be listed as a changed item.
Returned mutation operations are sorted by type.
old
Required
Type: array
Original array of items.
new
Required
Type: array
New array of items.
options
Type: object
options.equals
Type: function
Default: function equals(a, b) { return a === b; }
Equality function. Should return true if a
and b
items are considered
as the same entity. Entity means e.g. single user with id: 1.
If you have e.g. an array of users, this function answers to: is a
the same user as b
?
options.deepEquals
Type: function
Default: function deepEquals(a1, a2) { return _.isEqual(a1, a2); }
Deep equality function. Should return true if a1
is not equal to a2
.
Used to detect if an entity has changed.
If you have e.g. an array of users, this function answers to:
is a2
a changed version a1
?
License
MIT