From 6c4a9a243600460b93ef4f9faedbffb08473ed0f Mon Sep 17 00:00:00 2001
From: Lloyd Brookes <lloyd.brookes@gmail.com>
Date: Fri, 27 Nov 2015 19:55:51 +0000
Subject: [PATCH] mock docs

---
 README.md                                      | 87 +++++++++++++++++++++++---
 example/mock/.local-web-server.json            |  9 ++-
 example/mock/mocks/{four.js => stream-self.js} |  0
 jsdoc2md/README.hbs                            | 87 +++++++++++++++++++++++---
 lib/cli-options.js                             |  2 +-
 5 files changed, 163 insertions(+), 22 deletions(-)
 rename example/mock/mocks/{four.js => stream-self.js} (100%)

diff --git a/README.md b/README.md
index a428aba..c693a2b 100644
--- a/README.md
+++ b/README.md
@@ -11,16 +11,17 @@ A simple web-server for productive front-end development. Typical use cases:
 
 * Front-end Development
   * Static or Single Page App development
-  * reroute paths to local or remote resources
+  * Re-route paths to local or remote resources
   * Bundle with your front-end project
   * Very little configuration, just a few options
   * Outputs a dynamic statistics view to the terminal
   * Configurable log output, compatible with [Goaccess, Logstalgia and glTail](https://github.com/75lb/local-web-server/blob/master/doc/visualisation.md)
 * Back-end service mocking
   * Prototype a web service, microservice, REST API etc.
+  * Mocks are defined with config (static), or code (dynamic).
   * CORS-friendly, all origins allowed by default.
 * Proxy server
-  * Useful to workaround CORS issues with remote servers
+  * Map local routes to remote services. Removes CORS issues with remote servers.
 * File sharing
 
 **Requires node v4.0.0 or higher**.
@@ -142,9 +143,9 @@ $ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name'
 
 ### Mock Responses
 
-Mock a data service, serve any custom/dynamic content.
+Mocks give you full control over the response headers and body returned to the client. They can be used to return anything from a simple html string to a resourceful REST API. Typically, they're used to mock services but can be used for anything.
 
-A mock definition maps a route to a response. Mock a home page.
+In the config, define an array called `mocks`. Each mock definition maps a <code>[route](http://expressjs.com/guide/routing.html#route-paths)</code> to a `response`. A simple home page:
 ```json
 {
   "mocks": [
@@ -158,7 +159,23 @@ A mock definition maps a route to a response. Mock a home page.
 }
 ```
 
-Conditional response, depending on the request.
+Under the hood, the property values from the `response` object are written onto the underlying [koa response object](https://github.com/koajs/koa/blob/master/docs/api/response.md). You can set any valid koa response properies, for example [type](https://github.com/koajs/koa/blob/master/docs/api/response.md#responsetype-1):
+```json
+{
+  "mocks": [
+    {
+      "route": "/",
+      "response": {
+        "type": "text/plain",
+        "body": "<h1>Welcome to the Mock Responses example</h1>"
+      }
+    }
+  ]
+}
+```
+
+To define a **conditional response**, set a `request` object on the mock definition. The `request` value acts as a query - the response defined will only be returned if each property of the `request` query matches. For example, return an XML response *only* if the request headers include `accept: application/xml`, else return 404 Not Found.
+
 ```json
 {
   "mocks": [
@@ -173,7 +190,8 @@ Conditional response, depending on the request.
 }
 ```
 
-Multiple potential responses. First request to match.
+To specify **multiple potential responses**, set an array of mock definitions to the `responses` property. The first response with a matching request query will be sent. In this example, the client will get one of two responses depending on the request method:
+
 ```json
 {
   "mocks": [
@@ -199,25 +217,74 @@ Multiple potential responses. First request to match.
 }
 ```
 
-More dynamic response.
+The examples above all returned static data. To define a **dynamic response**, create a mock module. Specify its path in the `module` property:
 ```json
 {
   "mocks": [
     {
       "route": "/four",
-      "module": "/mocks/four.js"
+      "module": "/mocks/stream-self.js"
     }
   ]
 }
 ```
 
-Tokens in the route are passed to the response.
+Here's what the `stream-self` module looks like. The module should export a mock definition (an object with a `response` and optional `request`). In this example, the module simply streams itself to the response but you could craft and return *any* [valid value](https://github.com/koajs/koa/blob/master/docs/api/response.md#responsebody-1).
+```js
+const fs = require('fs')
+
+module.exports = {
+  response: {
+    body: fs.createReadStream(__filename)
+  }
+}
+```
+
+For more power, define the response body as a function. It will receive the [koa context](https://github.com/koajs/koa/blob/master/docs/api/context.md) as its first argument. Now you have full programmatic control over the response returned.
+```js
+const fs = require('fs')
+
+module.exports = {
+  response: {
+    body: function (ctx) {
+      ctx.body = '<h1>I can do anything i want.</h1>'
+    }
+  }
+}
+```
+
+If the route contains tokens, their values are passed to the response. For example, with this mock...
 ```json
 {
   "mocks": [
     {
       "route": "/five/:id\\?name=:name",
-      "module": "/mocks/five.js"
+      "module": "/mocks/example.js"
+    }
+  ]
+}
+```
+
+...the values `id` and `name` are passed to the body function. For example, a path of `/five/10?name=Lionel` would pass `10` and `Lionel` to the body function:
+```js
+const fs = require('fs')
+
+module.exports = {
+  response: {
+    body: function (ctx, id, name) {
+      ctx.body = `<h1>id: ${id}, name: ${name}</h1>`
+    }
+  }
+}
+```
+
+Here's an example of a REST collection (users). The config:
+```json
+{
+  "mocks": [
+    {
+      "route": "/users",
+      "module": "/mocks/users.js"
     }
   ]
 }
diff --git a/example/mock/.local-web-server.json b/example/mock/.local-web-server.json
index ffa1c2b..e0ef555 100644
--- a/example/mock/.local-web-server.json
+++ b/example/mock/.local-web-server.json
@@ -7,6 +7,13 @@
       }
     },
     {
+      "route": "/one",
+      "response": {
+        "type": "text/plain",
+        "body": "<h1>Welcome to the Mock Responses example</h1>"
+      }
+    },
+    {
       "route": "/two",
       "request": { "accepts": "xml" },
       "response": {
@@ -33,7 +40,7 @@
     },
     {
       "route": "/four",
-      "module": "/mocks/four.js"
+      "module": "/mocks/stream-self.js"
     },
     {
       "route": "/five/:id\\?name=:name",
diff --git a/example/mock/mocks/four.js b/example/mock/mocks/stream-self.js
similarity index 100%
rename from example/mock/mocks/four.js
rename to example/mock/mocks/stream-self.js
diff --git a/jsdoc2md/README.hbs b/jsdoc2md/README.hbs
index b71b55c..59cb2b9 100644
--- a/jsdoc2md/README.hbs
+++ b/jsdoc2md/README.hbs
@@ -11,16 +11,17 @@ A simple web-server for productive front-end development. Typical use cases:
 
 * Front-end Development
   * Static or Single Page App development
-  * reroute paths to local or remote resources
+  * Re-route paths to local or remote resources
   * Bundle with your front-end project
   * Very little configuration, just a few options
   * Outputs a dynamic statistics view to the terminal
   * Configurable log output, compatible with [Goaccess, Logstalgia and glTail](https://github.com/75lb/local-web-server/blob/master/doc/visualisation.md)
 * Back-end service mocking
   * Prototype a web service, microservice, REST API etc.
+  * Mocks are defined with config (static), or code (dynamic).
   * CORS-friendly, all origins allowed by default.
 * Proxy server
-  * Useful to workaround CORS issues with remote servers
+  * Map local routes to remote services. Removes CORS issues with remote servers.
 * File sharing
 
 **Requires node v4.0.0 or higher**.
@@ -142,9 +143,9 @@ $ ws --rewrite '/:user/repos/:name -> https://api.github.com/repos/:user/:name'
 
 ### Mock Responses
 
-Mock a data service, serve any custom/dynamic content.
+Mocks give you full control over the response headers and body returned to the client. They can be used to return anything from a simple html string to a resourceful REST API. Typically, they're used to mock services but can be used for anything.
 
-A mock definition maps a route to a response. Mock a home page.
+In the config, define an array called `mocks`. Each mock definition maps a <code>[route](http://expressjs.com/guide/routing.html#route-paths)</code> to a `response`. A simple home page:
 ```json
 {
   "mocks": [
@@ -158,7 +159,23 @@ A mock definition maps a route to a response. Mock a home page.
 }
 ```
 
-Conditional response, depending on the request.
+Under the hood, the property values from the `response` object are written onto the underlying [koa response object](https://github.com/koajs/koa/blob/master/docs/api/response.md). You can set any valid koa response properies, for example [type](https://github.com/koajs/koa/blob/master/docs/api/response.md#responsetype-1):
+```json
+{
+  "mocks": [
+    {
+      "route": "/",
+      "response": {
+        "type": "text/plain",
+        "body": "<h1>Welcome to the Mock Responses example</h1>"
+      }
+    }
+  ]
+}
+```
+
+To define a **conditional response**, set a `request` object on the mock definition. The `request` value acts as a query - the response defined will only be returned if each property of the `request` query matches. For example, return an XML response *only* if the request headers include `accept: application/xml`, else return 404 Not Found.
+
 ```json
 {
   "mocks": [
@@ -173,7 +190,8 @@ Conditional response, depending on the request.
 }
 ```
 
-Multiple potential responses. First request to match.
+To specify **multiple potential responses**, set an array of mock definitions to the `responses` property. The first response with a matching request query will be sent. In this example, the client will get one of two responses depending on the request method:
+
 ```json
 {
   "mocks": [
@@ -199,25 +217,74 @@ Multiple potential responses. First request to match.
 }
 ```
 
-More dynamic response.
+The examples above all returned static data. To define a **dynamic response**, create a mock module. Specify its path in the `module` property:
 ```json
 {
   "mocks": [
     {
       "route": "/four",
-      "module": "/mocks/four.js"
+      "module": "/mocks/stream-self.js"
     }
   ]
 }
 ```
 
-Tokens in the route are passed to the response.
+Here's what the `stream-self` module looks like. The module should export a mock definition (an object with a `response` and optional `request`). In this example, the module simply streams itself to the response but you could craft and return *any* [valid value](https://github.com/koajs/koa/blob/master/docs/api/response.md#responsebody-1).
+```js
+const fs = require('fs')
+
+module.exports = {
+  response: {
+    body: fs.createReadStream(__filename)
+  }
+}
+```
+
+For more power, define the response body as a function. It will receive the [koa context](https://github.com/koajs/koa/blob/master/docs/api/context.md) as its first argument. Now you have full programmatic control over the response returned.
+```js
+const fs = require('fs')
+
+module.exports = {
+  response: {
+    body: function (ctx) {
+      ctx.body = '<h1>I can do anything i want.</h1>'
+    }
+  }
+}
+```
+
+If the route contains tokens, their values are passed to the response. For example, with this mock...
 ```json
 {
   "mocks": [
     {
       "route": "/five/:id\\?name=:name",
-      "module": "/mocks/five.js"
+      "module": "/mocks/example.js"
+    }
+  ]
+}
+```
+
+...the values `id` and `name` are passed to the body function. For example, a path of `/five/10?name=Lionel` would pass `10` and `Lionel` to the body function:
+```js
+const fs = require('fs')
+
+module.exports = {
+  response: {
+    body: function (ctx, id, name) {
+      ctx.body = `<h1>id: ${id}, name: ${name}</h1>`
+    }
+  }
+}
+```
+
+Here's an example of a REST collection (users). The config:
+```json
+{
+  "mocks": [
+    {
+      "route": "/users",
+      "module": "/mocks/users.js"
     }
   ]
 }
diff --git a/lib/cli-options.js b/lib/cli-options.js
index 2578f4e..7ff9de2 100644
--- a/lib/cli-options.js
+++ b/lib/cli-options.js
@@ -50,7 +50,7 @@ module.exports = {
     description: 'A simple web-server for productive front-end development.',
     footer: 'Project home: [underline]{https://github.com/75lb/local-web-server}',
     synopsis: [
-      '$ ws [server options]',
+      '$ ws [<server options>]',
       '$ ws --config',
       '$ ws --help'
     ],