JSDoc: Class: KagoDB

new KagoDB(options) → {KagoDB}

KagoDB class constructor.

Parameters:

Name	Type	Description
`options`	Object	option parameters for the instance

Source:

core/base.js, line 7

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.

Type:

Object

Source:

core/base.js, line 31

Example

var utils = KagoDB.bundle.utils;

bundle :Object

This is a shortcut to access modules bundled.

Type:

Object

Source:

core/base.js, line 33

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:

core/base.js, line 92

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:

core/base.js, line 70

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:

core/base.js, line 49

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:

core/base.js, line 112

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:

mixin/dynamic_ajax.js, line 47

See:

https://npmjs.org/package/request

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:

query/count.js, line 24

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:

mixin/encode.js, line 12

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:

mixin/events.js, line 108

See:

http://nodejs.org/api/events.html#events_emitter_emit_event_arg1_arg2

Returns:

this class itself for method chaining

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:

mixin/encode.js, line 44

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:

mixin/dynamic_storage.js, line 50

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:

mixin/encode.js, line 79

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:

mixin/dynamic_storage.js, line 52

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:

query/find.js, line 28

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:

query/find_and_modify.js, line 20

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:

query/find_one.js, line 24

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:

core/base.js, line 146

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:

mixin/dynamic_storage.js, line 54

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:

mixin/init.js, line 5

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:

query/insert.js, line 38

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:

mixin/model.js, line 36

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:

mixin/noop.js, line 5

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:

mixin/obop.js, line 5

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:

mixin/events.js, line 47

Returns:

this class itself for method chaining

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:

mixin/events.js, line 30

See:

http://nodejs.org/api/events.html#events_emitter_on_event_listener

Returns:

this class itself for method chaining

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:

mixin/events.js, line 85

See:

http://nodejs.org/api/events.html#events_emitter_once_event_listener

Returns:

this class itself for method chaining

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:

mixin/pkey.js, line 41

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:

mixin/dynamic_storage.js, line 46

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:

query/remove.js, line 24

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:

query/insert.js, line 109

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:

core/base.js, line 162

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:

mixin/encode.js, line 81

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:

query/update.js, line 34

See:

http://docs.mongodb.org/manual/reference/operator/#update-operators

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:

webapi/webapi.js, line 62

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:

webapi/webapi.js, line 51

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:

mixin/dynamic_storage.js, line 48

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');
});