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 = ;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;mochila; found = mochila;foundname === 'Mothra' // true found = mochila;foundname === 'Godzilla' // truetypeof foundstats // 'object'foundstats === monsters1stats // false -- `load` does a deep clone if no factoryfoundkingOfMonsters // undefined // loading an object with the id of one already in the database merges the twomochila; foundname === 'Gojira' // truefoundkingOfMonsters // true
Using factories:
{ thisid = optsid; thisname = optstitle; thisdimensions = optsdimensions; thiscountId = ++count;} // when a factory is registered, its `create` property is passed the object from `load`Widget { return opts;}; var mochila = ;var count = 0;var cube = id: 0 title: 'Cube' isCube: true dimensions: width: 10 height: 10 depth: 10 ; var found; mochila;mochila;mochila; found = mochila; found instanceof Widget // truefoundtitle // undefinedfoundname // 'Cube'foundisCube // undefinedfoundcountId // 1typeof founddimensions // 'object'founddimensions === cubedimensions // 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~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
Param | Type | Description |
---|---|---|
name | String |
The name to be used for the collection. |
Boolean
mochila.hasCollection(name) ⇒ 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.
Param | Type | Description |
---|---|---|
name | String |
Name of the collection you're checking to see exists. |
Array.<String>
mochila.collectionNames() ⇒ 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
Param | Type | Description |
---|---|---|
name | String |
The name of the collection whose factory you want to delete from the mochila. |
mochila.addFactory(name, factory)
Register a factory that the named collection will use to create new models.
Kind: instance method of Mochila
Param | Type | Description |
---|---|---|
name | String |
The name of the collection. |
factory | function | Object |
An existing function, or an object that will create a new object of its type when its .create() method is invoked. |
Model
mochila.createModelOfType(name, ...objs) ⇒ 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.
Param | Type | Description |
---|---|---|
name | String |
The name of the collection. |
...objs | Object |
Optional. When a factory exists, these are passed to factory.create() . When no factory exists, a deep copy is made of each object into the newly-created 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
Param | Type | Description |
---|---|---|
name | String |
The name of the collection into which the models will be added. |
payload | Object | Array.<Object> | Model | Array.<Model> |
An object or array of objects to use for creating new models, or a model or array of models to be placed into the collection as is. 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. |
Array
mochila.sortBy(name, [key]) ⇒ 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
.
Param | Type | Default | Description |
---|---|---|---|
name | String |
The name of the collection. | |
[key] | String |
id |
A key name to sort by. |
Array
mochila.all(name, [key], [val]) ⇒ 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.
Param | Type | Default | Description |
---|---|---|---|
name | String |
The name of the collection. | |
[key] | String |
id |
The key to search on within models in the collection. |
[val] | Number | String | Date |
The value you're looking for in key . |
Model
| undefined
mochila.find(name, [key], val) ⇒ 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.
Param | Type | Default | Description |
---|---|---|---|
name | String |
The name of the collection you wish to search through. | |
[key] | String |
id |
The key to search on within models in the collection. |
val | Number | String | Date |
The value you're looking for in key . |
Array.<Model>
mochila.removeModels(name, models) ⇒ 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.
Param | Type | Description |
---|---|---|
name | String |
The name of the collection you wish to remove from. |
models | Model | Array.<Model> |
A model or array of models you wish to remove. |
Array.<Model>
mochila.removeWhere(name, [key], val) ⇒ 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.
Param | Type | Default | Description |
---|---|---|---|
name | String |
The name of the collection you wish to search through. | |
[key] | String |
id |
The key to search on within models in the collection. |
val | Number | String | Date |
The value you're looking for in key . |
License
MIT