Skip to content

Latest commit

 

History

History
713 lines (515 loc) · 17.5 KB

Readme.md

File metadata and controls

713 lines (515 loc) · 17.5 KB
Raw

mongoskin Build Status Dependencies

logo

This project is a wrapper for node-mongodb-native. The base API is same at the node-mongodb-native, you may want to familiarise yourself with the node-mongodb-native documentation first.

Compatible mongodb versions

You should use mongodb version 1.3.3. Prior mongodb versions might not work.

Automated tests

You can run the automated test by running make test. The tests have a coverage of 89% and you can browse the results.

Mongoskin documentation

Nodejs mongodb driver comparison

node-mongodb-native

One of the most powerful Mongo drivers is node-mongodb-native. Most other drivers build on top of it, including mongoskin. Unfortunately, it has an awkward interface with too many callbacks. Also, mongoskin provides helper method bindings on Collection instances.

See mongodb-native

mongoose

Mongoose provides a full blown ORM view of Collections and Models, and you are required to define a schema first. But why does mongodb need a schema? If you're like me, then you prefer to drive your schema from the application layer, and use fields without having had to define them beforehand.

Mongoose also provides a data abstraction layer with validation support. Again, if you're like me, then you would prefer a lighter weight solution and to craft your own validation. I think this is the tao of mongodb.

mongoskin

Mongoskin is an easy to use driver of mongodb for nodejs, it is similar with mongo shell, powerful like node-mongodb-native, and supports binding helper methods to Collections.

It provides the full features of node-mongodb-native, and makes good use of futures.

For validation you can use node-iform.

Back to index

Install

$ npm install mongoskin

Back to index

Quick start

Is mongoskin synchronized?

Nope! It is asynchronized, it use the future pattern. Mongoskin is the future layer above node-mongodb-native

Easier to connect

You can connect to mongodb easier now.

var mongo = require('mongoskin');
mongo.db('localhost:27017/testdb').collection('blog').find().toArray(function (err, items) {
  console.dir(items);
})

Server options and BSON options

You can also set auto_reconnect options querystring. And native_parser options will automatically set if native_parser is available.

var mongo = require('mongoskin');
var db = mongo.db('localhost:27017/test?auto_reconnect');

Similar API to node-mongodb-native

You can do everything that node-mongodb-native can do.

db.createCollection(...);
db.collection('user').ensureIndex([['username', 1]], true, function (err, replies) {});
db.collection('posts').hint = 'slug';
db.collection('posts').findOne({slug: 'whats-up'}, function (err, post) {
  // do something
});

Easier cursor

db.collection('posts').find().toArray(function (err, posts) {
  // do something
});

MVC helpers

You can bind additional methods for collection. It is very useful if you want to use MVC patterns with nodejs and mongodb. You can also invoke collection by properties after bind, it could simplfy your require.

To keep your code in line with DRY principles, it's possible to create your own data layer by for example, setting up your own validators and/or default values inside the MVC methods as shown below in the config example

db.bind('posts', {
  findTop10 : function (fn) {
   this.find({}, {limit:10, sort:[['views', -1]]}).toArray(fn);
  },
  removeTagWith : function (tag, fn) {
   this.remove({tags:tag},fn);
  }
 } 
});

db.bind('settings', {

  getAll: function(user, fn) {
  
  	this.find({user: user}).toArray(function(err, settings) {
  	
  	  // We want to set a default currency from within our app instead of storing it
  	  // for every user
  	  settings.currency = (typeof settings.currency !== "undefined") ? settings.currency : 'USD';
  		
  	  fn(err, settings);
  	
  	});
  }
});

     
db.bind('comments');

db.collection('posts').removeTagWith('delete', function (err, replies) {
  //do something
});

db.posts.findTop10(function (err, topPosts) {
  //do something
});

db.comments.find().toArray(function (err, comments) {
  //do something
});

Back to index

API documentation

for more information, see the source.

Back to index

Module

MongoSkin Url format

[*://][username:password@]host[:port][/database][?auto_reconnect[=true|false]]`

e.g.

localhost/blog
mongo://admin:[email protected]:27017/blog?auto_reconnect
127.0.0.1?auto_reconnect=false

db(serverURL[s], dbOptions, replicasetOptions)

Get or create instance of SkinDb.

var db = mongoskin.db('localhost:27017/testdb?auto_reconnect=true&poolSize=5');

for ReplSet server

var db = mongoskin.db([
  '192.168.0.1:27017/?auto_reconnect=true',
  '192.168.0.2:27017/?auto_reconnect=true',
  '192.168.0.3:27017/?auto_reconnect=true'
], {
  database: 'testdb',
  safe: true
}, {
  connectArbiter: false,
  socketOptions: {
    timeout: 2000
  }
});

router(select)

select is function(collectionName) returns a database instance, means router collectionName to that database.

var db = mongo.router(function (coll_name) {
  switch(coll_name) {
    case 'user':
    case 'message':
      return mongo.db('192.168.1.3/auth_db');
    default:
      return mongo.db('192.168.1.2/app_db');
  }
});
db.bind('user', require('./shared-user-methods'));
var users = db.user; //auth_db.user
var messages = db.collection('message'); // auth_db.message
var products = db.collection('product'); //app_db.product

classes extends frome node-mongodb-native

  • BSONPure
  • BSONNative
  • BinaryParser
  • Binary
  • Code
  • DBRef
  • Double
  • MaxKey
  • MinKey
  • ObjectID
  • Symbol
  • Timestamp
  • Long
  • BaseCommand
  • DbCommand
  • DeleteCommand
  • GetMoreCommand
  • InsertCommand
  • KillCursorCommand
  • QueryCommand
  • UpdateCommand
  • MongoReply
  • Admin
  • Collection
  • Connection
  • Server
  • ReplSetServers
  • Cursor
  • Db
  • connect
  • Grid
  • Chunk
  • GridStore
  • native
  • pure

Back to index

SkinServer

SkinServer(server)

Construct SkinServer from native Server instance.

db(dbname, username=null, password=null)

Construct SkinDb from SkinServer.

Back to index

SkinDb

SkinDb(db, username=null, password=null)

Construct SkinDb.

open(callback)

Connect to database, retrieval native Db instance, callback is function(err, db).

collection(collectionName)

Retrieval SkinCollection instance of specified collection name.

bind(collectionName)

bind(collectionName, SkinCollection)

bind(collectionName, extendObject1, extendObject2 ...)

Bind SkinCollection to db properties as a shortcut to db.collection(name). You can also bind additional methods to the SkinCollection, it is useful when you want to reuse a complex operation. This will also affect db.collection(name) method.

e.g.

db.bind('book', {
  firstBook: function (fn) {
    this.findOne(fn);
  }
});
db.book.firstBook(function (err, book) {});

all the methods from Db.prototype

See Db of node-mongodb-native for more information.

Back to index

SkinCollection

See Collection of node-mongodb-native for more information.

### open(callback)

Retrieval native Collection instance, callback is function(err, collection).

id(hex)

Equivalent to

db.bson_serializer.ObjectID.createFromHexString(hex);

See ObjectID.createFromHexString

Collection operation

checkCollectionName(collectionName)
options(callback)
rename(collectionName, callback)
drop(callback)

Indexes

createIndex(fieldOrSpec, unique, callback)
ensureIndex(fieldOrSpec, unique, callback)
indexInformation(callback)
dropIndex(indexName, callback)
dropIndexes(callback)

See mongodb-native indexes

Queries

See mongodb-native queries

findItems(..., callback)

Equivalent to

collection.find(..., function (err, cursor) {
  cursor.toArray(callback);
});

See Collection.find

findEach(..., callback)

Equivalent to

collection.find(..., function (err, cursor) {
  cursor.each(callback);
});

See Collection.find

findById(id, ..., callback)

Equivalent to

collection.findOne({_id, ObjectID.createFromHexString(id)}, ..., callback);

See Collection.findOne

find(...)

If the last parameter is function, it is equivalent to native Collection.find method, else it will return a future SkinCursor.

e.g.

// callback
db.book.find({}, function (err, cursor) {/* do something */});
// future SkinCursor
db.book.find().toArray(function (err, books) {/* do something */});

normalizeHintField(hint)

find

/**
 * Various argument possibilities
 * 1 callback
 * 2 selector, callback,
 * 2 callback, options  // really?!
 * 3 selector, fields, callback
 * 3 selector, options, callback
 * 4,selector, fields, options, callback
 * 5 selector, fields, skip, limit, callback
 * 6 selector, fields, skip, limit, timeout, callback
 *
 * Available options:
 * limit, sort, fields, skip, hint, explain, snapshot, timeout, tailable, batchSize
 */

findAndModify(query, sort, update, options, callback)

/**
  Fetch and update a collection
  query:        a filter for the query
  sort:         if multiple docs match, choose the first one in the specified sort order as the object to manipulate
  update:       an object describing the modifications to the documents selected by the query
  options:
    remove:   set to a true to remove the object before returning
    new:      set to true if you want to return the modified object rather than the original. Ignored for remove.
    upsert:       true/false (perform upsert operation)
**/

findOne(queryObject, options, callback)

Aggregation

mapReduce(map, reduce, options, callback)

e.g.

var map = function () {
  emit(test(this.timestamp.getYear()), 1);
}

var reduce = function (k, v){
  count = 0;
  for (i = 0; i < v.length; i++) {
    count += v[i];
  }
  return count;
}
var options = {scope: {test: new client.bson_serializer.Code(t.toString())}};
collection.mapReduce(map, reduce, options, function (err, collection) {
  collection.find(function (err, cursor) {
    cursor.toArray(function (err, results) {
    test.equal(2, results[0].value)
    finished_test({test_map_reduce_functions_scope:'ok'});            
  })
})

group(keys, condition, initial, reduce, command, callback)

e.g.

collection.group([], {}, {"count":0}, "function (obj, prev) { prev.count++; }", true, function(err, results) {});

count(query, callback)

distinct(key, query, callback)

Inserting

insert(docs, options, callback)

Updating

save(doc, options, callback)

/**
  Update a single document in this collection.
    spec - a associcated array containing the fields that need to be present in
      the document for the update to succeed

    document - an associated array with the fields to be updated or in the case of
      a upsert operation the fields to be inserted.

  Options:
    upsert - true/false (perform upsert operation)
    multi - true/false (update all documents matching spec)
    strict - true/false (perform check if the operation failed, required extra call to db)
  Deprecated Options:
    safe - true/false (perform check if the operation failed, required extra call to db)
**/

update(spec, document, options, callback)

updateById(_id, ..., callback)

Equivalent to

collection.update({_id, ObjectID.createFromHexString(id)}, ..., callback);

See Collection.update

Removing

remove(selector, options, callback)

removeById(_id, options, callback)

Back to index

SkinCursor

See Cursor of node-mongodb-native for more information.

All these methods will return the SkinCursor itself.

sort(keyOrList, [direction], [callback])
limit(limit, [callback])
skip(skip, [callback])
batchSize(skip, [callback])

toArray(callback)
each(callback)
count(callback)
nextObject(callback)
getMore(callback)
explain(callback)

Back to index

How to validate input?

I wrote a middleware to validate post data, node-iform base on node-validator

Authors

Below is the output from git-summary.

 project: node-mongoskin
 commits: 112
 active : 54 days
 files  : 39
 authors: 
    49  Lin Gui                 43.8%
    34  guilin 桂林           30.4%
     9  fengmk2                 8.0%
     5  guilin                  4.5%
     2  François de Metz       1.8%
     2  Paul Gebheim            1.8%
     2  Gui Lin                 1.8%
     1  humanchimp              0.9%
     1  Aneil Mallavarapu       0.9%
     1  wmertens                0.9%
     1  Harvey McQueen          0.9%
     1  Joe Faber               0.9%
     1  Matt Perpick            0.9%
     1  Quang Van               0.9%
     1  Rakshit Menpara         0.9%
     1  Wout Mertens            0.9%

License

(The MIT License)

Copyright (c) 2011 - 2012 kissjs.org

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.