@tsndr/cloudflare-worker-router
Version:
Cloudflare Workers Router is a super lightweight router (1.0K gzipped) with middleware support and **ZERO dependencies** for [Cloudflare Workers](https://workers.cloudflare.com/).
267 lines (266 loc) • 7.32 kB
TypeScript
/**
* Route Object
*
* @typedef Route
* @property {string} method HTTP request method
* @property {string} url URL String
* @property {RouterHandler[]} handlers Array of handler functions
*/
export type Route<Env, CtxExt, ReqExt> = {
method: string;
url: string;
handlers: RouterHandler<Env, CtxExt, ReqExt>[];
};
/**
* Router Context
*
* @typedef RouterContext
* @property {RouterEnv} env Environment
* @property {RouterRequest} req Request Object
* @property {ExecutionContext} ctx Context Object
*/
export type RouterContext<Env = any, CtxExt = {}, ReqExt = {}> = CtxExt & {
env: Env;
req: RouterRequest<ReqExt>;
dbg: boolean;
ctx?: ExecutionContext;
};
/**
* Request Object
*
* @typedef RouterRequest
* @property {string} url URL
* @property {string} method HTTP request method
* @property {RouterRequestParams} params Object containing all parameters defined in the url string
* @property {RouterRequestQuery} query Object containing all query parameters
* @property {Headers} headers Request headers object
* @property {Request} raw Raw Request Object
* @property {IncomingRequestCfProperties} [cf] object containing custom Cloudflare properties. (https://developers.cloudflare.com/workers/examples/accessing-the-cloudflare-object)
*/
export type RouterRequest<ReqExt> = ReqExt & {
url: string;
method: string;
params: RouterRequestParams;
query: RouterRequestQuery;
headers: Headers;
raw: Request;
arrayBuffer(): Promise<ArrayBuffer>;
text(): Promise<string>;
json<T>(): Promise<T>;
formData(): Promise<FormData>;
blob(): Promise<Blob>;
bearer(): string | undefined;
basic(): [string, string];
cf?: IncomingRequestCfProperties;
};
/**
* Request Parameters
*
* @typedef RouterRequestParams
*/
export type RouterRequestParams = {
[key: string]: string;
};
/**
* Request Query
*
* @typedef RouterRequestQuery
*/
export type RouterRequestQuery = {
[key: string]: string;
};
/**
* Handler Function
*
* @callback RouterHandler
* @param {RouterContext} ctx
* @returns {Promise<Response | void> Response | void}
*/
export type RouterHandler<Env = any, CtxExt = {}, ReqExt = {}> = {
(ctx: RouterContext<Env, CtxExt, ReqExt>): Promise<Response | void> | Response | void;
};
/**
* 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 {boolean} [allowCredentials="true"] Access-Control-Allow-Credentials (default: undefined)
* @property {string} [vary="origin"] vary (default: undefined)
* @property {number} [maxAge=86400] Access-Control-Max-Age (default: `86400`)
* @property {number} [optionsSuccessStatus=204] Return status code for OPTIONS request (default: `204`)
*/
export type RouterCorsConfig = {
allowOrigin?: string;
allowMethods?: string;
allowHeaders?: string;
allowCredentials?: boolean;
vary?: string;
maxAge?: number;
optionsSuccessStatus?: number;
};
export type RouterBuffer = {
arrayBuffer?: ArrayBuffer;
text?: string;
json?: any;
formData?: FormData;
blob?: Blob;
};
/**
* Router
*
* @public
* @class
*/
export declare class Router<Env = any, CtxExt = {}, ReqExt = {}> {
/**
* Router Array
*
* @protected
* @type {Route[]}
*/
protected routes: Route<Env, CtxExt, ReqExt>[];
/**
* Global Handlers
*
* @protected
* @type {RouterHandler[]}
*/
protected globalHandlers: RouterHandler<Env, CtxExt, ReqExt>[];
/**
* Debug Mode
*
* @protected
* @type {boolean}
*/
protected debugMode: boolean;
/**
* CORS Config
*
* @protected
* @type {RouterCorsConfig}
*/
protected corsConfig: RouterCorsConfig;
/**
* CORS enabled
*
* @protected
* @type {boolean}
*/
protected corsEnabled: boolean;
/**
* Register global handlers
*
* @param {RouterHandler[]} handlers
* @returns {Router}
*/
use(...handlers: RouterHandler<Env, CtxExt, ReqExt>[]): Router<Env, CtxExt, ReqExt>;
/**
* Register DELETE route
*
* @param {string} url
* @param {RouterHandler[]} handlers
* @returns {Router}
*/
delete(url: string, ...handlers: RouterHandler<Env, CtxExt, ReqExt>[]): Router<Env, CtxExt, ReqExt>;
/**
* Register GET route
*
* @param {string} url
* @param {RouterHandler[]} handlers
* @returns {Router}
*/
get(url: string, ...handlers: RouterHandler<Env, CtxExt, ReqExt>[]): Router<Env, CtxExt, ReqExt>;
/**
* Register HEAD route
*
* @param {string} url
* @param {RouterHandler[]} handlers
* @returns {Router}
*/
head(url: string, ...handlers: RouterHandler<Env, CtxExt, ReqExt>[]): Router<Env, CtxExt, ReqExt>;
/**
* Register OPTIONS route
*
* @param {string} url
* @param {RouterHandler[]} handlers
* @returns {Router}
*/
options(url: string, ...handlers: RouterHandler<Env, CtxExt, ReqExt>[]): Router<Env, CtxExt, ReqExt>;
/**
* Register PATCH route
*
* @param {string} url
* @param {RouterHandler[]} handlers
* @returns {Router}
*/
patch(url: string, ...handlers: RouterHandler<Env, CtxExt, ReqExt>[]): Router<Env, CtxExt, ReqExt>;
/**
* Register POST route
*
* @param {string} url
* @param {RouterHandler[]} handlers
* @returns {Router}
*/
post(url: string, ...handlers: RouterHandler<Env, CtxExt, ReqExt>[]): Router<Env, CtxExt, ReqExt>;
/**
* Register PUT route
*
* @param {string} url
* @param {RouterHandler[]} handlers
* @returns {Router}
*/
put(url: string, ...handlers: RouterHandler<Env, CtxExt, ReqExt>[]): Router<Env, CtxExt, ReqExt>;
/**
* Register route, ignoring method
*
* @param {string} url
* @param {RouterHandler[]} handlers
* @returns {Router}
*/
any(url: string, ...handlers: RouterHandler<Env, CtxExt, ReqExt>[]): Router<Env, CtxExt, ReqExt>;
/**
* Debug Mode
*
* @param {boolean} [state=true] Whether to turn on or off debug mode (default: true)
* @returns {Router}
*/
debug(state?: boolean): Router<Env, CtxExt, ReqExt>;
/**
* Enable CORS support
*
* @param {RouterCorsConfig} [config]
* @returns {Router}
*/
cors(config?: RouterCorsConfig): Router<Env, CtxExt, ReqExt>;
private setCorsHeaders;
/**
* 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;
/**
* Get Route by request
*
* @private
* @param {RouterRequest} request
* @returns {Route | undefined}
*/
private getRoute;
/**
* Handle requests
*
* @param {Request} request
* @param {Env} env
* @param {CtxExt} [ctxExt]
* @param {ReqExt} [reqExt]
* @returns {Promise<Response>}
*/
handle(request: Request, env: Env, ctx?: ExecutionContext, ctxExt?: CtxExt, reqExt?: ReqExt): Promise<Response>;
}