KVStore Namespace Reference

wilton/KVStore
Key-value store. More...

Functions
Boolean	append (String key, Array values, Function|Undefined callback)
	Append values to the list for the specified key.
Number	clear (Function|Undefined callback)
	Delete all stored entries.
Number	dequeue (String key, Integer|Undefined count, Function|Undefined callback)
	Dequeues the number of values from the list for the specified key.
Number	destroy (Function|Undefined callback)
	Deallocate native resources used for this store.
Object	entries (Function|Undefined callback)
	All the entries from this store.
Any	get (String key, Function|Undefined callback)
	Get an element from the store.
Object	getBatch (Array keyList, Function|Undefined callback)
	Get multiple elements from the store.
Array	keys (Function|Undefined callback)
	All the keys from this store.
Object	KVStore (String|Undefined|Number filePathOrHandle, Function|Undefined callback)
	Create KVStore instance.
Number	persist (Function|Undefined callback)
	Save all contents to file.
Any	put (String key, Object|Array value, Function|Undefined callback)
	Put an element to the store.
Object	putBatch (Object obj, Function|Undefined callback)
	Put multiple elements to the store.
Boolean	remove (String key, Function|Undefined callback)
	Remove an element from the store.
Array	removeBatch (Array keyList, Function|Undefined callback)
	Remove multiple elements from the store.
Number	size (Function|Undefined callback)
	Number of entries in this store.

Detailed Description

Key-value store (linked hash multimap) that lives in shared memory and can be safely accessed from multiple threads.

Can be optionally created over the persistent file on disk. In that case file contents are read on store creation and saved on store destroy (for example, on application shutdown) or on a persist() call.

Usage example:

// create transient (non-persistent store)
var st1 = new KVStore();

// create persistent store over a file
var st = new KVStore("path/to/my.json");

// put entries into store
st.put("foo", "bar");
st.put("baz": [42, 43]);

// append values to existing entry
// existing value must be an array
st.append("baz", [44, 45, 46];

// removes values from the head of the existing entry
// existing value must be an array
st.dequeue("baz", 1); // "baz" value now is [45, 46]

// remove entry
st.remove("foo");

// share store with other threads
var chan = new Channel("my/channel/name", 1);
chan.send({
    kvstoreHandle: st.handle
});

// access store from other thread
var channel = Channel.lookup("my/channel/name");
var handle = channel.peek().kvstoreHandle;
var st = new KVStore(handle);

// persist store to file
st.persist();

// destroy store, persisting it to file
// and de-allocating native resources
st.destroy()

Function Documentation

Boolean KVStore::append	(	String	key,
		Array	values,
		Function|Undefined	callback
	)

Extends the array, stored as a value for the specified key, with the specified list of values (appending each value to the end of the array).

If key doesn't exist in the store - it is created with the specified values list.

If key exists in the store, its value must be an Array.

Parameters

key	String key of the entry to append to, its already inserted value must be a JSON Array
values	Array list of values to append to the existing list already stored for the specified key
callback	Function|Undefined callback to receive result or error

Returns

Boolean true, if the key existed and its value (JSON Array) was actually appended to; false if key didn't exist and was created with the specified values list

Number KVStore::clear

(

Function|Undefined

callback

)

Removes all elements from the store and (if this store was constructed over a file) overwrites the persistent file with empty contents.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Number number of entries removed

Number KVStore::dequeue	(	String	key,
		Integer|Undefined	count,
		Function|Undefined	callback
	)

Removes the specified number of values from the head of the array, stored as a value for the specified key.

If the specified count is larger than a size of an Array - all elements from Array are removed.

If key exists in the store, its value must be an Array.

If key doesn't exist in the store or if Array is empty - does nothing.

Parameters

key	String key of the entry to to deque from, its already inserted value must be a JSON Array
count	Integer|Undefined number of elements to dequeue, default value: 1
callback	Function|Undefined callback to receive result or error

Returns

Number number of elements dequeued

Number KVStore::destroy

(

Function|Undefined

callback

)

Saves store contents to a file (if this store was constructed over a file) and destroys the store de-allocating the native resources associates with it.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Number number of elements in store before destroy

Object KVStore::entries

(

Function|Undefined

callback

)

Returns an Object containing all the entries from the store.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Object all the contents of the store

Any KVStore::get	(	String	key,
		Function|Undefined	callback
	)

Retrieves an element from the store with the specified key. Returns null if specified key is not found.

Parameters

key	String key to retrieve
callback	Function|Undefined callback to receive result or error

Returns

Any stored value (Object or Array) or null if no key was found

Object KVStore::getBatch	(	Array	keyList,
		Function|Undefined	callback
	)

Retrieves multiple elements from the store using specified keyList. Returning object contains only the keys (and retrieved values) that were found in the store. Keys, that were not found, are not included into result.

Parameters

keyList	Array list of keys to retrieve
callback	Function|Undefined callback to receive result or error

Returns

Object objects with each property containing a key from the specified list and a retrieved value for that key - Object or Array

Array KVStore::keys

(

Function|Undefined

callback

)

Returns an Array containing all the keys from this store. Keys are returned in the insertion order.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Array list of all the keys in the store

Object KVStore::KVStore	(	String|Undefined|Number	filePathOrHandle,
		Function|Undefined	callback
	)

Create a store instance allocating the native resources for it. If path to file is specified, entries from this file will be be loaded into store and this file will be used to persist the contents of the store.

If empty (or null) file path specified - store will be memory-only without dist persistence.

If handle value is specified - uses existing store with this handle.

Parameters

filePathOrHandle	String|Undefined|Number this argument represents either a path to the file (String) where to persist store contents; or a handle (Number) of the existing KVStore object created in another thread; if argument is null ot not specified persistence is not used
callback	Function|Undefined callback to receive result or error

Returns

Object KVStore instance

Number KVStore::persist

(

Function|Undefined

callback

)

Saves all the contents of the store to the file on disk. Throws an error, if no file path was specified on store creation.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Number number of elements saved to JSON file

Any KVStore::put	(	String	key,
		Object|Array	value,
		Function|Undefined	callback
	)

Inserts the specified value into the store using the specified key. If key already exist in the store, its value it overwritten.

Parameters

key	String key to insert
value	Object|Array value to insert
callback	Function|Undefined callback to receive result or error

Returns

Any value (Object or Array) that was stored with the specified key or null if no existing key was found

Object KVStore::putBatch	(	Object	obj,
		Function|Undefined	callback
	)

Inserts all properties from the specified Object into the store. If the store already contains some of the inserted keys, their values are overwritten.

Parameters

obj	Object object containing the set of elements to insert, each property value must be either Object or Array
callback	Function|Undefined callback to receive result or error

Returns

Object object containing entries with the matching keys that were overwritten by the insertion; entries that were not overwritten are not included

Boolean KVStore::remove	(	String	key,
		Function|Undefined	callback
	)

Removes the element with the specified key from the store.

Parameters

key	String key to remove
callback	Function|Undefined callback to receive result or error

Returns

Boolean true if the specified key was found (and the corresponding entry was removed), false otherwise

Array KVStore::removeBatch	(	Array	keyList,
		Function|Undefined	callback
	)

Remove the elemtns with the specified keys from the store.

Parameters

keyList	Array list of keys to remove
callback	Function|Undefined callback to receive result or error

Returns

Array list of the keys, that were found in the store and removed

Number KVStore::size

(

Function|Undefined

callback

)

Returns the number of entries in this store.

Parameters

callback

Function|Undefined callback to receive result or error

Returns

Number number of entries in the store