observatoryjs v1.0.3

Observatory

Observatory attempts to provide javascript developers an interface for Object.observe with mongodb style querying for specificity.

Installation

Observatory can be used in the browser as well as on the server via node.js.

// bower
bower install observatory

// npm
npm install observatoryjs

Usage

Simply import the library, instantiate a new Observatory instance and start binding events. You can use simple, mongodb style querying to specify exactly when you want your callback to trigger. Think of it as a jQuery on event binding, but for objects.

Below you can see a simple example of importing the library using the Commom.js standard, object instantiation and then finally a prototype of an event binding.

// import library. Supports AMD, Common.js, and browser loading
var Observatory = require("Observatory");

// create Observatory instance
var observer = new Observatory();

// observation event structure
observer.on( object , query , callback );

Queries

Queries can be defined in two different ways. You can either specify an object property to observe or you can create a expression for more granular observations.

observer.on( obj , { event: property } , callback );

	// or

observer.on( obj , { event: {expression} } , callback );

Note that you can replace the object property in the first example with the wildcard character '*' to observe events for all object properties.

Events

The currently supported events are listed below. More events will be added in future releases.

• $update - observe events that include an update to a queried property
• $add - observe events that include an addition to a queried property
• $delete - observe events that include an deletion from a queried property

Expressions

By using different selectors you can create an expression for more specific event handling. Below is a prototypical example of an expression in action, as well as a list of the different types of selectors you can use with examples for each.

observer.on( obj , { event: { property: { selector: parameter } } } , callback );

Value Selectors

$gt - check if the property is greater than the query value

var cat = {
	age: 3
};

observer.on( cat , { $update: { "age": { $gt: 10 } } } , function(){
	console.log("that cat is older than 10");
});	

$lt - check if the property is less than the query value

var cat = {
	age: 3
};

observer.on( cat , { $update: { "age": { $lt: 10 } } } , function(){
	console.log("that cat is younger than 10");
});	

$gte - check if the property is greater than or equal to the query value

var cat = {
	age: 3
};

observer.on( cat , { $update: { "age": { $gte: 10 } } } , function(){
	console.log("that cat is old!");
});	

$lte - check if the property is less than or equal to the query value

var cat = {
	age: 3
};

observer.on( cat , { $update: { "age": { $lte: 9 } } } , function(){
	console.log("that cat is young.");
});	

$eq - check if the property is equal to the query value

var cat = {
	age: 3
};

observer.on( cat , { $update: { "age": { $eq: 10 } } } , function(){
	console.log("that cat is 10");
});

Array Selectors

$in - check if the target array contains any of the query values after the event fires

var foo = {
	languages: [ "c++" , "c" , "java" ]
};

observer.on( foo , { $add: { "languages": { $in: [ "javascript" , "lua" ] } } } , function(){ 
	console.log("no scripting allowed!"); 
});

$all - check if the target array contains all of the query values after the event fires

var foo = {
	languages: [ "c++" , "c" , "java" ]
};

observer.on( foo , { $add: { "languages": { $all: [ "c" , "c++" , "c#" ] } } } , function(){ 
	console.log("much c!"); 
});	

Depth

You can observe as far as top level properties of objects that are nested within the observed object. This can be achieved by using object dot notation, wrapped in quotes, in your observation queries.

var obj = {
	foo:{
		bar: "gg m8" // you can observe this far
	}
}

observer.on( obj , { $update: "foo.bar" } , callback );

Notes:

• From the context of within the callback body, this is set to the observed object.
• The events array is always passed into the callback as the first and only argument.