object-observer

Summary

Observation of a changes performed on an object (array being a subtype of it) is a MUST HAVE facility in JavaScript world.

Native facility would be the best solution for this, since it may provide non-intrusive observation wihtout 'touching' the original objects, but seems like ES is not yet mature enough for that.

Present library attempts to provide this functionality in a most clean and performant way. 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, thus not being affected; this adds one more step to the normal usage flow:
  • first, create observable clone from the specified object
  • second, register observers on the observable (not on the original object)
• Arrays:
  • generic object-like mutations supported
  • intrinsic mutation methods supported: pop, push, shift, unshift, reverse, sort, fill, splice (see below for more info on changes delivery for these)
  • massive mutations delivered in a single callback, usually having an array of an atomic changes
• Enhanced intrinsic methods of Map, WeakMap, Set, WeakSet like set, get, delete etc are not observed (see this issue for more details)

Support matrix: ₄₉₊, ₄₂₊, ₁₃₊

Support matrix is mainly dependent on 2 advanced language features: Proxy and Reflect. The broader their adoption - the broader the support matrix of ObjectObserver.

Backlog:

• 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

Versions

• 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)

• 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

• 0.1.0

  • First stable API release

Loading the Library

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-oserver.js in your HTML will load it into the global scope:

<script src="object-observer.js"></script>
<script>
	var 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):

var customNamespace = {},
    person = { name: 'Nava', age: 6 },
    observablePerson;

fetch('object-observer.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);
		});
	}
});

APIs

Observable static properties

• from - receives a non-null object and returns Observable interface:

  var person = { name: 'Aya', age: '1' },
  	observablePerson;
  
  observablePerson = Observable.from(person);
  ...
  

Observable instance properties

• 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' changes
  • oldValue - 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 and unobserve methods will mimic the revoked Proxy behaviour and throw TypeError if used on the revoked Observable. Subsequent revoke invokations will have no effect:

  ...
  observablePerson.revoke();
  ...
  

Examples

Objects

var 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' }

Arrays

var 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' for sort. 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.