@raiyyan/brisk 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,229 @@
+import type { Express, RequestHandler } from "express";
+import type { Logger } from "../config/logger.ts";
+import type { Container, ProviderEntry } from "../di/container.ts";
+import type { RequestContext } from "./context.ts";
+import type { Controller } from "./controller.ts";
+import type { ErrorFormatter, ErrorMapper } from "./error-handler.ts";
+import type { Middleware } from "./middleware.ts";
+import type { OpenApiOptions } from "./openapi.ts";
+import type { Manifest } from "./routes.ts";
+import type { NodeServer } from "./server.ts";
+/** Controllers by name. The names are the typed client's top level: `{ users }` gives `api.users.get(...)`. */
+export type ControllerMap = Readonly<Record<string, Controller>>;
+/**
+ * Per-request hooks for metrics, tracing and error reporting. Logic that can reject a request is a middleware
+ * in `use`; startup and shutdown work belongs in a provider class (`onInit`, `onReady`, `onDrain`, `onShutdown`).
+ *
+ * @example
+ * ```ts
+ * hooks: {
+ *   onResponse: (ctx, { status, durationMs }) => metrics.observe(ctx.req.route?.path, status, durationMs),
+ *   onError: (error) => {
+ *     if (error instanceof HttpError && error.status < 500) return;
+ *     Sentry.captureException(error);
+ *   },
+ * }
+ * ```
+ */
+export interface AppHooks {
+    /**
+     * Once per request, when its connection is done with it. `aborted` is `true` when the client left before the
+     * response was fully sent; `status` is then what the server had set so far.
+     */
+    onResponse?: (ctx: RequestContext, info: {
+        status: number;
+        durationMs: number;
+        aborted: boolean;
+    }) => void;
+    /** Every error that reaches the error handler, client errors included, before the response is sent. */
+    onError?: (error: unknown, ctx: RequestContext) => void;
+}
+/** How errors become responses. */
+export interface ErrorOptions {
+    /**
+     * Turn library errors into HTTP errors in one place: `[(e) => isUniqueViolation(e) ? new ConflictError() : undefined]`.
+     * The first mapper that returns an error wins.
+     */
+    mappers?: readonly ErrorMapper[];
+    /** Replace the error body, such as with RFC 9457 problem details. Default `{ error: { code, message, details, requestId } }`. */
+    format?: ErrorFormatter;
+    /** Send the real message of unexpected errors to clients. Development only. Default `false`. */
+    exposeInternal?: boolean;
+}
+/** HTTP-level settings. Every default suits an API; change them only for a reason. */
+export interface HttpOptions {
+    /** Size limit for JSON bodies (`application/json` and `application/*+json`). Default `1mb`. */
+    bodyLimit?: string;
+    /**
+     * Express app settings, as `app.set(name, value)` takes them, such as `{ "trust proxy": 1 }` behind one proxy
+     * you control (never blindly, or clients can spoof `req.ip` with `X-Forwarded-For`), `{ etag: false }`, or
+     * `{ "query parser": "extended" }` for nested query objects (brisk's default is flat).
+     */
+    settings?: Readonly<Record<string, unknown>>;
+    /**
+     * Security headers on every response. `true` (default) sends strict API defaults; an object overrides single
+     * headers (`false` removes one), such as a relaxed `content-security-policy` for HTML pages.
+     */
+    securityHeaders?: boolean | Readonly<Record<string, string | false>>;
+    /** Health check path, or `false` for none. Default `/health`. */
+    healthPath?: string | false;
+    /**
+     * How long shutdown waits for in-flight requests before destroying the remaining sockets. Default 10 000 ms.
+     * A process the app manages also exits with code 1 if shutdown, hooks included, is not done 10 s later.
+     */
+    shutdownTimeoutMs?: number;
+}
+/**
+ * Options for {@link defineApp}. All are optional: an app with no controllers serves only its health check, or
+ * nothing at all when started with `app.start()`.
+ */
+export interface AppOptions<C extends ControllerMap = ControllerMap> {
+    /** Path every controller is mounted under, such as `/api`. Default `/`. */
+    prefix?: string;
+    /** Controllers by name: `{ users: usersController }`. */
+    controllers?: C;
+    /**
+     * Values for tokens (`provide(Clock, fakeClock)`), and classes to create at startup even when nothing injects
+     * them (a WebSocket gateway, a queue consumer) so their lifecycle hooks run.
+     */
+    providers?: readonly ProviderEntry[];
+    /** The app's pino logger. Default: `createLogger()`, JSON at `info`. */
+    logger?: Logger;
+    /**
+     * Middlewares for every request after the health check and OpenAPI routes: routes, mounts and 404s alike.
+     * The same values a route's `use` takes. An Express middleware (`fromExpress(cors())`) runs as a plain
+     * Express layer; a `defineMiddleware` runs once per request, its `security` is listed on every OpenAPI
+     * operation, and a route reads its output with `await middleware.run(ctx)`. To type a middleware's output on
+     * `ctx`, list it in the controller's `use`; it still runs only once.
+     *
+     * @example
+     * ```ts
+     * use: [fromExpress(cors({ origin: env.WEB_ORIGIN })), fromExpress(rateLimit({ limit: 100 }))],
+     * ```
+     */
+    use?: readonly Middleware[];
+    /**
+     * Express handlers that are not brisk routes, by path: static files, GraphQL, tRPC, webhooks that need the
+     * raw body, a single-page app's fallback. They answer what brisk's routes did not, so a mount never shadows
+     * a route, and they get the request's context, `inject()`, `use` and the error handler. Paths are absolute
+     * (the app `prefix` does not apply), and Express strips the path before the handler sees the URL. Brisk does
+     * not parse their bodies. A Node `(req, res)` handler, such as GraphQL Yoga's, mounts as
+     * `(req, res) => yoga(req, res)`.
+     *
+     * @example
+     * ```ts
+     * mount: {
+     *   "/graphql": (req, res) => yoga(req, res),
+     *   "/webhooks/stripe": [express.raw({ type: "application/json" }), stripeWebhook],
+     *   "/": express.static("public"),
+     * },
+     * ```
+     */
+    mount?: Readonly<Record<string, RequestHandler | readonly RequestHandler[]>>;
+    hooks?: AppHooks;
+    /** Serve an OpenAPI 3.1 document built from the routes' schemas, at `/openapi.json` by default. */
+    openapi?: OpenApiOptions;
+    errors?: ErrorOptions;
+    http?: HttpOptions;
+}
+/**
+ * Options for {@link App.create}: providers added after the app's own, typically fakes in tests. A value for a
+ * token the app already provides wins; a class is created alongside the app's.
+ */
+export interface CreateOptions {
+    providers?: readonly ProviderEntry[];
+}
+/** Options for {@link App.start}. */
+export interface StartOptions extends CreateOptions {
+    /**
+     * Let the app own the process (default `true`): SIGINT and SIGTERM shut it down gracefully and exit 0; an
+     * unhandled rejection or uncaught exception is logged, shuts it down and exits 1.
+     */
+    manageProcess?: boolean;
+}
+/** Options for {@link App.listen}. */
+export interface ListenOptions extends StartOptions {
+    /** Interface to bind, such as `127.0.0.1` for local only. Default: all interfaces. */
+    host?: string;
+    /** Your own server, such as `https.createServer(tls)`; brisk attaches its request handler. */
+    server?: NodeServer;
+}
+/** Types only: the app's controllers, read by `ApiOf` and `createClient`. */
+interface Typed<C> {
+    readonly "~controllers"?: C;
+}
+/**
+ * An app as {@link defineApp} declares it. Nothing runs until `listen`, `start` or `create`; each call makes a
+ * fresh, independent instance, so tests can run as many as they like.
+ */
+export interface App<C extends ControllerMap = ControllerMap> extends Typed<C> {
+    /**
+     * Creates an instance and serves HTTP: init hooks, listen, ready hooks. Resolves with the running instance.
+     * When startup fails (an `onInit` throws, the port is taken), what already started is shut down first.
+     *
+     * @example
+     * ```ts
+     * await app.listen(env.PORT);
+     * await app.listen(443, { server: https.createServer(tls) });
+     * ```
+     */
+    listen(port: number, options?: ListenOptions): Promise<AppInstance<C>>;
+    /**
+     * Creates an instance and starts it without HTTP: for workers and schedulers that share the app's providers.
+     *
+     * @example
+     * ```ts
+     * // worker.ts
+     * await defineApp({ providers: [EmailConsumer] }).start();
+     * ```
+     */
+    start(options?: StartOptions): Promise<AppInstance<C>>;
+    /**
+     * Creates an instance that is not started, for platforms that bring their own server, such as serverless:
+     * `const instance = app.create(); await instance.init();` then hand `instance.express` to the adapter.
+     */
+    create(options?: CreateOptions): AppInstance<C>;
+    /** The routes by name, as data: what `brisk client` writes for a frontend. */
+    readonly manifest: Manifest;
+    /** The OpenAPI 3.1 document for the routes: what `brisk openapi` writes. */
+    openapi(): Record<string, unknown>;
+}
+/** One instance of an app: its Express app, server and container, and its shutdown. */
+export interface AppInstance<C extends ControllerMap = ControllerMap> extends Typed<C> {
+    readonly express: Express;
+    /** The listening server, or `undefined` when the instance did not listen. */
+    readonly server: NodeServer | undefined;
+    readonly container: Container;
+    readonly logger: Logger;
+    readonly manifest: Manifest;
+    openapi(): Record<string, unknown>;
+    /** Runs the `onInit` hooks once; `listen` and `start` call it. Call it yourself after `create()`. */
+    init(): Promise<void>;
+    /** Graceful shutdown: drain, close the server, run `onShutdown`. Safe to call more than once. */
+    shutdown(): Promise<void>;
+}
+/**
+ * Declares an application: its controllers, providers and settings. Nothing runs at import time; `listen`,
+ * `start` and `create` each build a fresh instance. `typeof app` is the API's type for the typed client.
+ *
+ * @example
+ * ```ts
+ * // src/app.ts
+ * export const app = defineApp({
+ *   prefix: "/api",
+ *   controllers: { users: usersController },
+ *   logger: createLogger({ level: env.LOG_LEVEL }),
+ *   openapi: { title: "Shop API", version: "1.0.0" },
+ * });
+ * export type Api = typeof app;
+ *
+ * // src/main.ts
+ * await app.listen(env.PORT);
+ *
+ * // test/users.test.ts
+ * const api = await createTestClient(app, { providers: [provide(Clock, () => fixedDate)] });
+ * ```
+ */
+export declare function defineApp<const C extends ControllerMap = {}>(options?: AppOptions<C>): App<C>;
+export {};
+//# sourceMappingURL=app.d.ts.map

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

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

package/dist/src/http/app.js

@@ -0,0 +1,45 @@
+import { createInstance } from "./instance.js";
+/**
+ * Declares an application: its controllers, providers and settings. Nothing runs at import time; `listen`,
+ * `start` and `create` each build a fresh instance. `typeof app` is the API's type for the typed client.
+ *
+ * @example
+ * ```ts
+ * // src/app.ts
+ * export const app = defineApp({
+ *   prefix: "/api",
+ *   controllers: { users: usersController },
+ *   logger: createLogger({ level: env.LOG_LEVEL }),
+ *   openapi: { title: "Shop API", version: "1.0.0" },
+ * });
+ * export type Api = typeof app;
+ *
+ * // src/main.ts
+ * await app.listen(env.PORT);
+ *
+ * // test/users.test.ts
+ * const api = await createTestClient(app, { providers: [provide(Clock, () => fixedDate)] });
+ * ```
+ */
+export function defineApp(options = {}) {
+    let probe;
+    const inspect = () => (probe ??= createInstance(options));
+    return {
+        async listen(port, { providers, ...listenOptions } = {}) {
+            const instance = createInstance(options, providers);
+            await instance.listen(port, listenOptions);
+            return instance;
+        },
+        async start({ providers, ...startOptions } = {}) {
+            const instance = createInstance(options, providers);
+            await instance.start(startOptions);
+            return instance;
+        },
+        create: ({ providers } = {}) => createInstance(options, providers),
+        get manifest() {
+            return inspect().manifest;
+        },
+        openapi: () => inspect().openapi(),
+    };
+}
+//# sourceMappingURL=app.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../../src/http/app.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,cAAc,EAAe,MAAM,eAAe,CAAC;AA8M5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,SAAS,CAAqC,OAAO,GAAkB,EAAE;IACvF,IAAI,KAA4B,CAAC;IACjC,MAAM,OAAO,GAAG,GAAc,EAAE,CAAC,CAAC,KAAK,KAAK,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IACrE,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,GAAG,aAAa,EAAE,GAAG,EAAE;YACrD,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;YACpD,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;YAC3C,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,GAAG,YAAY,EAAE,GAAG,EAAE;YAC7C,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;YACpD,MAAM,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YACnC,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,SAAS,CAAC;QAClE,IAAI,QAAQ;YACV,OAAO,OAAO,EAAE,CAAC,QAAQ,CAAC;QAC5B,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE;KACnC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,66 @@
+import type { Request, Response } from "express";
+import type { Logger } from "../config/logger.ts";
+/**
+ * What every request carries from the start. A handler's `ctx` adds each middleware's output and the
+ * validated input to it.
+ *
+ * @example
+ * ```ts
+ * route.get("/me", ({ req, requestId, log }) => {
+ *   log.info({ ip: req.ip }, "profile viewed");
+ *   return { requestId };
+ * });
+ * ```
+ */
+export interface RequestContext {
+    /** The Express request. */
+    readonly req: Request;
+    /** The Express response. Once you write to it (a file, a stream), brisk sends nothing itself. */
+    readonly res: Response;
+    /** The caller's `x-request-id` when it is short and plain, otherwise a new UUID. Sent back in the response. */
+    readonly requestId: string;
+    /** The request's logger: every line carries `requestId`. */
+    readonly log: Logger;
+}
+/**
+ * A handler's context: the request's fields and the same lazy logger, plus middleware output and validated input.
+ * Every field is assigned in the constructor, so all handler contexts share one hidden class. Middleware outputs
+ * are written straight onto it; a middleware may return its own `log` (such as `log.child({ userId })`), which
+ * the setter accepts.
+ */
+export declare class HandlerContext implements RequestContext {
+    #private;
+    readonly req: Request;
+    readonly res: Response;
+    readonly requestId: string;
+    params: unknown;
+    query: unknown;
+    body: unknown;
+    headers: unknown;
+    constructor(base: RequestContext);
+    get log(): Logger;
+    set log(log: Logger);
+}
+export declare function createRequestContext(req: Request, res: Response, requestId: string, logger: Logger): RequestContext;
+/** The memo of middleware results for the request behind any context: the base one, a handler's, or a copy. */
+export declare function requestMemo(ctx: RequestContext): Map<object, unknown>;
+/**
+ * Returns a request's context, for code that only has the Express `req`, such as an Express handler in the
+ * app's `mount`.
+ *
+ * @throws When the request was not handled by an app made with `defineApp`.
+ *
+ * @example
+ * ```ts
+ * defineApp({
+ *   mount: {
+ *     "/events": (req, res) => {
+ *       getContext(req).log.info("stream opened");
+ *       res.type("text/event-stream").write("data: hello\n\n");
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function getContext(req: Request): RequestContext;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/http/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,iGAAiG;IACjG,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,+GAA+G;IAC/G,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAiCD;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,cAAc;;IACnD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IAIjB,YAAY,IAAI,EAAE,cAAc,EAS/B;IAED,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,EAElB;CACF;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,cAAc,CAIhB;AAED,+GAA+G;AAC/G,wBAAgB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAErE;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAEvD"}

package/dist/src/http/context.js

@@ -0,0 +1,96 @@
+const CONTEXT = Symbol("brisk.context");
+/**
+ * Fast to create: plain fields, with the request logger and the middleware memo created lazily, so a request
+ * that never logs or runs a middleware allocates neither.
+ */
+class Context {
+    req;
+    res;
+    requestId;
+    #logger;
+    #log;
+    #memo;
+    constructor(req, res, requestId, logger) {
+        this.req = req;
+        this.res = res;
+        this.requestId = requestId;
+        this.#logger = logger;
+    }
+    get log() {
+        return (this.#log ??= this.#logger.child({ requestId: this.requestId }));
+    }
+    /** Per-request results of middlewares, released with the request: no WeakMap entries for the GC to trace. */
+    static memo(ctx) {
+        return (ctx.#memo ??= new Map());
+    }
+}
+/**
+ * A handler's context: the request's fields and the same lazy logger, plus middleware output and validated input.
+ * Every field is assigned in the constructor, so all handler contexts share one hidden class. Middleware outputs
+ * are written straight onto it; a middleware may return its own `log` (such as `log.child({ userId })`), which
+ * the setter accepts.
+ */
+export class HandlerContext {
+    req;
+    res;
+    requestId;
+    params;
+    query;
+    body;
+    headers;
+    #base;
+    #log;
+    constructor(base) {
+        this.req = base.req;
+        this.res = base.res;
+        this.requestId = base.requestId;
+        this.params = undefined;
+        this.query = undefined;
+        this.body = undefined;
+        this.headers = undefined;
+        this.#base = base;
+    }
+    get log() {
+        return this.#log ?? this.#base.log;
+    }
+    set log(log) {
+        this.#log = log;
+    }
+}
+export function createRequestContext(req, res, requestId, logger) {
+    const ctx = new Context(req, res, requestId, logger);
+    Reflect.set(req, CONTEXT, ctx);
+    return ctx;
+}
+/** The memo of middleware results for the request behind any context: the base one, a handler's, or a copy. */
+export function requestMemo(ctx) {
+    return Context.memo(ctx instanceof Context ? ctx : contextOf(ctx.req));
+}
+function contextOf(req) {
+    const ctx = Reflect.get(req, CONTEXT);
+    if (ctx instanceof Context)
+        return ctx;
+    throw new Error("Request context missing: the request was not handled by an app made with defineApp()");
+}
+/**
+ * Returns a request's context, for code that only has the Express `req`, such as an Express handler in the
+ * app's `mount`.
+ *
+ * @throws When the request was not handled by an app made with `defineApp`.
+ *
+ * @example
+ * ```ts
+ * defineApp({
+ *   mount: {
+ *     "/events": (req, res) => {
+ *       getContext(req).log.info("stream opened");
+ *       res.type("text/event-stream").write("data: hello\n\n");
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function getContext(req) {
+    return contextOf(req);
+}
+//# sourceMappingURL=context.js.map

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

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

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

@@ -0,0 +1,195 @@
+import { Router, type Request, type RequestHandler } from "express";
+import type { z } from "zod";
+import type { Container, ProviderEntry } from "../di/container.ts";
+import { type RequestContext } from "./context.ts";
+import { type Middleware, type MiddlewareContext, type SecuritySchemes } from "./middleware.ts";
+import type { PathParams } from "./path-params.ts";
+import type { ControllerTypes, HttpMethod, Manifest, Route, RouteInput, RouteOutput, Routes } from "./routes.ts";
+type Schema = z.ZodType;
+type OptionalSchema = Schema | undefined;
+type Middlewares = readonly Middleware[];
+/** A route's success status: 2xx, or 3xx for redirects. Failures are thrown as errors, not returned. */
+export type SuccessStatus = 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 304 | 307 | 308;
+type Output<S, Fallback> = S extends Schema ? z.output<S> : Fallback;
+/** A handler's `ctx`: the request basics, every middleware's output, and the validated input. */
+export type RouteContext<Path extends string, P, Q, B, H, U extends Middlewares> = RequestContext & MiddlewareContext<U> & {
+    params: Output<P, PathParams<Path>>;
+    query: Output<Q, Record<string, unknown>>;
+    body: Output<B, unknown>;
+    headers: Output<H, Request["headers"]>;
+};
+/** With a `response` schema, a handler returns the schema's input; fields it does not list are stripped. */
+type Reply<R> = R extends Schema ? z.input<R> : unknown;
+type Handler<Path extends string, P, Q, B, H, U extends Middlewares, Returned> = (ctx: RouteContext<Path, P, Q, B, H, U>) => Returned | Promise<Returned>;
+/**
+ * A route's schemas and settings. Each schema is a Zod schema, and its validated value replaces the raw one on
+ * the handler's `ctx`.
+ *
+ * @example
+ * ```ts
+ * route.patch("/:id", {
+ *   params: z.object({ id: z.uuid() }),
+ *   body: UpdateUserBody,
+ *   response: UserResponse,
+ *   use: [requireRole("admin")],
+ * }, ({ params, body }) => users.update(params.id, body));
+ * ```
+ */
+export interface RouteOptions<P, Q, B, H, R, U extends Middlewares> {
+    params?: P;
+    query?: Q;
+    body?: B;
+    headers?: H;
+    /** The response's shape. The result is parsed through it, so fields it does not list never leak. */
+    response?: R;
+    /** Middlewares for this route only. They run after the controller's and the group's. */
+    use?: U;
+    /**
+     * The success status, which wins over `ctx.res.status()`. Default: 201 for POST, 200 otherwise, and 204 when
+     * the handler returns nothing.
+     */
+    status?: SuccessStatus;
+}
+/**
+ * Declares a route, as `(path, handler)` or `(path, options, handler)`, and returns it. Return it from the
+ * controller's setup under a name, and the typed client calls it by that name.
+ *
+ * Path params such as `:id` are typed on `ctx.params`. With a `response` schema, the handler must return the
+ * schema's input, and the client receives its output.
+ *
+ * @example
+ * ```ts
+ * get: route.get("/:id", { response: UserResponse }, ({ params }) => users.get(params.id)),
+ * ```
+ */
+export interface RouteMethod<Prefix extends string, MU extends Middlewares> {
+    <const Path extends string, Returned>(path: Path, handler: Handler<`${Prefix}${Path}`, undefined, undefined, undefined, undefined, MU, Returned>): Route<RouteInput<`${Prefix}${Path}`, undefined, undefined, undefined, undefined>, RouteOutput<undefined, Returned>>;
+    <const Path extends string, const U extends Middlewares = [], P extends OptionalSchema = undefined, Q extends OptionalSchema = undefined, B extends OptionalSchema = undefined, H extends OptionalSchema = undefined, R extends OptionalSchema = undefined, Returned extends Reply<R> = Reply<R>>(path: Path, options: RouteOptions<P, Q, B, H, R, U>, handler: Handler<`${Prefix}${Path}`, P, Q, B, H, [...MU, ...U], Returned>): Route<RouteInput<`${Prefix}${Path}`, P, Q, B, H>, RouteOutput<R, Returned>>;
+}
+/** Options for {@link RouteBuilder.group}. */
+export interface GroupOptions<U extends Middlewares> {
+    /** Middlewares for every route in the group. */
+    use?: U;
+}
+/**
+ * Nests routes under a sub-path, with extra middlewares when given: `(path, setup)` or `(path, options, setup)`.
+ * Returns what `setup` returns, so the group's routes nest under the group's name in the client.
+ *
+ * @example
+ * ```ts
+ * admin: route.group("/admin", { use: [requireRole("admin")] }, (admin) => ({
+ *   remove: admin.delete("/:id", ({ params }) => users.remove(params.id)),
+ * })),
+ * ```
+ */
+export interface GroupMethod<Prefix extends string, MU extends Middlewares> {
+    <const Path extends string, const R extends Routes | void>(path: Path, setup: (route: RouteBuilder<`${Prefix}${Path}`, MU>) => R): R;
+    <const Path extends string, const U extends Middlewares, const R extends Routes | void>(path: Path, options: GroupOptions<U>, setup: (route: RouteBuilder<`${Prefix}${Path}`, [...MU, ...U]>) => R): R;
+}
+/**
+ * The `route` object a controller's setup receives. Each method declares one route and returns it.
+ *
+ * @example
+ * ```ts
+ * defineController({ prefix: "/projects", use: [authenticate] }, (route) => ({
+ *   list: route.get("/", () => projects.list()),
+ *   members: route.group("/:projectId/members", { use: [requireRole("owner")] }, (members) => ({
+ *     add: members.post("/", { body: AddMember }, ({ params, body }) => projects.addMember(params.projectId, body)),
+ *   })),
+ * }));
+ * ```
+ */
+export interface RouteBuilder<Prefix extends string, MU extends Middlewares> {
+    get: RouteMethod<Prefix, MU>;
+    post: RouteMethod<Prefix, MU>;
+    put: RouteMethod<Prefix, MU>;
+    patch: RouteMethod<Prefix, MU>;
+    delete: RouteMethod<Prefix, MU>;
+    /** Nests routes under a sub-path, such as an admin-only section with its own middlewares. */
+    group: GroupMethod<Prefix, MU>;
+}
+/** Options for {@link defineController}. */
+export interface ControllerOptions<Prefix extends string, U extends Middlewares> {
+    /** The controller's path, under the app's `prefix`. */
+    prefix: Prefix;
+    /** Middlewares for every route; their outputs are typed on each handler's `ctx`. */
+    use?: U;
+    /**
+     * Providers this feature brings, such as the WebSocket gateway or cache invalidator behind its routes:
+     * created at startup with the app, so removing the controller removes them. A value the app or a test
+     * provides for the same token wins.
+     */
+    providers?: readonly ProviderEntry[];
+}
+/** A registered route, as listed in the startup log. */
+export interface RouteInfo {
+    method: HttpMethod;
+    path: string;
+}
+/** A registered route with what documentation needs: its schemas, success status and name, when it has one. */
+export interface Endpoint extends RouteInfo {
+    /** Dotted route name within its controller, such as `admin.remove`; `undefined` for unnamed routes. */
+    name: string | undefined;
+    schemas: Readonly<Partial<Record<"params" | "query" | "body" | "headers" | "response", z.ZodType>>>;
+    status: number | undefined;
+    /** The security schemes its middlewares enforce, merged; `undefined` for a public route. */
+    security: SecuritySchemes | undefined;
+}
+/** Where the app mounts a controller. */
+export interface MountTarget {
+    container: Container;
+    /** The app's one router; routes register full paths on it. */
+    router: Router;
+    /** The app prefix joined to the controller's. */
+    basePath: string;
+    /** The app's JSON body parser, which runs on brisk's own routes only. */
+    parseBody: RequestHandler;
+}
+/** What mounting a controller produced: every route it registered, and its named routes when it returned them. */
+export interface MountedController {
+    endpoints: Endpoint[];
+    manifest: Manifest | undefined;
+}
+/** A controller, as {@link defineController} returns it. Apps mount it; you only pass it to `defineApp`. */
+export interface Controller<R extends Routes | void = Routes | void> extends ControllerTypes<R> {
+    readonly prefix: string;
+    /** Providers the controller brings: created with the app, before the app's own providers. */
+    readonly providers: readonly ProviderEntry[];
+    /** Builds the controller inside the app's container and registers its routes. Called by the app. */
+    mount(target: MountTarget): MountedController;
+}
+/**
+ * Declares a feature's HTTP routes. `setup` runs once per app instance, inside its container, so it can
+ * `inject()` services. It declares routes and returns them by name; the names form the typed client, so
+ * `usersController` mounted as `users` gives `api.users.get(...)`.
+ *
+ * A handler's return value is the response: nothing sends 204, a `Readable` is streamed, a `Buffer` is sent
+ * as bytes, and anything else is JSON, parsed through `response` when given. Throw an error class to fail;
+ * never call `next()`.
+ *
+ * @example
+ * ```ts
+ * export const usersController = defineController({ prefix: "/users", use: [authenticate] }, (route) => {
+ *   const users = inject(UsersService);
+ *   return {
+ *     me: route.get("/me", ({ user }) => user),
+ *     get: route.get("/:id", { params: UserIdParams, response: UserResponse }, ({ params }) => users.get(params.id)),
+ *     create: route.post("/", { body: CreateUserBody, response: UserResponse }, ({ body }) => users.create(body)),
+ *   };
+ * });
+ * ```
+ */
+export declare function defineController<const Prefix extends string, const U extends Middlewares = [], const R extends Routes | void = void>(options: ControllerOptions<Prefix, U>, setup: (route: RouteBuilder<Prefix, U>) => R): Controller<R>;
+/**
+ * Answers requests no controller handled on a known path: `OPTIONS` gets 204, other methods 405, both with an
+ * `Allow` header that lists what every controller accepts there.
+ *
+ * The app mounts it twice. Before the controllers, for `OPTIONS` only, because an Express router would
+ * otherwise answer `OPTIONS` itself with just its own methods. After them, where only unmatched requests
+ * arrive. A request that matches a route never runs it.
+ */
+export declare function methodGuard(routes: readonly RouteInfo[]): Router;
+/** Joins URL segments into one normalized path: `("/api", "/users/", ":id")` gives `/api/users/:id`. */
+export declare function joinPath(...parts: readonly string[]): string;
+export {};
+//# sourceMappingURL=controller.d.ts.map