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
, exceptnull
andundefined
- 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 byJSON.stringify
, then a lookup will be performed on the table. Either a value is found and returned, or none is found andundefined
is returned.table(key,val)
: If key is as above, and val is anything whatsoever other thannull
orundefined
, then the key value pair is entered into the table.table(query)
: wherequery = function (key, value) {...}
is a predicate function, then an array of all key-value entries for whichquery
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 returnsfalse
otherwise.table(fn, 'iterate')
: wherefn = 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 tabletable.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, otherwisefalse
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 arraya
of pairs, and feeds them into the table, overwriting anything that is already there.
Enjoy?