witness

Witness v. 3. to bear witness to; testify to; give or afford evidence of.

Overview

The witness is an intelligent file content cache that keeps track ( optionally on a per-caller basis) of the state of a file.

Installing

Witness may be installed using Node and npm.

npm install witness

Usage

Witness can be used on a individual persistent basis or as a listener.

// For this example assume we have three files layed out as follows:
//  - src/one.coffee
//  - src/two.coffee
//  - src/three.coffee

// Require the witness and initialize it.

Witness = require('witness');
audtior = new Witness(/* The persistent cache file can be passed in here;
                         defaults to './.witness-cache' */);

// Checking the state of some files.

witness.state('src/one.coffee');   // == 'added'
witness.state('src/two.coffee');   // == 'added'
witness.state('src/three.coffee'); // == 'added'
witness.state('src/one.coffee');   // == 'ready'

// Now assume we have modified the content of one of 'src/one.coffee'.

witness.state('src/one.coffee');   // == 'changed'
witness.state('src/one.coffee');   // == 'ready'

// To allow a single process to maintain its event queue independent of another
// in a persistent way, one may specify a context as the second argument
// to `witness::state`.

witness.state('src/one.coffee', 'apple');   // == 'added'
witness.state('src/one.coffee', 'apple');   // == 'ready'
witness.state('src/one.coffee', 'orange');  // == 'added'
witness.state('src/one.coffee', 'orange');  // == 'ready'

// Now if we assume we modified the content again. Notice how 'apple' and
// 'orange' only get notified about the changed event once.

witness.state('src/one.coffee', 'apple');   // == 'changed'
witness.state('src/one.coffee', 'orange');  // == 'changed'
witness.state('src/one.coffee', 'apple');   // == 'ready'
witness.state('src/one.coffee', 'orange');  // == 'ready'

// This is to be used at the end of process; this writes the in-memory
// cache to a persistent file.

witness.store();

License

Unless otherwise noted, all files contained within this project are liensed under the MIT opensource license. See the included file LICENSE or visit opensource.org for more information.