Permalink
Browse files

update readme and examples

  • Loading branch information...
1 parent 1de7e1b commit 474043ec44eded3efebd1ee0384bb2e7b696a595 @guileen guileen committed Feb 15, 2014
Showing with 109 additions and 223 deletions.
  1. +87 −204 Readme.md
  2. +1 −1 examples/admin.js
  3. +2 −4 examples/config.js
  4. +6 −8 examples/gridfs.js
  5. +13 −6 examples/replset.js
View
291 Readme.md
@@ -3,43 +3,37 @@
[![Build Status](https://secure.travis-ci.org/kissjs/node-mongoskin.png)](http://travis-ci.org/kissjs/node-mongoskin)
[![Dependencies](https://david-dm.org/kissjs/node-mongoskin.png)](https://david-dm.org/kissjs/node-mongoskin)
[![Coverage Status](https://coveralls.io/repos/kissjs/node-mongoskin/badge.png?branch=1.3.20)](https://coveralls.io/r/kissjs/node-mongoskin?branch=1.3.20)
-
+[![NPM version](https://badge.fury.io/js/mongoskin.png)](http://badge.fury.io/js/mongoskin)
![logo](https://raw.github.com/kissjs/node-mongoskin/master/logo.png)
+[![NPM](https://nodei.co/npm/mongoskin.png?downloads=true&stars=true)](https://nodei.co/npm/mongoskin/)
+
This project is a wrapper for [node-mongodb-native](https://github.com/mongodb/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](http://mongodb.github.com/node-mongodb-native/) first.
## NOTE!! mongoskin API change from 1.3.20
Since node-mongodb-native has change a lot of API, mongoskin redesign from 1.3.20. The version number keep same with node-mongodb-native. And the API appearence is also keep same with node-mongodb-native
-### Removed API from mongoskin 1.3.20
-module.bind
-module.Skin*
-module.router
-skinDb.toId
-skinDb.toObjectId
-skinDb.admin
-skinDb.gridfs
-skinCollection.bind
+Install
+========
-### Modified API from mongoskin 1.3.20
-module.db
-skinDb.bind
+```bash
+$ npm install mongoskin
+```
+Usage
+========
-### Additional API from mongoskin 1.3.20
-module.MongoClient
-module.Grid
-module.GridStore
-module.helper.toObjectID
+Use dburl
```js
var mongo = require('mongoskin');
var MongoClient = mongo.MongoClient;
var db = MongoClient.connect("mongodb://localhost:27017/integration_tests", {native_parser:true});
-db.collection('mycollection').find().toArray(function(err, items) {
+db.bind('article');
+db.article.find().toArray(function(err, items) {
db.close();
});
```
@@ -64,226 +58,115 @@ db.collection('myconnection').find().setReadPreference(ReadPreference.SECONDARY)
});
```
-## Basic API document
+## Origin API part
For detail API reference see [node mongodb API](http://mongodb.github.io/node-mongodb-native/). Mongoskin is just change the API call chain.
-## Additional API by Mongoskin
-
-collection.findById
-collection.updateById
-collection.removeById
-
-## Automated tests
-
-You can run the automated test by running <strong>make test</strong>. The tests have a coverage of [**89%**](http://fengmk2.github.com/coverage/mongoskin.html) and you can [browse the results](https://github.com/kissjs/node-mongoskin/blob/master/test_results.md).
-
-
-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](https://github.com/christkv/node-mongodb-native/tree/master/docs)
-
-mongoose
---------
+We make some common use functioin in promise mode, we call it SkinClass of a normal Class. And the API is almost same with official API.
-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](https://github.com/christkv/node-mongodb-native),
- and makes good use of [futures](http://en.wikipedia.org/wiki/Future_%28programming%29).
-
-For validation you can use [node-iform](https://github.com/guileen/node-iform).
-
-Install
-========
-
-```bash
-$ npm install mongoskin
+origin:
+```js
+var mongo = require('mongodb');
+var Db = mongo.Db;
+var Server = mongo.Server;
+var MongoClient = mongo.MongoClient;
+var ReplSetServers = mongo.ReplSetServers;
+...
```
-Quick start
-========
-
- **Is mongoskin synchronized?**
-Nope! It is asynchronized, it use the [future pattern](http://en.wikipedia.org/wiki/Future_%28programming%29).
-**Mongoskin** is the future layer above [node-mongodb-native](https://github.com/christkv/node-mongodb-native)
-
-Easier to connect
---------
-You can connect to mongodb easier now.
+mongoskin:
```js
var mongo = require('mongoskin');
-mongo.db('localhost:27017/testdb').collection('blog').find().toArray(function (err, items) {
- console.dir(items);
-})
+var Db = mongo.Db;
+var Server = mongo.Server;
+var MongoClient = mongo.MongoClient;
+var ReplSetServers = mongo.ReplSetServers;
+...
```
-
-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.
+origin:
```js
-var mongo = require('mongoskin');
-var db = mongo.db('localhost:27017/test?auto_reconnect');
+MongoClient.connect(..., functioin(err, db) {
+})
```
-
-Similar API to node-mongodb-native
---------
-You can do everything that node-mongodb-native can do.
+mongoskin:
```js
-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
-});
+var db = MongoClient.connect(...)
```
-
-Easier cursor
---------
+origin:
```js
-db.collection('posts').find().toArray(function (err, posts) {
- // do something
+var db = new Db(...);
+db.open(functioin(err, db) {
+ db.collection('myCollection', {strict: true}, functioin(err, myCollection) {
+ // myCollection.find() ...
+ });
});
```
-
-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
+mongoskin:
```js
-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
-});
+var db = new Db(...);
+var myCollection = db.collection('myCollection', {strict: true});
```
+## Promised methods
+
+### MongoClient.connect(...)
+returns a `Db` instance
+alias origin `MongoClient.connect(..., function(err, db) { .... })`
+### db.collection
+returns a `Collection` instance
+alias origin `db.collection(..., function(err, collection) {....})`
+### collection.find
+returns a `Cursor` instance
+alias origin `collection.find(..., function(err, cursor) {....})`
+
+## MongoSkin API part
+
+### module.db(...)
+alias `MongoClient.connect(...)`
+### db.admin(...)
+alias `new Admin(db, ...)`
+### db.grid(...)
+alias `new Grid(db, ...)`
+### db.gridStore(...)
+alias `new GridStore(db, ...)`
+### collection.findById(id, ...)
+alias `collection.find({_id: toObjectID(id)}, ...)`
+### collection.updateById(id, ...)
+alias `collection.update({_id: toObjectID(id)}, ...)`
+### collection.removeById(id, ...)
+alias `collection.remove({_id: toObjectID(id)}, ...)`
+### Removed API from mongoskin 1.3.20
-API documentation
-========
-
-for more information, see the source.
-
-
-
-
-Module
---------
-
-### db(serverURL[s], dbOptions, replicasetOptions)
-
-Get or create instance of [SkinDb](#skindb).
-
-Parameters:
-* ```serverURLs``` can be a single mongoskin url, or an array of urls, each with the following format:
-```[*://][username:password@]host[:port][/database][?auto_reconnect[=true|false]]```
+* module.bind
+* module.Skin*
+* module.router
+* skinDb.toId
+* skinDb.toObjectId
+* skinDb.gridfs
+* skinCollection.bind
-* ```dbOptions``` is an object that can have following options in it:
- * ```database``` - the database to connect to. This overrides the database name passed in the url.
- * ```socketOptions``` - mongo socket options (see http://mongodb.github.com/node-mongodb-native/markdown-docs/database.html)
- * ```username``` - overrides the value set in the serverURl[s]
- * ```password``` - overrides the value set in the serverURl[s]
- * other parameters - see http://mongodb.github.io/node-mongodb-native/api-generated/db.html
-* ```replicasetOptions``` - mongodb ReplSet options (see http://mongodb.github.io/node-mongodb-native/driver-articles/mongoclient.html). This is only useful if an array of urls is passed.
+### Modified API from mongoskin 1.3.20
-Examples:
+* module.db
+* skinDb.bind
-```js
-var a = mongoskin.db('localhost:27017/testdb?auto_reconnect=true&poolSize=5');
-var b = mongoskin.db('mongo://admin:pass@127.0.0.1:27017/blog?auto_reconnect');
-var c = mongoskin.db('127.0.0.1?auto_reconnect=false');
-```
-for ReplSet server
+### Additional API from mongoskin 1.3.20
-```js
-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
- }
-});
-```
+* module.MongoClient
+* module.Grid
+* module.GridStore
+* module.helper.toObjectID
## Authors
View
2 examples/admin.js
@@ -1,6 +1,6 @@
var db = require('./config').db;
-db.admin.listDatabases(function(err, result){
+db.admin().listDatabases(function(err, result){
if(err) {
console.traceError(err);
}
View
6 examples/config.js
@@ -1,5 +1,3 @@
-var mongoskin = require('../lib/mongoskin/');
+var mongo = require('../');
-exports.db = mongoskin.db('localhost/test');
-
-mongoskin.db('localhost', { database: 'test' });
+exports.db = mongo.db('mongodb://localhost/test');
View
14 examples/gridfs.js
@@ -1,13 +1,11 @@
var db = require('./config').db;
-db.gridfs().open('test.txt', 'w', function(err, gs) {
- gs.write('blablabla', function(err, reply) {
- gs.close(function(err, reply){
- db.gridfs().open('test.txt', 'r' ,function(err, gs) {
- gs.read(function(err, reply){
- console.log(reply.toString());
- });
- });
+var gs = db.gridStore('test.txt', 'w')
+gs.write('blablabla', function(err, reply) {
+ gs.close(function(err, reply){
+ var gs = db.gridStore('test.txt', 'r')
+ gs.read(function(err, reply){
+ console.log(reply.toString());
});
});
});
View
19 examples/replset.js
@@ -1,10 +1,17 @@
-var mongoskin = require('../lib/mongoskin/');
+var mongo = require('../');
+var Db = mongo.Db;
+var Server = mongo.Server;
+var ReplSetServers = mongo.ReplSetServers;
-var db = mongoskin.db(['127.0.0.1:27017'], {
- database: 'test'
-});
-
-db.open(function(err, data) {
+var replSet = new ReplSetServers([
+ new Server('localhost', 30000),
+ new Server('localhost', 30001),
+ new Server('localhost', 30002)
+]);
+var db = new Db('integration_test_', replSet, {w:0});
+db.collection('article').find().toArray(function(err, data) {
console.log(err && err.stack);
console.log(data);
+
});
+

3 comments on commit 474043e

@fresheneesz

@guileen Why did you screw up the documentation so much in this commit? Was there a reason you removed SO MUCH information?

@vkarpov15

@fresheneesz please watch your language and be more courteous in the future. Cursing at people isn't a great way to get them to help you.

@fresheneesz

@vkarpov15 Noted, but I'm not expecting any help. I'm only here to express my frustration in the hopes he'll do better for people that aren't me in the future.

Please sign in to comment.