livelystream v2.1.1

livelystream

Stream changes to and from a lively dataase as a node.js stream.

Installation

This module is installed via npm:

$ npm install livelystream

Example Usage

LivelyStream when used in conjunction with ObserveStream will replicate data from the database pointed to LivelyStream with the local javascript object pointed to by ObserveStream:

// a database to replicate to/from
var memdb = new MemLively();

// bind the database to the lively stream, and give a key to watch, and an
// initial value if the key is not found in the database
var ls = new LivelyStream(memdb, 'eugene', {});

// scope will contain the local javascript versions of the data in the database
var scope = {};

// Watch for any changes on scope.target
var os = new ObserveStream(scope, 'target');

// Connect the database to the observestream to do two-way replication
ls.pipe(os).pipe(ls);

// Making any changes to the database, should eventually replicate
// the changes to scope.target
memdb.put('eugene', { name: 'Eugene', number: 42 }, function () {});

// Making any changes to the local scope.target will replicate to he database
scope.target.name = 'Susan';

API

LivelyStream(db, key, initialValue)

Constructs a new LivelyStream instance bound to a Lively database.

• db - the Lively database to synchronize to. (eg. MemLively
• key - the key in the database to watch for changes and to synchronize with the downstream stream.
• initialValue - If there is no data in the database at the key pointed to by key then return this initial value.

Outbound 'data' Events emitted by LivelyStream

The LivelyStream emits 'data' events with the following format:

Initial value events

The very first event that the LivelyStream fires will be the value event. This will contain the inital value of the key in the database, or if the key is not found in the database, then the initialValue will be returned.

For example, if the initial value in the database is my value then the first event emitted would be:

{ value: 'my value' }

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: 42 },
    { type: 'del', key: ['old'] } ] }

Inbound events consumed by LivelyStream to change database values

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: 42 },
    { type: 'del', key: ['old'] } ] }