@liveblocks/zenrouter 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,397 @@
+import { JSONObject, JSONValue, Decoder } from 'decoders';
+import { Resolve, JsonObject } from '@liveblocks/core';
+import { Pipe, Strings, Tuples, ComposeLeft, Unions, Objects } from 'hotscript';
+
+type HeadersInit = Record<string, string> | Headers;
+
+declare class HttpError extends Error {
+    static readonly codes: {
+        [code: number]: string | undefined;
+    };
+    readonly status: number;
+    readonly headers?: HeadersInit;
+    constructor(status: number, message?: string, headers?: HeadersInit);
+}
+declare class ValidationError extends HttpError {
+    readonly status = 422;
+    readonly reason: string;
+    constructor(reason: string);
+}
+
+/**
+ * Checks if a Response is a generic abort response (created by abort()).
+ */
+declare function isGenericAbort(resp: Response): boolean;
+/**
+ * Returns an empty HTTP 204 response.
+ */
+declare function empty(): Response;
+/**
+ * Return a JSON response.
+ */
+declare function json(value: JSONObject, status?: number, headers?: HeadersInit): Response;
+/**
+ * Return an HTML response.
+ */
+declare function html(content: string, status?: number, headers?: HeadersInit): Response;
+/**
+ * Throws a generic abort Response for the given status code. Use this to
+ * terminate the handling of a route and return an HTTP error to the user.
+ *
+ * The response body will be determined by the configured error handler.
+ * To return a custom error body that won't be replaced, throw a json() response instead.
+ */
+declare function abort(status: number, headers?: HeadersInit): never;
+/**
+ * Return a streaming text response from a generator that yields strings. The
+ * stream will be encoded as UTF-8.
+ *
+ * Small string chunks will get buffered into emitted chunks of `bufSize` bytes (defaults to 64 kB)
+ * at least 64kB that many characters before being encoded and enqueued,
+ * reducing per-chunk transfer overhead. (By default buffers chunks of at least
+ * 64kB size.)
+ */
+declare function textStream(iterable: Iterable<string>, headers?: HeadersInit, options?: {
+    bufSize: number;
+}): Response;
+/**
+ * Return a streaming NDJSON (Newline Delimited JSON) response from a generator
+ * that yields JSON values. Each value will be serialized as a single line.
+ */
+declare function ndjsonStream(iterable: Iterable<JSONValue>, headers?: HeadersInit): Response;
+/**
+ * Return a streaming JSON array response from a generator that yields JSON
+ * values. The output will be a valid JSON array: [value1,value2,...]\n
+ */
+declare function jsonArrayStream(iterable: Iterable<JSONValue>, headers?: HeadersInit): Response;
+
+type ErrorContext<RC> = {
+    req: Request;
+    ctx?: RC;
+};
+type ErrorHandlerFn<E, RC = unknown> = (error: E, extra: ErrorContext<RC>) => Response | Promise<Response>;
+/**
+ * Central registry instance for handling HTTP errors. Has configured defaults
+ * for every known HTTP error code. Allows you to override those defaults and
+ * provide your own error handling preferences.
+ */
+declare class ErrorHandler {
+    #private;
+    /**
+     * Registers a custom HTTP error handler.
+     *
+     * This will get called whenever an `HttpError` is thrown (which also happens
+     * with `abort()`) from a route handler.
+     *
+     * It will *NOT* get called if a `Response` instance is thrown (or returned)
+     * from a handler directly!
+     */
+    onError(handler: ErrorHandlerFn<HttpError>): void;
+    /**
+     * Registers a custom uncaught error handler.
+     *
+     * This will only get called if there is an unexpected error thrown from
+     * a route handler, i.e. something that isn't a `Response` instance, or an
+     * `HttpError`.
+     */
+    onUncaughtError(handler: ErrorHandlerFn<unknown>): void;
+    /**
+     * Given an error, will find the best (most-specific) error handler for it,
+     * and return its response.
+     */
+    handle(err: unknown, extra: ErrorContext<unknown>): Promise<Response>;
+}
+
+type Method = (typeof ALL_METHODS)[number];
+declare const ALL_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
+type PathPattern = `/${string}`;
+type Pattern = `${Method} ${PathPattern}`;
+type PathPrefix = `/${string}/*` | "/*";
+/**
+ * From a pattern like:
+ *
+ *   'GET /foo/<bar>/<qux>/baz'
+ *
+ * Extracts:
+ *
+ *   { foo: string, bar: string }
+ */
+type ExtractParamsBasic<P extends Pattern> = Pipe<P, // ....................................... 'GET /foo/<bar>/<qux>/baz'
+[
+    Strings.TrimLeft<`${Method} `>,
+    Strings.Split<"/">,
+    Tuples.Filter<Strings.StartsWith<"<">>,
+    Tuples.Map<ComposeLeft<[
+        Strings.Trim<"<" | ">">,
+        Unions.ToTuple,
+        Tuples.Append<string>
+    ]>>,
+    Tuples.ToUnion,
+    Objects.FromEntries
+]>;
+/**
+ * For:
+ *
+ *   {
+ *     a: Decoder<number>,
+ *     b: Decoder<'hi'>,
+ *     c: Decoder<boolean>,
+ *   }
+ *
+ * Will return:
+ *
+ *   {
+ *     a: number,
+ *     b: 'hi',
+ *     c: boolean,
+ *   }
+ *
+ */
+type MapDecoderTypes<T> = {
+    [K in keyof T]: T[K] extends Decoder<infer V> ? V : never;
+};
+/**
+ * From a pattern like:
+ *
+ *   'GET /foo/<bar>/<n>/baz'
+ *
+ * Extracts:
+ *
+ *   { foo: string, n: number }
+ */
+type ExtractParams<P extends Pattern, TParamTypes extends Record<string, unknown>, E = ExtractParamsBasic<P>> = Resolve<Pick<Omit<E, keyof TParamTypes> & TParamTypes, Extract<keyof E, string>>>;
+
+type CorsOptions = {
+    /**
+     * Send CORS headers only if the requested Origin is in this hardcoded list
+     * of origins. Note that the default is '*', but this still required all
+     * incoming requests to have an Origin header set.
+     *
+     * @default '*' (allow any Origin)
+     */
+    allowedOrigins: "*" | string[];
+    /**
+     * When sending back CORS headers, tell the browser which methods are
+     * allowed.
+     *
+     * @default All methods (you should likely not have to change this)
+     */
+    allowedMethods: string[];
+    /**
+     * Specify what headers are safe to allow on _incoming_ CORS requests.
+     *
+     * By default, all headers requested by the browser client will be allowed
+     * (as most headers will typically be ignored by the endpoint handlers), but
+     * you can specify a specific whitelist of allowed headers if you need to.
+     *
+     * Browsers will only ask for non-standard headers if those should be
+     * allowed, i.e. a browser can ask in a preflight (OPTIONS) request, if it's
+     * okay to send "X-Test", but won't ask if it's okay to send, say,
+     * "User-Agent".
+     *
+     * Note that this is different from the `exposeHeaders` config:
+     * - Allowed Headers: which headers a browser may include when
+     *                    _making_ the CORS request
+     * - Exposed Headers: which headers _returned_ in the CORS response the
+     *                    browser is allowed to safely expose to scripts
+     *
+     * @default '*'
+     */
+    allowedHeaders: "*" | string[];
+    /**
+     * The Access-Control-Allow-Credentials response header allows browsers
+     * to include include credentials in the next CORS request.
+     *
+     * Credentials are cookies, TLS client certificates, or WWW-Authentication
+     * headers containing a username and password.
+     *
+     * NOTE: The `Authorization` header is *NOT* considered a credential and as
+     * such you don’t need to enable this setting for sending such headers.
+     *
+     * NOTE: Allowing credentials alone doesn’t cause the browser to send those
+     * credentials automatically. For to to happen, make sure to also add `{
+     * credentials: "include" }` on the fetch request.
+     *
+     * WARNING: By default, these credentials are not sent in cross-origin
+     * requests, and doing so can make a site vulnerable to CSRF attacks.
+     *
+     * @default false
+     */
+    allowCredentials: boolean;
+    /**
+     * Specify what headers browsers *scripts* can access from the CORS response.
+     * This means when a client tries to programmatically read
+     * `resp.headers.get('...')`, this header determines which headers will be
+     * exposed to that client.
+     *
+     * Note that this is different from the `allowedHeaders` config:
+     * - Allowed Headers: which headers a browser may include when
+     *                    _making_ the CORS request
+     * - Exposed Headers: which headers _returned_ in the CORS response the
+     *                    browser is allowed to safely expose to scripts
+     *
+     * By default, browser scripts can only read the following headers from such
+     * responses:
+     * - Cache-Control
+     * - Content-Language
+     * - Content-Type
+     * - Expires
+     * - Last-Modified
+     * - Pragma
+     */
+    exposeHeaders: string[];
+    maxAge?: number;
+    /**
+     * When `allowedOrigins` isn't an explicit list of origins but '*' (= the
+     * default), normally the Origin will get allowed by echoing the Origin value
+     * back. When this option is set, it will instead allow '*'.
+     *
+     * Do not use this in combination with `allowCredentials` as this is not
+     * allowed by the spec.
+     *
+     * @default false
+     *
+     */
+    sendWildcard: boolean;
+    /**
+     * Always send CORS headers on all responses, even if the request didn't
+     * contain an Origin header and thus isn't interested in CORS.
+     *
+     * @default true
+     */
+    alwaysSend: boolean;
+    /**
+     * Normally, when returning a CORS response, it's a good idea to set the
+     * Vary header to include 'Origin', to behave better with caching. By default
+     * this will be done. If you don't want to auto-add the Vary header, set this
+     * to false.
+     *
+     * @default true
+     */
+    varyHeader: boolean;
+};
+
+/**
+ * An Incoming Request is what gets passed to every route handler. It includes
+ * the raw (unmodified) request, the derived context (user-defined), the parsed
+ * URL, the type-safe params `p`, the parsed query string `q`, and a verified
+ * JSON body (if a decoder is provided).
+ */
+type IncomingReq<RC, AC, TParams, TBody> = {
+    /**
+     * The incoming request.
+     */
+    readonly req: Request;
+    /**
+     * The incoming request parsed URL.
+     * This is equivalent to the result of `new URL(req.url)`.
+     */
+    readonly url: URL;
+    /**
+     * The user-defined static context associated with this request. This is the
+     * best place to attach metadata you want to carry around along with the
+     * request, without having to monkey-patch the request instance.
+     *
+     * Use this context for static metadata. Do not use it for auth.
+     *
+     * Basically the result of calling the configured `getContext()` function on
+     * the request.
+     */
+    readonly ctx: Readonly<RC>;
+    /**
+     * The result of the authorization check for this request. Basically the
+     * result of calling the configured `authorize()` function on the request.
+     */
+    readonly auth: Readonly<AC>;
+    /**
+     * The type-safe params available for this request. Automatically derived
+     * from dynamic placeholders in the pattern.
+     */
+    readonly p: TParams;
+    /**
+     * Convenience accessor for the parsed query string.
+     * Equivalent to `Object.entries(url.searchParams)`.
+     *
+     * Will only contain single strings, even if a query param occurs multiple
+     * times. If you need to read all of them, use the `url.searchParams` API
+     * instead.
+     */
+    readonly q: Record<string, string | undefined>;
+    /**
+     * Verified JSON body for this request, if a decoder instance was provided.
+     */
+    readonly body: TBody;
+};
+/**
+ * Limited version of an Incoming Request. This incoming request data is
+ * deliberately limited until after a successful auth check. Only once the
+ * request has been authorized, further parsing will happen.
+ */
+type PreAuthIncomingReq<RC> = Omit<IncomingReq<Readonly<RC>, never, never, never>, "auth" | "p" | "q" | "body">;
+/**
+ * Anything that can be returned from an endpoint implementation that would be
+ * considered a valid response.
+ */
+type ResponseLike = Promise<Response | JsonObject> | Response | JsonObject;
+type RouteHandler<RC, AC, TParams, TBody> = (input: IncomingReq<RC, AC, TParams, TBody>) => ResponseLike;
+type RouterOptions<RC, AC, TParams extends Record<string, Decoder<unknown>>> = {
+    errorHandler?: ErrorHandler;
+    /**
+     * Automatically handle CORS requests. Either set to `true` (to use all the
+     * default CORS options), or specify a CorsOptions object.
+     *
+     * When enabled, this will do two things:
+     * 1. It will respond to pre-flight requests (OPTIONS) automatically.
+     * 2. It will add the correct CORS headers to all returned responses.
+     *
+     * @default false
+     */
+    cors?: Partial<CorsOptions> | boolean;
+    getContext?: (req: Request, ...args: readonly any[]) => RC;
+    authorize?: AuthFn<RC, AC>;
+    params?: TParams;
+    debug?: boolean;
+};
+type AuthFn<RC, AC> = (input: PreAuthIncomingReq<RC>) => AC | Promise<AC>;
+declare class ZenRouter<RC, AC, TParams extends Record<string, Decoder<unknown>> = {}> {
+    #private;
+    constructor(options?: RouterOptions<RC, AC, TParams>);
+    get fetch(): (req: Request, ...rest: readonly any[]) => Promise<Response>;
+    route<P extends Pattern>(pattern: P, handler: RouteHandler<RC, AC, ExtractParams<P, MapDecoderTypes<TParams>>, never>): void;
+    route<P extends Pattern, TBody>(pattern: P, bodyDecoder: Decoder<TBody>, handler: RouteHandler<RC, AC, ExtractParams<P, MapDecoderTypes<TParams>>, TBody>): void;
+    onUncaughtError(handler: ErrorHandlerFn<unknown, RC>): this;
+    onError(handler: ErrorHandlerFn<HttpError | ValidationError, RC>): this;
+}
+
+type RequestHandler = (req: Request, ...args: readonly any[]) => Promise<Response>;
+type RelayOptions = {
+    errorHandler?: ErrorHandler;
+};
+/**
+ * Relay won't do any route handling itself. It will only hand-off any incoming
+ * request to one of the configured routers, based on the incoming request path
+ * (first matching prefix path wins).
+ *
+ * It does NOT check the HTTP verb (GET, POST, etc).
+ * It does NOT do any authentication.
+ * It does NOT look at any headers.
+ *
+ * Subrouters (typically Router instances) are responsible for all that
+ * themselves.
+ *
+ * If no matching route is found, it will return a generic 404 error response.
+ */
+declare class ZenRelay {
+    #private;
+    constructor(options?: RelayOptions);
+    get fetch(): (req: Request, ...rest: readonly any[]) => Promise<Response>;
+    /**
+     * If an incoming request matches the given prefix, forward the request as-is
+     * to the child router. Relaying happens strictly based on the request URL.
+     * It does not look at headers, or the HTTP method, or anything else to
+     * decide if it's a match.
+     */
+    relay(prefix: PathPrefix, router: ZenRouter<any, any, any> | RequestHandler): this;
+}
+
+export { type AuthFn, type ErrorContext, ErrorHandler, type ErrorHandlerFn, HttpError, ValidationError, ZenRelay, ZenRouter, abort, empty, html, isGenericAbort, json, jsonArrayStream, ndjsonStream, textStream };