ward

Ward
====

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

Installation
------------

``bash
npm install ward
`

Usage
-----

`js
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
---

$3

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

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

$3

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.

`js
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();
`

$3

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

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

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

$3

Return the count of an object’s enumerable properties.

`js
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.