Merge pull request #142 from Automattic/v3

.gitignore

@@ -16,3 +16,5 @@ npm-debug.log
 
 coverage
 .nyc_output
+
+_book

History.md

@@ -1,3 +1,15 @@
+3.0.0 / 2016-07-06
+==================
+  - remove Mongoskin dependency
+  - new documentation using gitbook
+  - add `opts` arg to `Collection.count` and `collection.distinct`
+  - deprecate `Collection.removeById`, `Collection.findById`, `Collection.updateById` in favor of using `remove`, `findOne` and `update` directly
+  - deprecate `collection.id` and `manager.id` in favor of `monk.id`
+  - `monk('localhost')` can be used as a promise which resolves when the connection opens and rejects when it throws an error (fix #24, fix #10)
+  - deprecate `Collection.findAndModify` in favor of `Collection.findOneAndDelete` and `Collection.findOneAndUpdate` (fix #74)
+  - add `Manager.create` (fix #50)
+  - add option `rawCursor` to `Collection.find` to return the raw cursor (fix #103)
+
 2.1.0 / 2016-06-24
 ==================
  - add aggregate method (#56)

Makefile

@@ -1,7 +1,8 @@
 BIN_DIR ?= node_modules/.bin
+P="\\033[34m[+]\\033[0m"
 
 SRC_DIR ?= src
-TEST_TARGET ?= tests/
+TEST_TARGET ?= test/
 
 lint:
 	echo "  $(P) Linting"
@@ -15,4 +16,32 @@ test-watch:
 	echo "  $(P) Testing forever"
 	NODE_ENV=test $(BIN_DIR)/ava --watch
 
-.PHONY: lint test test-watch
+docs-clean:
+	echo "  $(P) Cleaning gitbook"
+	rm -rf _book
+
+docs-prepare: docs-clean
+	echo "  $(P) Preparing gitbook"
+	$(BIN_DIR)/gitbook install
+
+docs-build: docs-prepare
+	echo "  $(P) Building gitbook"
+	$(BIN_DIR)/gitbook build -g Automattic/monk
+
+docs-watch: docs-prepare
+	echo "  $(P) Watching gitbook"
+	$(BIN_DIR)/gitbook serve
+
+docs-publish: docs-build
+	echo "  $(P) Publishing gitbook"
+	cd _book && \
+	git init && \
+	git commit --allow-empty -m 'update book' && \
+	git checkout -b gh-pages && \
+	touch .nojekyll && \
+	git add . && \
+	git commit -am 'update book' && \
+	git push https://github.com/Automattic/monk gh-pages --force
+
+.PHONY: lint test test-watch docs-clean docs-prepare docs-build docs-watch docs-publish
+.SILENT: lint test test-watch docs-clean docs-prepare docs-build docs-watch docs-publish

README.md

@@ -35,195 +35,12 @@ db.close()
 - Improvements to the MongoDB APIs (eg: `findAndModify` supports the
   `update` signature style)
 - Auto-casting of `_id` in queries
-- Builds on top of [mongoskin](http://github.com/kissjs/node-mongoskin)
 - Allows to set global options or collection-level options for queries. (eg:
   `safe` is `true` by default for all queries)
 
 ## How to use
 
-### Connecting
-
-#### Single server
-
-```js
-const db = require('monk')('localhost/mydb', options)
-```
-
-#### Replica set
-
-```js
-const db = require('monk')('localhost/mydb,192.168.1.1')
-```
-
-### Disconnecting
-
-```js
-db.close()
-```
-
-### Collections
-
-#### Getting one
-
-```js
-const users = db.get('users')
-// users.insert(), users.update() … (see below)
-```
-
-#### Dropping
-
-```js
-users.drop(fn)
-```
-
-### Signatures
-
-- All commands accept the simple `data[, …][, callback]`. For example
-    - `find({}, fn)`
-    - `findOne({}, fn)`
-    - `update({}, {}, fn)`
-    - `findAndModify({}, {}, fn)`
-    - `findById('id', fn)`
-    - `remove({}, fn)`
-- You can pass options in the middle: `data[, …], options[, fn]`
-- You can pass fields to select as an array: `data[, …], ['field', …][, fn]`
-- You can pass fields as a string delimited by spaces:
-  `data[, …], 'field1 field2'[, fn]`
-- To exclude a field, prefix the field name with '-':
-  `data[, …], '-field1'[, fn]`
-- You can pass sort option the same way as fields
-
-### Promises
-
-All methods that perform an async action return a promise.
-
-```js
-users.insert({}).then((doc) => {
-  // success
-}).catch((err) => {
-  // error
-})
-```
-
-### Indexes
-
-```js
-users.index('name.first')
-users.index('email', { unique: true }) // unique
-users.index('name.first name.last') // compound
-users.index({ 'email': 1, 'password': -1 }) // compound with sort
-users.index('email', { sparse: true }) // with options
-users.indexes() // get indexes
-users.dropIndex(name) // drop an index
-users.dropIndexes() // drop all indexes
-```
-
-### Inserting
-
-```js
-users.insert({ a: 'b' })
-```
-
-### Casting
-
-To cast to `ObjectId`:
-
-```js
-users.id() // returns new generated ObjectID
-users.id('hexstring') // returns ObjectId
-users.id(obj) // returns ObjectId
-```
-
-### Updating
-
-```js
-users.update({}, {})
-users.updateById('id', {})
-```
-
-### Finding
-
-#### Many
-
-```js
-users.find({}).then((docs) => {})
-```
-
-#### By ID
-
-```js
-users.findById('hex representation').then((doc) => {})
-users.findById(oid).then((doc) => {})
-```
-
-#### Single doc
-
-`findOne` also provides the `findById` functionality.
-
-```js
-users.findOne({ name: 'test' }).then((doc) => {})
-```
-
-#### And modify
-
-```js
-users.findAndModify({ query: {}, update: {} })
-users.findAndModify({ _id: '' }, { $set: {} }, { new: true })
-```
-
-#### Streaming
-
-Note: `stream: true` is optional if you register an `each` handler in the
-same tick. In the following example I just include it for extra clarity.
-
-```js
-users.find({}, { stream: true })
-  .each((doc, destroy) => {})
-  .then(() => {})
-  .catch((err) => {})
-```
-
-##### Destroying a cursor
-
-You can call `destroy()` in the `each` handler to close the cursor. Upon the cursor
-closing the `then` handler will be called.
-
-### Removing
-
-```js
-users.remove({ a: 'b' })
-```
-
-### Aggregate
-
-```js
-users.aggregate(stages, {})
-```
-
-### Global options
-
-```js
-const db = require('monk')('localhost/mydb')
-db.options.multi = true // global multi-doc update
-db.get('users').options.multi = false // collection-level
-```
-
-Monk sets `safe` to `true` by default.
-
-### Query debugging
-
-If you wish to see what queries `monk` passes to the driver, simply leverage
-[debug](http://github.com/visionmedia/debug):
-
-```bash
-DEBUG="monk:queries"
-```
-
-To see all debugging output:
-
-```bash
-DEBUG="monk:*"
-```
+[Documentation](https://Automattic.github.io/monk)
 
 ## Contributors
 

book.json

@@ -0,0 +1,17 @@
+{
+  "gitbook": "2.5.2",
+  "title": "Monk",
+  "structure": {
+    "summary": "docs/README.md"
+  },
+  "plugins": ["edit-link", "prism", "-highlight", "github", "anker-enable"],
+  "pluginsConfig": {
+    "edit-link": {
+      "base": "https://github.com/Automattic/monk/tree/master",
+      "label": "Edit This Page"
+    },
+    "github": {
+      "url": "https://github.com/Automattic/monk/"
+    }
+  }
+}

docs/Debugging.md

@@ -0,0 +1,14 @@
+# Query debugging
+
+If you wish to see what queries `monk` passes to the driver, simply leverage
+[debug](http://github.com/visionmedia/debug):
+
+```bash
+DEBUG="monk:queries"
+```
+
+To see all debugging output:
+
+```bash
+DEBUG="monk:*"
+```