aspic v0.0.7

Aspic

Aspic is a (dumb) key-value store. The module wraps a standard javascript object with some convenience functions that implement the following features:

• storage/retrieval on any key that is serializable by JSON.stringify, except null and undefined
• retrieval of just keys
• retrieval of just values
• querying the table for lists of key-value pairs
• deletion by query

Thats it! Like I said, its pretty dumb.

USAGE

var table = require('aspic')();

table({x:10}); //undefined

// arbitrary objects can be keys:

table({x:10,y:20}, "Perhaps a Point?"); 

// so can arrays: 
table([1,2,3], "An array");

table([3,2,1], "Another Array");

// we can look at the keys:

table.keys() // [ {x: 10, y: 20},
             //   [ 1, 2, 3 ],
			 //   [ 3, 2, 1 ] ]
			 
table([3,2,1]) // 'Another Array'

table('[3,2,1]') // undefined

table([3,2,1], 'Updating This value');

table([3,2,1])  //  'Updating This value'

table(function (k,v) {return k.constructor === Array;});

// [ { key : [1, 2, 3],
//     val : 'An array' },
//   { key : [3, 2, 1],
//     val : 'Updating This value' }]

table.size()  // 3

// adding the 'delete' argument will remove and return the matching items

table(function (k,v) {return k.constructor === Array;}, 'delete');

table.size() // 1

API

aspic()

Assuming you did var aspic = require('aspic'), a call to the aspic() funciton returns a table object.

Table Objects

First and foremost, a table is a function that accepts one or two parameters.

table( /* key or query */ arg1, /* value or option */ arg2)

Here are the different ways to call the table object:

• table(key) : If key is any object that is serializable by JSON.stringify, then a lookup will be performed on the table. Either a value is found and returned, or none is found and undefined is returned.
• table(key,val) : If key is as above, and val is anything whatsoever other than null or undefined, then the key value pair is entered into the table.
• table(query) : where query = function (key, value) {...} is a predicate function, then an array of all key-value entries for which query returns true will be returned.
• table(query, 'delete') : as above, but this time the matching entries will be delete and returned.
• table(query, 'first') : sometimes you don't want to search the whole table. Using the 'first' option returns as soon as a satisfactory entry is found, or returns false otherwise.

• table(fn, 'iterate') : where fn = function (key, val) {...} is an arbitrary function. This will be called on each key value pair stored in the table.

Table methods

A table object also has a number of methods:

• table.size() : returns the size of the table
• table.drop(key) : deletes at most one entry with the given key. If deleted, the entry will be returned as a {key : key, val: val} pair, otherwise false is returned.
• table.set(key,val) : an alias for table(key,val).
• table.get(key) : an alias for table(key).
• table.keys() : returns an array of all keys in the table.
• table.values() : returns an array of all values in the table.
• table.toArray() : returns an array of two element arrays, one per table entry.
• table.fromArray(a) : accepts an array a of pairs, and feeds them into the table, overwriting anything that is already there.

Enjoy?