Skip to main content
Module

x/workers_router/index.ts>WorkerRouter

A router for Worker Runtimes such and Cloudflare Workers or Service Workers.
worker-tools/router
Latest
class WorkerRouter
extends EventTarget
import { WorkerRouter } from "https://deno.land/x/workers_router@v0.3.0-pre.6/index.ts";

Constructors

new
WorkerRouter(middleware?: Middleware<RouteContext, RX> | null, opts?: WorkerRouterOptions)

Properties

readonly
fatal
fetch: (
request: Request,
env?: any,
ctx?: any,
) => Promise<Response>

Callback compatible with Cloudflare Worker's fetch module export. E.g. export default router.

deprecated
handle: (request: Request, ctx?: Omit<Context, "effects">) => unknown
handleEvent: (object: Event) => unknown

Implements the (ancient) event listener object interface to allow passing to fetch event directly, e.g. self.addEventListener('fetch', router).

serveCallback: (request: Request, connInfo: any) => Promise<Response>

Callback that is compatible with Deno's serve function. E.g. serve(router.serveCallback).

Methods

addEventListener(
type: "error",
listener: TypedEventListenerOrEventListenerObject<ErrorEvent> | null,
options?: boolean | AddEventListenerOptions,
): void
all<X extends RX>(path: string, handler: Handler<X>): this

Alias for for the more appropriately named any method

all<X extends RX>(
path: string,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
any<X extends RX>(path: string, handler: Handler<X>): this

Add a route that matches any HTTP method.

any<X extends RX>(
path: string,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
delete<X extends RX>(path: string, handler: Handler<X>): this

Add a route that matches the DELETE method.

delete<X extends RX>(
path: string,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
deprecated
external<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this

Add a route that matches any method with the provided pattern. Note that the pattern here is interpreted as a URLPatternInit which has important implication for matching. Mostly, this is for use in Service Workers to intercept requests to external resources.

The name external is a bit of a misnomer. It simply forwards init to the URLPattern constructor, instead of being limited to the pathname property in the general case.

external<X extends RX>(
init: string | URLPatternInit,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
deprecated
externalDELETE<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this

Like .external, but only matches DELETE

externalDELETE<X extends RX>(
init: string | URLPatternInit,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
deprecated
externalGET<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this

Like .external, but only matches GET

externalGET<X extends RX>(
init: string | URLPatternInit,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
deprecated
externalHEAD<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this

Like .external, but only matches HEAD

externalHEAD<X extends RX>(
init: string | URLPatternInit,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
deprecated
externalOPTIONS<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this

Like .external, but only matches OPTIONS

externalOPTIONS<X extends RX>(
init: string | URLPatternInit,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
deprecated
externalPATCH<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this

Like .external, but only matches PATCH

externalPATCH<X extends RX>(
init: string | URLPatternInit,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
deprecated
externalPOST<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this

Like .external, but only matches POST

externalPOST<X extends RX>(
init: string | URLPatternInit,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
deprecated
externalPUT<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this

Like .external, but only matches PUT

externalPUT<X extends RX>(
init: string | URLPatternInit,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
get<X extends RX>(path: string, handler: Handler<X>): this

Add a route that matches the GET method.

get<X extends RX>(
path: string,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
head<X extends RX>(path: string, handler: Handler<X>): this

Add a route that matches the HEAD method.

head<X extends RX>(
path: string,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
options<X extends RX>(path: string, handler: Handler<X>): this

Add a route that matches the OPTIONS method.

options<X extends RX>(
path: string,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
patch<X extends RX>(path: string, handler: Handler<X>): this

Add a route that matches the PATCH method.

patch<X extends RX>(
path: string,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
post<X extends RX>(path: string, handler: Handler<X>): this

Add a route that matches the POST method.

post<X extends RX>(
path: string,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
put<X extends RX>(path: string, handler: Handler<X>): this

Add a route that matches the PUT method.

put<X extends RX>(
path: string,
middleware: Middleware<RX, X>,
handler: Handler<X>,
): this
recover(path: string, handler: Handler<ErrorContext>): this

Register a special route to recover from an error during execution of a regular route.

In addition to the usual context properties, the provided handler receives a response and error property. In case of a well-known error (typically caused by middleware), the response contains a Fetch API Response object with matching status and status text set. In case of an unknown error, the response is a generic "internal server error" and the error property contains the value caught by the catch block.

Recover routes don't execute the router-level middleware (which might have caused the error), but can have middleware specifically for this route. Note that if another error occurs during the execution of this middleware, there are no more safety nets and an internal server error response is returned.

If a global DEBUG variable is set (or process.env.NODE_ENV is set to development in case of webpack) the router will throw on an unhandled error. This is to make it easier to spot problems during development. Otherwise, the router will not throw but instead dispatch a error event on itself before returning an empty internal server error response.

recover<X extends ErrorContext>(
path: string,
middleware: Middleware<ErrorContext, X>,
handler: Handler<X>,
): this
recoverExternal(init: string | URLPatternInit, handler: Handler<ErrorContext>): this
recoverExternal<X extends ErrorContext>(
init: string | URLPatternInit,
middleware: Middleware<ErrorContext, X>,
handler: Handler<X>,
): this
removeEventListener(
type: "error",
listener: TypedEventListenerOrEventListenerObject<ErrorEvent> | null,
options?: EventListenerOptions | boolean,
): void
deprecated
use<Y extends RouteContext>(path: string, subRouter: WorkerRouter<Y>): this

Use a different WorkerRouter for the provided pattern. Keep in mind that:

  • The pattern must end in a wildcard *
  • The corresponding match is the only part used for matching in the subRouter
  • Forwards all HTTP methods
  • Does not apply any middleware

Why does it not apply middleware?

There are 2 reasons: First, it interferes with type inference of middleware. As a developer you'd have to provide the correct types at the point of defining the sub router, which is at least as cumbersome as providing the middleware itself.

Second, without this there would be no way to opt a route out of the router-level middleware. For example you might want to opt out all /public* urls from cookie parsing, authentication, etc. but add a different caching policy instead.

deprecated
useExternal<Y extends RouteContext>(init: string | URLPatternInit, subRouter: WorkerRouter<Y>): this

See .external and .use.