fossa v2.6.18

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

• Object.readable
• Object.writable
• Object.fossa

Collection or Model functions

• Object.use
• Object.client
• Object.define
• Object.setup

Instances

• Collection
• Model

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

• Collection.model
• Collection._database

Fossa.Collection instance

• Collection.id
• Collection.sync
• Collection.clone

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. CallingCollection.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

• Model.idAttribute
• Model._stored

Fossa.Model instance

• Model.sync
• Model.save
• Model.isNew
• Model.clone
• Model.stored

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.