fossa

    2.6.18 • Public • Published

    Fossa

    Version npmBuild StatusDependenciesCoverage Status

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

    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.

    Install

    npm i fossa

    DownloadsWeekly Downloads

    26

    Version

    2.6.18

    License

    MIT

    Last publish

    Collaborators

    • swaagie