Chainable api support (#53)

Chainable api support

Author: delvedor

README.md

@@ -43,6 +43,36 @@ try {
 }
 ```
 
+You can also use chaining methods if you do not pass the callback function. Check [here](#method-chaining) for details.
+
+```js
+// chaining methods
+inject(dispatch)
+  .get('/')                   // set the request method to GET, and request URL to '/'
+  .headers({ foo: 'bar' })    // set the request headers
+  .query({ foo: 'bar' })      // set the query parameters
+  .end((err, res) => {
+    console.log(res.payload)
+  })
+
+inject(dispatch)
+  .post('/')                  // set the request method to POST, and request URL to '/'
+  .payload('request payload') // set the request payload
+  .body('request body')       // alias for payload
+  .end((err, res) => {
+    console.log(res.payload)
+  })
+
+// async-await is also supported
+try {
+  const chain = inject(dispatch).get('/')
+  const res = await chain.end()
+  console.log(res.payload)
+} catch (err) {
+  console.log(err)
+}
+```
+
 File uploads (multipart/form-data) can be achieved by using [form-data](https://github.com/form-data/form-data) package as shown below:
 
 ```js
@@ -103,7 +133,7 @@ The declaration file exports types for the following parts of the API:
 
 ## API
 
-#### `inject(dispatchFunc, options, callback)`
+#### `inject(dispatchFunc[, options, callback])`
 
 Injects a fake request into an HTTP server.
 
@@ -148,6 +178,50 @@ Note: You can also pass a string in place of the `options` object as a shorthand
 
 Checks if given object `obj` is a *light-my-request* `Request` object.
 
+#### Method chaining
+
+There are following methods you can used as chaining:
+- `delete`, `get`, `head`, `options`, `patch`, `post`, `put`, `trace`. They will set the HTTP request method and also the request URL.
+- `body`, `headers`, `payload`, `query`. They can be used to set the request options object.
+
+And finally you need to call `end`. It has the signature `function (callback)`.
+If you invoke `end` without a callback function, the method will return a promise, thus you can:
+
+```js
+const chain = inject(dispatch).get('/')
+
+try {
+  const res = await chain.end()
+  console.log(res.payload)
+} catch (err) {
+  // handle error
+}
+
+// or
+chain.end()
+  .then(res => {
+    console.log(res.payload)
+  })
+  .catch(err => {
+    // handle error
+  })
+```
+
+By the way, you can also use promises without calling `end`!
+
+```js
+inject(dispatch)
+  .get('/')
+  .then(res => {
+    console.log(res.payload)
+  })
+  .catch(err => {
+    // handle error
+  })
+```
+
+Note: The application would not respond multiple times. If you try to invoking any method after the application has responded, the application would throw an error.
+
 ## Acknowledgements
 This project has been forked from [`hapi/shot`](https://github.com/hapijs/shot) because we wanted to support *Node ≥ v4* and not only *Node ≥ v8*.  
 All the credits before the commit [00a2a82](https://github.com/fastify/light-my-request/commit/00a2a82eb773b765003b6085788cc3564cd08326) goes to the `hapi/shot` project [contributors](https://github.com/hapijs/shot/graphs/contributors).  

index.d.ts

@@ -12,16 +12,18 @@ type HTTPMethods = 'DELETE' | 'delete' |
 declare namespace LightMyRequest {
   function inject (
     dispatchFunc: DispatchFunc,
-    options: string | InjectOptions
-  ): Promise<Response>
+    options?: string | InjectOptions
+  ): Chain
   function inject (
     dispatchFunc: DispatchFunc,
     options: string | InjectOptions,
-    callback: (err: Error, response: Response) => void
+    callback: CallbackFunc
   ): void
 
   type DispatchFunc = (req: Request, res: Response) => void
 
+  type CallbackFunc = (err: Error, response: Response) => void
+
   type InjectPayload = string | object | Buffer | NodeJS.ReadableStream
 
   function isInjection (obj: Request | Response): boolean
@@ -78,6 +80,22 @@ declare namespace LightMyRequest {
     body: string
     json: () => object
   }
+
+  interface Chain {
+    delete: (url: string) => Chain
+    get: (url: string) => Chain
+    head: (url: string) => Chain
+    options: (url: string) => Chain
+    patch: (url: string) => Chain
+    post: (url: string) => Chain
+    put: (url: string) => Chain
+    trace: (url: string) => Chain
+    body: (body: InjectPayload) => Chain
+    headers: (headers: http.IncomingHttpHeaders | http.OutgoingHttpHeaders) => Chain
+    payload: (payload: InjectPayload) => Chain
+    query: (query: object) => Chain
+    end: (callback?: CallbackFunc) => Chain | Promise<Response>
+  }
 }
 
 export = LightMyRequest

index.js

@@ -63,6 +63,14 @@ const schema = {
 const optsValidator = ajv.compile(schema)
 
 function inject (dispatchFunc, options, callback) {
+  if (typeof callback === 'undefined') {
+    return new Chain(dispatchFunc, options)
+  } else {
+    return doInject(dispatchFunc, options, callback)
+  }
+}
+
+function doInject (dispatchFunc, options, callback) {
   options = (typeof options === 'string' ? { url: options } : options)
 
   if (options.validate !== false) {
@@ -90,11 +98,88 @@ function inject (dispatchFunc, options, callback) {
   }
 }
 
+function Chain (dispatch, option) {
+  this.option = Object.assign({}, option)
+  this.dispatch = dispatch
+  this._hasInvoked = false
+  this._promise = null
+}
+
+const httpMethods = [
+  'delete',
+  'get',
+  'head',
+  'options',
+  'patch',
+  'post',
+  'put',
+  'trace'
+]
+
+httpMethods.forEach(method => {
+  Chain.prototype[method] = function (url) {
+    if (this._hasInvoked === true || this._promise) {
+      throwIfAlreadyInvoked()
+    }
+    this.option.url = url
+    this.option.method = method.toUpperCase()
+    return this
+  }
+})
+
+const chainMethods = [
+  'body',
+  'headers',
+  'payload',
+  'query'
+]
+
+chainMethods.forEach(method => {
+  Chain.prototype[method] = function (value) {
+    if (this._hasInvoked === true || this._promise) {
+      throwIfAlreadyInvoked()
+    }
+    this.option[method] = value
+    return this
+  }
+})
+
+Chain.prototype.end = function (callback) {
+  if (this._hasInvoked === true || this._promise) {
+    throwIfAlreadyInvoked()
+  }
+  this._hasInvoked = true
+  if (typeof callback === 'function') {
+    doInject(this.dispatch, this.option, callback)
+  } else {
+    this._promise = doInject(this.dispatch, this.option)
+    return this._promise
+  }
+}
+
+Object.getOwnPropertyNames(Promise.prototype).forEach(method => {
+  if (method === 'constructor') return
+  Chain.prototype[method] = function (...args) {
+    if (!this._promise) {
+      if (this._hasInvoked === true) {
+        throwIfAlreadyInvoked()
+      }
+      this._promise = doInject(this.dispatch, this.option)
+      this._hasInvoked = true
+    }
+    return this._promise[method](...args)
+  }
+})
+
 function isInjection (obj) {
   return (obj instanceof Request || obj instanceof Response)
 }
 
 function toLowerCase (m) { return m.toLowerCase() }
 
+function throwIfAlreadyInvoked () {
+  throw new Error('The dispatch function has already been invoked')
+}
+
 module.exports = inject
 module.exports.isInjection = isInjection

test/async-await.js

@@ -1,7 +1,7 @@
 'use strict'
 
 function asyncAwaitTest (t, inject) {
-  t.plan(2)
+  t.plan(3)
 
   t.test('basic async await', async t => {
     const dispatch = function (req, res) {
@@ -29,6 +29,21 @@ function asyncAwaitTest (t, inject) {
       t.ok(err)
     }
   })
+
+  t.test('chainable api with async await', async t => {
+    const dispatch = function (req, res) {
+      res.writeHead(200, { 'Content-Type': 'text/plain' })
+      res.end('hello')
+    }
+
+    try {
+      const chain = inject(dispatch).get('http://example.com:8080/hello')
+      const res = await chain.end()
+      t.equal(res.payload, 'hello')
+    } catch (err) {
+      t.fail(err)
+    }
+  })
 }
 
 module.exports = asyncAwaitTest

test/index.test-d.ts

@@ -1,4 +1,4 @@
-import { inject, isInjection, Request, Response, DispatchFunc, InjectOptions } from '../index'
+import { inject, isInjection, Request, Response, DispatchFunc, InjectOptions, Chain } from '../index'
 import { expectType } from 'tsd'
 
 expectType<InjectOptions>({ url: '/' })
@@ -21,6 +21,15 @@ inject(dispatch, { method: 'get', url: '/' }, (err, res) => {
   expectType<Function>(res.json)
 })
 
-expectType<Promise<Response>>(inject(dispatch, { method: 'get', url: '/' }))
+inject(dispatch)
+  .get('/')
+  .end((err, res) => {
+    expectType<Error>(err)
+    expectType<Response>(res)
+    console.log(res.payload)
+  })
+
+expectType<Chain>(inject(dispatch))
+expectType<Chain>(inject(dispatch, { method: 'get', url: '/' }))
 // @ts-ignore tsd supports top-level await, but normal ts does not so ignore
 expectType<Response>(await inject(dispatch, { method: 'get', url: '/' }))