Merge pull request #36 from LuminescentMoon/master

Add TypeScript declaration

package.json

@@ -3,6 +3,7 @@
   "version": "3.3.0",
   "description": "The ultra-lightweight Node.js HTTP client",
   "main": "lib/phin.min.js",
+  "types": "types.d.ts",
   "scripts": {
     "test": "node ./tests/test.js",
     "prepublishOnly": "npm test",

types.d.ts

@@ -0,0 +1,103 @@
+// Default Options feature is not supported because it's basically impossible to write strongly-typed definitions for it.
+
+import * as http from 'http'
+
+interface IOptionsBase {
+  url: string
+  method?: string
+  headers?: object
+  core?: http.ClientRequestArgs
+  followRedirects?: boolean
+  stream?: boolean
+  compression?: boolean
+  timeout?: number
+  hostname?: string
+  port?: number
+  path?: string
+}
+
+// Form and data property has been written this way so they're mutually exclusive.
+type IWithData<T extends {}> = T & {
+  data: {
+    toString(): string
+  }
+}
+
+type IWithForm<T extends {}> = T & {
+  form: {
+    [index: string]: string
+  }
+}
+
+declare function phin<T>(options:
+  phin.IJSONResponseOptions |
+  IWithData<phin.IJSONResponseOptions> |
+  IWithForm<phin.IJSONResponseOptions>): Promise<phin.IJSONResponse<T>>
+
+declare function phin(options:
+  phin.IStreamResponseOptions |
+  IWithData<phin.IStreamResponseOptions> |
+  IWithForm<phin.IStreamResponseOptions>): Promise<phin.IStreamResponse>
+
+declare function phin(options:
+  phin.IOptions |
+  IWithData<phin.IOptions> |
+  IWithForm<phin.IOptions> |
+  string): Promise<phin.IResponse>
+
+declare namespace phin {
+  export interface IJSONResponseOptions extends IOptionsBase {
+    parse: 'json'
+  }
+
+  export interface IStreamResponseOptions extends IOptionsBase {
+    stream: true
+  }
+
+  export interface IOptions extends IOptionsBase {
+    parse?: 'none'
+  }
+
+  export interface IJSONResponse<T> extends http.IncomingMessage {
+    body: T
+  }
+
+  export interface IStreamResponse extends http.IncomingMessage {
+    stream: http.IncomingMessage
+  }
+
+  export interface IResponse extends http.IncomingMessage {
+    body: string
+  }
+
+  // NOTE: Typescript cannot infer type of union callback on the consumer side
+  // https://github.com/Microsoft/TypeScript/pull/17819#issuecomment-363636904
+  type IErrorCallback = (error: Error | string, response: null) => void
+  type ICallback<T> = (error: null, response: NonNullable<T>) => void
+
+  export let promisified: typeof phin
+
+  export function unpromisified<T>(
+    options:
+      IJSONResponseOptions |
+      IWithData<IJSONResponseOptions> |
+      IWithForm<IJSONResponseOptions>,
+    callback: IErrorCallback | ICallback<IJSONResponse<T>>): void
+
+  export function unpromisified(
+    options:
+      IStreamResponseOptions |
+      IWithData<IStreamResponseOptions> |
+      IWithForm<IStreamResponseOptions>,
+    callback: IErrorCallback | ICallback<IStreamResponse>): void
+
+  export function unpromisified(
+    options:
+      IOptions |
+      IWithData<IOptions> |
+      IWithForm<IOptions> |
+      string,
+    callback: IErrorCallback | ICallback<IResponse>): void
+}
+
+export = phin