1 | import { Context } from '@worker-tools/middleware';
|
2 | import type { URLPatternInit, URLPatternComponentResult, URLPatternInput, URLPatternResult } from '@worker-tools/middleware';
|
3 | export type { URLPatternInit, URLPatternComponentResult, URLPatternInput, URLPatternResult };
|
4 | export declare type Awaitable<T> = T | PromiseLike<T>;
|
5 | export interface RouteContext extends Context {
|
6 | |
7 |
|
8 |
|
9 |
|
10 |
|
11 | match: URLPatternResult;
|
12 | }
|
13 | export interface ErrorContext extends RouteContext {
|
14 | |
15 |
|
16 |
|
17 |
|
18 |
|
19 |
|
20 | response: Response;
|
21 | |
22 |
|
23 |
|
24 |
|
25 | error?: unknown;
|
26 | }
|
27 | export declare type Middleware<RX extends RouteContext, X extends RouteContext> = (x: Awaitable<RX>) => Awaitable<X>;
|
28 | export declare type Handler<X extends RouteContext> = (request: Request, ctx: X) => Awaitable<Response>;
|
29 | export declare type ErrorHandler<X extends ErrorContext> = (request: Request, ctx: X) => Awaitable<Response>;
|
30 | export declare type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
|
31 | export interface WorkerRouterOptions {
|
32 | fatal?: boolean;
|
33 | }
|
34 | export declare class WorkerRouter<RX extends RouteContext = RouteContext> extends EventTarget implements EventListenerObject {
|
35 | #private;
|
36 | constructor(middleware?: Middleware<RouteContext, RX> | null, opts?: WorkerRouterOptions);
|
37 | get fatal(): boolean;
|
38 | /** Add a route that matches *any* HTTP method. */
|
39 | any<X extends RX>(path: string, handler: Handler<X>): this;
|
40 | any<X extends RX>(path: string, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
41 | /** Alias for for the more appropriately named `any` method */
|
42 | all<X extends RX>(path: string, handler: Handler<X>): this;
|
43 | all<X extends RX>(path: string, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
44 | /** Add a route that matches the `GET` method. */
|
45 | get<X extends RX>(path: string, handler: Handler<X>): this;
|
46 | get<X extends RX>(path: string, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
47 | /** Add a route that matches the `POST` method. */
|
48 | post<X extends RX>(path: string, handler: Handler<X>): this;
|
49 | post<X extends RX>(path: string, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
50 | /** Add a route that matches the `PUT` method. */
|
51 | put<X extends RX>(path: string, handler: Handler<X>): this;
|
52 | put<X extends RX>(path: string, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
53 | /** Add a route that matches the `PATCH` method. */
|
54 | patch<X extends RX>(path: string, handler: Handler<X>): this;
|
55 | patch<X extends RX>(path: string, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
56 | /** Add a route that matches the `DELETE` method. */
|
57 | delete<X extends RX>(path: string, handler: Handler<X>): this;
|
58 | delete<X extends RX>(path: string, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
59 | /** Add a route that matches the `HEAD` method. */
|
60 | head<X extends RX>(path: string, handler: Handler<X>): this;
|
61 | head<X extends RX>(path: string, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
62 | /** Add a route that matches the `OPTIONS` method. */
|
63 | options<X extends RX>(path: string, handler: Handler<X>): this;
|
64 | options<X extends RX>(path: string, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
65 | /**
|
66 | * Add a route that matches *any* method with the provided pattern.
|
67 | * Note that the pattern here is interpreted as a `URLPatternInit` which has important implication for matching.
|
68 | * Mostly, this is for use in Service Workers to intercept requests to external resources.
|
69 | *
|
70 | * The name `external` is a bit of a misnomer. It simply forwards `init` to the `URLPattern` constructor,
|
71 | * instead of being limited to the `pathname` property in the general case.
|
72 | * @deprecated Might change name/API
|
73 | */
|
74 | external<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this;
|
75 | external<X extends RX>(init: string | URLPatternInit, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
76 | /** Like `.external`, but only matches `GET`
|
77 | * @deprecated Might change name/API */
|
78 | externalGET<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this;
|
79 | externalGET<X extends RX>(init: string | URLPatternInit, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
80 | /** Like `.external`, but only matches `POST`
|
81 | * @deprecated Might change name/API */
|
82 | externalPOST<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this;
|
83 | externalPOST<X extends RX>(init: string | URLPatternInit, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
84 | /** Like `.external`, but only matches `PUT`
|
85 | * @deprecated Might change name/API */
|
86 | externalPUT<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this;
|
87 | externalPUT<X extends RX>(init: string | URLPatternInit, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
88 | /** Like `.external`, but only matches `PATCH`
|
89 | * @deprecated Might change name/API */
|
90 | externalPATCH<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this;
|
91 | externalPATCH<X extends RX>(init: string | URLPatternInit, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
92 | /** Like `.external`, but only matches `DELETE`
|
93 | * @deprecated Might change name/API */
|
94 | externalDELETE<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this;
|
95 | externalDELETE<X extends RX>(init: string | URLPatternInit, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
96 | /** Like `.external`, but only matches `OPTIONS`
|
97 | * @deprecated Might change name/API */
|
98 | externalOPTIONS<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this;
|
99 | externalOPTIONS<X extends RX>(init: string | URLPatternInit, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
100 | /** Like `.external`, but only matches `HEAD`
|
101 | * @deprecated Might change name/API */
|
102 | externalHEAD<X extends RX>(init: string | URLPatternInit, handler: Handler<X>): this;
|
103 | externalHEAD<X extends RX>(init: string | URLPatternInit, middleware: Middleware<RX, X>, handler: Handler<X>): this;
|
104 | /**
|
105 | * Use a different `WorkerRouter` for the provided pattern. Keep in mind that:
|
106 | *
|
107 | * - The pattern must end in a wildcard `*`
|
108 | * - The corresponding match is the only part used for matching in the `subRouter`
|
109 | * - Forwards all HTTP methods
|
110 | * - Does not apply any middleware
|
111 | *
|
112 | * #### Why does it not apply middleware?
|
113 | *
|
114 | * There are 2 reasons: First, it interferes with type inference of middleware.
|
115 | * As a developer you'd have to provide the correct types at the point of defining the sub router,
|
116 | * which is at least as cumbersome as providing the middleware itself.
|
117 | *
|
118 | * Second, without this there would be no way to opt a route out of the router-level middleware.
|
119 | * For example you might want to opt out all `/public*` urls from cookie parsing, authentication, etc.
|
120 | * but add a different caching policy instead.
|
121 | *
|
122 | * @param path A pattern ending in a wildcard, e.g. `/items*`
|
123 | * @param subRouter A `WorkerRouter` that handles the remaining part of the URL, e.g. `/:category/:id`
|
124 | * @deprecated The name of this method might change to avoid confusion with `use` method known from other routers.
|
125 | */
|
126 | use<Y extends RouteContext>(path: string, subRouter: WorkerRouter<Y>): this;
|
127 | /**
|
128 | * See `.external` and `.use`.
|
129 | * @deprecated Might change name/API
|
130 | */
|
131 | useExternal<Y extends RouteContext>(init: string | URLPatternInit, subRouter: WorkerRouter<Y>): this;
|
132 | /**
|
133 | * Register a special route to recover from an error during execution of a regular route.
|
134 | *
|
135 | * In addition to the usual context properties, the provided handler receives a `response` and `error` property.
|
136 | * In case of a well-known error (typically caused by middleware),
|
137 | * the `response` contains a Fetch API `Response` object with matching status and status text set.
|
138 | * In case of an unknown error, the `response` is a generic "internal server error" and the `error` property
|
139 | * contains the value caught by the catch block.
|
140 | *
|
141 | * Recover routes don't execute the router-level middleware (which might have caused the error), but
|
142 | * can have middleware specifically for this route. Note that if another error occurs during the execution of
|
143 | * this middleware, there are no more safety nets and an internal server error response is returned.
|
144 | *
|
145 | * If a global `DEBUG` variable is set (or `process.env.NODE_ENV` is set to `development` in case of webpack)
|
146 | * the router will throw on an unhandled error. This is to make it easier to spot problems during development.
|
147 | * Otherwise, the router will not throw but instead dispatch a `error` event on itself before returning an empty
|
148 | * internal server error response.
|
149 | */
|
150 | recover(path: string, handler: Handler<ErrorContext>): this;
|
151 | recover<X extends ErrorContext>(path: string, middleware: Middleware<ErrorContext, X>, handler: Handler<X>): this;
|
152 | recoverExternal(init: string | URLPatternInit, handler: Handler<ErrorContext>): this;
|
153 | recoverExternal<X extends ErrorContext>(init: string | URLPatternInit, middleware: Middleware<ErrorContext, X>, handler: Handler<X>): this;
|
154 | /** @deprecated Name/API might change */
|
155 | handle: (request: Request, ctx?: Omit<Context, 'effects'>) => Promise<Response>;
|
156 | /**
|
157 | * Implements the (ancient) event listener object interface to allow passing to fetch event directly,
|
158 | * e.g. `self.addEventListener('fetch', router)`.
|
159 | */
|
160 | handleEvent: (object: Event) => void;
|
161 | /**
|
162 | * Callback compatible with Cloudflare Worker's `fetch` module export.
|
163 | * E.g. `export default router`.
|
164 | */
|
165 | fetch: (request: Request, env?: any, ctx?: any) => Promise<Response>;
|
166 | /**
|
167 | * Callback that is compatible with Deno's `serve` function.
|
168 | * E.g. `serve(router.serveCallback)`.
|
169 | */
|
170 | serveCallback: (request: Request, connInfo: any) => Promise<Response>;
|
171 | addEventListener(type: 'error', listener: TypedEventListenerOrEventListenerObject<ErrorEvent> | null, options?: boolean | AddEventListenerOptions): void;
|
172 | removeEventListener(type: 'error', listener: TypedEventListenerOrEventListenerObject<ErrorEvent> | null, options?: EventListenerOptions | boolean): void;
|
173 | }
|
174 | declare type TypedEventListener<E extends Event> = (evt: E) => void | Promise<void>;
|
175 | declare type TypedEventListenerObject<E extends Event> = {
|
176 | handleEvent(evt: E): void | Promise<void>;
|
177 | };
|
178 | declare type TypedEventListenerOrEventListenerObject<E extends Event> = TypedEventListener<E> | TypedEventListenerObject<E>;
|