Extremely Popular
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079/** * Adapted directly from @koa/router at * https://github.com/koajs/router/ which is licensed as: * * The MIT License (MIT) * * Copyright (c) 2015 Alexander C. Mingoia * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN * THE SOFTWARE. */
import type { State } from "./application.ts";import type { Context } from "./context.ts";import { assert, compile, Key, ParseOptions, pathParse, pathToRegexp, Status, TokensToRegexpOptions,} from "./deps.ts";import { httpErrors } from "./httpError.ts";import { compose, Middleware } from "./middleware.ts";import type { HTTPMethods, RedirectStatus } from "./types.d.ts";import { decodeComponent } from "./util.ts";
interface Matches { path: Layer[]; pathAndMethod: Layer[]; route: boolean;}
export interface RouterAllowedMethodsOptions { /** Use the value returned from this function instead of an HTTP error * `MethodNotAllowed`. */ // deno-lint-ignore no-explicit-any methodNotAllowed?(): any;
/** Use the value returned from this function instead of an HTTP error * `NotImplemented`. */ // deno-lint-ignore no-explicit-any notImplemented?(): any;
/** When dealing with a non-implemented method or a method not allowed, throw * an error instead of setting the status and header for the response. */ throw?: boolean;}
export interface Route< P extends RouteParams = RouteParams, // deno-lint-ignore no-explicit-any S extends State = Record<string, any>,> { /** The HTTP methods that this route handles. */ methods: HTTPMethods[];
/** The middleware that will be applied to this route. */ middleware: RouterMiddleware<P, S>[];
/** An optional name for the route. */ name?: string;
/** Options that were used to create the route. */ options: LayerOptions;
/** The parameters that are identified in the route that will be parsed out * on matched requests. */ paramNames: (keyof P)[];
/** The path that this route manages. */ path: string;
/** The regular expression used for matching and parsing parameters for the * route. */ regexp: RegExp;}
/** The context passed router middleware. */export interface RouterContext< P extends RouteParams = RouteParams, // deno-lint-ignore no-explicit-any S extends State = Record<string, any>,> extends Context<S> { /** When matching the route, an array of the capturing groups from the regular * expression. */ captures: string[];
/** The routes that were matched for this request. */ matched?: Layer<P, S>[];
/** Any parameters parsed from the route when matched. */ params: P;
/** A reference to the router instance. */ router: Router;
/** If the matched route has a `name`, the matched route name is provided * here. */ routeName?: string;
/** Overrides the matched path for future route middleware, when a * `routerPath` option is not defined on the `Router` options. */ routerPath?: string;}
export interface RouterMiddleware< P extends RouteParams = RouteParams, // deno-lint-ignore no-explicit-any S extends State = Record<string, any>,> { (context: RouterContext<P, S>, next: () => Promise<unknown>): | Promise<unknown> | unknown; /** For route parameter middleware, the `param` key for this parameter will * be set. */ param?: keyof P; // deno-lint-ignore no-explicit-any router?: Router<any, any>;}
export interface RouterOptions { /** Override the default set of methods supported by the router. */ methods?: HTTPMethods[];
/** Only handle routes where the requested path starts with the prefix. */ prefix?: string;
/** Override the `request.url.pathname` when matching middleware to run. */ routerPath?: string;
/** Determines if routes are matched in a case sensitive way. Defaults to * `false`. */ sensitive?: boolean;
/** Determines if routes are matched strictly, where the trailing `/` is not * optional. Defaults to `false`. */ strict?: boolean;}
/** Middleware that will be called by the router when handling a specific * parameter, which the middleware will be called when a request matches the * route parameter. */export interface RouterParamMiddleware< P extends RouteParams = RouteParams, // deno-lint-ignore no-explicit-any S extends State = Record<string, any>,> { ( param: string, context: RouterContext<P, S>, next: () => Promise<unknown>, ): Promise<unknown> | unknown; // deno-lint-ignore no-explicit-any router?: Router<any, any>;}
export type RouteParams = Record<string | number, string | undefined>;
type LayerOptions = TokensToRegexpOptions & ParseOptions & { ignoreCaptures?: boolean; name?: string;};
type RegisterOptions = LayerOptions & { ignorePrefix?: boolean;};
type UrlOptions = TokensToRegexpOptions & ParseOptions & { /** When generating a URL from a route, add the query to the URL. If an * object */ query?: URLSearchParams | Record<string, string> | string;};
/** Generate a URL from a string, potentially replace route params with * values. */function toUrl(url: string, params: RouteParams = {}, options?: UrlOptions) { const tokens = pathParse(url); let replace: RouteParams = {};
if (tokens.some((token) => typeof token === "object")) { replace = params; } else { options = params; }
const toPath = compile(url, options); const replaced = toPath(replace);
if (options && options.query) { const url = new URL(replaced, "http://oak"); if (typeof options.query === "string") { url.search = options.query; } else { url.search = String( options.query instanceof URLSearchParams ? options.query : new URLSearchParams(options.query), ); } return `${url.pathname}${url.search}${url.hash}`; } return replaced;}
class Layer< P extends RouteParams = RouteParams, // deno-lint-ignore no-explicit-any S extends State = Record<string, any>,> { #opts: LayerOptions; #paramNames: Key[] = []; #regexp: RegExp;
methods: HTTPMethods[]; name?: string; path: string; stack: RouterMiddleware<P, S>[];
constructor( path: string, methods: HTTPMethods[], middleware: RouterMiddleware<P, S> | RouterMiddleware<P, S>[], { name, ...opts }: LayerOptions = {}, ) { this.#opts = opts; this.name = name; this.methods = [...methods]; if (this.methods.includes("GET")) { this.methods.unshift("HEAD"); } this.stack = Array.isArray(middleware) ? middleware.slice() : [middleware]; this.path = path; this.#regexp = pathToRegexp(path, this.#paramNames, this.#opts); }
clone(): Layer<P, S> { return new Layer( this.path, this.methods, this.stack, { name: this.name, ...this.#opts }, ); }
match(path: string): boolean { return this.#regexp.test(path); }
params( captures: string[], existingParams: RouteParams = {}, ): RouteParams { const params = existingParams; for (let i = 0; i < captures.length; i++) { if (this.#paramNames[i]) { const c = captures[i]; params[this.#paramNames[i].name] = c ? decodeComponent(c) : c; } } return params; }
captures(path: string): string[] { if (this.#opts.ignoreCaptures) { return []; } return path.match(this.#regexp)?.slice(1) ?? []; }
url( params: RouteParams = {}, options?: UrlOptions, ): string { const url = this.path.replace(/\(\.\*\)/g, ""); return toUrl(url, params, options); }
param( param: string, // deno-lint-ignore no-explicit-any fn: RouterParamMiddleware<any, any>, ) { const stack = this.stack; const params = this.#paramNames; const middleware: RouterMiddleware = function ( this: Router, ctx, next, ): Promise<unknown> | unknown { const p = ctx.params[param]; assert(p); return fn.call(this, p, ctx, next); }; middleware.param = param;
const names = params.map((p) => p.name);
const x = names.indexOf(param); if (x >= 0) { for (let i = 0; i < stack.length; i++) { const fn = stack[i]; if (!fn.param || names.indexOf(fn.param as (string | number)) > x) { stack.splice(i, 0, middleware); break; } } } return this; }
setPrefix(prefix: string): this { if (this.path) { this.path = this.path !== "/" || this.#opts.strict === true ? `${prefix}${this.path}` : prefix; this.#paramNames = []; this.#regexp = pathToRegexp(this.path, this.#paramNames, this.#opts); } return this; }
// deno-lint-ignore no-explicit-any toJSON(): Route<any, any> { return { methods: [...this.methods], middleware: [...this.stack], paramNames: this.#paramNames.map((key) => key.name), path: this.path, regexp: this.#regexp, options: { ...this.#opts }, }; }
[Symbol.for("Deno.customInspect")](inspect: (value: unknown) => string) { return `${this.constructor.name} ${ inspect({ methods: this.methods, middleware: this.stack, options: this.#opts, paramNames: this.#paramNames.map((key) => key.name), path: this.path, regexp: this.#regexp, }) }`; }}
/** An interface for registering middleware that will run when certain HTTP * methods and paths are requested, as well as provides a way to parameterize * parts of the requested path. */export class Router< RP extends RouteParams = RouteParams, // deno-lint-ignore no-explicit-any RS extends State = Record<string, any>,> { #opts: RouterOptions; #methods: HTTPMethods[]; // deno-lint-ignore no-explicit-any #params: Record<string, RouterParamMiddleware<any, any>> = {}; #stack: Layer[] = [];
#match(path: string, method: HTTPMethods): Matches { const matches: Matches = { path: [], pathAndMethod: [], route: false, };
for (const route of this.#stack) { if (route.match(path)) { matches.path.push(route); if (route.methods.length === 0 || route.methods.includes(method)) { matches.pathAndMethod.push(route); if (route.methods.length) { matches.route = true; } } } }
return matches; }
#register( path: string | string[], middlewares: RouterMiddleware[], methods: HTTPMethods[], options: RegisterOptions = {}, ): void { if (Array.isArray(path)) { for (const p of path) { this.#register(p, middlewares, methods, options); } return; }
let layerMiddlewares: RouterMiddleware[] = []; for (const middleware of middlewares) { if (!middleware.router) { layerMiddlewares.push(middleware); continue; }
if (layerMiddlewares.length) { this.#addLayer(path, layerMiddlewares, methods, options); layerMiddlewares = []; }
const router = middleware.router.#clone();
for (const layer of router.#stack) { if (!options.ignorePrefix) { layer.setPrefix(path); } if (this.#opts.prefix) { layer.setPrefix(this.#opts.prefix); } this.#stack.push(layer); }
for (const [param, mw] of Object.entries(this.#params)) { router.param(param, mw); } }
if (layerMiddlewares.length) { this.#addLayer(path, layerMiddlewares, methods, options); } }
#addLayer( path: string, middlewares: RouterMiddleware[], methods: HTTPMethods[], options: LayerOptions = {}, ) { const { end, name, sensitive = this.#opts.sensitive, strict = this.#opts.strict, ignoreCaptures, } = options; const route = new Layer(path, methods, middlewares, { end, name, sensitive, strict, ignoreCaptures, });
if (this.#opts.prefix) { route.setPrefix(this.#opts.prefix); }
for (const [param, mw] of Object.entries(this.#params)) { route.param(param, mw); }
this.#stack.push(route); }
#route(name: string): Layer | undefined { for (const route of this.#stack) { if (route.name === name) { return route; } } }
#useVerb( nameOrPath: string, pathOrMiddleware: string | RouterMiddleware, middleware: RouterMiddleware[], methods: HTTPMethods[], ): void { let name: string | undefined = undefined; let path: string; if (typeof pathOrMiddleware === "string") { name = nameOrPath; path = pathOrMiddleware; } else { path = nameOrPath; middleware.unshift(pathOrMiddleware); }
this.#register(path, middleware, methods, { name }); }
#clone(): Router<RP, RS> { const router = new Router<RP, RS>(this.#opts); router.#methods = router.#methods.slice(); router.#params = { ...this.#params }; router.#stack = this.#stack.map((layer) => layer.clone()); return router; }
constructor(opts: RouterOptions = {}) { this.#opts = opts; this.#methods = opts.methods ?? [ "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT", ]; }
/** Register named middleware for the specified routes when the `DELETE`, * `GET`, `POST`, or `PUT` method is requested. */ all<P extends RouteParams = RP, S extends State = RS>( name: string, path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; /** Register middleware for the specified routes when the `DELETE`, * `GET`, `POST`, or `PUT` method is requested. */ all<P extends RouteParams = RP, S extends State = RS>( path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; all<P extends RouteParams = RP, S extends State = RS>( nameOrPath: string, pathOrMiddleware: string | RouterMiddleware<P, S>, ...middleware: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)> { this.#useVerb( nameOrPath, pathOrMiddleware as (string | RouterMiddleware), middleware as RouterMiddleware[], ["DELETE", "GET", "POST", "PUT"], ); // deno-lint-ignore no-explicit-any return this as Router<any, any>; }
/** Middleware that handles requests for HTTP methods registered with the * router. If none of the routes handle a method, then "not allowed" logic * will be used. If a method is supported by some routes, but not the * particular matched router, then "not implemented" will be returned. * * The middleware will also automatically handle the `OPTIONS` method, * responding with a `200 OK` when the `Allowed` header sent to the allowed * methods for a given route. * * By default, a "not allowed" request will respond with a `405 Not Allowed` * and a "not implemented" will respond with a `501 Not Implemented`. Setting * the option `.throw` to `true` will cause the middleware to throw an * `HTTPError` instead of setting the response status. The error can be * overridden by providing a `.notImplemented` or `.notAllowed` method in the * options, of which the value will be returned will be thrown instead of the * HTTP error. */ allowedMethods( options: RouterAllowedMethodsOptions = {}, ): Middleware { const implemented = this.#methods;
const allowedMethods: Middleware = async (context, next) => { const ctx = context as RouterContext; await next(); if (!ctx.response.status || ctx.response.status === Status.NotFound) { assert(ctx.matched); const allowed = new Set<HTTPMethods>(); for (const route of ctx.matched) { for (const method of route.methods) { allowed.add(method); } }
const allowedStr = [...allowed].join(", "); if (!implemented.includes(ctx.request.method)) { if (options.throw) { throw options.notImplemented ? options.notImplemented() : new httpErrors.NotImplemented(); } else { ctx.response.status = Status.NotImplemented; ctx.response.headers.set("Allowed", allowedStr); } } else if (allowed.size) { if (ctx.request.method === "OPTIONS") { ctx.response.status = Status.OK; ctx.response.headers.set("Allowed", allowedStr); } else if (!allowed.has(ctx.request.method)) { if (options.throw) { throw options.methodNotAllowed ? options.methodNotAllowed() : new httpErrors.MethodNotAllowed(); } else { ctx.response.status = Status.MethodNotAllowed; ctx.response.headers.set("Allowed", allowedStr); } } } } };
return allowedMethods; }
/** Register named middleware for the specified routes when the `DELETE`, * method is requested. */ delete<P extends RouteParams = RP, S extends State = RS>( name: string, path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; /** Register middleware for the specified routes when the `DELETE`, * method is requested. */ delete<P extends RouteParams = RP, S extends State = RS>( path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; delete<P extends RouteParams = RP, S extends State = RS>( nameOrPath: string, pathOrMiddleware: string | RouterMiddleware<P, S>, ...middleware: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)> { this.#useVerb( nameOrPath, pathOrMiddleware as (string | RouterMiddleware), middleware as RouterMiddleware[], ["DELETE"], ); // deno-lint-ignore no-explicit-any return this as Router<any, any>; }
/** Iterate over the routes currently added to the router. To be compatible * with the iterable interfaces, both the key and value are set to the value * of the route. */ *entries(): IterableIterator<[Route, Route]> { for (const route of this.#stack) { const value = route.toJSON(); yield [value, value]; } }
/** Iterate over the routes currently added to the router, calling the * `callback` function for each value. */ forEach( callback: (value1: Route, value2: Route, router: this) => void, // deno-lint-ignore no-explicit-any thisArg: any = null, ): void { for (const route of this.#stack) { const value = route.toJSON(); callback.call(thisArg, value, value, this); } }
/** Register named middleware for the specified routes when the `GET`, * method is requested. */ get<P extends RouteParams = RP, S extends State = RS>( name: string, path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; /** Register middleware for the specified routes when the `GET`, * method is requested. */ get<P extends RouteParams = RP, S extends State = RS>( path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; get<P extends RouteParams = RP, S extends State = RS>( nameOrPath: string, pathOrMiddleware: string | RouterMiddleware<P, S>, ...middleware: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)> { this.#useVerb( nameOrPath, pathOrMiddleware as (string | RouterMiddleware), middleware as RouterMiddleware[], ["GET"], ); // deno-lint-ignore no-explicit-any return this as Router<any, any>; }
/** Register named middleware for the specified routes when the `HEAD`, * method is requested. */ head<P extends RouteParams = RP, S extends State = RS>( name: string, path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; /** Register middleware for the specified routes when the `HEAD`, * method is requested. */ head<P extends RouteParams = RP, S extends State = RS>( path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; head<P extends RouteParams = RP, S extends State = RS>( nameOrPath: string, pathOrMiddleware: string | RouterMiddleware<P, S>, ...middleware: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)> { this.#useVerb( nameOrPath, pathOrMiddleware as (string | RouterMiddleware), middleware as RouterMiddleware[], ["HEAD"], ); // deno-lint-ignore no-explicit-any return this as Router<any, any>; }
/** Iterate over the routes currently added to the router. To be compatible * with the iterable interfaces, the key is set to the value of the route. */ *keys(): IterableIterator<Route> { for (const route of this.#stack) { yield route.toJSON(); } }
/** Register named middleware for the specified routes when the `OPTIONS`, * method is requested. */ options<P extends RouteParams = RP, S extends State = RS>( name: string, path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; /** Register middleware for the specified routes when the `OPTIONS`, * method is requested. */ options<P extends RouteParams = RP, S extends State = RS>( path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; options<P extends RouteParams = RP, S extends State = RS>( nameOrPath: string, pathOrMiddleware: string | RouterMiddleware<P, S>, ...middleware: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)> { this.#useVerb( nameOrPath, pathOrMiddleware as (string | RouterMiddleware), middleware as RouterMiddleware[], ["OPTIONS"], ); // deno-lint-ignore no-explicit-any return this as Router<any, any>; }
/** Register param middleware, which will be called when the particular param * is parsed from the route. */ param<S extends State = RS>( param: keyof RP, middleware: RouterParamMiddleware<RP, S>, ): Router<RP, S> { this.#params[param as string] = middleware; for (const route of this.#stack) { route.param(param as string, middleware); } return this; }
/** Register named middleware for the specified routes when the `PATCH`, * method is requested. */ patch<P extends RouteParams = RP, S extends State = RS>( name: string, path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; /** Register middleware for the specified routes when the `PATCH`, * method is requested. */ patch<P extends RouteParams = RP, S extends State = RS>( path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; patch<P extends RouteParams = RP, S extends State = RS>( nameOrPath: string, pathOrMiddleware: string | RouterMiddleware<P, S>, ...middleware: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)> { this.#useVerb( nameOrPath, pathOrMiddleware as (string | RouterMiddleware), middleware as RouterMiddleware[], ["PATCH"], ); // deno-lint-ignore no-explicit-any return this as Router<any, any>; }
/** Register named middleware for the specified routes when the `POST`, * method is requested. */ post<P extends RouteParams = RP, S extends State = RS>( name: string, path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; /** Register middleware for the specified routes when the `POST`, * method is requested. */ post<P extends RouteParams = RP, S extends State = RS>( path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; post<P extends RouteParams = RP, S extends State = RS>( nameOrPath: string, pathOrMiddleware: string | RouterMiddleware<P, S>, ...middleware: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)> { this.#useVerb( nameOrPath, pathOrMiddleware as (string | RouterMiddleware), middleware as RouterMiddleware[], ["POST"], ); // deno-lint-ignore no-explicit-any return this as Router<any, any>; }
/** Set the router prefix for this router. */ prefix(prefix: string): this { prefix = prefix.replace(/\/$/, ""); this.#opts.prefix = prefix; for (const route of this.#stack) { route.setPrefix(prefix); } return this; }
/** Register named middleware for the specified routes when the `PUT` * method is requested. */ put<P extends RouteParams = RP, S extends State = RS>( name: string, path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; /** Register middleware for the specified routes when the `PUT` * method is requested. */ put<P extends RouteParams = RP, S extends State = RS>( path: string, middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; put<P extends RouteParams = RP, S extends State = RS>( nameOrPath: string, pathOrMiddleware: string | RouterMiddleware<P, S>, ...middleware: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)> { this.#useVerb( nameOrPath, pathOrMiddleware as (string | RouterMiddleware), middleware as RouterMiddleware[], ["PUT"], ); // deno-lint-ignore no-explicit-any return this as Router<any, any>; }
/** Register a direction middleware, where when the `source` path is matched * the router will redirect the request to the `destination` path. A `status` * of `302 Found` will be set by default. * * The `source` and `destination` can be named routes. */ redirect( source: string, destination: string | URL, status: RedirectStatus = Status.Found, ): this { if (source[0] !== "/") { const s = this.url(source); if (!s) { throw new RangeError(`Could not resolve named route: "${source}"`); } source = s; } if (typeof destination === "string") { if (destination[0] !== "/") { const d = this.url(destination); if (!d) { try { const url = new URL(destination); destination = url; } catch { throw new RangeError(`Could not resolve named route: "${source}"`); } } else { destination = d; } } }
this.all(source, async (ctx, next) => { await next(); ctx.response.redirect(destination); ctx.response.status = status; }); return this; }
/** Return middleware that will do all the route processing that the router * has been configured to handle. Typical usage would be something like this: * * ```ts * import { Application, Router } from "https://deno.land/x/oak/mod.ts"; * * const app = new Application(); * const router = new Router(); * * // register routes * * app.use(router.routes()); * app.use(router.allowedMethods()); * await app.listen({ port: 80 }); * ``` */ routes(): Middleware { const dispatch = ( context: Context, next: () => Promise<unknown>, ): Promise<unknown> => { const ctx = context as RouterContext; let pathname: string; let method: HTTPMethods; try { const { url: { pathname: p }, method: m } = ctx.request; pathname = p; method = m; } catch (e) { return Promise.reject(e); } const path = this.#opts.routerPath ?? ctx.routerPath ?? decodeURIComponent(pathname); const matches = this.#match(path, method);
if (ctx.matched) { ctx.matched.push(...matches.path); } else { ctx.matched = [...matches.path]; }
// deno-lint-ignore no-explicit-any ctx.router = this as Router<any, any>;
if (!matches.route) return next();
const { pathAndMethod: matchedRoutes } = matches;
const chain = matchedRoutes.reduce( (prev, route) => [ ...prev, ( ctx: RouterContext, next: () => Promise<unknown>, ): Promise<unknown> => { ctx.captures = route.captures(path); ctx.params = route.params(ctx.captures, ctx.params); ctx.routeName = route.name; return next(); }, ...route.stack, ], [] as RouterMiddleware[], ); return compose(chain)(ctx, next); }; dispatch.router = this; return dispatch; }
/** Generate a URL pathname for a named route, interpolating the optional * params provided. Also accepts an optional set of options. */ url<P extends RouteParams = RP>( name: string, params?: P, options?: UrlOptions, ): string | undefined { const route = this.#route(name);
if (route) { return route.url(params, options); } }
/** Register middleware to be used on every matched route. */ use<P extends RouteParams = RP, S extends State = RS>( middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; /** Register middleware to be used on every route that matches the supplied * `path`. */ use<P extends RouteParams = RP, S extends State = RS>( path: string | string[], middleware: RouterMiddleware<P, S>, ...middlewares: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)>; use<P extends RouteParams = RP, S extends State = RS>( pathOrMiddleware: string | string[] | RouterMiddleware<P, S>, ...middleware: RouterMiddleware<P, S>[] ): Router<P extends RP ? P : (P & RP), S extends RS ? S : (S & RS)> { let path: string | string[] | undefined; if ( typeof pathOrMiddleware === "string" || Array.isArray(pathOrMiddleware) ) { path = pathOrMiddleware; } else { middleware.unshift(pathOrMiddleware); }
this.#register( path ?? "(.*)", middleware as RouterMiddleware[], [], { end: false, ignoreCaptures: !path, ignorePrefix: !path }, );
// deno-lint-ignore no-explicit-any return this as Router<any, any>; }
/** Iterate over the routes currently added to the router. */ *values(): IterableIterator<Route<RP, RS>> { for (const route of this.#stack) { yield route.toJSON(); } }
/** Provide an iterator interface that iterates over the routes registered * with the router. */ *[Symbol.iterator](): IterableIterator<Route<RP, RS>> { for (const route of this.#stack) { yield route.toJSON(); } }
/** Generate a URL pathname based on the provided path, interpolating the * optional params provided. Also accepts an optional set of options. */ static url( path: string, params?: RouteParams, options?: UrlOptions, ): string { return toUrl(path, params, options); }
[Symbol.for("Deno.customInspect")](inspect: (value: unknown) => string) { return `${this.constructor.name} ${ inspect({ "#params": this.#params, "#stack": this.#stack }) }`; }}