mochila v2.0.0

Intro

Give your data a place to rest its head. Easy data storage and retrieval, with the ability to use factories.

Install

Using bower:

$ bower install mochila --save

Use your favorite flavor in the dist/ directory. Under AMD it registers the module name: mochila. As a global, use: Mochila.

Using npm:

$ npm install mochila --save

Use var x = require('mochila') in your code.

Simple usage examples

var mochila = new Mochila();
var monsters = [
    {
        id: 'abc-222-xu985',
        name: 'Mothra'
    },
    {
        id: 'xyz-333-pk254',
        name: 'Godzilla',
        stats: {
            heightFt: 330,
            weightTons: 60000,
            fistSizeFt: 36,
            shoeSizeFt: 74
        }
    }
];

var found;

mochila.addCollection('monster');
mochila.load('monster', monsters);

found = mochila.find('monster', 'abc-222-xu985');
found.name === 'Mothra' // true

found = mochila.find('monster', 'xyz-333-pk254');
found.name === 'Godzilla' // true
typeof found.stats // 'object'
found.stats === monsters[1].stats // false -- `load` does a deep clone if no factory
found.kingOfMonsters // undefined

// loading an object with the id of one already in the database merges the two
mochila.load('monster', {
    id: 'xyz-333-pk254',
    name: 'Gojira',
    kingOfMonsters: true
});

found.name === 'Gojira' // true
found.kingOfMonsters // true

Using factories:

function Widget(opts) {
    this.id = opts.id;
    this.name = opts.title;
    this.dimensions = opts.dimensions;
    this.countId = ++count;
}

// when a factory is registered, its `create` property is passed the object from `load`
Widget.create = function(opts) {
    return new this(opts);
};

var mochila = new Mochila();
var count = 0;
var cube = {
    id: 0,
    title: 'Cube',
    isCube: true,
    dimensions: {
        width: 10,
        height: 10,
        depth: 10,
    },
};

var found;

mochila.addCollection('widget');
mochila.addFactory('widget', Widget);
mochila.load('widget', cube);

found = mochila.find('widget', 0);

found instanceof Widget // true
found.title // undefined
found.name // 'Cube'
found.isCube // undefined
found.countId // 1
typeof found.dimensions // 'object'
found.dimensions === cube.dimensions // true -- factory did a shallow copy

Note: Make sure your data records each have an id property. It's used to store and search records efficiently. id can be a number or a string.

API Reference

Mochila

• mochila
  • ~Mochila
    • .clearCollections()
    • .addCollection(name)
    • .hasCollection(name) ⇒ Boolean
    • .collectionNames() ⇒ Array.<String>
    • .clearFactories()
    • .removeFactory(name)
    • .addFactory(name, factory)
    • .createModelOfType(name, ...objs) ⇒ Model
    • .load(name, payload)
    • .sortBy(name, [key]) ⇒ Array
    • .all(name, [key], [val]) ⇒ Array
    • .find(name, [key], val) ⇒ Model | undefined
    • .removeModels(name, models) ⇒ Array.<Model>
    • .removeWhere(name, [key], val) ⇒ Array.<Model>

mochila~Mochila

Creates a new Mochila container, which holds collections of records, with collections accessed by name.

Kind: inner class of mochila

• ~Mochila
  • .clearCollections()
  • .addCollection(name)
  • .hasCollection(name) ⇒ Boolean
  • .collectionNames() ⇒ Array.<String>
  • .clearFactories()
  • .removeFactory(name)
  • .addFactory(name, factory)
  • .createModelOfType(name, ...objs) ⇒ Model
  • .load(name, payload)
  • .sortBy(name, [key]) ⇒ Array
  • .all(name, [key], [val]) ⇒ Array
  • .find(name, [key], val) ⇒ Model | undefined
  • .removeModels(name, models) ⇒ Array.<Model>
  • .removeWhere(name, [key], val) ⇒ Array.<Model>

mochila.clearCollections()

Remove all models from each collection. All models, if not referenced elsewhere, are lost. All factories registered will remain.

Kind: instance method of Mochila

mochila.addCollection(name)

Add a named collection that you can load models and objects into. It is initialized empty.

Kind: instance method of Mochila

mochila.hasCollection(name) ⇒ Boolean

Returns whether the mochila has that particular collection.

Kind: instance method of Mochila
Returns: Boolean - true if the collection exists in the mochila, false if not.

mochila.collectionNames() ⇒ Array.<String>

Returns the names of all the collections that have been added.

Kind: instance method of Mochila
Returns: Array.<String> - The names of all the collections that have been added.

mochila.clearFactories()

Remove all factories from each collection. All factories, if not referenced elsewhere, are lost. All models will remain.

Kind: instance method of Mochila

mochila.removeFactory(name)

Remove a factory associated with a collection.

Kind: instance method of Mochila

mochila.addFactory(name, factory)

Register a factory that the named collection will use to create new models.

Kind: instance method of Mochila

mochila.createModelOfType(name, ...objs) ⇒ Model

Create a new model using its factory, passing all arguments, or if a factory doesn't exist, create a plain object that will be extended by a deep copy of all arguments that are objects.

Kind: instance method of Mochila
Returns: Model - The new model.

mochila.load(name, payload)

Load models or objects/JSON into the named collection. Models are placed into the collection as is. Objects are passed into the previously-registered factory of the named collection to create new models. If the factory doesn't exist, a model is made from a deep copy of the object. The payload can be an object, model, or an array of objects or models. Each object/model MUST have a property named 'id' that is a number or a string. An object or model that has the same id as a model in the mochila will have its own properties merged using a deep copy.

Kind: instance method of Mochila

mochila.sortBy(name, key) ⇒ Array

Sort the given collection by a specified key. Since collections are always sorted by id, searching by id offers a significant speedup. To determine whether one object should come before another in sorted order, the - operator is used if key holds a Number type, and < otherwise.

Kind: instance method of Mochila
Returns: Array - A copy of the collection, but sorted by key.

mochila.all(name, key, val) ⇒ Array

Returns all models in a collection whose key === val. Returns all models if none of the optional parameters are given.

Kind: instance method of Mochila
Returns: Array - An array with any models that matched the search parameters, or all models if no search parameters were given.

mochila.find(name, key, val) ⇒ Model | undefined

Finds the first model in the named collection with key === val.

Kind: instance method of Mochila
Returns: Model | undefined - The model or undefined if it wasn't found.

mochila.removeModels(name, models) ⇒ Array.<Model>

Remove a model or models from the named collection. If not referenced elsewhere, they will be lost. Uses the models' id to find and remove them.

Kind: instance method of Mochila
Returns: Array.<Model> - An array of the models removed from the collection.

mochila.removeWhere(name, key, val) ⇒ Array.<Model>

Remove all models from the named collection that have key === val. If not referenced elsewhere, they will be lost.

Kind: instance method of Mochila
Returns: Array.<Model> - An array of the models removed from the collection.

License

MIT