Tags starting with "v" are automatically published to npm

Install

npm install cachearoo

Cachearoo

const Cachearoo = require('cachearoo').Cachearoo;

Communicates with Cachearoo server, maintains a persistent connection, handles data store operations and event signaling. If the persistent connection (websocket) is not connected, REST will be used. Events can be registered without having the connection active, the client will automatically register them with the server when connection is established. Works with node.js and in browser.

Constructor

new Cachearoo(options);

Cachearoo Options

| Property | Type | Default | Description | |--------------|---------|-----------|----------------------------------------------------| | host | string | 127.0.0.1 | Cachearoo Server host or ip | | port | number | 4300 | Cachearoo Server port | | path | string | | Path to api if behind proxy | | apiKey | string | | Secret key to access API (if set in server) | | secure | boolean | false | Use TLS | | enablePing | boolean | false | | | pingInterval | number | 5000 | Time in milliseconds | | clientId | string | | Name of client, visible in admin UI status section | | bucket | string | | Default bucket for operations |

Methods

read(key, [opts])

Returns promise with read object. If empty string is passed as key, an array of all objects in bucket will be returned.

options (optional)

| Property | Type | Default | Description | |-----------|---------|---------|----------------------------------------| | bucket | string | null | Optionally override default bucket | | forceHttp | boolean | false | Force request to be sent over REST api | | async | boolean | true | |

Example

const cro = new Cachearoo({ bucket: 'myBucket' });
cro.read('myKey')
  .then(value => console.log(value));

list([opts])

List objects in bucket. Returns promise with array.

options (optional)

| Property | Type | Default | Description | |-----------|---------|---------|----------------------------------------| | bucket | string | null | Optionally override default bucket | | keysOnly | boolean | true | Set to false to retrieve object content | | forceHttp | boolean | false | Force request to be sent over REST api | | async | boolean | true | |

Example

const cro = new Cachearoo({ bucket: 'myBucket' });
cro.list()
  .then(objects => console.log(objects));

write(key, data, [opts])

Returns promise

options (optional)

| Property | Type | Default | Description | |--------------|---------|---------|-----------------------------------------------------------------------------------------------| | bucket | string | null | Optionally override default bucket | | forceHttp | boolean | false | Force request to be sent over REST api | | async | boolean | true | | | failIfExists | boolean | false | Operation will fail if key already exists in data store | | expire | string | | Set expiration for object, possible values: 'session' - Delete object when client disconnects |

Example

const cro = new Cachearoo({ bucket: 'myBucket' });
cro.write('myKey', { text: 'hello!' })
  .then(() => console.log('Written!');

patch(key, patch, [opts])

Returns promise. JSON patch existing object.

options (optional)

| Property | Type | Default | Description | |--------------|---------|---------|-----------------------------------------------------------------------------------------------| | bucket | string | null | Optionally override default bucket | | removeDataFromReply | boolean | false | Optionally remove patch result from reply | | forceHttp | boolean | false | Force request to be sent over REST api | | async | boolean | true | |

Example

const cro = new Cachearoo({ bucket: 'myBucket' });
cro.patch('myKey', [{ op: 'replace', path: '/text', value: 'hey!' }])
  .then(() => console.log('Patched!');

remove(key, [opts])

Returns promise. Removes an object from data store.

options (optional)

| Property | Type | Default | Description | |--------------|---------|---------|-----------------------------------------------------------------------------------------------| | bucket | string | null | Optionally override default bucket | | forceHttp | boolean | false | Force request to be sent over REST api | | async | boolean | true | |

Example

const cro = new Cachearoo({ bucket: 'myBucket' });
cro.remove('myKey')
  .then(() => console.log('Removed!');

Properties

Connection: PersistentConnection

PersistentConnection

PersistentConnection is automatically created in the Cachearoo instance as property connection

Methods

addListener(bucket, key, sendValues, callbackFn(eventObject))

Add listener for specific bucket and key. Wildcard * can be used to listen to all events in a bucket. If * is used for bucket, events will be triggered for all buckets.

eventObject

| Property | Type | Description | |----------|--------|----------------------------------------------------------| | bucket | string | bucket of event origin | | key | string | key of event origin | | value | object | written object if sendEvent was true in addListener call |

Example

const cro = new Cachearoo({ bucket: 'myBucket' });
cro.connection.addListener('myBucket', 'myKey', true, (event) => {
  console.log(`Event received for 
    key ${event.key} in
    bucket ${event.bucket},
    value=${event.value}`); 
});

signalEvent(bucket, key, value)

Send data to Cachearoo only to be propagated as an event to other clients.

Example

const cro = new Cachearoo({ bucket: 'myBucket' });
cro.connection.signalEvent(
  'myEventBucket',
  'myEventKey',
  { message: 'hello yall!' }
});

Events (callbacks)

onConnect(persistentConnection)

Callback triggered when connection is established.

Example

const cro = new Cachearoo({ bucket: 'myBucket' });
cro.connection.onConnect = (serverId) => {
  console.log(`Client connected to server with id ${serverId}`);
};

onDisconnect()

Callback triggered when connection is closed.

Example

const cro = new Cachearoo({ bucket: 'myBucket' });
cro.connection.onDisconnect = () => {
  console.log('Client disconnected');
};

onPong()

Callback triggered when pong packet is received from server.

Example

const cro = new Cachearoo({ bucket: 'myBucket' });
cro.connection.onPong = () => {
  console.log('Server is responding!');
};

Messaging.RequestReply

const RequestReply = require('cachearoo').Messaging.RequestReply;

Thin abstraction for sending and receiving messages between two clients connected to same Cachearoo. Cachearoo messaging is using the signalEvent method of PersistentConnection.

Requestor

Requestor is used to send messages to a receiver. Request will fail if no response is received within timeoutInMs or if no progress update is received within progressTimeoutInMs.

Constructor

new RequestReply.Requestor(CachearooInstance, channel, timeoutInMs, progressTimeoutInMs);

Methods

request(msg)

Returns promise with reply.

Example

const cro = new Cachearoo();

// We cannot send request before we are connected
cro.connection.onConnect = (serverId) => {
  // fail if response > 30 sec or if progress is not received < every 3 sec
  const requestor = new Requestor(bap, 'my-channel', 30000, 3000);
  requestor.request({ msg: 'hello?' })
  .then(reply => console.log(`Got reply! ${reply}`);
  .catch(err => console.error(err));
};

Replier

Replier is used to receive and reply to messages.

Constructor

new RequestReply.Replier(CachearooInstance, channel);

Events

onMessage(msg, replyFn(err, obj), progressFn(obj))

Called when a message is received. Reply is sent by calling replyFn with either an error or some data. In case of lengthy processing before reply can be sent, replier can call progressFn to avoid timeout in requestor.

Example

const cro = new Cachearoo();

const replier = new Replier(bap, 'my-channel');
replier.onMessage = (msg, reply, progress) => {
  console.log(`Got request: ${msg}`);
  // send progress after 2 sec, and reply after 5 sec
  setTimeout(() => progress({ someprop: 'some value' }), 2000);
  setTimeout(() => reply(null, { someProperty: 'some value' }), 5000);
};

Messaging.CompetingConsumers

const CompetingConsumers = require('cachearoo').Messaging.CompetingConsumers;

This pattern is used when one producer generates jobs that many listening consumers can claim. Only one of the consumers can claim each job.

#Producer Producer creates jobs.

Constructor

new CompetingConsumers.Producer(CachearooInstance, channel, timeoutInMs, progressTimeoutInMs);

Methods

addJob(job, progressFn?, timoutInMs?, progressTimeoutInMs?)

Returns promise, resolved if consumer processed it successfully. Consumer can optionally call a progress callback (passed in progressFn) during its job processing.

Example

const cro = new Cachearoo();

const producer = new Producer(bap, 'render-jobs', 10000);
cro.connection.onConnect = (serverId) => {
  producer.addJob({ someProperty: 'value' }, (progress) => console.log(progress))
  .then((data) => {
    console.log(`Job done: ${data.result}`);
  })
  .catch(err => console.error(err));
}

CompetingConsumer

Consumer of jobs.

Constructor

new CompetingConsumers.CompetingConsumer(CachearooInstance, channel);

Events

onJobQuery(job, callback(errno, worker))

Called when a job is requested by producer. errno should have one of values:

const JOB_NOT_SUPPORTED = 100;
const NO_WORKER_AVAILABLE = 200;
const JOB_OK = null;

Worker object must implement following:

class Worker {
  constructor(id) {
    this.id = id;
    this.available = true;
  }

  work(job, done, progress) {
    // do things
    // signal progress with progress();
    done(err, result);
  }
  
  release() {
    this.available = true;
  }
}

Example

class MyWorker {
  constructor(id) {
  this.id = id;
  this.available = true;
  }

  work(job, done, progress) {
    console.log('working..');
    // send progress every sec
    setTimeout(() => progress({ someProperty: 'value' }), 1000);
    // signal done after 10 sec
    setTimeout(() => done(null, { someProperty: 'value' }), 10000);
  }
  
  release() {
    this.available = true;
  }
}

const de = new Cachearoo();

const consumer = new CompetingConsumer(de, 'my-channel');
const worker = new MyWorker('myworker1');

consumer.onJobQuery = (job, callback) => {
  if (worker.available) {
    callback(null, worker);
  } else {
    callback(200); // no worker available
  }
};