observable.md

Observable API

Observable API provides the whole life cycle of object observation functionality.

Additionally, this API defines the Change object, list of which being a parameter of an observer callback function.

object-observer provides Observable top level object as a named import: import { Observable } from 'object-observer.js'

Static methods

Observable.from(input[, options])

• input is a non-null object; returns input's clone, decorated with an Observable interface

  • clone is deep
  • nested objects are turned into Observable instances too
  • cloning performed only on own enumerable properties, leaving a possibility to 'hide' some data from observation

• options is an object, optional; may include any of these:

  • async: boolean, defaults to false, controls the sync/async fashion of changes delivery; details here

    This flag will affect all observers of this Observable

let person = {
        name: 'Aya',
        age: '1',
        address: {
            city: 'city',
            street: 'street'
        }
    },
    observablePerson;

observablePerson = Observable.from(person);

Observable.isObservable(input)

• input is a non-null object; returns true if it stands for implementation of Observable API as it is defined here

Observable.isObservable({});                            //  false
Observable.isObservable(observablePerson);              //  true
Observable.isObservable(observablePerson.address);      //  true

Observable.observe(observable, callback[, options])

• observable MUST be an instance of Observable (see from)
• callback is a function, which will be added to the list of observers subscribed for a changes of this observable; changes delivered always as a never-null-nor-empty array of Change objects; each change is a defined, non-null object, see Change definition below
• options is an object, optional

function personUIObserver(changes) {
    changes.forEach(change => {
        console.log(change.type);
        console.log(change.path);
        console.log(change.value);
        console.log(change.oldValue);
    });
}
...
//  following the observablePerson example from above
Observable.observe(observablePerson, personUIObserver, options);    //  options is optional

const observableAddress = observablePerson.address;
Observable.observe(observableAddress, personUIObserver);            //  nested objects are observables too

observablePerson.address = {};                          			//  see below

Attention! Observation set on the nested objects, like address in the example above, 'sticks' to that object. So if one replaces the nested object of the observable graph (see the last line of code above), observer callbacks are NOT moved to the new object, they stick to the old one and continue to live there - think of detaching/replacing a sub-graph from the parent.

Observable.unobserve([callback[, callback]+])

• observable MUST be an instance of Observable (see from)
• receives a function/s which previously was/were registered as an observer/s and removes it/them. If no arguments passed, all observers will be removed.

Observable.unobserve(observablePerson, personUIObserver);
//  or
Observable.unobserve(observablePerson);

//  same applies to the nested
Observable.unobserve(observableAddress);

Observation options

If/When provided, options MUST be an object. Unknown properties are rejected — incorrect observation options throw, to fail fast.

• filters - non-empty array of Filter instances; changes that survive all filters (logical AND) are delivered to the observer; details here

Change instance properties

• type - one of the following: insert, update, delete, shuffle or reverse
• path - path to the changed property represented as an Array of nodes
• value - new value; undefined in delete, shuffle and reverse changes
• oldValue - old value; undefined in insert, shuffle or reverse changes
• object - an immediate subject of change, property of which has been changed (ES6 module distro ONLY)