tjstebbing/fickle

Fickle objects, with multiple observer contexts.

Fickle objects, with multiple observer contexts.

Fickle is intended for situations where there are multiple contexts for receiving notifications about changes, with different requirements such as time-base batch processing, different change-set formats etc.

Fickle has two very simple concepts:

Models

A model is an object with setters and getters:

var ink = fickle({
    name : 'shadow',
    hue : '#333',
    ml : 200,
    stats : { views : 0 },
    tags : ['monochrome'] });

// single value set
ink.set('name', 'smoke');

// multi value set
ink.set({'stats.views' : 1, 'ml' : 80});

// increment views by 2
ink.increment('stats.views', 2);

// decrement views by 1
ink.decrement('stats.views', 1);

// get stats
ink.get('stats') // -> { views : 2 }

// push a value onto an array
ink.push('tags', 'special');
ink.get('tags'); // -> ['monochrome', 'special']

// insert a value at a given index of an array
ink.insert('tags', 'dark', 0);
ink.get('tags'); // -> ['dark', 'monochrome', 'special']

// 'empty' a value: reduces a string to '', an object to {}, an array to []
ink.empty('tags');
ink.get('tags'); // -> []

// delete a value
ink.del('stats.views') 
ink.get('stats'); // -> {}

Contexts

In Fickle, models are observed through an 'Observer Context'. Contexts determine the manner in which observers are updated, and provide methods for registering observer functions.

var ink = fickle({
    name : 'shadow',
    hue : '#333',
    ml : 200,
    stats : { views : 0 },
    tags : ['monochrome'] });

// A default context updates as soon as changes come in, this is great for
// connecting to view logic.
var viewCtx = fickle.context(); 

// A batching context is useful when updating the server, this one updates
// observers at a maximum frequency of 5 seconds
serverCtx = fickle.context({
    cacheTime : 5000
});

// observe a specific key path on an object with 'on'
viewCtx.on(ink, 'name', function(obj, name) { 
    console.log("name changed to", name); 
});

// observe any changes
serverCtx.onAny(ink, function(obj, changes) { 
    console.log("saving fields:", changes); 
    //save changes to server ...
});

// set and get some values..
ink.set('name', 'slate');
ink.set({name : 'silver', hue : '#777'});
ink.get("ml");

// output:
name changed to slate
name changed to silver
saving fields: {'name' : 'silver', 'hue' : '#777'}
200

// pausing a context stops it receiving any updates
viewCtx.pause(true);
viewCtx.pause(false);

// clearing a context unbinds observers
viewCtx.clear(ink);
serverCtx.clearAll();