Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Evented, in-process key/value store for Node.js and the Browser

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 lib
Octocat-spinner-32 test
Octocat-spinner-32 .gitignore
Octocat-spinner-32 README.md
Octocat-spinner-32 logo.png
README.md

Alt text

Synopsis

EventVat is an in-process key/value store with an API inspired by Redis. But it's also event based, which means that when changes to the data are made, events will be raised for which a callback can be provided. It supports 5 data types, Strings, Numbers, Booleans, Arrays and Hashes.

Motivation

  • Reduce trips across the process boundary.
  • Portability, works in the browser and on the server.
  • Event based key/value storage and retrieval.
  • A single API for many data storage end-points (such as local browser storage, a local filesystem or couchdb).

Usage

Instantiate EventVat with existing data or without. Methods and events are hung off of the new instance. Each method that can act on the instance will raise an event by the same name.

events

EventVat uses an implementation of EventEmitter. Listeners can attached to an EventVat object. An EventVat object can emit and event and a listener will respond. An event has three characteristics, the event name, a listener and an associated data key or wildcard.

Key based events

  var demo = EventVat();

  demo.on('get.foo', function(event, key, value) {
    console.log('getting: ', key, value);
  });

  demo.get('foo');

Wildcard events

  var demo = EventVat();

  demo.on('get.foo', function(key, value) {
    console.log('getting: ', key, value);
  });

  demo.get('foo');

API

Constructor

EventVat(data)

  var demo = EventVat(data); // create a new EventVat object with a existing key/value pairs, returns new instance.

Instance methods

KEYS

del(key)

Delete the key. Returns boolean value to represent the success of the operation.

  demo.del('key');

exists(key)

Checks to see if the key exists. Returns boolean value to represent the success of the operation.

  demo.exists('foo');

expires(key)

Set a key's time to live in seconds

  demo.expires('foo');

expireat()

Set the expiration for a key as a Javascript Date Object timestamp

  demo.expires('foo', Date.now()); // obviously only for demonstration, expires now

keys()

Find all keys matching the given pattern using a regular expression.

  demo.keys(/foo/);

move(key, db)

Move a key to another database. NOT IMPLEMENTED

  demo.move(key, db); // not sure how this is relevant.

object()

Inspect the internals of an object. console.log instead? NOT IMPLEMENTED

  demo.move(key, db);

persist(key)

Remove the expiration from a key.

  demo.persist('foo');

randomkey()

Return a random key from the data.

  demo.randomkey();

sort(key) NOT IMPLEMENTED

Return a random key from the data.

  demo.sort('foo'); // needs to get implemented.

type()

Return the javascript type of the value contained in the key.

  demo.type('foo');

STRINGS

append(key)

If key already exists and is a string, this command appends the value at the end of the string. If key does not exist it is created and set as an empty string, so append will be similar to set in this special case.

  demo.append('foo', 'bar'); // if foo's value was `re` then the new value would be `rebar`.

decr(key [, value])

If the value of key is numeric, decrement it and return the new value. Implementation for decrby.

  demo.decr('foo');

get(key)

Get the value of the key, returns the value retrieved.

  demo.get('foo'); 

getbit(key, ...offset)

Returns the bit value at offset in the string value stored at key. When offset is beyond the string length, the string is assumed to be a contiguous space with 0 bits. When key does not exist it is assumed to be an empty string, so offset is always out of range and the value is also assumed to be a contiguous space with 0 bits.

  demo.set('foo', 7);

set(key [, value, ttl])

Set the value of key to value, returns boolean value to represent the success of the operation. If no value is assigned, the key's value will be emptied. if a time to live is specified, the key will be deleted after N milliseconds.

  demo.set('foo', 'bar');

setnx(key, value)

Set a value on a key, but only do so if one does not exist. If the key already exists, return false.

  demo.setnx('foo', 'bar'); // create 'key' and assign it nothing.

ttl(key [, value])

Find the TTL (time to live) value, or assign one to a key.

  demo.ttl('foo'); // reutns the time to live.

rename(a, b, reset)

Rename a key from a to b. Will preserve the date/timestamp unless the boolean value reset is provided. Returns boolean value to represent the success of the operation.

  demo.rename('foo', 'bar');

incr(key [, value])

If the value of key is numeric, increment it and return the new value. Implementation for incrby.

  demo.incr('foo'); // if the value is numeric, increment it.

swap(a, b, depth)

Swap the value of a with b, if the boolean value depth is provided, the created, modified, value and ttl values will be

  demo.swap('foo', 'bar');

findin(key, value)

Return an index reflecting the position at which a match was found the key's value.

  demo.findin('foo', 'bla'); // same as indexOf in a string.

replace(key, valueA, valueB, global)

Within the value of key, replace valueA with valueB once, unless specified by the boolean value global.

  demo.replace('foo', 'foo', 'bar', true)

dump(stringify)

Get the current data store and dump it. stringify determines if the method should call JSON.stringify on the data-store prior to returning it.

  demo.dump(true);

HASHES

To-Do: Implement.

LISTS

To-Do: Implement.

SETS

To-Do: Implement.

SORTED SETS

To-Do: Implement.

TRANSACTIONS

discard() NOT IMPLEMENTED YET

Discard all commands issued after MULTI

exec() NOT IMPLEMENTED YET

Execute all commands issued after MULTI

multi() NOT IMPLEMENTED YET

Mark the start of a transaction block

unwatch() NOT IMPLEMENTED YET

Forget about all watched keys

watch(key [, ...key]) NOT IMPLEMENTED YET

Watch the given keys to determine execution of the MULTI/EXEC block

  // This implementation needs to take into account the 'killer'. At the time of invocation, 
  // keys that fall into the transaction scope may have their ttl-counts preserved for use with `discard()`.

Static Methods

random()

Generates a random key and assigns it 'value', returns the new key.

  demo.set(m.random(), 'value');

save() NOT IMPLEMENTED YET

Attempts to save a string to a either the local browser storage or a file stream.

  demo.save(m.dump(true)); // attempt dump to local storage

Events

Events can be raised

newListener

function (event, listener) { }

This event is emitted any time a new listener is added.

set

function (key, value) { }

This event is emitted when a value is set on a key.

setnx

function (key, value) { }

This event is emitted when a value is retrieved from a key that does not exist.

get

function (key, value) { }

This event is emitted when a value is retrieved from a key.

rename

function (oldKey, newKey) { }

This event is emitted when a key is renamed.

renamenx

function (oldKey, newKey) { }

This event is emitted when a key is renamed, but only if the new key does not exist.

decr

function (key, value) { }

This event is emitted when a key is numeric and its value is decremented.

incr

function (key, value) { }

This event is emitted when a key is numeric and its value is incremented.

swap

function (key, a, b, depth) { }

This event is emitted when the values of two keys are swapped.

findin

function (key, value, index) { }

This event is emitted when a key is found.

del

function (key, value, index) { }

This event is emitted when a key is deleted.

exists

function (key, value, index) { }

This event is emitted when a key is found to exist.

persist

function (key, value, index) { }

This event is emitted when a key is made to persist.

append

function (key, value, newValue) { }

This event is emitted when a key's value is appended to with a new value.

Licence

(The MIT License)

Copyright (c) 2010 hij1nx http://www.twitter.com/hij1nx

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Something went wrong with that request. Please try again.