hqv.loki v1.1.1

Husqvarna - LOKI

Loki is a library for accessing JSON objects stored in NO-SQL storage. Loki features:

• caching - All reads from the data source is cached, and re-read onyl when they expire.
• offline - When the data source goes offline, cache times is extended to allow data to be avalible even though the database goes offline.
• find - Functionallity for conditional document retrival, matching input JSON object properties with document-conditions.
• cloud - Builtin support for: Azure - DocumentDb.
• promises - All functions are turned as promises.

##Installation ###Package

The package uses promisses callback model for response, exposed through DocumentViewer

npm install hqv.loki

Cache configuration

The cache-mechanism within Loki can be configured by either passing your own cache-object or by setting timeouts for the built in cache.

• cacheDuration - The number of seconds an item can stay in cache before being discarded, requiring a read to the database.
• disconnectTimeout - When an item is expired from cache and the database is disconnected (not accessible), the cache duration can be extended to allow the database to restart (or what ever).
• cache - Allows a custom cache object / class to be used. See document-cache.js for a hint on how to build one.

Example:

var loki = require('hqv.loki');

loki.init({
	cacheDuration : 3600, // number of seconds that an item can stay in cache
	disconnectTimeout : 3600*10 // extend cache duration when database is offline
}, null, function (err) {
	console.log(err);
});

Persistant storage configuration

Each type of persisant database storage requires different kinds of configuration, which is specified by passing a configuration object to the Loki's init function. Below is a list of supported databases and what kind of configuration they require.

Currently, only Azure's DocumentDB is supported.

Azure documentDB

• hostURI - The public URL to the Azure DocumentDB instance docUtil, https://my-documentdb-instance.documents.azure.com:443/
• authKey - Authentication key, called PRIMARY KEY in Azure.
• databaseId - Name of the database to access (within the DocumentDB instance).
• collectionId - Name of the collection within the database to read and write to.

Example:

var loki = require('hqv-loki');

loki.init({
	// optional cache params
	cacheDuration : 60,
	disconnectTimeout : 3600,
	// database specific
	hostURI : 'https://my-documentdb-instance.documents.azure.com:443/',
	authKey : 'ALKJSDLAKSJDLAKSDJSDLKAJDLKASJDL',
	databaseId : 'MyDatabase',
	collectionId : 'MyCollection'
}, null, function (err) {
	if(!err) {
		console.log('Database connection established.');
	} else {
		throw err;
	}
});

init

Initializes the module, establishing connection to the datasource and local cache.

loki.init(
	// db and cache config
	config,
	// called each time a internal error occurs (even if they are handled) 
	onError,
	// init done callback 
	function (err) {
	
});

function onError(err) {
	...	
}

insert

Inserts a document into storage. Any 'id' property of the document will be ignored. A new id is generated and returned when the item has been created.

loki.context().insert({
		"name" : "cake"
		"age" : "15"
	})
	.then(function (res) {
		// success
		console.log('Id of the new document: ' + res);
	})
	.fail(function (err) {
		// failure
		console.log(err);
	})
	.done();

get

Reads a document with a specific id from storage. The function checks if the item is stored in a non-expired cache before returning. The item may also be read from cache if the data source is expired, and the disconnect-timeout has not yet expired.

loki.context().get('generated-doc-id')
.then( function (doc) {
	// success
	console.log(doc);
})
.fail( function (err) {
	// failure
	console.log(err);
})
.done();

delete

Removes a document from storage (persistent and cache).

loki.context.()delete('generated-doc-id')
.then(function (res) {
	// success
	console.log(res);
})
.fail( function (err) {
	// failure
	console.log(err);
})
.done();

find

Finds all documents which contains a condition property which, conditions which should match the incoming JSON object.

loki.context().find({
		"name" : "cake"
		"age" : "15"
	})
.done(function (docs) {
	// success
	console.log('found ' + docs.length + ' matches.');	
}
.fail(function (err) {
	// failure
	console.log(err);
})
.done();

Examples

The examples below is avalible in the examples directory.

examples/azure-documentdb.js

var loki = require('./../');

var config = {
	// optional, defaults to 3600 and 3600*10
	cacheDuration : 10,
	disconnectTimeout : 100,
	// azure document db connection keys
	hostURI : process.env.HOSTURI || 'https://my-documentdb.documents.azure.com:443/',
	authKey : process.env.AUTHKEY || '...',
	databaseId : process.env.DBID || 'MyDatabase',
	collectionId : process.env.COLID || 'MyCollection'
};

loki.init(config, internalError, function (err) {
	if(err) {
		console.log('Failed to connect to database: ' + err);
		return;
	}
	
	loki.context().insert({
		"name" : "cake",
		"age" : "15"
	})
	.then(function (docId) {
		return loki.context().get(docId);
	})
	.then(function (doc) {
		console.log('Name "' + doc.name + "', age " + doc.age);
	})
	.fail(function (err) {
		console.log('An error occured: ' + err);
	})
	.done();
});

function internalError (err) {
	console.log('An error occured within Loki: ' + err);
}