@raiyyan/brisk 0.0.0-stage → 0.1.0

package/dist/src/http/instance.js

@@ -0,0 +1,309 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import express, { Router } from "express";
+import { createLogger, Logger } from "../config/logger.js";
+import { Container, provide } from "../di/container.js";
+import { NotFoundError } from "../errors/http-errors.js";
+import { createRequestContext, getContext } from "./context.js";
+import { joinPath, methodGuard } from "./controller.js";
+import { defaultErrorFormatter, errorHandler } from "./error-handler.js";
+import { buildOpenApi } from "./openapi.js";
+import { HttpServer } from "./server.js";
+const DEFAULT_SECURITY_HEADERS = {
+    "x-content-type-options": "nosniff",
+    "x-frame-options": "DENY",
+    "referrer-policy": "no-referrer",
+    "cross-origin-resource-policy": "same-origin",
+    "content-security-policy": "default-src 'none'; frame-ancestors 'none'",
+};
+/** Accepts a caller's `x-request-id` only when it is short and plain, so it cannot forge log lines. */
+const SAFE_REQUEST_ID = /^[\w.:-]{1,128}$/;
+/**
+ * Builds one instance of an app: security headers, request ids and logging, your Express setup, JSON parsing,
+ * health check and OpenAPI routes, controllers, 404 and error handling, and the container that runs every
+ * lifecycle hook. `overrides` come after the app's own providers, so they win.
+ */
+export function createInstance(options, overrides = []) {
+    const logger = options.logger ?? createLogger();
+    const hooks = options.hooks ?? {};
+    const http = options.http ?? {};
+    const errors = options.errors ?? {};
+    const container = new Container([provide(Logger, logger), ...(options.providers ?? []), ...overrides]);
+    const app = express();
+    const draining = { active: false, responses: new Map() };
+    app.disable("x-powered-by");
+    app.set("query parser", "simple");
+    if (http.trustProxy !== undefined)
+        app.set("trust proxy", http.trustProxy);
+    app.use(prelude({ logger, hooks, draining, container, headers: securityHeaders(http.securityHeaders) }));
+    options.configureExpress?.(app);
+    const router = Router();
+    const manifest = {};
+    const allRoutes = [];
+    for (const [name, controller] of Object.entries(options.controllers ?? {})) {
+        const mounted = controller.mount(container, router, joinPath(options.prefix ?? "/", controller.prefix));
+        for (const endpoint of mounted.endpoints)
+            allRoutes.push({ ...endpoint, tag: name });
+        if (mounted.manifest)
+            manifest[name] = mounted.manifest;
+    }
+    let document;
+    const openapi = () => (document ??= buildOpenApi(allRoutes, options.openapi ?? { title: "API", version: "0.0.0" }));
+    const routes = allRoutes.map(({ method, path }) => `${method.toUpperCase()} ${path}`);
+    const guard = methodGuard(allRoutes);
+    const json = express.json({
+        limit: http.bodyLimit ?? "1mb",
+        type: ["application/json", "application/*+json"],
+    });
+    app.use((req, res, next) => {
+        if (req.method === "OPTIONS")
+            guard(req, res, next);
+        else
+            json(req, res, next);
+    });
+    if (hooks.onRequest)
+        app.use(onRequest(hooks.onRequest));
+    const openapiPath = options.openapi?.path ?? "/openapi.json";
+    if (options.openapi && openapiPath !== false) {
+        app.get(openapiPath, (_req, res) => {
+            res.json(openapi());
+        });
+    }
+    if (http.healthPath !== false) {
+        app.get(http.healthPath ?? "/health", (_req, res) => {
+            res.json({ status: "ok" });
+        });
+    }
+    app.use(router);
+    app.use(guard);
+    app.use((req) => {
+        throw new NotFoundError(`Cannot ${req.method} ${req.path}`, { code: "ROUTE_NOT_FOUND" });
+    });
+    app.use(errorHandler({
+        mappers: errors.mappers ?? [],
+        format: errors.format ?? defaultErrorFormatter,
+        exposeInternalErrors: errors.exposeInternal ?? false,
+        onError: hooks.onError,
+    }));
+    let initializing;
+    let stopping;
+    let server;
+    const sockets = new Set();
+    const signals = ["SIGINT", "SIGTERM"];
+    const shutdownTimeoutMs = http.shutdownTimeoutMs ?? 10_000;
+    /** Shuts down and exits; a hook that never settles cannot keep the process alive past the deadline. */
+    const exitAfterShutdown = (code) => {
+        setTimeout(() => {
+            logger.fatal("shutdown did not finish in time, exiting");
+            process.exit(1);
+        }, shutdownTimeoutMs + 10_000).unref();
+        void shutdown().then(() => process.exit(code));
+    };
+    let firstSignal;
+    /**
+     * The first signal starts a graceful shutdown. While it runs, the listeners stay installed: tools often send a
+     * second, different signal (`node --watch` and some init systems forward SIGTERM right after the terminal's
+     * SIGINT), and without a listener Node would kill the process mid-drain. Repeating the same signal (Ctrl+C
+     * twice) is a person asking to stop now, so it exits immediately.
+     */
+    const onSignal = (signal) => {
+        if (firstSignal === undefined) {
+            firstSignal = signal;
+            logger.info({ signal }, "shutting down");
+            exitAfterShutdown(0);
+        }
+        else if (signal === firstSignal) {
+            logger.warn({ signal }, "second signal, exiting without waiting");
+            process.exit(1);
+        }
+        else {
+            logger.info({ signal }, "already shutting down");
+        }
+    };
+    const onCrash = (reason) => {
+        if (stopping) {
+            logger.error({ err: reason }, "unhandled error during shutdown");
+            return;
+        }
+        logger.fatal({ err: reason }, "unhandled error, shutting down");
+        exitAfterShutdown(1);
+    };
+    const reportHookError = (hook) => (error, provider) => {
+        logger.error({ err: error, provider }, `${hook} failed`);
+    };
+    const init = () => (initializing ??= container.init());
+    const becomeReady = async (manageProcess) => {
+        await container.ready();
+        if (manageProcess) {
+            for (const signal of signals)
+                process.on(signal, onSignal);
+            process.on("unhandledRejection", onCrash);
+            process.on("uncaughtException", onCrash);
+        }
+    };
+    /** Boots, and shuts down whatever already started when booting fails. */
+    const boot = async (run) => {
+        try {
+            return await run();
+        }
+        catch (error) {
+            await shutdown();
+            throw error;
+        }
+    };
+    const start = ({ manageProcess = true }) => boot(async () => {
+        await init();
+        await becomeReady(manageProcess);
+        logger.info("started without an HTTP server");
+    });
+    const listen = (port, listenOptions) => boot(() => serve(port, listenOptions));
+    const serve = async (port, { host, server: custom, manageProcess = true }) => {
+        await init();
+        const target = custom ?? createServer();
+        target.on("request", app);
+        target.on("connection", (socket) => {
+            sockets.add(socket);
+            draining.responses.set(socket, undefined);
+            socket.once("close", () => {
+                sockets.delete(socket);
+                draining.responses.delete(socket);
+            });
+        });
+        await new Promise((resolve, reject) => {
+            target.once("error", reject);
+            const onListening = () => {
+                target.off("error", reject);
+                resolve();
+            };
+            if (host === undefined)
+                target.listen(port, onListening);
+            else
+                target.listen(port, host, onListening);
+        });
+        server = target;
+        container.set(HttpServer, target);
+        await becomeReady(manageProcess);
+        const address = target.address();
+        const boundPort = typeof address === "object" && address ? address.port : port;
+        logger.info({ port: boundPort, routes }, `listening on http://${host ?? "localhost"}:${boundPort}`);
+    };
+    const shutdown = () => (stopping ??= (async () => {
+        draining.active = true;
+        for (const res of draining.responses.values()) {
+            if (res && !res.headersSent)
+                res.setHeader("connection", "close");
+        }
+        const closed = server?.listening ? closeServer(server, sockets, shutdownTimeoutMs) : undefined;
+        await container.drain(reportHookError("onDrain"));
+        await closed;
+        await container.shutdown(reportHookError("onShutdown"));
+        for (const signal of signals)
+            process.off(signal, onSignal);
+        process.off("unhandledRejection", onCrash);
+        process.off("uncaughtException", onCrash);
+        logger.info("shutdown complete");
+    })());
+    return {
+        manifest,
+        openapi,
+        express: app,
+        logger,
+        container,
+        get server() {
+            return server;
+        },
+        init,
+        listen,
+        start,
+        shutdown,
+    };
+}
+/** The security headers to send, computed once; `undefined` when they are turned off. */
+function securityHeaders(option) {
+    if (option === false)
+        return undefined;
+    const merged = { ...DEFAULT_SECURITY_HEADERS, ...(typeof option === "object" ? option : {}) };
+    const headers = new Map();
+    for (const [name, value] of Object.entries(merged))
+        if (value !== false)
+            headers.set(name, value);
+    return headers;
+}
+const proceed = (next) => next();
+/**
+ * Everything brisk does before your Express code, in one layer: security headers, the request id and context
+ * (with its lazy logger), the response log and `onResponse`, shutdown's `Connection: close`, and the app's
+ * dependency scope, so `inject()` works for the rest of the request, `configureExpress` included.
+ *
+ * The response is logged on `close`, which also fires for requests the client abandoned (`finish` would not).
+ * The listener exists only when something consumes it: the `info` log level or an `onResponse` hook.
+ */
+function prelude({ logger, hooks, draining, container, headers }) {
+    return (req, res, next) => {
+        if (headers)
+            res.setHeaders(headers);
+        const incoming = req.get("x-request-id");
+        const requestId = incoming && SAFE_REQUEST_ID.test(incoming) ? incoming : randomUUID();
+        const ctx = createRequestContext(req, res, requestId, logger);
+        res.setHeader("x-request-id", requestId);
+        if (draining.active)
+            res.setHeader("connection", "close");
+        else if (draining.responses.has(req.socket))
+            draining.responses.set(req.socket, res);
+        const log = logger.isLevelEnabled("info");
+        if (log || hooks.onResponse) {
+            const started = performance.now();
+            res.once("close", () => {
+                const durationMs = Math.round(performance.now() - started);
+                const aborted = !res.writableFinished;
+                if (log) {
+                    const line = {
+                        method: req.method,
+                        url: pathOf(req.originalUrl),
+                        status: res.statusCode,
+                        durationMs,
+                    };
+                    ctx.log.info(aborted ? { ...line, aborted } : line, "request");
+                }
+                hooks.onResponse?.(ctx, { status: res.statusCode, durationMs, aborted });
+            });
+        }
+        container.run(proceed, next);
+    };
+}
+/**
+ * The URL without its query string. Query strings carry secrets often enough (reset tokens, OAuth codes, API
+ * keys) that brisk never writes them to logs; log what you need from `ctx.req.query` in `onResponse`.
+ */
+function pathOf(url) {
+    const query = url.indexOf("?");
+    return query === -1 ? url : url.slice(0, query);
+}
+function onRequest(hook) {
+    return async (req, _res, next) => {
+        await hook(getContext(req));
+        next();
+    };
+}
+/**
+ * Stops accepting connections and resolves once every in-flight request has finished. Keep-alive sockets
+ * close as soon as they go idle; after `timeoutMs` every remaining socket is destroyed, including upgraded
+ * WebSocket connections, which Node's `closeAllConnections` does not track.
+ */
+function closeServer(server, sockets, timeoutMs) {
+    return new Promise((resolve) => {
+        const sweep = setInterval(() => server.closeIdleConnections(), 10);
+        const force = setTimeout(() => {
+            server.closeAllConnections();
+            for (const socket of sockets)
+                socket.destroy();
+        }, timeoutMs);
+        server.close(() => {
+            clearInterval(sweep);
+            clearTimeout(force);
+            resolve();
+        });
+        server.closeIdleConnections();
+    });
+}
+//# sourceMappingURL=instance.js.map

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

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

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

@@ -0,0 +1,54 @@
+import { type RequestContext } from "./context.ts";
+/**
+ * Per-request logic shared by many routes, as {@link defineMiddleware} makes it. `run(ctx)` resolves to its
+ * output, computing it at most once per request.
+ */
+export interface Middleware<Out extends object = object> {
+    readonly name: string;
+    run(ctx: RequestContext): Promise<Out>;
+}
+/**
+ * Names a middleware may not return: the request basics and validated input share the handler's ctx, and a
+ * middleware field with one of these names would be silently replaced. `log` is allowed, to enrich the logger.
+ */
+type ReservedKey = "req" | "res" | "requestId" | "params" | "query" | "body" | "headers";
+/** Rejects outputs that use a {@link ReservedKey}; the error names the offending key. */
+type NoReservedKeys<Out> = {
+    [K in keyof Out]: K extends ReservedKey ? `"${K}" is reserved on ctx` : Out[K];
+};
+/** The middleware's output, or a type error naming any {@link ReservedKey} it uses. */
+type Checked<Out> = Out extends object ? Out & NoReservedKeys<Out> : Out;
+/**
+ * Declares per-request logic shared by many routes. Return an object to add typed fields to the handler's ctx,
+ * return nothing for a pure check, or throw an error class to stop the request. Sync or async.
+ *
+ * Each middleware runs at most once per request: another middleware, or a handler, can `await other.run(ctx)`
+ * and reuse its result. The names `req`, `res`, `requestId`, `params`, `query`, `body` and `headers` are
+ * reserved on ctx and rejected at compile time; returning `log` replaces the request logger.
+ *
+ * @example
+ * ```ts
+ * export const authenticate = defineMiddleware(async ({ req, log }) => {
+ *   const user = await inject(Sessions).verify(req.get("authorization"));
+ *   if (!user) throw new UnauthorizedError();
+ *   return { user, log: log.child({ userId: user.id }) };
+ * }, "authenticate");
+ *
+ * export const requireRole = (role: Role) =>
+ *   defineMiddleware(async (ctx) => {
+ *     const { user } = await authenticate.run(ctx);
+ *     if (user.role !== role) throw new ForbiddenError();
+ *   });
+ * ```
+ */
+export declare function defineMiddleware<Out extends object | void>(fn: (ctx: RequestContext) => Checked<Out> | Promise<Checked<Out>>, name?: string): Middleware<Out extends object ? Out : {}>;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/** Merges the outputs of a middleware list into one type: `[auth, tenant]` gives `{ user } & { tenant }`. */
+export type MiddlewareContext<T extends readonly Middleware[]> = [T[number]] extends [never] ? {} : UnionToIntersection<T[number] extends infer M ? (M extends Middleware<infer O> ? O : never) : never>;
+/**
+ * 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 declare function applyMiddlewares(base: RequestContext, target: object, list: readonly Middleware[], from?: number): void | Promise<void>;
+export {};
+//# sourceMappingURL=middleware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../src/http/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAEhE;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACxC;AAED;;;GAGG;AACH,KAAK,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAEzF,yFAAyF;AACzF,KAAK,cAAc,CAAC,GAAG,IAAI;KAAG,CAAC,IAAI,MAAM,GAAG,GAAG,CAAC,SAAS,WAAW,GAAG,IAAI,CAAC,sBAAsB,GAAG,GAAG,CAAC,CAAC,CAAC;CAAE,CAAC;AAE9G,uFAAuF;AACvF,KAAK,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,MAAM,GAAG,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,SAAS,MAAM,GAAG,IAAI,EACxD,EAAE,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EACjE,IAAI,GAAE,MAAgB,GACrB,UAAU,CAAC,GAAG,SAAS,MAAM,GAAG,GAAG,GAAG,EAAE,CAAC,CAE3C;AAsDD,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,IAAI,GACnG,CAAC,GACD,KAAK,CAAC;AAEV,6GAA6G;AAC7G,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACxF,EAAE,GACF,mBAAmB,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,CAAC;AAEzG;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3B,IAAI,SAAI,GACP,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CActB"}

package/dist/src/http/middleware.js

@@ -0,0 +1,101 @@
+import { requestMemo } from "./context.js";
+/**
+ * Declares per-request logic shared by many routes. Return an object to add typed fields to the handler's ctx,
+ * return nothing for a pure check, or throw an error class to stop the request. Sync or async.
+ *
+ * Each middleware runs at most once per request: another middleware, or a handler, can `await other.run(ctx)`
+ * and reuse its result. The names `req`, `res`, `requestId`, `params`, `query`, `body` and `headers` are
+ * reserved on ctx and rejected at compile time; returning `log` replaces the request logger.
+ *
+ * @example
+ * ```ts
+ * export const authenticate = defineMiddleware(async ({ req, log }) => {
+ *   const user = await inject(Sessions).verify(req.get("authorization"));
+ *   if (!user) throw new UnauthorizedError();
+ *   return { user, log: log.child({ userId: user.id }) };
+ * }, "authenticate");
+ *
+ * export const requireRole = (role: Role) =>
+ *   defineMiddleware(async (ctx) => {
+ *     const { user } = await authenticate.run(ctx);
+ *     if (user.role !== role) throw new ForbiddenError();
+ *   });
+ * ```
+ */
+export function defineMiddleware(fn, name = fn.name) {
+    return new DefinedMiddleware(fn, name);
+}
+const EMPTY = Object.freeze({});
+/**
+ * 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 {
+    name;
+    #fn;
+    constructor(fn, name) {
+        this.name = name;
+        this.#fn = fn;
+    }
+    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.#fn(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;
+    }
+    /** 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 = isDefined(middleware) ? middleware.resolve(base) : middleware.run(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;
+}
+/** `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":"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"}

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,CAmB1G;AAsCD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAOnD"}

package/dist/src/http/openapi.js

@@ -0,0 +1,123 @@
+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 = {};
+    for (const endpoint of endpoints) {
+        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 } },
+    };
+}
+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}`,
+        ...(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 json;
+}
+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