Observable
APIObservable
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
providesObservable
top level object as a named import:import { Observable } from 'object-observer.js'
Observable.
from(input[, options])
Observable
interface
Observable
instances tooasync
: 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)
true
if it stands for implementation of Observable
API as it is defined hereObservable.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
)Change
objects; each change is a defined, non-null object, see Change
definition belowfunction 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
)Observable.unobserve(observablePerson, personUIObserver);
// or
Observable.unobserve(observablePerson);
// same applies to the nested
Observable.unobserve(observableAddress);
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 propertiestype
- one of the following: insert
, update
, delete
, shuffle
or reverse
path
- path to the changed property represented as an Array of nodesvalue
- new value; undefined
in delete
, shuffle
and reverse
changesoldValue
- old value; undefined
in insert
, shuffle
or reverse
changesobject
- an immediate subject of change, property of which has been changed (ES6 module distro ONLY)