array-tracker

array-tracker

Statefully tracks additions and deletions to an array. Works on arrays containing simple types or objects. With objects, you can track uniqueness of the whole object or of configured key(s).

Usage: Use 'require' to include the module

Create new instance of the array-tracker for every array you wish to track.

var tracker = new array-tracker();

Initialize array-tracker with a) initial state of the array b) optional : if the array is embedded in an object then pass the dot notation path to the array c) optional : if you wish to track uniqueness by key(s) then pass an array for the keys.

Initialization Examples

Intialize array-tracker with an array containing primitive JavaScript types

var arrayToTrack = [1,2,3];
tracker.initialize(arrayToTrack);

Intialize array-tracker with an array containing JavaScript objects

var arrayToTrack = [  {letter: 'a', number: 1},  {letter: 'b', number: 2},  {letter: 'c', number: 3}];
tracker.initialize(arrayToTrack);

Intialize array-tracker with an array containing JavaScript objects with a keyed Id.

var arrayToTrack = [  {letter: 'a', number: 1},  {letter: 'b', number: 2},  {letter: 'c', number: 3}];
tracker.initialize(arrayToTrack,['letter']);

Intialize array-tracker with an array containing an array embedded in a JavaScript object.

var arrayToTrack = { test: true, deep: { deeper: { deepest: { arr: [
                                {id: 1, name: 'first', age: 10},
                                {id: 2, name: 'second', age: 10},
                                {id: 3, name: 'third', age: 14}
                            ]  }}}};

tracker.initialize(arrayToTrack,'deep.deeper.deepest.arr');

Intialize array-tracker with an array containing an array embedded in a JavaScript object and use keyed Ids.

var arrayToTrack = { test: true, deep: { deeper: { deepest: { arr: [
                                {id: 1, name: 'first', age: 10},
                                {id: 2, name: 'second', age: 10},
                                {id: 3, name: 'third', age: 14}
                            ]  }}}};

tracker.initialize(arrayToTrack,'deep.deeper.deepest.arr', ['id','name']);

Tracking changes to the array involves passing an array to the "evaluate" function of array-tracker. You can then pass a callback to one of 4 chainable methods: "changed", "unchanged", "itemAdded", "itemDeleted". Depending on the state of the array passed to "evaluate" one or more of the callbacks will fire. The "changed" and "unchanged" callbacks are passed the original array. The "itemAdded" callback is passed an array of the items added. The "itemDeleted" callback is passed an array of the items deleted.

Evaluation Examples

Simply tracking changes to an array

    tracker.evaluate(arrayToTrack)
       .unchanged(function (arr) {

        })
       .changed(function (arr) {
          changedResult = arr;
       });

Tracking all changes to an array

     tracker.evaluate(arrayToTrack)
            .unchanged(function (arr) {
                //nothing changed
             })
            .changed(function (arr) {
               //the array is different
            })
            .itemAdded(function (arr) {
               //items added
            })
            .itemDeleted(function (arr) {
               //items deleted
            });