Merge pull request #11 from codeclown/type-definitions

Type definitions

Author: codeclown

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## Upcoming
+
+Features:
+- TypeScript type definitions (4beec22)
+
 ## 1.3.0
 
 Features:

CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing
+
+## Code conventions, code style
+
+Yea is written as pure JavaScript with no precompilation (other than minification for the distributed version).
+
+## Documentation
+
+Documentation of all methods should be kept up-to-date in two places:
+
+- `README.md` – Extensive documentation for each method, with examples
+- `index.d.ts` – 1-to-2 sentence documentation for each method, with minimal examples
+
+## Changelog
+
+Each change should be complemented with a bulletpoint in CHANGELOG.md under "Upcoming".

README.md

@@ -12,6 +12,7 @@ Requests are configured via method calls and each method always returns a fresh
 - Immutable API, Promise-based, throws meaningful errors
 - No external dependencies, quite small (<2.4KB minified and gzipped)
 - Understands Content-Type (decodes JSON responses by default)
+- [TypeScript support](#usage-with-typescript)
 - [Works on modern browsers and some older ones](#browser-support)
 - [Fully tested](/test/specs) (see e.g. [requests.spec.js](/test/specs/requests.spec.js))
 
@@ -22,6 +23,7 @@ Why not use fetch, axios, jQuery, etc..? See [COMPARISON.md](COMPARISON.md).
 
 - [Installation](#installation)
 - [Usage](#usage)
+- [Usage with TypeScript](#usage-with-typescript)
 - [API](#api)
 - [Inspect request config](#inspect-request-config)
 - [Extending (instances)](#extending-instances)
@@ -141,6 +143,21 @@ const account = await request.get('https://example.com/accounts.json').prop('dat
 ```
 
 
+## Usage with TypeScript
+
+Yea comes with built-in type declarations.
+
+```ts
+import yea, { YeaRequestError } from 'yea';
+request.get('https://example.com').then(response => {
+  // Response is implicitly an instance of YeaResponse
+  console.log(response.body);
+}).catch((error: YeaRequestError) => {
+  console.error(error.response.status);
+});
+```
+
+
 ## API
 
 The following methods are available.
@@ -243,14 +260,21 @@ request.baseUrl('https://example.com/nested/foo').url('accounts')  // => https:/
 
 ### query
 
-Sets query parameters from an object. Overwrites existing query.
+Sets query parameters from an object or a string. Overwrites existing query.
 
 ```js
 .query(object | string)
 ```
 
 Where `object` is key-value object of query parameters to set, or a valid query string.
 
+Example:
+
+```js
+request.query({ first: 'foo', second: 'bar' })
+request.query('first=foo&second=bar')
+```
+
 ### headers
 
 Sets request headers from an object. Overwrites existing headers.
@@ -324,7 +348,7 @@ console.log(req.toObject().headers) // => { 'x-token': 'secret123' }
 
 ### body
 
-Set the body of the request.
+Set the raw body of the request.
 
 ```js
 .body(data)
@@ -348,13 +372,13 @@ Shorthand for `request.header('Content-Type', 'application/json').body(JSON.stri
 
 ### urlencoded
 
-Sets a JSON-encoded body and sets the `Content-Type` header to `'application/urlencoded'`.
+Sets a URL-encoded body and sets the `Content-Type` header to `'application/urlencoded'`.
 
 ```js
-.urlencoded(value)
+.urlencoded(data)
 ```
 
-Where `value` is mixed.
+Where `value` is an object.
 
 Shorthand for `request.header('content-type', 'application/x-www-form-urlencoded').body(_valueUrlEncoded_)`.
 
@@ -391,8 +415,8 @@ Where `path` is a string or an array.
 Example:
 
 ```js
-cosnt account = await request.get('...').prop('data.accounts[0]');
-cosnt contentType = await request.get('...').prop(['headers', 'content-type']);
+const account = await request.get('...').prop('data.accounts[0]');
+const contentType = await request.get('...').prop(['headers', 'content-type']);
 ```
 
 ### send
@@ -439,15 +463,15 @@ Note that calling `.send()` is not always necessary. You can usually directly ca
 
 ### sendUrlencoded
 
-Short-hand for `.urlencoded(data).send()`.
+Shorthand for `.urlencoded(data).send()`.
 
 ```js
 .sendUrlencoded(data)
 ```
 
 ### sendJson
 
-Short-hand for `.json(data).send()`.
+Shorthand for `.json(data).send()`.
 
 ```js
 .sendJson(data)

index.d.ts

@@ -0,0 +1,188 @@
+export as namespace yea;
+
+export interface YeaResponse {
+  headers: {
+    [key: string]: string;
+  };
+  body: string;
+  status: number;
+}
+
+/**
+ * Error thrown when sending a request fails.
+ */
+export interface YeaRequestError extends Error {
+  response: YeaResponse;
+}
+
+export type ResponseTransformer = (response: YeaResponse) => YeaResponse;
+
+declare class YeaAjaxRequest implements PromiseLike<YeaResponse> {
+  jsonResponseTransformer: ResponseTransformer;
+
+  then<TResult1 = YeaResponse, TResult2 = never>(
+    onfulfilled?:
+      | ((value: YeaResponse) => TResult1 | PromiseLike<TResult1>)
+      | undefined
+      | null,
+    onrejected?:
+      | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+      | undefined
+      | null
+  ): Promise<TResult1 | TResult2>;
+
+  /**
+   * Sets the HTTP method.
+   * @see get
+   * @see post
+   * @see put
+   * @see delete
+   */
+  method(
+    method:
+      | "GET"
+      | "POST"
+      | "PUT"
+      | "DELETE"
+      | "get"
+      | "post"
+      | "put"
+      | "delete"
+  ): this;
+
+  /**
+   * Initializes a GET request
+   * @example `yea.get('http://example.com/data.json')`
+   */
+  get(url: string): this;
+
+  /**
+   * Initializes a POST request
+   * @example `yea.post('http://example.com/data')`
+   */
+  post(url: string): this;
+
+  /**
+   * Initializes a PUT request
+   */
+  put(url: string): this;
+
+  /**
+   * Initializes a DELETE request
+   */
+  delete(url: string): this;
+
+  /**
+   * Sets the full URL of the request. If a query-string is present, it will override any previously set query parameters.
+   */
+  url(url: string): this;
+
+  /**
+   * Sets the base URL to which all subsequent request URLs will be appended.
+   */
+  baseUrl(baseUrl: string): this;
+
+  /**
+   * Sets query parameters from an object. Overwrites existing query.
+   */
+  query(query: object | string): this;
+
+  /**
+   * Sets request headers from an object. Overwrites existing headers.
+   */
+  headers(headers: object): this;
+
+  /**
+   * Sets request headers from an object. Only overwrites headers present in the given object.
+   */
+  amendHeaders(headers: object): this;
+
+  /**
+   * Adds or updates a header value.
+   */
+  header(name: string, value: string): this;
+
+  /**
+   * Removes a header from the request.
+   */
+  unsetHeader(name: string): this;
+
+  /**
+   * Set the raw body of the request. See also `json` and `urlencoded`.
+   */
+  body(data: string | number): this;
+
+  /**
+   * Sets a URL-encoded body and sets the `Content-Type` header to `'application/urlencoded'`.
+   */
+  urlencoded(data: object): this;
+
+  /**
+   * Sets a JSON-encoded body and sets the `Content-Type` header to `'application/json'`.
+   */
+  json(data: any): this;
+
+  /**
+   * Sets a timeout after which the request will be aborted and the Promise rejected.
+   */
+  timeout(milliseconds): this;
+
+  /**
+   * Removes the timeout-value previously set with `timeout`.
+   */
+  unsetTimeout(): this;
+
+  /**
+   * Sets a path (similar to `lodash.get`) which will be resolved once the response is returned.
+   * @example
+```js
+const account = await request.get('...').prop('data.accounts[0]');
+const contentType = await request.get('...').prop(['headers', 'content-type']);
+```
+   */
+  prop(path: string): this;
+
+  /**
+   * Sets a list of response transformers which are called when a response is received. See the documentation for more information.
+   */
+  setResponseTransformers(transformers: ResponseTransformer[]): this;
+
+  /**
+   * By default any 2XX status code resolves the Promise and other status codes will reject it. This can be customized using `setAllowedStatusCode`.
+   */
+  setAllowedStatusCode(
+    allowedStatusCode: number | RegExp | ((statusCode: number) => boolean)
+  ): this;
+
+  /**
+   * Override global dependencies which are used internally (like Promise). See the documentation for more information.
+   */
+  polyfills(polyfills: { Promise: typeof Promise }): this;
+
+  /**
+   * Returns the request configuration as an object.
+   */
+  toObject(): object;
+  config(): object;
+  debug(): object;
+
+  /**
+   * Shorthand for `.urlencoded(data).send()`.
+   */
+  sendUrlencoded(data: object): Promise<YeaResponse>;
+
+  /**
+   * Shorthand for `.json(data).send()`.
+   */
+  sendJson(data: any): Promise<YeaResponse>;
+
+  /**
+   * Dispatches the request and returns a Promise. See also `sendJson` and `sendUrlencoded`.
+   */
+  send(body?: string): Promise<YeaResponse>;
+}
+
+// An instance of a class is exported
+// i.e. `module.exports = new YeaAjaxRequest()`
+declare const _YeaAjaxRequest: YeaAjaxRequest;
+export default _YeaAjaxRequest;