Skip to main content
Deno 2 is finally here 🎉️
Learn more
Module

x/oak/router.ts>Router

A middleware framework for handling HTTP with Deno, Node, Bun and Cloudflare Workers 🐿️ 🦕
oakserver/oak
Very Popular
Latest
class Router
import { Router } from "https://deno.land/x/oak@v17.1.2/router.ts";

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.

Basic example

import { Application, Router } from "jsr:@oak/oak/";

const router = new Router();
router.get("/", (ctx, next) => {
  // handle the GET endpoint here
});
router.all("/item/:item", (ctx, next) => {
  // called for all HTTP verbs/requests
  ctx.params.item; // contains the value of `:item` from the parsed URL
});

const app = new Application();
app.use(router.routes());
app.use(router.allowedMethods());

app.listen({ port: 8080 });

Constructors

new
Router(opts?: RouterOptions)

Type Parameters

optional
RS extends State = Record<string, any>

Methods

add<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
methods: HTTPMethods[] | HTTPMethods,
name: string,
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register named middleware for the specified routes when specified methods are requested.

add<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
methods: HTTPMethods[] | HTTPMethods,
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the specified methods is requested.

add<P extends RouteParams<string>, S extends State = RS>(
methods: HTTPMethods[] | HTTPMethods,
nameOrPath: string,
pathOrMiddleware: string | RouterMiddleware<string, P, S>,
...middleware: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the specified methods are requested with explicit path parameters.

all<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
name: string,
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register named middleware for the specified routes when the DELETE, GET, POST, or PUT method is requested.

all<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<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<string>, S extends State = RS>(
nameOrPath: string,
pathOrMiddleware: string | RouterMiddleware<string, P, S>,
...middleware: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the DELETE, GET, POST, or PUT method is requested with explicit path parameters.

allowedMethods(options?: RouterAllowedMethodsOptions): Middleware

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.

delete<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
name: string,
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register named middleware for the specified routes when the DELETE, method is requested.

delete<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the DELETE, method is requested.

delete<P extends RouteParams<string>, S extends State = RS>(
nameOrPath: string,
pathOrMiddleware: string | RouterMiddleware<string, P, S>,
...middleware: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the DELETE, method is requested with explicit path parameters.

entries(): IterableIterator<[Route<string>, Route<string>]>

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.

forEach(callback: (
value1: Route<string>,
value2: Route<string>,
router: this,
) => void, thisArg?: any): void

Iterate over the routes currently added to the router, calling the callback function for each value.

get<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
name: string,
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register named middleware for the specified routes when the GET, method is requested.

get<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the GET, method is requested.

get<P extends RouteParams<string>, S extends State = RS>(
nameOrPath: string,
pathOrMiddleware: string | RouterMiddleware<string, P, S>,
...middleware: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the GET, method is requested with explicit path parameters.

head<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
name: string,
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register named middleware for the specified routes when the HEAD, method is requested.

head<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the HEAD, method is requested.

head<P extends RouteParams<string>, S extends State = RS>(
nameOrPath: string,
pathOrMiddleware: string | RouterMiddleware<string, P, S>,
...middleware: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the HEAD, method is requested with explicit path parameters.

keys(): IterableIterator<Route<string>>

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.

options<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
name: string,
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register named middleware for the specified routes when the OPTIONS, method is requested.

options<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the OPTIONS, method is requested.

options<P extends RouteParams<string>, S extends State = RS>(
nameOrPath: string,
pathOrMiddleware: string | RouterMiddleware<string, P, S>,
...middleware: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the OPTIONS, method is requested with explicit path parameters.

param<R extends string, S extends State = RS>(param: keyof RouteParams<R>, middleware: RouterParamMiddleware<R, RouteParams<R>, S>): Router<S>

Register param middleware, which will be called when the particular param is parsed from the route.

patch<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
name: string,
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register named middleware for the specified routes when the PATCH, method is requested.

patch<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the PATCH, method is requested.

patch<P extends RouteParams<string>, S extends State = RS>(
nameOrPath: string,
pathOrMiddleware: string | RouterMiddleware<string, P, S>,
...middleware: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the PATCH, method is requested with explicit path parameters.

post<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
name: string,
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register named middleware for the specified routes when the POST, method is requested.

post<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the POST, method is requested.

post<P extends RouteParams<string>, S extends State = RS>(
nameOrPath: string,
pathOrMiddleware: string | RouterMiddleware<string, P, S>,
...middleware: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the POST, method is requested with explicit path parameters.

prefix(prefix: string): this

Set the router prefix for this router.

put<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
name: string,
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register named middleware for the specified routes when the PUT method is requested.

put<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the PUT method is requested.

put<P extends RouteParams<string>, S extends State = RS>(
nameOrPath: string,
pathOrMiddleware: string | RouterMiddleware<string, P, S>,
...middleware: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware for the specified routes when the PUT method is requested with explicit path parameters.

redirect(
source: string,
destination: string | URL,
status?: RedirectStatus,
): this

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.

routes(): Middleware

Return middleware that will do all the route processing that the router has been configured to handle. Typical usage would be something like this:

import { Application, Router } from "jsr:@oak/oak/";

const app = new Application();
const router = new Router();

// register routes

app.use(router.routes());
app.use(router.allowedMethods());
await app.listen({ port: 80 });
url<P extends RouteParams<string> = RouteParams<string>>(
name: string,
params?: P,
options?: UrlOptions,
): string | undefined

Generate a URL pathname for a named route, interpolating the optional params provided. Also accepts an optional set of options.

use<P extends RouteParams<string> = RouteParams<string>, S extends State = RS>(middleware: RouterMiddleware<string, P, S>, ...middlewares: RouterMiddleware<string, P, S>[]): Router<S extends RS ? S : (S & RS)>

Register middleware to be used on every matched route.

use<R extends string, P extends RouteParams<R> = RouteParams<R>, S extends State = RS>(
path: R,
middleware: RouterMiddleware<R, P, S>,
...middlewares: RouterMiddleware<R, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware to be used on every route that matches the supplied path.

use<P extends RouteParams<string>, S extends State = RS>(
path: string,
middleware: RouterMiddleware<string, P, S>,
...middlewares: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>

Register middleware to be used on every route that matches the supplied path with explicit path parameters.

use<P extends RouteParams<string> = RouteParams<string>, S extends State = RS>(
path: string[],
middleware: RouterMiddleware<string, P, S>,
...middlewares: RouterMiddleware<string, P, S>[],
): Router<S extends RS ? S : (S & RS)>
values(): IterableIterator<Route<string, RouteParams<string>, RS>>

Iterate over the routes currently added to the router.

[Symbol.for("Deno.customInspect")](inspect: (value: unknown) => string): string
[Symbol.for("nodejs.util.inspect.custom")](
depth: number,
options: any,
inspect: (value: unknown, options?: unknown) => string,
): any
[Symbol.iterator](): IterableIterator<Route<string, RouteParams<string>, RS>>

Provide an iterator interface that iterates over the routes registered with the router.

Static Methods

url<R extends string>(
path: R,
params?: RouteParams<R>,
options?: UrlOptions,
): string

Generate a URL pathname based on the provided path, interpolating the optional params provided. Also accepts an optional set of options.