{
"name": "mongoskin",
"description": "The future layer above node-mongodb-native",
"version": "0.5.0",
"author": {
"name": "Gui Lin",
"email": "guileen@gmail.com"
},
"homepage": "https://github.com/kissjs/node-mongoskin",
"repository": {
"type": "git",
"url": "git://github.com/guileen/node-mongoskin.git"
},
"bugs": {
"url": "https://github.com/kissjs/node-mongoskin/issues"
},
"main": "./index.js",
"keywords": [
"mongodb",
"database",
"nosql"
],
"engines": {
"node": ">= 0.4.0"
},
"dependencies": {
"mongodb": "1.2.x"
},
"devDependencies": {
"mocha": "*",
"jscover": "*",
"should": "*"
},
"scripts": {
"test": "make test"
},
"directories": {
"example": "./examples",
"lib": "./lib/mongoskin"
},
"license": "MIT",
"contributors": [
{
"name": "Gui Lin",
"email": "guileen@gmail.com",
"url": "https://github.com/guileen"
},
{
"name": "François de Metz",
"email": "francois@2metz.fr",
"url": "https://github.com/francois2metz"
},
{
"name": "fengmk2",
"email": "fengmk2@gmail.com",
"url": "http://fengmk2.github.com"
},
{
"name": "Quang Van",
"email": "quangvvv@gmail.com",
"url": "https://github.com/quangv"
},
{
"name": "Matt Perpick",
"email": "clutchski@gmail.com",
"url": "https://github.com/clutchski"
},
{
"name": "humanchimp",
"email": "morphcham@gmail.com",
"url": "https://github.com/humanchimp"
},
{
"name": "Joe Faber",
"email": "joe.faber@mandiant.com",
"url": "https://github.com/jlfaber"
},
{
"name": "Harvey McQueen",
"email": "hmcqueen@gmail.com",
"url": "https://github.com/hmcqueen"
},
{
"name": "Paul Gebheim",
"email": "pgebheim@monkeyinferno.com",
"url": "https://github.com/paulirish"
},
{
"name": "Aneil Mallavarapu",
"email": "aneil@blipboard.com",
"url": "https://github.com/amallavarapu"
},
{
"name": "wmertens",
"email": "Wout.Mertens@gmail.com",
"url": "https://github.com/wmertens"
},
{
"name": "Rakshit Menpara",
"email": "deltasquare4@gmail.com",
"url": "https://github.com/deltasquare4"
}
],
"readme": "# mongoskin [](http://travis-ci.org/kissjs/node-mongoskin)\n\n\n\nThis project is a wrapper of [node-mongodb-native](https://github.com/mongodb/node-mongodb-native).\nThe api is same to node-mongodb-native, please see the [document](http://mongodb.github.com/node-mongodb-native/) first.\n\n## Test\n\n* test results: [test_results.md](https://github.com/kissjs/node-mongoskin/blob/master/test_results.md)\n* jscoverage: [**89%**](http://fengmk2.github.com/coverage/mongoskin.html)\n\n## Test pass [mongodb] versions\n\n* >= 0.9.8 < 1.0.0: mongodb have bug, it will throw a `TypeError: object is not a function` \n when connection open error.\n* 1.0.x\n* 1.1.x\n* 1.2.x\n\n```bash\n$ make test\n```\n\n\n\n# Mongoskin document\n\n* [Nodejs mongodb drivers comparation](#comparation)\n* [Install](#install)\n* [Quick Start](#quickstart)\n * [Connect easier](#quickstart-1)\n * [Server options and BSON options](#quickstart-2)\n * [Similar API with node-mongodb-native](#quickstart-3)\n * [Cursor easier](#quickstart-4)\n * [MVC helper](#quickstart-5)\n* [Documentation](#documentation)\n * [Module](#module)\n * [SkinServer](#skinserver)\n * [SkinDb](#skindb)\n * [SkinCollection](#skincollection)\n * [Additional methods](#additional-collection-op)\n * [Collection operation](#inherit-collection-op)\n * [Indexes](#inherit-indexes)\n * [Querying](#inherit-query)\n * [Aggregation](#inherit-aggregation)\n * [Inserting](#inherit-inserting)\n * [Updating](#inherit-updating)\n * [Removing](#inherit-removing)\n * [SkinCursor](#skincursor)\n\n\n\nNodejs Mongodb Driver Comparison\n========\n\nnode-mongodb-native\n--------\n\nOne of the most powerful Mongo drivers is node-mongodb-native. Most other drivers build\non top of it, including mongoskin. Unfortunately, it has an awkward interface with too many \ncallbacks. Also, mongoskin needs a way to hold a Collection instance as an MVC model.\n \nSee [mongodb-native](https://github.com/christkv/node-mongodb-native/tree/master/docs)\n\nmongoose\n--------\n\nMongoose provides an ORM way to hold Collection instance as Model,\n you should define schema first. But why mongodb need schema?\n Some guys like me, want to write code from application layer but not database layer,\n and we can use any fields without define it before.\n\n Mongoose provide a DAL that you can do validation, and write your middlewares.\n But some guys like me would like to validate manually, I think it is the tao of mongodb.\n\n If you don't thinks so, [Mongoose-ORM](https://github.com/LearnBoost/mongoose) is probably your choice.\n\nmongoskin\n--------\n\nMongoskin is an easy to use driver of mongodb for nodejs,\n it is similar with mongo shell, powerful like node-mongodb-native,\n and support additional javascript method binding, which make it can act as a Model(in document way).\n\nIt will provide full features of [node-mongodb-native](https://github.com/christkv/node-mongodb-native),\n and make it [future](http://en.wikipedia.org/wiki/Future_%28programming%29).\n\nIf you need validation, you can use [node-iform](https://github.com/guileen/node-iform).\n\n[Back to index](#index)\n\n\n\nInstall\n========\n\n```bash\n$ npm install mongoskin\n```\n\n[Back to index](#index)\n\n\n\n\nQuick Start\n========\n\n **Is mongoskin synchronized?**\n\nNope! It is asynchronized, it use the [future pattern](http://en.wikipedia.org/wiki/Future_%28programming%29).\n**Mongoskin** is the future layer above [node-mongodb-native](https://github.com/christkv/node-mongodb-native)\n\n\n\nConnect easier\n--------\nYou can connect to mongodb easier now.\n\n```js\nvar mongo = require('mongoskin');\nmongo.db('localhost:27017/testdb').collection('blog').find().toArray(function (err, items) {\n console.dir(items);\n})\n```\n\n\n\nServer options and BSON options\n--------\nYou can also set `auto_reconnect` options querystring.\nAnd native_parser options will automatically set if native_parser is available.\n\n```js\nvar mongo = require('mongoskin');\nvar db = mongo.db('localhost:27017/test?auto_reconnect');\n```\n\n\n\nSimilar API with node-mongodb-native\n--------\nYou can do everything that node-mongodb-native can do.\n\n```js\ndb.createCollection(...);\ndb.collection('user').ensureIndex([['username', 1]], true, function (err, replies) {});\ndb.collection('posts').hint = 'slug';\ndb.collection('posts').findOne({slug: 'whats-up'}, function (err, post) {\n // do something\n});\n```\n\n\n\nCursor easier\n--------\n\n```js\ndb.collection('posts').find().toArray(function (err, posts) {\n // do something\n});\n```\n\n\n\nMVC helper\n--------\n\nYou can bind **additional methods** for collection.\nIt is very useful if you want to use MVC patterns with nodejs and mongodb.\nYou can also invoke collection by properties after bind,\nit could simplfy your `require`.\n\nTo keep your code in line with DRY principles, it's possible to create your own\ndata layer by for example, setting up your own validators and/or default values\ninside the MVC methods as shown below in the config example\n\n```js\ndb.bind('posts', {\n findTop10 : function (fn) {\n this.find({}, {limit:10, sort:[['views', -1]]}).toArray(fn);\n },\n removeTagWith : function (tag, fn) {\n this.remove({tags:tag},fn);\n }\n } \n});\n\ndb.bind('settings', {\n\n getAll: function(user, fn) {\n \n \tthis.find({user: user}).toArray(function(err, settings) {\n \t\n \t // We want to set a default currency from within our app instead of storing it\n \t // for every user\n \t settings.currency = (typeof settings.currency !== \"undefined\") ? settings.currency : 'USD';\n \t\t\n \t fn(err, settings);\n \t\n \t});\n }\n});\n\n \ndb.bind('comments');\n\ndb.collection('posts').removeTagWith('delete', function (err, replies) {\n //do something\n});\n\ndb.posts.findTop10(function (err, topPosts) {\n //do something\n});\n\ndb.comments.find().toArray(function (err, comments) {\n //do something\n});\n```\n\n[Back to index](#index)\n\n\n\n\nDocumentation\n========\n\nfor more information, see the source.\n\n[Back to index](#index)\n\n\n\n\nModule\n--------\n\n### MongoSkin Url format\n\n```\n[*://][username:password@]host[:port][/database][?auto_reconnect[=true|false]]`\n```\n\ne.g.\n\n```\nlocalhost/blog\nmongo://admin:pass@127.0.0.1:27017/blog?auto_reconnect\n127.0.0.1?auto_reconnect=false\n```\n\n### db(serverURL[s], dbOptions, replicasetOptions)\n\nGet or create instance of [SkinDb](#skindb).\n\n```js\nvar db = mongoskin.db('localhost:27017/testdb?auto_reconnect=true&poolSize=5');\n```\n\nfor ReplSet server\n\n```js\nvar db = mongoskin.db([\n '192.168.0.1:27017/?auto_reconnect=true',\n '192.168.0.2:27017/?auto_reconnect=true',\n '192.168.0.3:27017/?auto_reconnect=true'\n], {\n database: 'testdb',\n safe: true\n}, {\n connectArbiter: false,\n socketOptions: {\n timeout: 2000\n }\n});\n```\n\n### router(select)\n\nselect is `function(collectionName)` returns a database instance, means router collectionName to that database.\n\n```js\nvar db = mongo.router(function (coll_name) {\n switch(coll_name) {\n case 'user':\n case 'message':\n return mongo.db('192.168.1.3/auth_db');\n default:\n return mongo.db('192.168.1.2/app_db');\n }\n});\ndb.bind('user', require('./shared-user-methods'));\nvar users = db.user; //auth_db.user\nvar messages = db.collection('message'); // auth_db.message\nvar products = db.collection('product'); //app_db.product\n```\n\n### classes extends frome node-mongodb-native\n\n* BSONPure\n* BSONNative\n* BinaryParser\n* Binary\n* Code\n* DBRef\n* Double\n* MaxKey\n* MinKey\n* ObjectID\n* Symbol\n* Timestamp\n* Long\n* BaseCommand\n* DbCommand\n* DeleteCommand\n* GetMoreCommand\n* InsertCommand\n* KillCursorCommand\n* QueryCommand\n* UpdateCommand\n* MongoReply\n* Admin\n* Collection\n* Connection\n* Server\n* ReplSetServers\n* Cursor\n* Db\n* connect\n* Grid\n* Chunk\n* GridStore\n* native\n* pure\n\n\n[Back to index](#index)\n\n\n\nSkinServer\n--------\n\n### SkinServer(server)\n\nConstruct SkinServer from native Server instance.\n\n### db(dbname, username=null, password=null)\n\nConstruct [SkinDb](#skindb) from SkinServer.\n\n[Back to index](#index)\n\n\n\nSkinDb\n--------\n\n### SkinDb(db, username=null, password=null)\n\nConstruct SkinDb.\n\n### open(callback)\n\nConnect to database, retrieval native\n[Db](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/db.js#L17)\ninstance, callback is function(err, db).\n\n### collection(collectionName)\n\nRetrieval [SkinCollection](#skincollection) instance of specified collection name.\n\n\n\n### bind(collectionName)\n\n### bind(collectionName, SkinCollection)\n\n### bind(collectionName, extendObject1, extendObject2 ...)\n\nBind [SkinCollection](#skincollection) to db properties as a shortcut to db.collection(name).\nYou can also bind additional methods to the SkinCollection, it is useful when\nyou want to reuse a complex operation. This will also affect\ndb.collection(name) method.\n\ne.g.\n\n```js\ndb.bind('book', {\n firstBook: function (fn) {\n this.findOne(fn);\n }\n});\ndb.book.firstBook(function (err, book) {});\n```\n\n### all the methods from Db.prototype\n\nSee [Db](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/db.js#L17) of node-mongodb-native for more information.\n\n[Back to index](#index)\n\n\n\nSkinCollection\n--------\n\nSee [Collection](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/collection.js#L45) of node-mongodb-native for more information.\n\n\n### open(callback)\n\nRetrieval native\n[Collection](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/collection.js#L45)\ninstance, callback is function(err, collection).\n\n### id(hex)\n\nEquivalent to\n\n```js\ndb.bson_serializer.ObjectID.createFromHexString(hex);\n```\n\nSee [ObjectID.createFromHexString](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/bson/bson.js#L548)\n\n\n\n\n### Collection operation\n\n```js\ncheckCollectionName(collectionName)\noptions(callback)\nrename(collectionName, callback)\ndrop(callback)\n```\n\n\n\n### Indexes\n\n```js\ncreateIndex(fieldOrSpec, unique, callback)\nensureIndex(fieldOrSpec, unique, callback)\nindexInformation(callback)\ndropIndex(indexName, callback)\ndropIndexes(callback)\n```\n \nSee [mongodb-native indexes](https://github.com/christkv/node-mongodb-native/blob/master/docs/indexes.md)\n\n\n\n### Queries\n\nSee [mongodb-native queries](https://github.com/christkv/node-mongodb-native/blob/master/docs/queries.md)\n\n#### findItems(..., callback)\n\nEquivalent to\n\n```js\ncollection.find(..., function (err, cursor) {\n cursor.toArray(callback);\n});\n```\n\nSee [Collection.find](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/collection.js#L348)\n\n#### findEach(..., callback)\n\nEquivalent to\n\n```js\ncollection.find(..., function (err, cursor) {\n cursor.each(callback);\n});\n```\n\nSee [Collection.find](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/collection.js#L348)\n\n#### findById(id, ..., callback)\n\nEquivalent to\n\n```js\ncollection.findOne({_id, ObjectID.createFromHexString(id)}, ..., callback);\n```\n\nSee [Collection.findOne](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/collection.js#L417)\n\n#### find(...)\n\nIf the last parameter is function, it is equivalent to native\n[Collection.find](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/collection.js#L348)\nmethod, else it will return a future [SkinCursor](#skincursor).\n\ne.g.\n\n```js\n// callback\ndb.book.find({}, function (err, cursor) {/* do something */});\n// future SkinCursor\ndb.book.find().toArray(function (err, books) {/* do something */});\n```\n\n#### normalizeHintField(hint)\n\n#### find\n\n```js\n/**\n * Various argument possibilities\n * 1 callback\n * 2 selector, callback,\n * 2 callback, options // really?!\n * 3 selector, fields, callback\n * 3 selector, options, callback\n * 4,selector, fields, options, callback\n * 5 selector, fields, skip, limit, callback\n * 6 selector, fields, skip, limit, timeout, callback\n *\n * Available options:\n * limit, sort, fields, skip, hint, explain, snapshot, timeout, tailable, batchSize\n */\n```\n\n#### findAndModify(query, sort, update, options, callback) \n\n```js\n/**\n Fetch and update a collection\n query: a filter for the query\n sort: if multiple docs match, choose the first one in the specified sort order as the object to manipulate\n update: an object describing the modifications to the documents selected by the query\n options:\n remove: set to a true to remove the object before returning\n new: set to true if you want to return the modified object rather than the original. Ignored for remove.\n upsert: true/false (perform upsert operation)\n**/\n```\n\n#### findOne(queryObject, options, callback)\n\n\n\n### Aggregation\n\n#### mapReduce(map, reduce, options, callback)\n\ne.g.\n\n```js\nvar map = function () {\n emit(test(this.timestamp.getYear()), 1);\n}\n\nvar reduce = function (k, v){\n count = 0;\n for (i = 0; i < v.length; i++) {\n count += v[i];\n }\n return count;\n}\nvar options = {scope: {test: new client.bson_serializer.Code(t.toString())}};\ncollection.mapReduce(map, reduce, options, function (err, collection) {\n collection.find(function (err, cursor) {\n cursor.toArray(function (err, results) {\n test.equal(2, results[0].value)\n finished_test({test_map_reduce_functions_scope:'ok'}); \n })\n})\n```\n\n#### group(keys, condition, initial, reduce, command, callback)\n\ne.g. \n\n```js\ncollection.group([], {}, {\"count\":0}, \"function (obj, prev) { prev.count++; }\", true, function(err, results) {});\n```\n\n#### count(query, callback)\n#### distinct(key, query, callback)\n\n\n\n### Inserting\n\n#### insert(docs, options, callback)\n\n\n\n### Updating\n\n#### save(doc, options, callback)\n\n```js\n/**\n Update a single document in this collection.\n spec - a associcated array containing the fields that need to be present in\n the document for the update to succeed\n\n document - an associated array with the fields to be updated or in the case of\n a upsert operation the fields to be inserted.\n\n Options:\n upsert - true/false (perform upsert operation)\n multi - true/false (update all documents matching spec)\n strict - true/false (perform check if the operation failed, required extra call to db)\n Deprecated Options:\n safe - true/false (perform check if the operation failed, required extra call to db)\n**/\n```\n\n#### update(spec, document, options, callback)\n\n#### updateById(_id, ..., callback)\n\nEquivalent to\n\n```js\ncollection.update({_id, ObjectID.createFromHexString(id)}, ..., callback);\n```\n\nSee [Collection.update](https://github.com/christkv/node-mongodb-native/blob/master/docs/insert.md)\n\n\n\n### Removing\n\n#### remove(selector, options, callback)\n\n#### removeById(_id, options, callback)\n\n[Back to index](#index)\n\n\n\nSkinCursor\n---------\n\nSee [Cursor](https://github.com/christkv/node-mongodb-native/blob/master/lib/mongodb/cursor.js#L1)\nof node-mongodb-native for more information.\n\nAll these methods will return the SkinCursor itself.\n\n```js\nsort(keyOrList, [direction], [callback])\nlimit(limit, [callback])\nskip(skip, [callback])\nbatchSize(skip, [callback])\n\ntoArray(callback)\neach(callback)\ncount(callback)\nnextObject(callback)\ngetMore(callback)\nexplain(callback)\n```\n\n[Back to index](#index)\n\n## How to validate input?\n\nI wrote a middleware to validate post data, [node-iform](https://github.com/guileen/node-iform) \nbase on [node-validator](https://github.com/chriso/node-validator)\n\n## Authors\n\nBelow is the output from `git-summary`.\n\n```\n project: node-mongoskin\n commits: 112\n active : 54 days\n files : 39\n authors: \n 49 Lin Gui 43.8%\n 34 guilin 桂林 30.4%\n 9 fengmk2 8.0%\n 5 guilin 4.5%\n 2 François de Metz 1.8%\n 2 Paul Gebheim 1.8%\n 2 Gui Lin 1.8%\n 1 humanchimp 0.9%\n 1 Aneil Mallavarapu 0.9%\n 1 wmertens 0.9%\n 1 Harvey McQueen 0.9%\n 1 Joe Faber 0.9%\n 1 Matt Perpick 0.9%\n 1 Quang Van 0.9%\n 1 Rakshit Menpara 0.9%\n 1 Wout Mertens 0.9%\n```\n\n## License \n\n(The MIT License)\n\nCopyright (c) 2011 - 2012 kissjs.org\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n'Software'), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n",
"readmeFilename": "Readme.md",
"_id": "mongoskin@0.5.0",
"_from": "mongoskin@>= 0.0.1"
}