hoser v0.0.5

Hoser.js

Hoser.js is a small JavaScript library (< 4kb minified) for creating observable data objects whose attributes can be lexically scoped.

API Reference

Creating a new instance

Create a new instance in hoser by wrapping an object in hoser.

var instance = hoser({ value: 'value', object: { deepValue: 'deepValue' } });

get

You can retreive any value by calling #get on a hoser instance.

var instance = hoser({ key: 'value', object: { deepKey: 'deepValue' } });

instance.get('key');
// => 'value'

instance.get('object');
// => { deepKey: 'deepValue' }

instance.get('object.deepKey');
// => 'deepValue'

set

You can set any value by calling #set on a hoser instance. This also works for arbitrary levels of nesting.

var instance = hoser({ key: 'value', object: { deepKey: 'deepValue' } });

instance.set('key', 'otherValue');
// => true

instance.set('object.deepKey', 'otherDeepValue');
// => true

instance.get('key');
// => 'otherValue'

instance.get('object.deepKey');
// => 'otherDeepValue'

watch

You can observe changes in a hoser instance by calling #watch with a callback. You cannot observe values that have not yet been defined.

var instance = hoser({ key: 'value', object: { deepKey: 'deepValue' } });

instance.watch('object.deepKey', function (value) {
  // value is the new value of object.deepKey
});

instance.watch('object', function (value) {
  // value is the new value of object
});

instance.set('object.deepKey', 'otherDeepValue');
// => true
// both callbacks will be executed

unwatch

You can remove watchers on a hoser instance by calling #unwatch.

var instance = hoser({ key: 'value', object: { deepKey: 'deepValue' } });
var someCallback = function () { /* ... */ };

instance.watch('key', someCallback);

instnace.unwatch('key', someCallback);

scope

Creating new scopes of your data can be done with #scope. When an instance is scoped, a new child object is returned which holds a reference to all previous ancestors. This means that if an attribute is set on a parent object, it will immediately be available to all of it's children; however, the inverse is not true when an attribute is set on a child object; that is, the new attribute is scoped to the child.

var instance = hoser({ key: 'value', object: { deepKey: 'deepValue' } });
var scoped = instance.scope();

scoped.get('key');
// => 'value'

instance.set('key', 'otherValue');

scoped.get('key');
// => 'otherValue'

scoped.set('otherKey', 123);

instance.get('otherKey');
// => undefined

Observing changes is also determined by the scope where the attribute was created.

var instance = hoser({ key: 'value', object: { deepKey: 'deepValue' } });
var scoped = instance.scope();

scoped.watch('key', function () {
  alert('this is an alert!');
});

instance.watch('key', function () {
  console.log('this is a log!');
});

instance.set('key', 'otherValue');
// => true
// alert will appear and console will log

scoped.set('key', 'yetAnotherValue');
// => true
// alert will appear and console will log