hqv.loki

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:

``javascript
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.

$3

* 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:

`javascript
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;
}
});
`

$3


Initializes the module, establishing connection to the datasource and local cache.
`javascript
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) {
...
}
`

$3


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.
`javascript
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();
`

$3

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.
`javascript
loki.context().get('generated-doc-id')
.then( function (doc) {
// success
console.log(doc);
})
.fail( function (err) {
// failure
console.log(err);
})
.done();
`

$3

Removes a document from storage (persistent and cache).
`javascript
loki.context.()delete('generated-doc-id')
.then(function (res) {
// success
console.log(res);
})
.fail( function (err) {
// failure
console.log(err);
})
.done();
`

$3

Finds all documents which contains a condition property which, conditions which should match the incoming JSON object.
`javascript
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
`javascript
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);
}
``