mongodb-wrapper/Readme.md

Exactly-like-the-console wrapper for node-mongodb-native

[node-mongodb-native]: https://github.com/christkv/node-mongodb-native     
[javascript driver]: http://www.mongodb.org/display/DOCS/Manual
[docs]: http://www.mongodb.org/display/DOCS/Manual

# node-mongodb-wrapper

A wrapper for [node-mongodb-native][node-mongodb-native] as close as possible to the [native javascript driver][javascript driver]. Why learn two interfaces?


## History

v1.0.0 - A complete rewrite of the driver that now uses mongoclient. The interface is generally the same, but all the messiness
of reconnecting has been removed, as thats transparently handeled by the mongo client. If you see any breakage, please open an issue!

## Features

1. Minimal interface closely matching the command-line driver: [http://www.mongodb.org/display/DOCS/Manual][docs]
2. Lazy open/close of connections (now handeled by the low level node-mongodb-native)
3. Most features of [node-mongodb-native][node-mongodb-native]

## Installation

```
  npm install mongodb-wrapper
```

## Usage

1. You have to tell the db object which collections you're about to use (Harmony Proxies, I need you!)
2. You have to provide callbacks on "actionable" calls (`toArray`, `count`, but not `find`)
3. Otherwise, just like the native [javascript driver][javascript driver]

``` JavaScript
	var mongo = require('mongodb-wrapper')
	var db = mongo.db('localhost', 27017, 'test')
	db.collection('posts')
	
	db.posts.save({title: "A new post", body: "Here is some text"}, function(err, post) {
		db.posts.findOne({_id: doc._id}, function(err, post) {
			db.posts.find().limit(1).toArray(function(err, posts) {
				// posts[0].title == "A new post"
			})
		})
	})      
```

For more examples, [please look at the test suite](https://github.com/idottv/node-mongodb-wrapper/blob/master/lib/mongodb-wrapper.js)

## Documentation

Remember the guiding principle: the syntax exactly matches the [command-line driver][docs], except you pass a call back to any function that hits the database. 

#### Connecting

There are lots of ways to open up a database connection
`mongo.db(mongodbConnectionString)` - returns a database object, for details on the connection string see [mongodb docs](http://mongodb.github.com/node-mongodb-native/driver-articles/mongoclient.html)
* NOTE: this mode does not support a prefix!
`mongo.db(host, port, dbname, [prefix], [username], [password])` - returns a database project

* If prefix is specified all collections will use the prefix in mongo, but you refer to them without the prefix in node.
* If username and password are specified, it will attempt to authenticate. 

`db.collection(name)` - Returns a `Collection` object. Also creates `db[name]` so you can do this:
    
    db.collection('users')
    db.users.count(cb)

#### Replica Sets

Replica sets are also supported with an alternate function signature:
``` JavaScript
var hostsArray = [
  // opts is a hash of mongodb-native server opts: http://mongodb.github.com/node-mongodb-native/api-generated/server.html
  // also optional
  {host: "host1", port: 27017, opts: {}},
  {host: "host1", port: 27018, opts: {}},
  ...
]
// other replica set opts, such as read_secondary, are passed in here
// these opts are also passed to each mongodb-native server object, so you can have defaults for your servers
var opts = {rs_name: "myReplicaSet"}

mongo.db(hostsArray, opts, dbname, [prefix], [username], [password])
```
 

#### Authentication

`db.auth(username, password, cb)` - You can pass `username` and `password` into mongo.db instead of calling this manually

`db.addUser(username, password, cb)`

`db.removeUser(username, password, cb)`

#### Database 

`db.dropDatabase(cb)`

`db.lastError(cb)` - `cb(err, lastError)`

`db.eval(code, [parameters], cb)`

`db.createCollection(name, options, cb)` - allows you to create a collection by hand if you want to specify the options

### Collection

`collection.ensureIndex(index, options, cb)`

`collection.dropIndexes(cb)`

`collection.renameCollection(newName, dropTarget, cb)`

`collection.insert(doc(s), cb)`

`collection.remove(selector, cb)`

`collection.drop(cb)`

`collection.save(doc, cb)`

`collection.update(selector, updates, [upsert], [multi], cb)`

`collection.count(cb)`

`collection.findAndModify(options, cb)`

`collection.find(selector, fields)` - Returns a `Cursor`

`collection.findOne(selector, fields, cb)`

`collection.group(options, cb)`

`collection.mapReduce(map, reduce, options, cb)` - map and reduce can be functions, it will toString them for you. 

`collection.distinct(key, [query], cb)`

### Cursor

`cursor.limit(num)` 

`cursor.skip(num)`

`cursor.sort({field:1})`

`cursor.next(cb)`

`cursor.explain(cb)`

`cursor.toArray(cb)`

`cursor.count(cb)`

`cursor.getRawCursor` - retrieves a raw mongodb-native cursor, so you can do things like cursor streams, and other fancy things not supported

### Useful Exports

`mongo.ObjectID` - you need to wrap any string ids in this class to match on `_id`