Class: KagoDB

KagoDB

new KagoDB(options) → {KagoDB}

KagoDB class constructor.
Parameters:
Name Type Description
options Object option parameters for the instance
Source:
Returns:
an instance
Type
KagoDB
Example
var collection = new KagoDB(options);

var collection2 = KagoDB(options); // same as above

Members

<static> bundle :Object

This is a shortcut to access modules bundled.
Source:
Example
var utils = KagoDB.bundle.utils;

bundle :Object

This is a shortcut to access modules bundled.
Source:
Example
var collection = new KagoDB(opts);

var utils = collection.bundle.utils;

Methods

<static> get(key)

This gets a default parameter value for the class.
Parameters:
Name Type Description
key String parameter name
Source:
Returns:
parameter value
Example
var MyKago = KagoDB.inherit();

MyKago.set('foo', 'bar');
var foo1 = MyKago.get('foo'); // => bar

var collection = new MyKago();
var foo2 = collection.get('foo'); // => bar

<static> inherit(options)

This generates a sub class which inherits KagoDB class or its descendant.
Parameters:
Name Type Description
options Object default option parameters for the child class
Source:
Returns:
a sub class
Example
var MyKago = KagoDB.inherit();

MyKago.mixin(somemixin()); // load some mixin
MyKago.set('foo', 'bar');  // define default value

var collection = new MyKago();

<static> mixin(mixin)

This applies a mixin object which exports instance methods.
Parameters:
Name Type Description
mixin Object | Function mixin object or mixin function which returns mixin object
Source:
Returns:
this class itself for method chaining
Example
var MyKago = KagoDB.inherit();

var MyMixin = {
  mymethod: function() {}
};
MyKago.use(MyMixin);

var collection = new MyKago();

<static> set(key, val)

This sets a default parameter value for the class.
Parameters:
Name Type Argument Description
key String | Object parameter name or a parameters object
val any <optional>
new value
Source:
Returns:
this class itself for method chaining
Example
var MyKago = KagoDB.inherit();

MyKago.set('path', 'data');
MyKago.set({'storage': 'yaml'});

ajax(options, callback) → {KagoDB}

This performs a HTTP request.
Parameters:
Name Type Description
options Object parameters: method, url, json, form
callback Function function(err, body) {}
Source:
See:
Returns:
itself for method chaining
Type
KagoDB
Example
var MyKago = KagoDB.inherit();
MyKago.mixin(KagoDB.bundle.request());
var collection = new MyKago();

var options = {
  method: 'GET',
  url: 'http://graph.facebook.com/4',
};
collection.ajax(options, function(err, body) {
  console.log(body); // JSON
});

count(condition, options, callback) → {KagoDB}

This counts number of items matched with condition.
Parameters:
Name Type Argument Description
condition same as find() method
options Object <optional>
options: skip, limit
callback Function function(err, cursor) {}
Source:
Returns:
collection instance itself for method chaining
Type
KagoDB
Example
collection.find().count(function(err, count) {
  console.log(count);
});

decode(source, callback) → {Cursor}

This unserializes a string as an item object. Override this method when you need another serialized representation other than JSON.
Parameters:
Name Type Description
source String source string
callback Function function(err, item) {}
Source:
Returns:
instance itself for method chaining
Type
Cursor
Example
var xml2js = require('xml2js');
var MyKago = KagoDB.inherit();
MyKago.prototype.decode = function(source, callback) {
    xml2js.parseString(source, callback);
};
var collection = new MyKago();

emit(event)

This fires an event with the supplied arguments. It executes each of the listeners in order.
Parameters:
Name Type Description
event String event name
args... multiple arguments allowed.
Source:
See:

encode(item, callback) → {Cursor}

This serialize an item object as a serialized string. Override this method when you need another serialized representation other than JSON.
Parameters:
Name Type Description
item Object source item
callback Function function(err, str) {}
Source:
Returns:
instance itself for method chaining
Type
Cursor
Example
var js2xml = require('js2xml');
var MyKago = KagoDB.inherit();
MyKago.prototype.decode = function(source, callback) {
  var js2xml = new Js2Xml('item', person);
  var str = js2xml.toString();
  callback(null, str);
};
var collection = new MyKago();

erase(id, callback) → {KagoDB}

This erases an item.
Parameters:
Name Type Description
id String item ID
callback Function function(err) {}
Source:
Returns:
collection instance itself for method chaining
Type
KagoDB
Example
var collection = new KagoDB();

collection.erase('foo', function(err) {
  console.log(err || 'no error');
});

escape(source) → {String}

This escapes a special characters in the item ID string. It uses encodeURIComponent function per default. Override this method when you need another escape representation other than URI (percent) encoding.
Parameters:
Name Type Description
source String unescaped string
Source:
Returns:
escaped string
Type
String
Example
var MyKago = KagoDB.inherit();
MyKago.prototype.escape = function(source) {
    return source.replace(/\W/g, '_');
};
var collection = new MyKago();

exist(id, callback) → {KagoDB}

This tests an item existance.
Parameters:
Name Type Description
id String item ID
callback Function function(err, exist) {}
Source:
Returns:
collection instance itself for method chaining
Type
KagoDB
Example
var collection = new KagoDB();

collection.exist('foo', function(err, exist) {
  console.log(exist ? 'exists' : 'not exist');
});

find(condition, projection, options) → {Cursor}

This creates a cursor object with condition given as a test function or query parameters. Null condition will find all items in the collection
Parameters:
Name Type Argument Description
condition Function | Object test function or query selectors
projection Function | Object map function or output fields
options Object <optional>
options: sort, skip, limit, fields
Source:
Returns:
cursor instance
Type
Cursor
Example
var collection = new KagoDB();

// all items
collection.find().toArray(function(err, list) {
  list.forEach(function(item) {
    console.log(item.name, item.price);
  });
});

// condition using a test function
var test = function(item) {
  return item.price > 100;
};
collection.find(test).toArray(function(err, list) {
  list.forEach(function(item) {
    console.log(item.name, item.price);
  });
});

// condition using query parameters
var cond = {
  name: 'Apple'
};
collection.find(cond).toArray(function(err, list) {
  list.forEach(function(item) {
    console.log(item.name, item.price);
  });
});

// projection
var proj = {
  name: 1,
  price: 1
};
collection.find({}, proj).toArray(function(err, list) {
  list.forEach(function(item) {
    console.log(item.name, item.price);
  });
});

findAndModify(condition, sort, update, options, callback)

This updates the first item which matches the specified condition. This works similar to update() but update only the first item in the specified order.
Parameters:
Name Type Argument Description
condition Object | Function query selector or function
sort Object | Function order parameters or function
update Object | Function update operator or function
options Object <optional>
update options
callback Function <optional>
function(err) {}
Source:
Example
var collection = new KagoDB();

var query = {
  type: 'book',
  reading: false
};
var order = {
  published_at: 1
};
var update = {
  $set: {
    reading: true
  }
};
collection.findAndModify(query, order, update, null, function(err){
  console.log(err);
});

findOne(condition, options, callback) → {KagoDB}

This invokes a callback function with an item found under specified condition.
Parameters:
Name Type Argument Description
condition Function | Object test function or query selectors
options Object <optional>
options: sort, skip
callback Function <optional>
function(err, item) {}
Source:
Returns:
collection instance itself for method chaining
Type
KagoDB
Example
collection.findOne({}, function(err, item) {
  console.log(item);
});

get(key)

This gets a parameter value for the instance parameters.
Parameters:
Name Type Description
key String parameter name
Source:
Returns:
parameter value
Example
var collection = new KagoDB({path: 'data'});

var path = collection.get('path');

index(id, callback) → {KagoDB}

This lists all item IDs in array.
Parameters:
Name Type Description
id String item ID
callback Function function(err, list) {}
Source:
Returns:
collection instance itself for method chaining
Type
KagoDB
Example
var collection = new KagoDB();

collection.index(function(err, list) {
  console.log(list.length + ' items found');
});

init() → {KagoDB}

This may initialize something. This method may be called automatically. This is a hook point at start-up. It means that you could override this method when you do initialize something with your class.
Source:
Returns:
itself for method chaining
Type
KagoDB
Example
var opts = {storage: 'json', path: './data'};
var collection = new KagoDB(opts);
collection.init(); // may do something
collection.write('foo', item);

insert(item, callback) → {KagoDB}

This inserts an item to the collection. This requires a primary key defined.
Parameters:
Name Type Argument Description
item Object | Array an item or an array of items
callback Function <optional>
function(err) {}
Source:
Returns:
for chaining
Type
KagoDB
Example
var opts = {
  storage: 'memory',
  primary_key: '_id' // primary key like MongoDB does
};
var collection = new KagoDB(opts);

var item = {
  name: 'Apple'
};

collection.insert(item, function(err) {
  console.log(err || 'no error');
});

model(model) → {String}

This gets or sets a model class.
Parameters:
Name Type Description
model String model class to set
Source:
Returns:
model class
Type
String
Example
function Item() {} // model class

var collection = new KagoDB();
collection.model(Item); // => setter
collection.model(); // => getter
collection.get('model'); // => getter

collection.read(id, function(err, item){
  console.log(item instanceof Item); // => true
})

noop() → {KagoDB}

This does no operation per default.
Source:
Returns:
itself for method chaining
Type
KagoDB
Example
var collection = new KagoDB({storage: 'json'});

collection.noop().noop().noop().noop(); // does nothing four times

obop() → {obop}

This returns a cached instance of obop class.
Source:
Returns:
obop instance
Type
obop
Example
var collection = new KagoDB({storage: 'memory'});
var obop = collection.obop();

var src = [ { a: 1 }, { a: 2 }, { a: 3 } ];
var func = obop.where( { a: 2 } );
var out = src.filter(func);
// => [ { a: 2 } ]

off(event, listener)

This removes listeners.
Parameters:
Name Type Argument Description
event String <optional>
event name
listener Function <optional>
listner function
Source:

on(event, listener)

This adds a listener to the end of the listeners array for the specified event.
Parameters:
Name Type Description
event String event name
listener Function listner function
Source:
See:

once(event, listener)

This adds a one time listener for the event. This listener is invoked only the next time the event is fired, after which it is removed.
Parameters:
Name Type Description
event String event name
listener Function listner function
Source:
See:

pkey(pkey) → {String}

This gets or sets a primary key. Use this interface to change a primary key after a session started.
Parameters:
Name Type Description
pkey String primary key to set
Source:
Returns:
primary key
Type
String
Example
var collection = new KagoDB();
collection.pkey('_id'); // => '_id'
collection.pkey(); // => '_id'
collection.get('primary_key'); // => '_id'

read(id, callback) → {KagoDB}

This reads an item.
Parameters:
Name Type Description
id String item ID
callback Function function(err, item) {}
Source:
Returns:
collection instance itself for method chaining
Type
KagoDB
Example
var collection = new KagoDB();

collection.read('foo', function(err, item) {
  console.log(item);
});

remove(condition, options, callback)

This removes item(s) which matches the specified query.
Parameters:
Name Type Argument Description
condition Object | Function query selector
options Object <optional>
single:true - removes the first item found (default:false)
callback Function <optional>
function(err) {}
Source:
Example
var collection = new KagoDB();

collection.remove({name: 'john'}, true, function(err){
  console.log(err);
});

save(item, callback) → {KagoDB}

This inserts or updates an item to the collection. This requires a primary key defined.
Parameters:
Name Type Argument Description
item Object an item
callback Function <optional>
function(err) {}
Source:
Returns:
for chaining
Type
KagoDB
Example
var opts = {
  storage: 'memory',
  primary_key: 'name'
};
var collection = new KagoDB(opts);

var item = {
  name: 'Apple'
};

collection.save(item, function(err) {
  collection.save(item, function(err) {
    console.log(err || 'no error');
  });
});

set(key, val) → {KagoDB}

This sets a parameter value for the instance parameters.
Parameters:
Name Type Argument Description
key String | Object parameter name or a parameters object
val any <optional>
new parameter value
Source:
Returns:
this instance itself for method chaining
Type
KagoDB
Example
var collection = new KagoDB();

collection.set('path', 'data');
collection.set({'storage': 'yaml'});

unescape(source) → {String}

This unescapes a special characters in the item ID string It uses decodeURIComponent function per default. Override this method when you need another escape representation other than URI (percent) encoding.
Parameters:
Name Type Description
source String escaped string
Source:
Returns:
unescaped string
Type
String
Example
var MyKago = KagoDB.inherit();
MyKago.prototype.unescape = function(source) {
    return source.replace(/^prefix-/, ''); // remove a prefix
};
var collection = new MyKago();

update(condition, update, options, callback)

This updates item(s) which matches the specified query. $set, $unset, $inc, $push, $pull, $rename operators are available as update parameters.
Parameters:
Name Type Argument Description
condition Object | Function query selector or function
update Object | Function update operator or function
options Object <optional>
update options: multi
callback Function <optional>
function(err) {}
Source:
See:
Example
var collection = new KagoDB();

var query = {
  name: 'John'
};
var update = {
  $set: {
    child: 'Sean'
  },
  $inc: {
    age: 1
  }
};
var options = {
  multi: false
};
collection.update(query, update, options, function(err){
  console.log(err);
});

webapi() → {Function}

This generates a RESTful Web API function for Express.js.
Source:
Returns:
a Web API function for express
Type
Function
Example
var express = require('express');
var KagoDB = require('KagoDB');

var opts = {
  storage: 'json',
  path: './data/'
};

var app = express();
app.use(express.static(__dirname + '/public'));
app.all('/data/:id?', KagoDB(opts).webapi());
app.listen(3000);

webmethods() → {WebMethods}

This returns a set of bridge methods from express app to KagoDB.
Source:
Returns:
Type
WebMethods

write(id, item, callback) → {KagoDB}

This writes an item.
Parameters:
Name Type Description
id String item ID
item Object item content
callback Function function(err) {}
Source:
Returns:
collection instance itself for method chaining
Type
KagoDB
Example
var collection = new KagoDB();

var item = {
  name: 'FOO',
};
collection.write('foo', item, function(err) {
  console.log(err || 'no error');
});