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 parameter MUST contain ONLY one of the properties below, no 'unknown' properties allowed.

In order to fail-fast and prevent unexpected mess down the hill, incorrect observation options will throw.

• path - non-empty string; specific path to observe, only a changes of this exact path will be notified; details here

• pathsOf - string, MAY be empty; direct properties of the specified path will be notified; details here

• pathsFrom - non-empty string, any changes from the specified path and deeper will be 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)