fossa
v2.6.18
Published
Backbone powered model interface to MongoDB, thin wrapper around MongoJS
Downloads
77
Maintainers
Readme
Fossa
Backbone powered model interface to MongoDB, thin wrapper around MongoDB. Fossa uses the API provided by Backbone and proxies it methods to the native MongoDB driver.
Fossa provides first class database and collection control. This great power comes with responsibilities. The developer should manage database switches, seperation of concerns and data integrity. In return Fossa will provide an easy interface for interaction with the objects in MongoDB.
Installation
npm install fossa --save
Examples
Will follow asap
Versioning
Fossa's version is synced to MongoDB releases (since 2.6.0). For instance, version 2.6.x will be compatible with MongDB 2.6 and patch releases.
Documentation
The API of fossa is 1:1 compatible with backbone. For a good reference of available methods see the BackboneJS documentation.
Table of Contents
Collection or Model properties
Collection or Model functions
Instances
Instantiation
Create a new Fossa instance by calling the constructor. After construction Fossa
will expose a model and collection sprinkled with mongoDB proxy methods. The
connection will be prepared and exposed through Fossa.mongoclient
. The native
C++ parser of MongoDB will be enabled by default.
var fossa = new Fossa({
host: '127.0.0.1' // defaults to localhost
, port: '1337' // defaults to 27017
, options: { native_parser: true } // optional options
});
Object.readable
Create a read-only property on the Collection
or Model
. This method is a
shorthand for Object.defineProperty
and not enumerable or writable.
- key: {String} required property key
- value: {Mixed} required value can be string, array, object or function
var collection = new fossa.Collection;
collection.readable('url', 'http://not.changable.after');
Object.writable
Create a writable property on the Collection
or Model
. This method is a
shorthand for Object.defineProperty
with writable and configurable properties.
- key: {String} required property key
- value: {Mixed} required value can be string, array, object or function
var model = new fossa.Model;
model.writable('url', 'http://is.changeable.after');
model.url = 'http://changed.url.com';
Object.fossa
Read-only reference to the Fossa
instance. On construction of the Collection
or Model
the instance is set. The instance is used to connect to the database.
var model = new fossa.Model;
model.fossa.connect('mydatabase', 'mycollection', function done(err, client) {
console.log('connected to mydatabase');
});
Object.use
Collections are the equivalent of a MongoDB database. However, the mapping to a specific database is not forced or persisted automatically. Any collection can be switched to another database name. Only data in memory will be saved to the database.
- database: {String} required database name
account.use('observer').save(...);
Object.client
Establishes a connection with MongoDB. The Fossa
instance will make sure
connections are made from one pool. The completion callback receives two arguments.
An error (if any) argument and an object representating a connected client.
- done: {Function} required completion callback
account.client(function done(err, client) {
console.log(client);
})
Object.define
Helper method to define a key:value on the Collection
or a Model
.
- key: {String} required key
- value: {Mixed} required value
account.define('username', 'idontwantanaccount');
Object.setup
Add before and after hooks for specific methods. The hooks need to be define on
the model as objects. Where the first part is a known synchronization method, per
example create
. In the example below the method username
will be called before
and after the the username property is stored/changed.
- hooks: {Array} keys of hooks to use
var Model = Base.extend({
before: { 'create username': 'username' },
after: { 'delete username': 'username' }
})
, model = new Model().setup(['before', 'after']);
Collection
Fossa will expose a Backbone Collection
, which can be extended upon to suit your
needs. This offers flexibility, however beware you don't overwrite our
proxied methods. Initialize the Collection before use.
var Accounts = fossa.Collection.extend({
database: 'observer'
});
//
// Initialize a new account.
//
var accounts = new Accounts;
Fossa.Collection properties
Fossa.Collection instance
Fossa Collections have no required keys. However, before saving models a database should always be provided.
Collection.model
The default model for a Collection
is the fossa.Model. Calling
Collection.add`
will create a new Model of that type on the Collection. If you like to define a
different default Model, extend the Collection.
var Accounts = fossa.Collection.extend({
model: fossa.Model.extend({
idAttribute: 'ID'
})
})
Collection._database
Used to store the current database name. All synchronization will be done against
the database set on this key. Can be set by prodiving options.database = 'mydb
to
the constructor of the Collection.
Collection.id
Find a Model
in the Collection
by ObjectId
. An ObjectId
is a
native property stored on each MongoDB model. Only one model is
returned. The find is performed against the Models in Collection memory only.
- key: {ObjectId} required 24 byte hex string, valid MongoDB ObjectId
var user = account.id('4cdfb11e1f3c000000007822');
console.log(user);
Collection.sync
Synchronise the Models in Collection memory to MongoDB. Manually calling this
method is usally not required or advised. The global Backbone.sync
is
overwritten and will proxy to this method. To mimic Backbone.sync
patterns a promise is returned.
If the method is create
and the colletion contains any models that
are already stored, the method will be switched to update. Similarly if
there are new models in the collection, options.upsert = true
will be set.
- method: {String} optional CREATE, READ, UPDATE or DELETE, defaults to create
- collection: {Collection} optional collection object or this
- options: {Object} optional options
account.sync('create', account, {}).done(function done(err, result) {
console.log(result);
});
Collection.clone
Duplicated behavior of the original Collection.clone
method. With the exception
that options are provided to restore the url
and database
properties on the
object. This is done to ensure sync
works with fresh objects and does not
affect the used models.
var users = new fossa.Collection([{ firstname: 'Davy' }, { firstname: 'Jones' }])
, otherGroup = users.clone();
Model
Fossa will expose a Backbone Model
, which can be extended with additional
properties and values.
var User = fossa.Model.extend({
firstname: 'Davy',
lastname: 'Jones'
});
Fossa.Model properties
Fossa.Model instance
Model.idAttribute
Sets the reference ID for all models to _id
, which is the internal MongoDB ID.
This will ensure models can be correctly resolved when synchronized. This can be
changed to any user defined ID, however this is not advised. MongoDB will ensure
each model is suppied with a unique ID on _id
.
var User = fossa.Model.extend({
idAttribute: 'cid'
});
If you like to instantiate a Model with an existing id. For instance to fetch
Model data already stored in the database, pass an ObjectId to _id
.
var User = new fossa.Model({
_id: new fossa.Model.ObjectId('5492adcaded9fc7b72f2ddae')
});
Model._stored
Keep track of the current state of the Model. If the _id
of the Model changes,
the _stored
state will be updated. This property is set on construction and used
by isNew.
Model.sync
Synchronise the Model to MongoDB. Manually calling this method is usally not
required or advised. The global Backbone.sync
is overwritten and will proxy to
this method. To mimic Backbone.sync patterns a promise is returned.
Like with Collection.sync
the method will be changed to update if the Model has
a _stored
property.
- method: {String} optional CREATE, READ, UPDATE or DELETE, defaults to create
- model: {Model} optional model object or this
- options: {Object} optional options
user.sync('create', user, {}).done(function done(err, result) {
console.log(result);
});
Model.save
The default model.save is overwritten. This is done to ensure an XHR object is
returned from the method. otherwise if validation fails, false
would be
returned. Other than that the save
method proxies to the default method. In
other words you can now do the following without worrying about the return value.
If the validation fails, an error is returned.
user.save().done(function done(error, result) {
console.log(error);
})
Model.isNew
Helper function to check if the current Model is stored in the database yet. The method will return a boolean, if false the Model has been stored in the database.
var stored = user.isNew();
Model.clone
Duplicated behavior of the original Model.clone
method. With the exception
that options are provided to restore the urlRoot
and database
properties on
the object. This is done to ensure sync
works with fresh objects and does not
affect the model.
var user = new fossa.Model({ firstname: 'Davy', lastname: 'Jones' })
, otherUser = user.clone();
Model.stored
Simple helper to update the _stored
property of the model. If no argument is
passed the model will be tagged as stored. Pass false
to set the stored state
to false
. Under normal circumstances this method should not be called. sync
will handle updates to the _stored
property.
- state: {Boolean} optional pass explicit false to set stored to false
user.stored(); // Model will be tagged as stored.
user.stored(false); // Model will be tagged as not stored.
Tests
Test can be run as follows, make sure all devDependencies have been installed.
npm test
License
Fossa is released under MIT.