Ward

A library for effortlessly managing deeply-nested immutable data structures in node and the browser.

Installation

npm install ward

Usage

var ward = require('ward');
var data = ward({
  user: {
    firstName: 'John',
    friends: ['Mike', 'Alex']
  }
});

var observer = ward.observe(data, function (newData) {
  // When something changes in the data structure,
  // this gets called with the new data structure.
  data = newData;
});

data.user.firstName.get(); // -> 'John'
data.user.friends.get(); // -> ['Mike', 'Alex']

data.user.firstName.set('Jack');
data.user.firstName.get(); // -> 'Jack'

data.user.friends[0].set('Josh');
data.user.friends.get(); // -> ['Josh', 'Alex']

// Stop observing changes to data.
observer.dispose();

API

ward(value)

Create a ward wrapper object around any value. Ward will recursively wrap plain objects and arrays. All ward object are immutable.

var data = ward({a: 1});

ward.observe(object, observer)

Observe ward object for changes, triggering observer function on any change to object’s value or nested values, passing in the new value wrapped in a ward object.

var students = ward({
  groupA: ['Alex', 'Chris', 'Jones'],
  groupB: ['Michael', 'Donna']
});

var observer1 = ward.observe(students, function (newStudents) {
  newStudents.groupA[0].get() == 'Rob';
  students.groupA[0].get() == 'Alex';
});

var observer2 = ward.observe(students.groupA, function (newGroupA) {
  newGroupA[0].get() == 'Rob';
});

// This will trigger the above observers.
students.groupA[0].get('Rob');

observer1.dispose();
observer2.dispose();

ward.keys(object)

Given an object returned by ward(value), return an array of all enumerable properties of value.

var fruits = ward({red: 'apple', yellow: 'banana'});
ward.keys(fruits); // -> 'red', 'yellow'

var units = ward(['px', 'em', 'rem']);
ward.keys(units); // -> '0', '1', '2'

ward.count(object)

Return the count of an object’s enumerable properties.

var fruits = ward({red: 'apple', yellow: 'banana'});
ward.count(fruits); // -> 2

var units = ward(['px', 'em', 'rem']);
ward.count(units); // -> 3

ward.count(units) === ward.keys(units).length // -> true

IE8 Support

For Ward to work on IE8, make sure to include ES5 shim and sham.