README.md

hive-model

A javascript based database for local memory based storage of data or resources.

Models are lists of data a la backbone collections. They can contain any sort of data.

Models are not designed for any specific backend. They are designed to provide real-time node repositories of records for transient information management.

There is no structural schema for model data or structure, beyond the existence of a unique identifying key identified by the _pk property (that defaults to 'id'). Although the default _make_pk assumes integer based IDs, you can easily override this for a different index basis.

Dataspaces

Models are stored in dataspaces, which ensure/maintain uniqueness of model name within the dataspace. Dataspaces are hive-components that store models by name in their config.

Queries

Many methods of the model have optional callbacks that if omitted result in a query object being returned. Query objects allow you to compound filtering operations such as

var hive_model = require('hive-model');

var ds = hive_model.Dataspace();

var myModel = hive_model.Model({data: [
		{id: 1, name: 'alpha', weight: 200},
		{id: 2, name: 'beta', weight: 100},
		{id: 3, name: 'delta', weight: 0},
		{id: 4, name: 'gamma': weight: 100},
	]
}, {name: 'foos'}, ds);

var lightweights = myModel.find(function(record){ return record.weight <= 100; });

// note - lightweights is not an array of objects: it is a query object.
// There is no guarantee of ordering of the records returned .. yet.

var lightweight_records = lightweights.records();

// these are the records from the query object.

var sorted_lightweights = lightweights.sort('name');

// sorted_lightweights is another query;

var sorted_lightweight_records = sorted_lightweights.records();

// HERE we have the desired result - all foos that weight up to 100, ordered by name.

// the practical way to use queries is to chain commands and end with a records output.

var slr_faster = myModel.find(function(record){ return record.weight <= 100;}).sort('name').records()

Creating a Model

Models are instances of the hive-component Component system. A hive-component Component is created with the following API:

var hive_component = require('hive-component');

var mixins = {
	increment: function(){
		var c = this.get_config('value') + 1;
		this.set_config(c);
		return c;
	}
}

var config = {
	value: 0;
}

// you can think of the API as "hive_component({methods}, {properties})" -- usually -- but once in a while
// you will need to pass data in as a mixin, as is the case with model data.
var MyCompFactory = hive_component(mixins, config);

var mycomp = MyComp():

mycomp.get_config('value') // 0;
mycomp.increment();
mycomp.get_config('value') // 1;

The Model function allows for a third argument, to pass the dataspace in seperately, as shown aboe. You can also create a service that buries the dataspace in closure as in:

var hive_model = require('hive-model');

var ds = hive_model.Dataspace();

var ds_factory = Model.factory(ds);

var _model_bar_mixin = { name: 'bar_model', data: [ {id: 1, name: 'a', weight: 100} , {id: 2, name: 'b', weight: 150} , {id: 3, name: 'c', weight: 200} , {id: 4, name: 'aa', weight: 125} , {id: 5, name: 'ab', weight: 175} , {id: 6, name: 'ba', weight: 50} , {id: 7, name: 'bb', weight: 75} ] }

var bar_model = ds_factory(_model_bar_mixin, {_pk: 'id'});

THE NAME IS REQUIRED in the first parameter. Its how dataspace indeses the model. You don't have to pass data in, though if you have it its a convenient way to start up your model.

The second parameter (config) has no mandataory properties, unless you want to use an object whose _pk (primary key) is different than "id".

Adding Data

You can add data to a model in one of three ways:

1. initally, as in the example above.
2. record by record via my_model.put({foo: 1, bar: 2});
3. in an array of data viar my_model.add([{}, {}]);

Each of these actions will emit('record', record) for each individual record. If you want to hook your data to a real repo, you can do so by listening for this event.

Updating Data

Putting data in that already has a PK value will overwrite / update a record; you can also call update to update a single record based on its ID, or by calling my_model.update(filter_function,