@raiyyan/brisk 0.0.0-stage → 0.2.0

package/dist/src/http/middleware.js

@@ -0,0 +1,160 @@
+import { HandlerContext, requestMemo } from "./context.js";
+import { parseInput, Pending, settle } from "./validation.js";
+export function defineMiddleware(optionsOrFn, maybeFn) {
+    if (typeof optionsOrFn === "function")
+        return new DefinedMiddleware(optionsOrFn, {});
+    if (typeof maybeFn !== "function") {
+        throw new TypeError("defineMiddleware takes (fn) or (options, fn)");
+    }
+    return new DefinedMiddleware(maybeFn, optionsOrFn);
+}
+const EMPTY = Object.freeze({});
+/**
+ * Runs an Express middleware as a brisk middleware, in order with the others in `use`: a body parser such as
+ * multer then runs after authentication, on the one route that needs it. An error it passes to `next` goes
+ * to the app's error handler; when it answers the request itself, the route stops there.
+ *
+ * @example
+ * ```ts
+ * upload: route.post(
+ *   "/:taskId/attachments",
+ *   { use: [authenticate, fromExpress(multer({ limits: { fileSize: 5_000_000 } }).single("file"))] },
+ *   ({ req, params }) => attachments.save(params.taskId, req.file),
+ * ),
+ * ```
+ */
+export function fromExpress(handler) {
+    return new ExpressMiddleware(handler);
+}
+/**
+ * An Express middleware wrapped by {@link fromExpress}. In a route's `use` it runs in order with the others;
+ * in the app's `use` the app registers `handler` itself as a plain Express layer, at no extra cost.
+ */
+export class ExpressMiddleware {
+    handler;
+    constructor(handler) {
+        this.handler = handler;
+    }
+    run({ req, res }) {
+        return new Promise((resolve, reject) => {
+            const answered = () => resolve(EMPTY);
+            res.once("finish", answered);
+            const next = (error) => {
+                res.off("finish", answered);
+                if (error === undefined || error === "route" || error === "router")
+                    resolve(EMPTY);
+                else
+                    reject(error);
+            };
+            Promise.resolve(this.handler(req, res, next)).catch(reject);
+        });
+    }
+}
+/**
+ * A middleware made by {@link defineMiddleware}. Its result is memoized in the request's own context: a plain
+ * value when `fn` is synchronous, so sync middlewares never allocate a promise on the request path, and a
+ * promise (replaced by its value once settled) when `fn` is async.
+ */
+class DefinedMiddleware {
+    security;
+    #fn;
+    #params;
+    #query;
+    constructor(fn, options) {
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- fn's ctx type was checked by the overload that declared it
+        this.#fn = fn;
+        this.#params = options.params;
+        this.#query = options.query;
+        this.security = options.security;
+    }
+    run(ctx) {
+        try {
+            const out = this.resolve(ctx);
+            return out instanceof Promise ? out : Promise.resolve(out);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    resolve(ctx) {
+        const memo = requestMemo(ctx);
+        const cached = memo.get(this);
+        if (cached instanceof Promise)
+            return cached.then((settled) => this.#output(settled));
+        if (cached !== undefined)
+            return this.#output(cached);
+        const out = this.#call(ctx);
+        if (!(out instanceof Promise)) {
+            const value = this.#output(out);
+            memo.set(this, value);
+            return value;
+        }
+        const pending = out.then((settled) => {
+            const value = this.#output(settled);
+            memo.set(this, value);
+            return value;
+        });
+        memo.set(this, pending);
+        return pending;
+    }
+    /** Calls `fn`, first validating the input it declared onto a ctx of its own. */
+    #call(ctx) {
+        if (!this.#params && !this.#query)
+            return this.#fn(ctx);
+        const input = new HandlerContext(ctx);
+        const params = parseInput(this.#params, ctx.req.params, "params");
+        const query = parseInput(this.#query, ctx.req.query, "query");
+        if (params instanceof Pending || query instanceof Pending) {
+            return Promise.all([settle(params), settle(query)]).then(([p, q]) => {
+                input.params = p;
+                input.query = q;
+                return this.#fn(input);
+            });
+        }
+        input.params = params;
+        input.query = query;
+        return this.#fn(input);
+    }
+    /** What `fn` returned, as the output its signature declared (`{}` for a check-only middleware). */
+    #output(out) {
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- fn is typed to return Out (or nothing)
+        return (typeof out === "object" && out !== null ? out : EMPTY);
+    }
+}
+/**
+ * Runs `list` in order against the request's context and writes each output onto `target`. Stays synchronous
+ * while the middlewares are, and returns a promise only from the first async one on.
+ */
+export function applyMiddlewares(base, target, list, from = 0) {
+    for (let index = from; index < list.length; index++) {
+        const middleware = list[index];
+        if (!middleware)
+            continue;
+        const out = resolveMiddleware(middleware, base);
+        if (out instanceof Promise) {
+            return out.then((value) => {
+                Object.assign(target, value);
+                return applyMiddlewares(base, target, list, index + 1);
+            });
+        }
+        Object.assign(target, out);
+    }
+    return undefined;
+}
+/**
+ * Runs one middleware for the request, reusing its memoized result: a value when it stays synchronous, a
+ * promise otherwise.
+ */
+export function resolveMiddleware(middleware, ctx) {
+    return isDefined(middleware) ? middleware.resolve(ctx) : middleware.run(ctx);
+}
+/** The security schemes a list of middlewares enforces, merged; `undefined` when none does. */
+export function securityOf(middlewares) {
+    const entries = middlewares.flatMap((middleware) => Object.entries(middleware.security ?? {}));
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+/** `instanceof` on a generic class narrows to `any` type arguments; this keeps the output typed as `object`. */
+function isDefined(middleware) {
+    return middleware instanceof DefinedMiddleware;
+}
+//# sourceMappingURL=middleware.js.map

package/dist/src/http/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../../src/http/middleware.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAuB,MAAM,cAAc,CAAC;AAChF,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAmG9D,MAAM,UAAU,gBAAgB,CAC9B,WAA2F,EAC3F,OAAsB;IAEtB,IAAI,OAAO,WAAW,KAAK,UAAU;QAAE,OAAO,IAAI,iBAAiB,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IACrF,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,IAAI,iBAAiB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,KAAK,GAAW,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAKxC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,OAAuB;IACjD,OAAO,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IACnB,OAAO,CAAiB;IAEjC,YAAY,OAAuB;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,EAAkB;QAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,QAAQ,GAAG,GAAS,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC5C,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAC7B,MAAM,IAAI,GAAG,CAAC,KAAe,EAAQ,EAAE;gBACrC,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBAC5B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,QAAQ;oBAAE,OAAO,CAAC,KAAK,CAAC,CAAC;;oBAC9E,MAAM,CAAC,KAAK,CAAC,CAAC;YACrB,CAAC,CAAC;YACF,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC9D,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,iBAAiB;IACZ,QAAQ,CAA8B;IACtC,GAAG,CAAmC;IACtC,OAAO,CAAwB;IAC/B,MAAM,CAAwB;IAEvC,YAAY,EAAgB,EAAE,OAAwE;QACpG,6HAA6H;QAC7H,IAAI,CAAC,GAAG,GAAG,EAAsC,CAAC;QAClD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IACnC,CAAC;IAED,GAAG,CAAC,GAAmB;QACrB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC9B,OAAO,GAAG,YAAY,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAmB;QACzB,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,MAAM,YAAY,OAAO;YAAE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,OAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/F,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACtD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,CAAC,GAAG,YAAY,OAAO,CAAC,EAAE,CAAC;YAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACtB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,OAAgB,EAAE,EAAE;YAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACpC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACtB,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,GAAmB;QACvB,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAClE,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9D,IAAI,MAAM,YAAY,OAAO,IAAI,KAAK,YAAY,OAAO,EAAE,CAAC;YAC1D,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE;gBAClE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;gBACjB,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;gBAChB,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;QACtB,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,mGAAmG;IACnG,OAAO,CAAC,GAAY;QAClB,yGAAyG;QACzG,OAAO,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAQ,CAAC;IACxE,CAAC;CACF;AAWD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAoB,EACpB,MAAc,EACd,IAA2B,EAC3B,IAAI,GAAG,CAAC;IAER,KAAK,IAAI,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACpD,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,UAAU;YAAE,SAAS;QAC1B,MAAM,GAAG,GAAG,iBAAiB,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAChD,IAAI,GAAG,YAAY,OAAO,EAAE,CAAC;YAC3B,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;gBACxB,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;gBAC7B,OAAO,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YACzD,CAAC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAsB,EAAE,GAAmB;IAC3E,OAAO,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC/E,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,UAAU,CAAC,WAAkC;IAC3D,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;IAC/F,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACtE,CAAC;AAED,gHAAgH;AAChH,SAAS,SAAS,CAAC,UAAsB;IACvC,OAAO,UAAU,YAAY,iBAAiB,CAAC;AACjD,CAAC"}

package/dist/src/http/openapi.d.ts

@@ -0,0 +1,34 @@
+import type { Endpoint } from "./controller.ts";
+/**
+ * The OpenAPI document an app serves: `openapi: { title: "Shop API", version: "1.0.0" }`.
+ */
+export interface OpenApiOptions {
+    title: string;
+    version: string;
+    description?: string;
+    /** Base URLs of the API, such as `[{ url: "https://api.example.com" }]`. Default: same origin. */
+    servers?: readonly {
+        url: string;
+        description?: string;
+    }[];
+    /** Where the document is served. Default `/openapi.json`; `false` to only build it with `app.openapi()`. */
+    path?: string | false;
+}
+/** An endpoint as the document lists it: the controller's name is its tag. */
+export interface DocumentedEndpoint extends Endpoint {
+    tag: string;
+}
+type JsonObject = Record<string, unknown>;
+/**
+ * Builds an OpenAPI 3.1 document from the routes' Zod schemas. Requests are documented as clients send them
+ * (`io: "input"`) and responses as clients receive them (`io: "output"`). A named route's dotted name is its
+ * `operationId`, such as `users.get`: the same name the typed client uses.
+ */
+export declare function buildOpenApi(endpoints: readonly DocumentedEndpoint[], options: OpenApiOptions): JsonObject;
+/**
+ * Converts an Express path: `:id` and `*path` become `{id}` and `{path}`. OpenAPI has no optional segments, so
+ * a `{/:slug}` group gives two paths, one with it and one without.
+ */
+export declare function openApiPaths(path: string): string[];
+export {};
+//# sourceMappingURL=openapi.d.ts.map

package/dist/src/http/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../src/http/openapi.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,OAAO,CAAC,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC3D,4GAA4G;IAC5G,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CACvB;AAED,8EAA8E;AAC9E,MAAM,WAAW,kBAAmB,SAAQ,QAAQ;IAClD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAmB1C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,UAAU,CAwB1G;AAyCD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAOnD"}

package/dist/src/http/openapi.js

@@ -0,0 +1,151 @@
+import { STATUS_CODES } from "node:http";
+import { z } from "zod";
+const ERROR_RESPONSE = {
+    type: "object",
+    required: ["error"],
+    properties: {
+        error: {
+            type: "object",
+            required: ["code", "message", "requestId"],
+            properties: {
+                code: { type: "string", examples: ["NOT_FOUND"] },
+                message: { type: "string" },
+                details: {},
+                requestId: { type: "string" },
+            },
+        },
+    },
+};
+/**
+ * Builds an OpenAPI 3.1 document from the routes' Zod schemas. Requests are documented as clients send them
+ * (`io: "input"`) and responses as clients receive them (`io: "output"`). A named route's dotted name is its
+ * `operationId`, such as `users.get`: the same name the typed client uses.
+ */
+export function buildOpenApi(endpoints, options) {
+    const paths = {};
+    const securitySchemes = {};
+    for (const endpoint of endpoints) {
+        Object.assign(securitySchemes, endpoint.security);
+        for (const path of openApiPaths(endpoint.path)) {
+            const item = (paths[path] ??= {});
+            item[endpoint.method] = operation(endpoint, path);
+        }
+    }
+    return {
+        openapi: "3.1.1",
+        info: {
+            title: options.title,
+            version: options.version,
+            ...(options.description === undefined ? {} : { description: options.description }),
+        },
+        ...(options.servers ? { servers: options.servers } : {}),
+        paths,
+        components: {
+            schemas: { ErrorResponse: ERROR_RESPONSE },
+            ...(Object.keys(securitySchemes).length > 0 ? { securitySchemes } : {}),
+        },
+    };
+}
+function operation(endpoint, path) {
+    const { schemas } = endpoint;
+    const parameters = [
+        ...pathParameters(path, schemas.params),
+        ...fieldParameters(schemas.query, "query"),
+        ...fieldParameters(schemas.headers, "header"),
+    ];
+    const success = String(endpoint.status ?? (endpoint.method === "post" ? 201 : 200));
+    const responses = {
+        [success]: schemas.response
+            ? {
+                description: describe(success),
+                content: { "application/json": { schema: jsonSchema(schemas.response, "output") } },
+            }
+            : { description: describe(success) },
+        default: {
+            description: "Error",
+            content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } },
+        },
+    };
+    return {
+        tags: [endpoint.tag],
+        operationId: endpoint.name === undefined ? undefined : `${endpoint.tag}.${endpoint.name}`,
+        ...(endpoint.security
+            ? { security: [Object.fromEntries(Object.keys(endpoint.security).map((name) => [name, []]))] }
+            : {}),
+        ...(parameters.length > 0 ? { parameters } : {}),
+        ...(schemas.body
+            ? {
+                requestBody: {
+                    required: true,
+                    content: { "application/json": { schema: jsonSchema(schemas.body, "input") } },
+                },
+            }
+            : {}),
+        responses,
+    };
+}
+/**
+ * Converts an Express path: `:id` and `*path` become `{id}` and `{path}`. OpenAPI has no optional segments, so
+ * a `{/:slug}` group gives two paths, one with it and one without.
+ */
+export function openApiPaths(path) {
+    const group = /\{([^{}]*)\}/.exec(path);
+    if (group) {
+        const [whole, inner = ""] = group;
+        return [...openApiPaths(path.replace(whole, inner)), ...openApiPaths(path.replace(whole, ""))];
+    }
+    return [path.replace(/[:*]([\w$]+)/g, "{$1}")];
+}
+function pathParameters(path, schema) {
+    const properties = schema ? objectProperties(jsonSchema(schema, "input")) : {};
+    return [...path.matchAll(/\{([\w$]+)\}/g)].map(([, name = ""]) => ({
+        name,
+        in: "path",
+        required: true,
+        schema: properties[name] ?? { type: "string" },
+    }));
+}
+function fieldParameters(schema, location) {
+    if (!schema)
+        return [];
+    const json = jsonSchema(schema, "input");
+    const required = new Set(Array.isArray(json["required"]) ? json["required"] : []);
+    return Object.entries(objectProperties(json)).map(([name, property]) => ({
+        name,
+        in: location,
+        required: required.has(name),
+        schema: property,
+    }));
+}
+function jsonSchema(schema, io) {
+    const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { io, unrepresentable: "any" });
+    return withoutFormatPatterns(json);
+}
+/**
+ * Removes `pattern` wherever `format` already names the type (`email`, `uuid`, `date-time`). Zod emits both,
+ * and docs UIs such as Swagger UI build example values from the regex: several KB of noise for an email.
+ */
+function withoutFormatPatterns(json) {
+    const result = {};
+    for (const [key, value] of Object.entries(json)) {
+        if (key === "pattern" && typeof json["format"] === "string")
+            continue;
+        result[key] = clean(value);
+    }
+    return result;
+}
+function clean(value) {
+    if (Array.isArray(value))
+        return value.map(clean);
+    if (typeof value !== "object" || value === null)
+        return value;
+    return withoutFormatPatterns({ ...value });
+}
+function objectProperties(json) {
+    const properties = json["properties"];
+    return typeof properties === "object" && properties !== null ? { ...properties } : {};
+}
+function describe(status) {
+    return STATUS_CODES[Number(status)] ?? "Success";
+}
+//# sourceMappingURL=openapi.js.map

package/dist/src/http/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../../src/http/openapi.ts"],"names":[],"mappings":"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"}

package/dist/src/http/path-params.d.ts

@@ -0,0 +1,24 @@
+/** The union of characters in `S`: `CharsOf<"ab">` is `"a" | "b"`. Tail-recursive, so long strings are fine. */
+type CharsOf<S extends string, Found = never> = S extends `${infer C}${infer Rest}` ? CharsOf<Rest, Found | C> : Found;
+/** Characters a path parameter name may contain, as Express 5 (path-to-regexp v8) reads them. */
+type NameChar = CharsOf<"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_$">;
+/** Splits `"id/rest"` into the parameter name and what follows it: `["id", "/rest"]`. */
+type ReadName<S extends string, Name extends string = ""> = S extends `${infer C}${infer Rest}` ? C extends NameChar ? ReadName<Rest, `${Name}${C}`> : [Name, S] : [Name, S];
+/** Rewrites `*name` as `:*name`, so every parameter starts with `:`. */
+type MarkWildcards<S extends string> = S extends `${infer Before}*${infer After}` ? `${Before}:*${MarkWildcards<After>}` : S;
+/** Parameters outside optional groups. A `*name` wildcard is an array of segments, as Express 5 gives it. */
+type RequiredParams<S extends string> = S extends `${string}:${infer After}` ? After extends `*${infer Wildcard}` ? Named<Wildcard, string[]> : Named<After, string> : {};
+type Named<S extends string, Value> = ReadName<S> extends [infer Name extends string, infer Rest extends string] ? {
+    [K in Name]: Value;
+} & RequiredParams<Rest> : never;
+type GroupedParams<S extends string> = S extends `${infer Before}{${infer Inside}}${infer After}` ? RequiredParams<Before> & Partial<RequiredParams<Inside>> & GroupedParams<After> : RequiredParams<S>;
+/**
+ * The parameters of an Express 5 path, typed from the string.
+ *
+ * - `"/orgs/:orgId/users/:id"` gives `{ orgId: string; id: string }`
+ * - `"/files/*path"` gives `{ path: string[] }`
+ * - `"/posts{/:slug}"` gives `{ slug?: string }`
+ */
+export type PathParams<S extends string> = GroupedParams<MarkWildcards<S>>;
+export {};
+//# sourceMappingURL=path-params.d.ts.map

package/dist/src/http/path-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-params.d.ts","sourceRoot":"","sources":["../../../src/http/path-params.ts"],"names":[],"mappings":"AAAA,gHAAgH;AAChH,KAAK,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,GAAG,KAAK,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,MAAM,IAAI,EAAE,GAC/E,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,GACxB,KAAK,CAAC;AAEV,iGAAiG;AACjG,KAAK,QAAQ,GAAG,OAAO,CAAC,kEAAkE,CAAC,CAAC;AAE5F,yFAAyF;AACzF,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,SAAS,MAAM,GAAG,EAAE,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,MAAM,IAAI,EAAE,GAC3F,CAAC,SAAS,QAAQ,GAChB,QAAQ,CAAC,IAAI,EAAE,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC,GAC7B,CAAC,IAAI,EAAE,CAAC,CAAC,GACX,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAEd,wEAAwE;AACxE,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,MAAM,IAAI,MAAM,KAAK,EAAE,GAC7E,GAAG,MAAM,KAAK,aAAa,CAAC,KAAK,CAAC,EAAE,GACpC,CAAC,CAAC;AAEN,6GAA6G;AAC7G,KAAK,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,KAAK,EAAE,GACxE,KAAK,SAAS,IAAI,MAAM,QAAQ,EAAE,GAChC,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,GACzB,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,GACtB,EAAE,CAAC;AAEP,KAAK,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,IAChC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,IAAI,SAAS,MAAM,EAAE,MAAM,IAAI,SAAS,MAAM,CAAC,GACtE;KAAG,CAAC,IAAI,IAAI,GAAG,KAAK;CAAE,GAAG,cAAc,CAAC,IAAI,CAAC,GAC7C,KAAK,CAAC;AAEZ,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,MAAM,IAAI,MAAM,MAAM,IAAI,MAAM,KAAK,EAAE,GAC7F,cAAc,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,GAC/E,cAAc,CAAC,CAAC,CAAC,CAAC;AAEtB;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/src/http/path-params.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=path-params.js.map

package/dist/src/http/path-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-params.js","sourceRoot":"","sources":["../../../src/http/path-params.ts"],"names":[],"mappings":""}

package/dist/src/http/routes.d.ts

@@ -0,0 +1,141 @@
+import type { z } from "zod";
+import type { PathParams } from "./path-params.ts";
+/** An HTTP method a route can declare. */
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+/**
+ * A declared route, as `route.get(...)` and the other route methods return it. At runtime it holds the method
+ * and full path; its `~types` field exists only for the compiler, carrying what a client sends and receives.
+ *
+ * @example
+ * ```ts
+ * type Ping = Route<{}, { pong: true }>; // no input, resolves to { pong: true }
+ * ```
+ */
+export interface Route<Input = unknown, Output = unknown> {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly "~types"?: {
+        input: Input;
+        output: Output;
+    };
+}
+/** What a controller's setup returns: named routes, nested for groups. */
+export interface Routes {
+    readonly [name: string]: Route | Routes;
+}
+/**
+ * An app's routes as data: the typed client's map from names to method and path.
+ *
+ * @example
+ * ```ts
+ * const manifest = { users: { get: ["GET", "/api/users/:id"] } } as const satisfies Manifest;
+ * ```
+ */
+export interface Manifest {
+    readonly [name: string]: readonly [method: string, path: string] | Manifest;
+}
+/** A field that is left out when its type has no keys, and optional when every key is optional. */
+type Field<K extends string, T> = [keyof T] extends [never] ? {} : {} extends T ? {
+    [P in K]?: T;
+} : {
+    [P in K]: T;
+};
+type SchemaInput<S, Fallback> = S extends z.ZodType ? z.input<S> : Fallback;
+/** A value a URL can carry. */
+type UrlValue = string | number | boolean;
+/** A value the client can write into a URL: it turns numbers, booleans, bigints and dates into text. */
+type UrlScalar = UrlValue | bigint | Date;
+type SchemaOutput<S, Fallback> = S extends z.ZodType ? z.output<S> : Fallback;
+/**
+ * Path and query fields as a client writes them: the schema's input, or its output when that is something a
+ * URL can carry, so \`z.stringbool()\` takes \`true\` and \`z.coerce.number()\` takes \`2\`. A coercing schema's
+ * \`unknown\` input accepts any URL value.
+ */
+type UrlFields<In, Out> = {
+    [K in keyof In]: unknown extends In[K] ? UrlValue | UrlValue[] : In[K] | (K extends keyof Out ? Extract<Out[K], UrlScalar | readonly UrlScalar[] | undefined> : never);
+};
+/**
+ * Headers a client sends: the typed ones from the route's schema, plus any others, such as the
+ * `authorization` a middleware reads.
+ */
+type HeadersField<H> = H extends z.ZodType ? Field<"headers", z.input<H> & Record<string, string>> : {
+    headers?: Record<string, string>;
+};
+/** What a client sends: path params, query, body and headers, each typed by its schema. */
+export type RouteInput<Path extends string, P, Q, B, H> = Field<"params", UrlFields<SchemaInput<P, PathParams<Path>>, SchemaOutput<P, {}>>> & Field<"query", UrlFields<SchemaInput<Q, {}>, SchemaOutput<Q, {}>>> & Field<"body", SchemaInput<B, {}>> & HeadersField<H>;
+/** A Node stream, recognized by shape so these types never need `@types/node`. */
+interface StreamLike {
+    pipe(...args: never[]): unknown;
+    read(...args: never[]): unknown;
+}
+/**
+ * What a value becomes after `JSON.stringify` and `JSON.parse`: dates become strings, and functions and
+ * `undefined` fields disappear.
+ *
+ * @example
+ * ```ts
+ * type Sent = Jsonify<{ at: Date; run(): void; note?: string }>; // { at: string; note?: string }
+ * ```
+ */
+export type Jsonify<T> = T extends {
+    toJSON(): infer J;
+} ? Jsonify<J> : T extends string | number | boolean | null ? T : T extends readonly (infer E)[] ? Jsonify<E>[] : T extends object ? {
+    [K in keyof T as T[K] extends (...args: never[]) => unknown ? never : K]: Jsonify<T[K]>;
+} : never;
+/**
+ * What a client gets back: the response schema's output, or else the handler's JSON-serialized result. A
+ * stream or bytes come back as the raw `Response`, and nothing as `undefined` (204).
+ */
+export type RouteOutput<R, Returned> = R extends z.ZodType ? z.output<R> : [Returned] extends [undefined | void] ? undefined : Returned extends StreamLike | Uint8Array ? Response : Jsonify<Returned>;
+/** What `defineController` returns: carries its routes' types, read by {@link ApiOf}. */
+export interface ControllerTypes<R> {
+    readonly "~routes"?: R;
+}
+/**
+ * An app, or a map of controllers, reduced to its named routes: the shape of the typed client.
+ *
+ * @example
+ * ```ts
+ * type Api = ApiOf<typeof app>; // { users: { get: Route<...>, create: Route<...> } }
+ * ```
+ */
+export type ApiOf<T> = "~controllers" extends keyof T ? T extends {
+    readonly "~controllers"?: infer C;
+} ? RoutesOf<NonNullable<C>> : never : RoutesOf<T>;
+/** Controllers whose setup returned named routes; others have no place in the client. */
+type RoutesOf<C> = {
+    [K in keyof C as C[K] extends ControllerTypes<Routes> ? K : never]: C[K] extends ControllerTypes<infer R> ? R : never;
+};
+/**
+ * A typed client for routes: every route becomes a function that takes its input and resolves to its output.
+ *
+ * @example
+ * ```ts
+ * const user = await api.users.get({ params: { id } }); // typed from the route's schemas
+ * ```
+ */
+export type Client<T> = {
+    readonly [K in keyof T]: T[K] extends Route<infer I, infer O> ? Call<I, O> : Client<T[K]>;
+};
+/** A body sent as it is, without JSON encoding: a file, a form, bytes or a stream. */
+export type RawBody = FormData | Blob | URLSearchParams | ArrayBuffer | ArrayBufferView | ReadableStream | string;
+/** The input of {@link Call.raw}: the route's own input, with any body `fetch` accepts. */
+type RawInput<I> = Omit<I, "body"> & {
+    body?: RawBody | (I extends {
+        body?: infer B;
+    } ? B : never);
+};
+type Send<I, R> = {} extends I ? (input?: I, init?: RequestInit) => Promise<R> : (input: I, init?: RequestInit) => Promise<R>;
+/**
+ * One route as a function. It resolves to the route's output and rejects with `ApiError` on a non-2xx
+ * response; `init` passes fetch options such as `signal`.
+ */
+export type Call<I, O> = Send<I, O> & {
+    /**
+     * The same request, resolving to the raw `Response` whatever its status: for downloads, uploads
+     * (`body: formData`) and anything that is not JSON. The client's headers are still applied.
+     */
+    readonly raw: Send<RawInput<I>, Response>;
+};
+export {};
+//# sourceMappingURL=routes.d.ts.map

package/dist/src/http/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/http/routes.ts"],"names":[],"mappings":"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"}

package/dist/src/http/routes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=routes.js.map

package/dist/src/http/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../../src/http/routes.ts"],"names":[],"mappings":""}

package/dist/src/http/server.d.ts

@@ -0,0 +1,23 @@
+import type { Server as HttpServerType } from "node:http";
+import type { Server as HttpsServerType } from "node:https";
+/** The Node server an app listens on: plain HTTP, or HTTPS when you pass your own. */
+export type NodeServer = HttpServerType | HttpsServerType;
+/**
+ * The listening server, injectable once the app listens. Attach WebSockets (`ws`, Socket.IO) to it in a
+ * provider's `onReady`; it does not exist before then, so never inject it in a class field or `onInit`.
+ *
+ * @example
+ * ```ts
+ * export class ChatGateway implements OnReady, OnDrain {
+ *   #wss?: WebSocketServer;
+ *   onReady() {
+ *     this.#wss = new WebSocketServer({ server: inject(HttpServer) });
+ *   }
+ *   onDrain() {
+ *     for (const client of this.#wss?.clients ?? []) client.close(1001);
+ *   }
+ * }
+ * ```
+ */
+export declare const HttpServer: import("../di/container.ts").InjectionToken<NodeServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/src/http/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/http/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,KAAK,EAAE,MAAM,IAAI,eAAe,EAAE,MAAM,YAAY,CAAC;AAG5D,sFAAsF;AACtF,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,eAAe,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,yDAIrB,CAAC"}

package/dist/src/http/server.js

@@ -0,0 +1,22 @@
+import { defineToken } from "../di/container.js";
+/**
+ * The listening server, injectable once the app listens. Attach WebSockets (`ws`, Socket.IO) to it in a
+ * provider's `onReady`; it does not exist before then, so never inject it in a class field or `onInit`.
+ *
+ * @example
+ * ```ts
+ * export class ChatGateway implements OnReady, OnDrain {
+ *   #wss?: WebSocketServer;
+ *   onReady() {
+ *     this.#wss = new WebSocketServer({ server: inject(HttpServer) });
+ *   }
+ *   onDrain() {
+ *     for (const client of this.#wss?.clients ?? []) client.close(1001);
+ *   }
+ * }
+ * ```
+ */
+export const HttpServer = /* @__PURE__ */ defineToken("HttpServer", () => {
+    throw new Error("HttpServer exists only once the app listens: inject it in onReady(), not in a field or onInit().");
+});
+//# sourceMappingURL=server.js.map

package/dist/src/http/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/http/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAKjD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,eAAe,CAAC,WAAW,CAAa,YAAY,EAAE,GAAG,EAAE;IACnF,MAAM,IAAI,KAAK,CACb,kGAAkG,CACnG,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/src/http/validation.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * Zod parsing shared by routes and middlewares. Every parse is synchronous, the fast path, unless a schema has
+ * async refinements: then it switches to `safeParseAsync` and the value comes back wrapped in {@link Pending}.
+ */
+/** An input whose schema needs async validation; never a value a schema can produce. */
+export declare class Pending {
+    readonly promise: Promise<unknown>;
+    constructor(promise: Promise<unknown>);
+}
+export declare const settle: (value: unknown) => unknown;
+export declare function parseInput(schema: z.ZodType | undefined, value: unknown, location: string): unknown;
+/** A result that breaks its own response schema is a server bug: a 500, never a 400. */
+export declare function serializeOutput(schema: z.ZodType | undefined, value: unknown): unknown;
+export declare function safeParse(schema: z.ZodType, value: unknown): z.ZodSafeParseResult<unknown> | Promise<z.ZodSafeParseResult<unknown>>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/src/http/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/http/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;GAGG;AAEH,wFAAwF;AACxF,qBAAa,OAAO;IAClB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,YAAY,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,EAEpC;CACF;AAED,eAAO,MAAM,MAAM,UAAW,OAAO,KAAG,OAA6D,CAAC;AAEtG,wBAAgB,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMnG;AAOD,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAItF;AAOD,wBAAgB,SAAS,CACvB,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,KAAK,EAAE,OAAO,GACb,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAOxE"}