From 8ca334b113c3147ef0280af0d2c4fef0dc54a873 Mon Sep 17 00:00:00 2001 From: Tobias Schneider Date: Wed, 26 May 2021 02:05:00 +0200 Subject: [PATCH] Added docs --- index.d.ts | 325 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 281 insertions(+), 44 deletions(-) diff --git a/index.d.ts b/index.d.ts index f3fc6be..d4d56da 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,58 +1,295 @@ -export = Router +export = Router; +/** + * Router + * + * @class + * @constructor + * @public + */ declare class Router { - protected routes: Route[] - protected corsConfig: RouterCorsConfig - connect(url: string, ...handlers: RouterHandler[]): Router - delete(url: string, ...handlers: RouterHandler[]): Router - get(url: string, ...handlers: RouterHandler[]): Router - head(url: string, ...handlers: RouterHandler[]): Router - options(url: string, ...handlers: RouterHandler[]): Router - patch(url: string, ...handlers: RouterHandler[]): Router - post(url: string, ...handlers: RouterHandler[]): Router - put(url: string, ...handlers: RouterHandler[]): Router - trace(url: string, ...handlers: RouterHandler[]): Router - any(url: string, ...handlers: RouterHandler[]): Router - all(url: string, ...handlers: RouterHandler[]): Router - cors(config: RouterCorsConfig): Router + /** + * Router Array + * + * @protected + * @type {Route[]} + */ + protected routes: Route[]; + /** + * CORS Config + * + * @protected + * @type {RouterCorsConfig} + */ + protected corsConfig: RouterCorsConfig; + /** + * Route Object + * + * @typedef Route + * @property {string} method HTTP request method + * @property {string} url URL String + * @property {RouterHandler[]} handlers Array of handler functions + */ + /** + * Request Object + * + * @typedef RouterRequest + * @property {string} method HTTP request method + * @property {Object} params Object containing all parameters defined in the url string + * @property {Object} headers Object containing request headers + * @property {Object|string} body Only available if method is `POST`, `PUT` or `PATCH`. Contains either the received body string or a parsed object if valid JSON was sent. + */ + /** + * Response Object + * + * @typedef RouterResponse + * @property {Object} headers Object you can set response headers in + * @property {number} status Return status code (default: `204`) + * @property {Object|string} body Either an `object` (will be converted to JSON) or a string + */ + /** + * Next Function + * + * @callback RouterNext + * @returns {Promise} + */ + /** + * Handler Function + * + * @callback RouterHandler + * @param {Request} request + * @param {Response} response + * @param {next} next + */ + /** + * Register CONNECT route + * + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + connect(url: string, ...handlers: RouterHandler[]): Router; + /** + * Register DELETE route + * + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + delete(url: string, ...handlers: RouterHandler[]): Router; + /** + * Register GET route + * + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + get(url: string, ...handlers: RouterHandler[]): Router; + /** + * Register HEAD route + * + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + head(url: string, ...handlers: RouterHandler[]): Router; + /** + * Register OPTIONS route + * + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + options(url: string, ...handlers: RouterHandler[]): Router; + /** + * Register PATCH route + * + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + patch(url: string, ...handlers: RouterHandler[]): Router; + /** + * Register POST route + * + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + post(url: string, ...handlers: RouterHandler[]): Router; + /** + * Register PUT route + * + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + put(url: string, ...handlers: RouterHandler[]): Router; + /** + * Register TRACE route + * + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + trace(url: string, ...handlers: RouterHandler[]): Router; + /** + * Register route, ignoring method + * + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + any(url: string, ...handlers: RouterHandler[]): Router; + /** + * Register route, ignoring method + * + * @deprecated since version 1.0.2, use .any(url, ...handlers) instead. + * @param {string} url + * @param {...RouterHandler} handlers + * @returns {Router} + */ + all(url: string, ...handlers: RouterHandler[]): Router; + /** + * CORS Config + * + * @typedef RouterCorsConfig + * @property {string} allowOrigin Access-Control-Allow-Origin (default: `*`) + * @property {string} allowMethods Access-Control-Allow-Methods (default: `*`) + * @property {string} allowHeaders Access-Control-Allow-Headers (default: `*`) + * @property {number} maxAge Access-Control-Max-Age (default: `86400`) + * @property {number} optionsSuccessStatus Return status code for OPTIONS request (default: `204`) + */ + /** + * Enable CORS support + * + * @param {RouterCorsConfig} config + * @returns {Router} + */ + cors(config: RouterCorsConfig): Router; + /** + * Register route + * + * @private + * @param {string} method HTTP request method + * @param {string} url URL String + * @param {RouterHandler[]} handlers Arrar of handler functions + * @returns {Router} + */ private register(method: string, url: string, handlers: RouteHandler[]): Router - private getRoute(request: Request): Route | undefined - handle(event: Event): Response + /** + * Get Route by request + * + * @private + * @param {Request} request + * @returns {Route|undefined} + */ + private getRoute(request: Request): Route | undefined + /** + * Handle requests + * + * @param {Event} event + * @returns {Response} + */ + handle(event: Event): Response; } declare namespace Router { - export { Route, RouterRequest, RouterResponse, RouterNext, RouterHandler, RouterCorsConfig } + export { Route, RouterRequest, RouterResponse, RouterNext, RouterHandler, RouterCorsConfig }; } +/** + * Route Object + */ type Route = { - method: string - url: string - handlers: RouterHandler[] -} + /** + * HTTP request method + */ + method: string; + /** + * URL String + */ + url: string; + /** + * Array of handler functions + */ + handlers: RouterHandler[]; +}; +/** + * CORS Config + */ type RouterCorsConfig = { - allowOrigin: string - allowMethods: string - allowHeaders: string - maxAge: number - optionsSuccessStatus: number -} -type RouterHandler = (request: Request, response: Response, next: RouterNext) => any + /** + * Access-Control-Allow-Origin (default: `*`) + */ + allowOrigin: string; + /** + * Access-Control-Allow-Methods (default: `*`) + */ + allowMethods: string; + /** + * Access-Control-Allow-Headers (default: `*`) + */ + allowHeaders: string; + /** + * Access-Control-Max-Age (default: `86400`) + */ + maxAge: number; + /** + * Return status code for OPTIONS request (default: `204`) + */ + optionsSuccessStatus: number; +}; +/** + * Handler Function + */ +type RouterHandler = (request: Request, response: Response, next: any) => any; +/** + * Request Object + */ type RouterRequest = { - method: string + /** + * HTTP request method + */ + method: string; + /** + * Object containing all parameters defined in the url string + */ params: { - [x: string]: string - } + [x: string]: string; + }; + /** + * Object containing request headers + */ headers: { - [x: string]: string - } + [x: string]: string; + }; + /** + * Only available if method is `POST`, `PUT` or `PATCH`. Contains either the received body string or a parsed object if valid JSON was sent. + */ body: { - [x: string]: string - } | string -} + [x: string]: string; + } | string; +}; +/** + * Response Object + */ type RouterResponse = { + /** + * Object you can set response headers in + */ headers: { - [x: string]: string - } - status: number + [x: string]: string; + }; + /** + * Return status code (default: `204`) + */ + status: number; + /** + * Either an `object` (will be converted to JSON) or a string + */ body: { - [x: string]: string - } | string -} -type RouterNext = () => Promise \ No newline at end of file + [x: string]: string; + } | string; +}; +/** + * Next Function + */ +type RouterNext = () => Promise;