object-observer
provides an observation of a changes performed on an object graph (array being a subtype of it).
Main aspects:
- implementation relies on Proxy mechanism (specifically, revokable Proxy)
- observation is 'deep', yielding changes from a sub-graphs too
- changes delivered in a synchronous way
- changes delivered always as an array, in order to have unified callback API signature supporting also bulk changes delivery in a single call back
- original objects are cloned while turned into
Observable
s - arrays:
- generic object-like mutations supported
- intrinsic
Array
mutation methods supported:pop
,push
,shift
,unshift
,reverse
,sort
,fill
,splice
- massive mutations delivered in a single callback, usually having an array of an atomic changes
- intrinsic mutation methods of
Map
,WeakMap
,Set
,WeakSet
(set
,delete
) etc are not observed (see this issue for more details) - following host objects are not observed, but left as they are (the list will be updated upon changes):
Date
,Blob
,Number
,String
,Boolean
,Error
,SyntaxError
,TypeError
,URIError
,Function
,Promise
,RegExp
- Changes, probably based on my own consumption of this library in data-tier module (GitHub, NPM) and/or community feedback. Status: in progress
- Consider adding support for a Symbol defined object properties. Status: in progress
- Prepare the library to be consumed as ES module (via
import
API)
-
0.2.6
- Fixed cloning logic to allow observability for host objects like
DOMStringMap
and alike (gave up on calling the original object's constructor) - Documentation fixes
- Fixed cloning logic to allow observability for host objects like
-
0.2.5
- Fix: issue #8 - incorrect
oldValue
supplied inupdate
/delete
events when handling inner object/s sub-graph
- Fix: issue #8 - incorrect
-
0.2.4
- Minor syntactic fixes
-
0.2.3
-
0.2.2
- Fix: Switched internal implementation to use
Map
instead ofWeakMap
object, due to this issue in Edge browsers. Once the Edge will be fixed, I'll switch back to 'weak' maps.
- Fix: Switched internal implementation to use
-
0.2.1
- Bug fix: implemented 'non-observable' object types functionality for the ones, that their observation is meaningless (or even harmful and bug causing); 'non-observables' are:
Date
,Blob
,Number
,String
,Boolean
,Error
,SyntaxError
,TypeError
,URIError
,Function
,Promise
,RegExp
(see this issue for more details)
- Bug fix: implemented 'non-observable' object types functionality for the ones, that their observation is meaningless (or even harmful and bug causing); 'non-observables' are:
-
0.2.0
- Tech: moved proxy implementation to revokable
- Tech: refactored algorithm of sub-graphs indexing and management; speed and memory improved, arrays massive changes improved significantly
- API: added revokability to an Observable
- 'detached' (
pop
,shift
,splice
actions on arrays) and replaced (simple update on objects and arrays,fill
on arrays) observed sub-graphs are being revoked as well - results of 'detach' actions (
pop
,shift
,splice
) are turned back to the plain object (yet having all of the changes done to the observable) when returned by APIs
For a short preview you may want to play with this JSFiddle.
You have 2 ways to load the library: into a 'window' global scope, or a custom scope provided by you.
- Simple a reference (script tag) to the
object-observer.min.js
/object-observer.js
in yourHTML
will load it into the global scope:
<script src="object-observer.min.js"></script>
<script>
let person = { name: 'Uriya', age: 8 },
observablePerson;
observablePerson = Observable.from(person);
</script>
- Following loader exemplifies how to load the library into a custom scope (add error handling as appropriate):
let customNamespace = {},
person = { name: 'Nava', age: 6 },
observablePerson;
fetch('object-observer.min.js').then(function (response) {
if (response.status === 200) {
response.text().then(function (code) {
Function(code).call(customNamespace);
// the below code is an example of consumption, locate it in your app lifecycle/flow as appropriate
observablePerson = customNamespace.Observable.from(person);
});
}
});
-
from
- receives a non-null object and returns its clone, decorated with anObservable
interface:let person = { name: 'Aya', age: '1' }, observablePerson; observablePerson = Observable.from(person); ...
Clone is deep, having cloned all of the object's sub-graph. Cloning performed by means of
Object.assign
, therefore only own enumerables are going to be observed.
-
observe
- receives a function, which will be added to the list of observers subscribed for a changes of this observable:function personUIObserver(changes) { changes.forEach(change => { console.log(change.type); console.log(change.path); console.log(change.value); console.log(change.oldValue); }); } ... observablePerson = Observable.from(person); observablePerson.observe(personUIObserver);
Changes delivered always as an array. Changes MAY NOT be null. Changes MAY be an empty array. Each change is a defined, non-null object, having:
type
- one of the following: 'insert', 'update', 'delete', 'shuffle' or 'reverse'path
- path to the changed property represented as an Array of nodes (see examples below)value
- new value; not available in 'delete', 'shuffle' and 'reverse' changesoldValue
- old value; not available in 'insert', 'shuffle' or 'reverse' changes
-
unobserve
- 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:... observablePerson.unobserve(personUIObserver); ... observablePerson.unobserve(); ...
-
revoke
- parameterless. All of the proxies along the observed graph will be revoked and thus become unusable.observe
andunobserve
methods will mimic the revokedProxy
behaviour and throwTypeError
if used on the revokedObservable
. Subsequentrevoke
invokations will have no effect:... observablePerson.revoke(); ...
let order = { type: 'book', pid: 102, ammount: 5, remark: 'remove me' },
observableOrder;
observableOrder = Observable.from(order);
observableOrder.observe(changes => {
changes.forEach(change => {
console.log(change);
});
});
observableOrder.ammount = 7; // { type: 'update', path: ['ammount'], value: 7, oldValue: 5 }
observableOrder.address = { // { type: "insert", path: ['address'], value: { ... } }
street: 'Str 75',
apt: 29
};
observableOrder.address.apt = 30; // { type: "update", path: ['address','apt'], value: 30, oldValue: 29 }
delete observableOrder.remark; // { type: "delete", path: ['remark'], oldValue: 'remove me' }
let a = [ 1, 2, 3, 4, 5],
observableA;
observableA = Observable.from(a);
observableA.observe(changes => {
changes.forEach(change => {
console.log(change);
});
});
// observableA = [ 1, 2, 3, 4, 5 ]
observableA.pop(); // { type: 'delete', path: [4], oldValue: 5 }
// observableA = [ 1, 2, 3, 4 ]
// the following operation will cause a single callback to the observer with an array of 2 changes in it)
observableA.push('a', 'b'); // { type: 'insert', path: [4], value: 'a' }
// { type: 'insert', path: [5], value: 'b' }
// observableA = [1, 2, 3, 4, 'a', 'b']
observableA.shift(); // { type: 'delete', path: [0], oldValue: 1 }
// observableA = [ 2, 3, 4, 'a', 'b' ]
// the following operation will cause a single callback to the observer with an array of 2 changes in it)
observableA.unshift('x', 'y'); // { type: 'insert', path: [0], value: 'x' }
// { type: 'insert', path: [1], value: 'y' }
// observableA = [ 2, 3, 4, 'a', 'b' ]
observableA.reverse(); // { type: 'reverse' }
// observableA = [ 'b', 'a', 4, 3, 2 ]
observableA.sort(); // { type: 'shuffle' }
// observableA = [ 2, 3, 4, 'a', 'b' ]
observableA.fill(0, 0, 1); // { type: 'update', path: [0], value: 0, oldValue: 2 }
// observableA = [ 0, 3, 4, 'a', 'b' ]
// the following operation will cause a single callback to the observer with an array of 2 changes in it)
observableA.splice(0, 1, 'x', 'y'); // { type: 'update', path: [0], value: 'x', oldValue: 0 }
// { type: 'insert', path: [1], value: 'y' }
Arrays notes:
- Some of array operations are effectively moving/reindexing the whole array (shift, unshift, splice, reverse, sort). In cases of massive changes touching presumably the whole array I took a pessimistic approach with a special non-detailed events: 'reverse' for
reverse
, 'shuffle' forsort
. The rest of these methods I'm handling in an optimistic way delivering the changes that are directly related to the method invokation, while leaving out the implicit outcomes like reindexing of the rest of the Array.