Wondering what’s next for npm?Check out our public roadmap! »

    mongo-repo

    1.0.2 • Public • Published

    mongo-repo

    Fast, lightweight, promise like repository implementation over mongodb.
    Defines a clear api to perform CRUD operations over a mongodb collection. All repository methods returns promises.
    The connectDB(connectionString) method resolves with a database object that is a MongoClient with an extended functionallity to access a collection as a repository: db.repo(collectionName).

    var repo = require('mongo-repo');
     
    var db
    repo.connectDB('my connection string').then(function(client){
      db = client
    }).then(run)
     
    function run(){
      db.repo('users').add({ userName: 'JohnDoe', createdOn: db.$currentDate()})
        .then(function(user){
          console.log('Added user with id: ' + user._id)
          
          // count all documents
          return db.repo('users').count()
        })
        .then(function(n){
          console.log('Total users now: ' + n)
          
          // get the document
          return db.repo('users')
            .getOne({userName: 'JohnDoe'})
        })
        .then(function(user){
          // update the document
          return db.repo('users')
            .update({_id: user._id, userName: 'Joe', modified: db.$currentDate()})
        })
        .then(function(){
          // delete the document
          return db.repo('users')
            .removeOne({userName: 'Joe'})
        })
    }

    The repository object is a thin wrapper over mongodb collections, that is lazily created only once per request. The database object is also extended with operators like db.$inc(), db.$mul() etc. that can be used to pass update instructions in a cleaner way, rather then native mongo dot notation. For more details about mongodb update operators see mongo-dot-notation.

    Installation

    Install from npm:

    npm install mongo-repo --save

    Connecting to DB and accesing the repository

    A db client that exposes repositories can be connected using the connectDB method.

    var Repository = require('mongo-repo')
    Repository.connectDB('your connection string...').then(function(db){
      // access a repository
      var repo = db.repo('my_collection_name')
    })

    Alternatively, you can manyally create a repository instance:

    var MongoClient = require('mongodb').MongoClient;
     
    var url = 'mongodb://localhost:27017/mydatabase';
    MongoClient.connect(url, function(err, db) {
      var repo = Repository.create(db.collection('my_collection_name'))
    }) 

    Methods

    CRUD methods are divided into 3 categories:

    • CRUD by id/document
    // Get the document by id
    // @document - either an ObjectID, a valid string representation of an ObjectID
    //            or an abject with _id field
    db.repo(collectionName).get(document) 
     
    // Get a subset of document's fields by id
    // @document - either an ObjectID, a valid string representation of an ObjectID
    //            or an abject with _id field
    // @projection - an object specifying which fields to get
    db.repo(collectionName).project(document, projection)
     
    // Add a new document; this method always produces inserts
    // @document - the document to be inserted
    db.repo(collectionName).add(document) 
     
    // Adds or updates a new document; when the object exists then is updated, otherwise inserted.
    // @document - the document to be inserted or updated
    db.repo(collectionName).addOrUpdate(document) 
     
    // update a document only if exists
    // @document - an object identified by _id field (mandatory) and fields to update
    db.repo(collectionName).update(document)
     
    // delete a document
    // @document - either an ObjectID, a valid string representation of an ObjectID
    //            or an abject with _id field
    db.repo(collectionName).remove(document)
    • CRUD only one
    // Get the first document that matches the criteria
    // @criteria - same style as used by mongo
    db.repo(collectionName).getOne(criteria) 
     
    // Get a subset of the (first) document's fields that matches the criteria
    // @criteria - same style as used by mongo
    // @projection - an object specifying which fields to get
    db.repo(collectionName).projectOne(criteria, projection)
     
    // add if not exists, or update first document matching the criteria
    // @criteria - same style as used by mongo
    // @document - an object with fields to update
    db.repo(collectionName).addOrUpdateOne(criteria, document)
     
    // update only first document that matches the criteria
    // @criteria - same style as used by mongo
    // @document - an object with fields to update
    db.repo(collectionName).updateOne(criteria, document)
     
    // deletes the first document that matches the criteria
    // @criteria - same style as used by mongo
    db.repo(collectionName).removeOne(criteria)
    • CRUD multiple
     
    // gets all documents matching the criteria
    // @criteria - same style as used by mongo
    // @sort (optional) - an object specifying by which fields to sort 
    // @skip (otional) - an int specifying how many documents to skip from the beggining
    // @take (optional) - an int specifying how many documents to take
    db.getAll(criteria, sort, skip, take)
     
    // gets a subset of fields for all documents matching the criteria
    // @criteria - same style as used by mongo
    // @projection - an object specifying which fields to get
    // @sort (optional) - an object specifying by which fields to sort 
    // @skip (otional) - an int specifying how many documents to skip from the beggining
    // @take (optional) - an int specifying how many documents to take
    db.projectAll(criteria, projection, sort, skip, take)
     
    // adds the document if there are no matches for the criteria,
    // otherwise updates all documents that matches the criteria
    // @criteria - same style as used by mongo
    // @document - an object with fields to update
    db.addOrUpdateAll(criteria, document)
     
    // updates all documents that matches the criteria
    // @criteria - same style as used by mongo
    // @document - an object with fields to update
    db.updateAll(criteria, document)
     
    // deletes all documents that matches the criteria
    // @criteria (optional) - same style as used by mongo
    db.removeAll(criteria)

    Additionally, there is a count method.

    // @criteria (optional) - same style as used by mongo
    db.repo(collectionName).count(criteria)

    More examples

    Getting all IDs of the users with age >= 25.

    db.repo('my_collection').projectAll({age: {$gte: 25}}, {_id: 1})
      .then(function(ids){ console.log(ids) })

    Updating a document using operators.

    var documentId;
    db.repo('my_collection').update({
      _id: documentId,
      visits: db.$inc(), // increment the field
      name: db.$rename('fullName'), // renames the field from name to fullName
      blocked: db.$unset() // deletes the field from the document
      updatedOn: db.$currentDate() // sets the current date
    })

    Add or update a document:

    var doc = {
      _id: db.$newid(),
      name: 'johndoe',
      createdOn: db.$setOnInsert(new Date())
    }
     
    db.repo('users').addOrUpdate(doc).then(function(res){
      console.log(res) // {_id: '...', name: 'johndoe', createdOn: '...'}
    }).then(function(){
      return db.repo('users').addOrUpdate({_id: doc._id, email: 'john@doe.com'})
    }).then(function(){
      return db.repo('users').get(doc)
    }).then(function(res){
      console.log(res) // {_id: '...', name: 'johndoe', createdOn: '...', email: 'john@doe.test'}
    })

    Copyright © 2015 Dumitru Deveatii, released under the MIT license

    Install

    npm i mongo-repo

    DownloadsWeekly Downloads

    1

    Version

    1.0.2

    License

    MIT

    Last publish

    Collaborators

    • avatar