observestream
Duplex node.js stream to replicate live changes to and from Javascript objects.
Installation
This module is installed via npm:
$ npm install observestream
Example Usage
ObserveStream when used in conjunction with LivelyStream will replicate data from the database pointed to LivelyStream with the local javascript object pointed to by ObserveStream:
// require the observestream classvar ObserveStream = ;// a database to replicate to/fromvar memdb = ;// bind the database to the lively streamvar ls = memdb;// scope will contain the local javascript versions of the data in the databasevar scope = {};// Watch for any changes on scope.target and replicate to the 'eugene' key in// the remote databasevar os = 'eugene' scope 'target' {};// Connect the database to the observestream to do two-way replicationls;// Making any changes to the database, should eventually replicate// the changes to scope.targetmemdb;// Making any changes to the local scope.target will replicate to he databasescopetargetname = 'Susan';
API
ObserveStream(key, scope, path, initialValue[, options])
Constructs a Duplex ObserveStream.
key
- This is the key to listen to in the remote database, which will be bound to the local scope variable.scope
- This is the scope object (similar to a scope in angularjs) which contains the local javascript object that is to be replicated by the upstream database through LivelyStream. The object to be watched and replicated isscope[path]
. So if the path is 'foo', then the object to be replicated would bescope['foo']
.path
- The property of thescope
object which will congtain the local javascript object to be replicated to and from the database attached to the LivelyStream.initialValue
- This is the initial value that will be stored in the remote database and used locally, if there is nothing in the database for thekey
.options
- An optional options object that the following options:nextTurn
(function) - A function that will be used to poll for changes of the monitored object. By default, this is a function that doessetTimeout(fn, 0)
. But you can easily change this tosetImmediate
by passing insetImmediate
to theNextTurn
property of the options object. Note that doing this will increase the CPU utilization considerably.observejs
(boolean) - This default to false. This uses observejs to detect changes on the watched object. In practice this wraps the object in a series of getters and setters to detect changes. However, the limitation of this method is that you can't detect if a property has been deleted. This is why we use thenextTurn
function to poll for changes. Also there maybe times where wrapping an object in getters and setters may cause issues. If you can use this method of change detection, then this will be much more CPU friendly. ObserveJS may be re-written to use the new ECMAScript Object.observe feature, which would be the best of both worlds. However, this won't work in older browsers or node.js implementations.
Examples:
// Scope object which will hold the data to be watchedvar scope = {} os;// Watch for any changes on scope.targetos = 'my key' scope 'target' {};// Use observejs to detect changes of the objectos = 'my key' scope 'target' {} observejs: true ;// Use setImmediate for pollingos = 'my key' scope 'target' {} nextTurn: setImmediate ;
Outbound 'data' Events emitted by ObserveStream
The ObserveStream emits 'data' events with the following format:
listen
events
When the ObserveStream initially is piped to a LivelyStream, it emits a
listen
event to tell the remote database which key to bind to and the
initial value to use if the key is not present in the remote database.
Eg:
'listen' key: 'my key' initialValue: {}
change
events
Any time there is a change in the database, a change
event is emitted.
The change is in changeset object
diff format. For example:
'change'type: 'put' key: 'name' value: 'Eugene'type: 'put' key: 'number' value: 42type: 'del' key: 'old'
Inbound events consumed by ObserveStream to change database values
value
events
Initial The very first event that the LivelyStream fires will be the value
event.
The ObserveStream processes this event, and expects it, to set the initial
value of the monitored object.
For example, if the initial value in the database is my value
then the
first event emitted would be:
'value' 'my value'
change
events
When piped from a stream such as
ObserveStream, the inbound
stream can write events that can modify the underlying database values pointed
to by the key
.
The format of these events is the same as the change
event listed above.
Eg:
'change'type: 'put' key: 'name' value: 'Eugene'type: 'put' key: 'number' value: 42type: 'del' key: 'old'