Add TypeScript typings (#39)

* add init typings

* Perfect typings and add tsd

* Update docs and remove test file

Author: Ethan-Arrowood

README.md

@@ -65,6 +65,42 @@ try {
 }
 ```
 
+This module ships with a handwritten TypeScript declaration file for TS support. The declaration exports a single namespace `LightMyRequest`. You can import it one of two ways:
+```typescript
+import * as LightMyRequest from 'light-my-request'
+
+const dispatch: LightMyRequest.DispatchFunc = function (req, res) {
+  const reply = 'Hello World'
+  res.writeHead(200, { 'Content-Type': 'text/plain', 'Content-Length': reply.length })
+  res.end(reply)
+}
+
+LightMyRequest.inject(dispatch, { method: 'get', url: '/' }, (err, res) => {
+  console.log(res.payload)
+})
+
+// or
+import { inject, DistpatchFunc } from 'light-my-request'
+
+const dispatch: DispatchFunc = function (req, res) {
+  const reply = 'Hello World'
+  res.writeHead(200, { 'Content-Type': 'text/plain', 'Content-Length': reply.length })
+  res.end(reply)
+}
+
+inject(dispatch, { method: 'get', url: '/' }, (err, res) => {
+  console.log(res.payload)
+})
+```
+The declaration file exports types for the following parts of the API:
+- `inject` - standard light-my-request `inject` method
+- `DispatchFunc` - the fake HTTP dispatch function
+- `InjectPayload` - a union type for valid payload types
+- `isInjection` - standard light-my-request `isInjection` method
+- `InjectOptions` - options object for `inject` method
+- `Request` - custom light-my-request `request` object interface. Extends Node.js `stream.Readable` type
+- `Response` - custom light-my-re uest `response` object interface. Extends Node.js `http.ServerResponse` type
+
 ## API
 
 #### `inject(dispatchFunc, options, callback)`

index.d.ts

@@ -0,0 +1,76 @@
+import * as stream from 'stream'
+import * as http from 'http'
+
+type HTTPMethods = 'DELETE' | 'delete' |
+                   'GET' | 'get' |
+                   'HEAD' | 'head' |
+                   'PATCH' | 'patch' |
+                   'POST' | 'post' |
+                   'PUT' | 'put' |
+                   'OPTIONS' | 'options'
+
+declare namespace LightMyRequest {
+  function inject (
+    dispatchFunc: DispatchFunc,
+    options: string | InjectOptions
+  ): Promise<Response>
+  function inject (
+    dispatchFunc: DispatchFunc,
+    options: string | InjectOptions,
+    callback: (err: Error, response: Response) => void
+  ): void
+
+  type DispatchFunc = (req: Request, res: Response) => void
+
+  type InjectPayload = string | object | Buffer | NodeJS.ReadableStream
+
+  function isInjection (obj: Request | Response): boolean
+
+  interface InjectOptions {
+    url: string | {
+      pathname: string
+      protocal?: string
+      hostname?: string
+      port?: string | number
+      query?: string
+    }
+    headers?: http.IncomingHttpHeaders | http.OutgoingHttpHeaders
+    query?: string
+    simulate?: {
+      end: boolean,
+      split: boolean,
+      error: boolean,
+      close: boolean
+    }
+    authority?: string
+    remoteAddress?: string
+    method?: HTTPMethods
+    validate?: boolean
+    payload?: InjectPayload
+    server?: http.Server
+  }
+
+  interface Request extends stream.Readable {
+    url: string
+    httpVersion: string
+    method: HTTPMethods
+    headers: http.IncomingHttpHeaders
+    prepare: (next: () => void) => void
+  }
+
+  interface Response extends http.ServerResponse {
+    raw: {
+      res: http.ServerResponse
+    }
+    rawPayload: Buffer
+    headers: http.OutgoingHttpHeaders
+    statusCode: number
+    statusMessage: string
+    trailers: { [key: string]: string }
+    payload: string
+    body: string
+    addTrailers: (trailers: { [key: string]: string }) => void
+  }
+}
+
+export = LightMyRequest

package.json

@@ -7,17 +7,21 @@
     "ajv": "^6.8.1",
     "readable-stream": "^3.1.1"
   },
+  "types": "index.d.ts",
   "devDependencies": {
+    "@types/node": "^11.11.4",
     "form-data": "^2.3.3",
     "pre-commit": "^1.2.2",
     "standard": "^12.0.0",
-    "tap": "^12.5.1"
+    "tap": "^12.5.1",
+    "tsd": "^0.7.0"
   },
   "scripts": {
-    "test": "npm run lint && npm run unit",
+    "test": "npm run lint && npm run unit && npm run tsd",
     "lint": "standard",
     "unit": "tap test/test.js",
-    "coverage": "npm run unit -- --cov --coverage-report=html"
+    "coverage": "npm run unit -- --cov --coverage-report=html",
+    "tsd": "tsd"
   },
   "repository": {
     "type": "git",
@@ -35,5 +39,8 @@
   "bugs": {
     "url": "https://github.com/fastify/light-my-request/issues"
   },
-  "homepage": "https://github.com/fastify/light-my-request/blob/master/README.md"
+  "homepage": "https://github.com/fastify/light-my-request/blob/master/README.md",
+  "tsd": {
+    "directory": "test"
+  }
 }

test/index.test-d.ts

@@ -0,0 +1,25 @@
+import { inject, isInjection, Request, Response, DispatchFunc, InjectOptions } from '../index'
+import { expectType } from 'tsd'
+
+expectType<InjectOptions>({ url: '/' })
+
+const dispatch = function (req: Request, res: Response) {
+  expectType<boolean>(isInjection(req))
+  expectType<boolean>(isInjection(res))
+
+  const reply = 'Hello World'
+  res.writeHead(200, { 'Content-Type': 'text/plain', 'Content-Length': reply.length })
+  res.end(reply)
+}
+
+expectType<DispatchFunc>(dispatch)
+
+inject(dispatch, { method: 'get', url: '/' }, (err, res) => {
+  expectType<Error>(err)
+  expectType<Response>(res)
+  console.log(res.payload)
+})
+
+expectType<Promise<Response>>(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: '/' }))

tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "module": "commonjs",
+    "noEmit": true,
+    "strict": true,
+    "noImplicitAny": true
+  },
+  "files": [
+    "./test/index.test-d.ts"
+  ]
+}