Merge pull request #197 from Automattic/plugins

middlewares architecture

Author: mathieudutour

CHANGELOG.md

@@ -1,3 +1,8 @@
+5.0.0 / 2017-05-21
+==================
+  - Remove deprecated methods
+  - Middleware architecture! See https://automattic.github.io/monk/docs/middlewares.html for more information
+
 4.1.0 / 2017-05-20
 ==================
   - Update dev dependencies - Thanks @ratson(◕ᴥ◕)

LICENCE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 Automattic
+Copyright (c) 2012 Guillermo Rauch <[email protected]>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -6,7 +6,7 @@ TEST_TARGET ?= test/
 
 lint:
 	echo "  $(P) Linting"
-	$(BIN_DIR)/eslint $(SRC_DIR) && $(BIN_DIR)/eslint $(TEST_TARGET)
+	$(BIN_DIR)/eslint lib && $(BIN_DIR)/eslint test && $(BIN_DIR)/eslint middlewares
 
 test: lint
 	echo "  $(P) Testing"

README.md

@@ -1,12 +1,19 @@
-# monk
+<h1 align="center">Monk</h1>
+
+<div align="center">
+  <img src="https://avatars2.githubusercontent.com/u/28830676?v=3&s=200" />
+</div>
+<br />
+<div align="center">
+  <strong>A tiny layer that provides simple yet substantial usability
+improvements for MongoDB usage within Node.JS.</strong>
+</div>
+<br />
 
 [![build status](https://secure.travis-ci.org/Automattic/monk.svg?branch=master)](https://secure.travis-ci.org/Automattic/monk)
 [![codecov](https://codecov.io/gh/Automattic/monk/branch/master/graph/badge.svg)](https://codecov.io/gh/Automattic/monk)
 [![Join the chat at https://gitter.im/Automattic/monk](https://badges.gitter.im/Automattic/monk.svg)](https://gitter.im/Automattic/monk?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-Monk is a tiny layer that provides simple yet substantial usability
-improvements for MongoDB usage within Node.JS.
-
 *note*: monk 2.x drop the support for node < 0.12. If you are still using an earlier version, stick to monk 1.x
 
 ```js
@@ -28,41 +35,28 @@ db.close()
 
 ## Features
 
-- Command buffering. You can start querying right away.
-- Promises built-in for all queries. Easy interoperability with modules.
+- Well-designed API signatures
 - Easy connections / configuration
-- Well-designed signatures
-- Improvements to the MongoDB APIs (eg: `findAndModify` supports the
-  `update` signature style)
+- Command buffering. You can start querying right away
+- Promises built-in for all queries. Easy interoperability with modules
 - Auto-casting of `_id` in queries
 - Allows to set global options or collection-level options for queries. (eg:
   `safe` is `true` by default for all queries)
 
-## How to use
+## Middlewares
 
-[Documentation](https://Automattic.github.io/monk)
+Most of the Monk's features are implemented as [middleware](https://automattic.github.io/monk/docs/middlewares.html).
 
-## License
+There are a bunch of third-parties middlewares that add even more functionalities to Monk:
+- [monk-middleware-wrap-non-dollar-update](https://github.com/monk-middlewares/monk-middleware-wrap-non-dollar-update)
+- [monk-middleware-debug](https://github.com/monk-middlewares/monk-middleware-debug)
 
-(The MIT License)
+*Created an nice middleware? Send a PR to add to the list!*
 
-Copyright (c) 2012 Guillermo Rauch &lt;[email protected]&gt;
+## How to use
 
-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:
+[Documentation](https://Automattic.github.io/monk)
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+## License
 
-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.
+MIT

SUMMARY.md

@@ -1,13 +1,19 @@
 ## Monk
 
-* [Read Me](/README.md)
+* [Introduction](/README.md)
 * [Getting Started](/docs/GETTING_STARTED.md)
 
+## Guides
+* [Middlewares](/docs/middlewares.md)
+* [Debugging](/docs/Debugging.md)
+* [Writing a middleware](/docs/writing-middleware.md)
+
 ## API Reference
 * [Manager](/docs/manager/README.md)
   * [close](/docs/manager/close.md)
   * [create](/docs/manager/create.md)
   * [get](/docs/manager/get.md)
+  * [addMiddleware](/docs/manager/addMiddleware.md)
 * [Collection](/docs/collection/README.md)
   * [aggregate](/docs/collection/aggregate.md)
   * [bulkWrite](/docs/collection/bulkWrite.md)
@@ -28,9 +34,6 @@
   * [update](/docs/collection/update.md)
 * [id](/docs/id.md)
 
-## Guides
-* [Debugging](/docs/Debugging.md)
-
 ---
 
 * [Change Log](/CHANGELOG.md)

book.json

@@ -2,10 +2,14 @@
   "gitbook": ">=3.2.2",
   "title": "Monk",
   "description": "The wise MongoDB API",
-  "plugins": ["prism", "-highlight", "github", "anker-enable"],
+  "plugins": ["edit-link", "prism", "-highlight", "github", "anker-enable"],
   "pluginsConfig": {
     "github": {
       "url": "https://github.com/Automattic/monk/"
+    },
+    "edit-link": {
+      "base": "https://github.com/Automattic/monk/redux/tree/master",
+      "label": "Edit This Page"
     }
   }
 }

docs/Debugging.md

@@ -1,4 +1,14 @@
-# Query debugging
+# Debugging
+
+To get some information on what monk is doing, use the `monk-middleware-debug`:
+
+```
+npm install --save monk-middleware-debug
+```
+
+```js
+db.addMiddleware(require('monk-middleware-debug))
+```
 
 * If you wish to see what queries `monk` passes to the driver, simply leverage
   [debug](http://github.com/visionmedia/debug):
@@ -12,13 +22,13 @@
   ```bash
   DEBUG="monk:*" npm start
   ```
-  
+
 * You can also see the output from the mongo driver using `debug`:
 
   ```bash
   DEBUG="mongo:*" npm start
   ```
-  
+
   There are several separated features available on this namespace:
 
     * Db: The Db instance log statements
@@ -29,9 +39,9 @@
     * Pool: Connection Pool specific log statements
     * Connection: Singular connection specific log statements
     * Ping: Replicaset ping inquiry log statements
-    
+
   To see the output of only one of those features:
-  
+
   ```bash
   DEBUG="mongo:Cursor" npm start // will only print the Cursor log statements
   ```

docs/manager/addMiddleware.md

@@ -0,0 +1,13 @@
+# `manager.addMiddleware`
+
+Add a middleware to the middlewares chain.
+
+#### Arguments
+
+1. `middleware` *(function)*: the middleware to add the the chain
+
+#### Example
+
+```js
+db.addMiddleware(require('monk-plugin-dereference'))
+```