@raiyyan/brisk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,1418 @@
-# Temporary Holding Version
+# brisk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, typed, opinionated layer over Express 5 and Zod. You keep the Express you know: plain functions, plain classes, any Express middleware. brisk removes the wiring you write by hand in every Express app: request validation, response DTOs, typed request data, error responses, environment validation, dependency injection, lifecycle and graceful shutdown, and scaffolding.
+
+```ts
+import { defineApp, defineController, inject, NotFoundError, z } from "@raiyyan/brisk";
+
+const users = defineController({ prefix: "/users" }, (route) => {
+  const service = inject(UsersService);
+
+  return {
+    get: route.get("/:id", { params: z.object({ id: z.uuid() }), response: UserResponse }, ({ params }) => {
+      const user = service.find(params.id);
+      if (!user) throw new NotFoundError("User not found");
+      return user; // validated, typed, and stripped to UserResponse
+    }),
+  };
+});
+
+export const app = defineApp({ prefix: "/api", controllers: { users } });
+
+await app.listen(3000);
+```
+
+## Contents
+
+- [Why brisk](#why-brisk)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Project structure](#project-structure)
+- [Configuration](#configuration)
+- [Controllers and routes](#controllers-and-routes)
+- [Validation](#validation)
+- [Middleware](#middleware)
+- [Dependency injection](#dependency-injection)
+- [Lifecycle](#lifecycle)
+- [Errors](#errors)
+- [The request context](#the-request-context)
+- [Logging](#logging)
+- [Security defaults](#security-defaults)
+- [defineApp options](#defineapp-options)
+- [App reference](#app-reference)
+- [Typed client](#typed-client)
+- [OpenAPI](#openapi)
+- [Testing](#testing)
+- [CLI](#cli)
+- [Working with the ecosystem](#working-with-the-ecosystem)
+- [Production checklist](#production-checklist)
+- [Performance](#performance)
+- [AI coding agents](#ai-coding-agents)
+- [FAQ](#faq)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why brisk
+
+Express is easy to read and easy to start with, but every project re-implements the same plumbing: validation middleware, `try/catch` with `next(err)`, DTO mapping, `req.user` assignment, unvalidated `process.env`, and no agreed place for code. NestJS answers that with modules, decorators, provider arrays, guards, pipes and interceptors, which is a lot to learn and to fight.
+
+brisk sits in between:
+
+- **Express mental model.** A controller is a function that declares routes. Middlewares are functions. Express is always reachable.
+- **Zod first.** Schemas validate and type `params`, `query`, `body` and `headers`, and response schemas strip what clients must not see.
+- **Typed middleware output.** A middleware that returns `{ user }` gives every route that uses it a typed `ctx.user`.
+- **Dependency injection without decorators.** `readonly #repo = inject(UsersRepository)` in a class field. Services and repositories are plain classes.
+- **Just throw.** Error classes carry status, code and headers, and every error reaches the client in one response shape.
+- **Typed client and OpenAPI from the same routes.** Named routes become `api.users.get(...)` in tests and frontends, and an OpenAPI 3.1 document.
+- **Production lifecycle.** Init, ready, drain and shutdown hooks on provider classes, graceful shutdown, crash handling.
+- **No build step in development.** Node runs your TypeScript directly.
+
+Six ideas, nothing else:
+
+| Idea                     | You write                                   | You get                                                             |
+| ------------------------ | ------------------------------------------- | ------------------------------------------------------------------- |
+| `defineEnv`              | a Zod shape                                 | typed, frozen config; the app refuses to boot with a bad `.env`     |
+| `defineController`       | routes with Zod schemas                     | validated, typed `params` `query` `body` `headers`; response DTOs   |
+| plain classes            | services and repositories                   | business logic with no HTTP in it                                   |
+| `inject` / `defineToken` | `readonly #repo = inject(UsersRepository)`  | singletons, swappable in tests, no decorators or constructor wiring |
+| `defineMiddleware`       | a function returning `{ user }`             | `ctx.user`, typed, in every route that uses it                      |
+| error classes            | `throw new NotFoundError("User not found")` | status, code, headers and one response shape; no try/catch          |
+
+## Requirements
+
+- Node.js 24 or later.
+- npm or pnpm (any package manager works).
+- TypeScript 5.8 or later (including 7) with `erasableSyntaxOnly`, so Node can run your `.ts` files directly.
+- ES modules (`"type": "module"`).
+
+## Installation
+
+```bash
+npm install @raiyyan/brisk
+npm install --save-dev typescript @types/node vitest
+```
+
+```bash
+pnpm add @raiyyan/brisk
+pnpm add --save-dev typescript @types/node vitest
+```
+
+Zod, Express and pino come with brisk. Import Zod from brisk (`import { z } from "@raiyyan/brisk"`) so your schemas and brisk use the same Zod. If your own code imports Express (`express.static`, `express.raw`, the `Request` and `Response` types), add it yourself: `pnpm add express` and `pnpm add -D @types/express` (pnpm does not let you import a dependency's dependencies). For colored development logs also install the optional `pino-pretty`.
+
+## Quick start
+
+In an empty folder, with npm:
+
+```bash
+npm init -y
+npm install @raiyyan/brisk
+npm install --save-dev typescript @types/node vitest
+npx brisk init
+cp .env.example .env
+npx brisk g feature products
+npx tsc --noEmit
+npx vitest run
+npm run dev
+```
+
+With pnpm:
+
+```bash
+pnpm init
+pnpm add @raiyyan/brisk
+pnpm add --save-dev typescript @types/node vitest
+pnpm exec brisk init
+cp .env.example .env
+pnpm brisk g feature products
+pnpm typecheck
+pnpm test
+pnpm dev
+```
+
+The server listens on port 3000:
+
+```bash
+curl -X POST localhost:3000/api/products -H 'content-type: application/json' -d '{"name":"Desk"}'
+curl localhost:3000/api/products
+curl -X POST localhost:3000/api/products -H 'content-type: application/json' -d '{"name":""}'   # 400 with field issues
+```
+
+`brisk init` asks about a database, auth, Docker, CI and web extras (or takes [flags](#brisk-init)), then installs the packages it needs. It never overwrites existing files, so it is safe in an existing project: it only adds missing files, `"type": "module"` and missing scripts.
+
+### Adding brisk to an existing Express project
+
+Move your existing Express setup into `configureExpress`. Routers, middlewares and routes keep working unchanged, and new features are written as brisk controllers next to them:
+
+```ts
+export const app = defineApp({
+  controllers,
+  configureExpress: (expressApp) => {
+    expressApp.use(express.json()); // your legacy routes read req.body before brisk parses JSON
+    expressApp.use(legacyRouter); // your existing express.Router()
+  },
+});
+```
+
+Then migrate route by route: write the new route in a controller, delete the old one.
+
+## Project structure
+
+`brisk init` and `brisk g feature` create this layout:
+
+```
+src/
+  env.ts                        defineEnv: typed configuration
+  app.ts                        export const app = defineApp({ prefix: "/api", ... }); export type Api = typeof app
+  main.ts                       await app.listen(env.PORT)
+  middlewares/<name>.ts         defineMiddleware (brisk g middleware)
+  features/
+    index.ts                    export const controllers = { products: productsController }  (keep the @brisk markers)
+    products/
+      products.schema.ts        Zod schemas: what clients send and may see
+      products.repository.ts    data access only
+      products.service.ts       business rules; throws error classes
+      products.controller.ts    defineController: HTTP only, delegates to the service
+test/
+  products.test.ts              HTTP tests with createTestClient
+.env.example
+.gitignore
+tsconfig.json                   lets Node run .ts directly
+vitest.config.ts                test environment variables
+AGENTS.md, CLAUDE.md            guide for AI coding agents (brisk agents)
+```
+
+The options of `brisk init` add more (a database provider, auth, Docker, CI); see [CLI](#cli).
+
+`src/app.ts` declares the app and `src/main.ts` starts it. Declaring runs nothing, so tests, `brisk client` and `brisk openapi` import the same `app` without opening a port or a database:
+
+```ts
+// src/app.ts
+import { createLogger, defineApp } from "@raiyyan/brisk";
+import { env } from "./env.ts";
+import { controllers } from "./features/index.ts";
+
+export const app = defineApp({
+  prefix: "/api",
+  controllers,
+  logger: createLogger({ level: env.NODE_ENV === "test" ? "silent" : env.LOG_LEVEL }),
+  errors: { exposeInternal: env.NODE_ENV === "development" },
+});
+
+/** The API's type, for a frontend's typed client. */
+export type Api = typeof app;
+```
+
+```ts
+// src/main.ts
+import { app } from "./app.ts";
+import { env } from "./env.ts";
+
+await app.listen(env.PORT);
+```
+
+Each layer of a feature has one job:
+
+- **schema**: Zod schemas for request bodies, params, queries and responses.
+- **repository**: reads and writes data. No HTTP, no business rules.
+- **service**: business rules. Takes and returns plain values, throws error classes (`NotFoundError`, `ConflictError`, ...). Knows nothing about Express.
+- **controller**: maps HTTP to service calls. Reads top to bottom.
+
+```ts
+// products.schema.ts
+import { z } from "@raiyyan/brisk";
+
+export const CreateProductBody = z.object({ name: z.string().trim().min(1) });
+export const ProductIdParams = z.object({ id: z.uuid() });
+export const ProductResponse = z.object({ id: z.string(), name: z.string() });
+export type CreateProductBody = z.infer<typeof CreateProductBody>;
+```
+
+```ts
+// products.repository.ts
+export interface Product {
+  id: string;
+  name: string;
+}
+
+export class ProductsRepository {
+  readonly #rows = new Map<string, Product>();
+
+  findById(id: string): Product | undefined {
+    return this.#rows.get(id);
+  }
+
+  save(row: Product): Product {
+    this.#rows.set(row.id, row);
+    return row;
+  }
+}
+```
+
+```ts
+// products.service.ts
+import { randomUUID } from "node:crypto";
+import { inject, NotFoundError } from "@raiyyan/brisk";
+import { ProductsRepository, type Product } from "./products.repository.ts";
+import type { CreateProductBody } from "./products.schema.ts";
+
+export class ProductsService {
+  readonly #repository = inject(ProductsRepository);
+
+  get(id: string): Product {
+    const row = this.#repository.findById(id);
+    if (!row) throw new NotFoundError("Product not found");
+    return row;
+  }
+
+  create(input: CreateProductBody): Product {
+    return this.#repository.save({ id: randomUUID(), ...input });
+  }
+}
+```
+
+```ts
+// products.controller.ts
+import { defineController, inject } from "@raiyyan/brisk";
+import { CreateProductBody, ProductIdParams, ProductResponse } from "./products.schema.ts";
+import { ProductsService } from "./products.service.ts";
+
+export const productsController = defineController({ prefix: "/products" }, (route) => {
+  const products = inject(ProductsService);
+
+  return {
+    get: route.get("/:id", { params: ProductIdParams, response: ProductResponse }, ({ params }) =>
+      products.get(params.id),
+    ),
+    create: route.post("/", { body: CreateProductBody, response: ProductResponse }, ({ body }) =>
+      products.create(body),
+    ),
+  };
+});
+```
+
+## Configuration
+
+```ts
+// src/env.ts
+import { defineEnv, z } from "@raiyyan/brisk";
+
+export const env = defineEnv({
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+  PORT: z.coerce.number().int().positive().default(3000),
+  DATABASE_URL: z.url(),
+  API_TOKEN: z.string().min(16),
+});
+
+env.PORT; // number
+```
+
+`defineEnv(shape, options?)`:
+
+- Loads `.env` into `process.env` when the file exists, then validates `process.env` against the shape.
+- Returns a frozen, fully typed object.
+- On failure it prints every invalid variable and exits with code 1, so the app never starts half-configured. Under `NODE_ENV=test` it throws instead.
+- Environment values are strings: use `z.coerce.number()`, `z.stringbool()` or `z.enum([...])`. Never `z.coerce.boolean()`: it calls `Boolean(value)`, so `FEATURE_X=false` becomes `true`. `z.stringbool()` reads `true/false`, `1/0`, `yes/no` and `on/off`, and rejects anything else.
+
+| Option   | Type                                  | Default  | Description                                                   |
+| -------- | ------------------------------------- | -------- | ------------------------------------------------------------- |
+| `file`   | `string`                              | `".env"` | Dotenv file to load when present                              |
+| `source` | `Record<string, string \| undefined>` | none     | Validate this object instead of `process.env`; failures throw |
+
+## Controllers and routes
+
+```ts
+import { defineController, inject } from "@raiyyan/brisk";
+
+export const ordersController = defineController({ prefix: "/orders", use: [authenticate] }, (route) => {
+  const orders = inject(OrdersService);
+
+  return {
+    list: route.get("/", { query: ListOrdersQuery, response: OrderResponse.array() }, ({ query, user }) =>
+      orders.list(user.id, query),
+    ),
+    get: route.get("/:id", ({ params }) => orders.get(params.id)), // params typed as { id: string }
+    create: route.post("/", { body: CreateOrderBody, response: OrderResponse }, ({ body, user }) =>
+      orders.create(user.id, body),
+    ),
+    admin: route.group("/admin", { use: [requireRole("admin")] }, (admin) => ({
+      remove: admin.delete("/:id", ({ params }) => orders.remove(params.id)),
+    })),
+  };
+});
+```
+
+`defineController(options, setup)`:
+
+| Option   | Type           | Description                                                                |
+| -------- | -------------- | -------------------------------------------------------------------------- |
+| `prefix` | `string`       | Mount path, joined to the app's `prefix`                                   |
+| `use`    | `Middleware[]` | Middlewares for every route; their outputs are typed on each handler's ctx |
+
+`setup` runs once per app instance, when the instance is built (`listen`, `start`, `create` or `createTestClient`), and can call `inject()`. It returns the controller's routes as an object of names. The names are how the [typed client](#typed-client) calls the routes (`api.orders.create(...)`, `api.orders.admin.remove(...)`) and become OpenAPI operation ids (`orders.create`).
+
+- Route methods (`route.get`, `route.post`, `route.put`, `route.patch`, `route.delete`) take `(path, handler)` or `(path, options, handler)` and return the route.
+- `route.group(path, setup)` or `route.group(path, { use }, setup)` nests routes under a sub-path with extra middlewares, and returns what its `setup` returns, so a group's routes nest under the group's name. Groups can nest.
+- When `setup` returns an object, it must include every route it declares; a missing one is an error naming the route, thrown when an instance is built.
+- A `setup` that returns nothing still serves its routes, but the controller is absent from the typed client and its routes have no operation id.
+
+| Route option | Type           | Description                                                                                                              |
+| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `params`     | Zod schema     | Validates path params; the parsed value is `ctx.params`                                                                  |
+| `query`      | Zod schema     | Validates the query string; `ctx.query`                                                                                  |
+| `body`       | Zod schema     | Validates the request body; `ctx.body`                                                                                   |
+| `headers`    | Zod schema     | Validates request headers (lower-case names); `ctx.headers`                                                              |
+| `response`   | Zod schema     | The handler's result is parsed through it: its return type is checked and unlisted fields are stripped                   |
+| `use`        | `Middleware[]` | Route middlewares, run after the controller's and the group's                                                            |
+| `status`     | 2xx or 3xx     | Success status; anything else is a type error, and an error when an instance is built. Throw an error class for failures |
+
+Without a `params` schema, path params are typed from the full path, controller prefix and groups included:
+
+| Path                                    | `ctx.params`                    |
+| --------------------------------------- | ------------------------------- |
+| `"/members/:id"` under `"/orgs/:orgId"` | `{ orgId: string; id: string }` |
+| `"/files/*path"`                        | `{ path: string[] }`            |
+| `"/posts{/:slug}"`                      | `{ slug?: string }`             |
+
+Express matches routes in the order they are declared, across all controllers in the order they are listed. Declare wildcard and optional-segment routes after the more specific routes they would otherwise catch.
+
+### What a handler returns
+
+The return value is the response:
+
+| Return value              | Response                                                         |
+| ------------------------- | ---------------------------------------------------------------- |
+| `undefined` (or nothing)  | `204 No Content` (or `status`)                                   |
+| a Node `Readable`         | streamed to the client                                           |
+| a `Buffer` / `Uint8Array` | sent as bytes (`application/octet-stream` unless you set a type) |
+| anything else             | JSON, parsed through `response` when set                         |
+
+Success status defaults to `201` for POST and `200` otherwise; `ctx.res.status(code)` in the handler overrides the default (for 202, or 200 vs 201 on an upsert), and the route's `status` option overrides both. Handlers can also write to `ctx.res` directly (files, SSE, redirects); once the response has started, brisk sends nothing more.
+
+If a stream fails, or a handler throws after it started writing, brisk destroys the connection instead of ending the response, so the client sees a failed download rather than a truncated file that looks complete. A client that disconnects mid-stream is not a server error: it is logged on the request line with `aborted: true`.
+
+```ts
+import { createReadStream } from "node:fs";
+
+return {
+  report: route.get("/report.csv", ({ res }) => {
+    res.type("text/csv").attachment("report.csv");
+    return createReadStream("report.csv");
+  }),
+  logo: route.get("/logo", ({ res }) => res.sendFile("/srv/assets/logo.png")),
+};
+```
+
+Handlers and setup may be sync or async. A thrown error, sync or async, becomes the error response; never call `next()`.
+
+## Validation
+
+Every input schema is a Zod schema. Invalid input stops the request before your handler runs and produces a `400`:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_FAILED",
+    "message": "Invalid request body",
+    "details": {
+      "location": "body",
+      "issues": [{ "path": "email", "message": "Invalid email address", "code": "invalid_format" }]
+    },
+    "requestId": "3f0c9a1e-..."
+  }
+}
+```
+
+- `location` is `params`, `query`, `body` or `headers`. `path` is a dot path (`items.0.qty`), ready to map onto form fields.
+- Path params and query values arrive as strings: use `z.coerce.number()`, `z.stringbool()` (not `z.coerce.boolean()`, which turns `"false"` into `true`) or `z.enum([...])`, and `.default(...)` for optional query values.
+- A repeated query key (`?tag=a&tag=b`) arrives as an array, a single one as a string. Accept both with `z.union([z.string(), z.array(z.string())]).transform((v) => [v].flat())`.
+- Async refinements work (`z.string().refine(async (email) => !(await users.exists(email)))`); schemas without them stay on the synchronous fast path.
+- JSON bodies are parsed for `application/json` and every `application/*+json` type, such as `application/merge-patch+json`.
+- Unknown keys in a body are stripped, so extra fields never reach your code. The same applies to `params`: a `params` schema on a route under `/:orgId` must list `orgId` too, or it is stripped.
+- `UpdateBody = CreateBody.partial()` keeps the create schema's `.default(...)` values, so a PATCH that omits a field resets it to the default. Build update schemas without defaults.
+- For a dynamic success status, call `ctx.res.status(202)` in the handler. A route's `status` option fixes the status and wins over it.
+- A `ZodError` thrown anywhere in your code (for example a service calling `schema.parse(...)`) becomes the same 400 with `location: "input"`.
+- A handler result that does not match its `response` schema is a server bug and becomes a 500, never a 400.
+
+```ts
+export const ListOrdersQuery = z.object({
+  status: z.enum(["open", "paid"]).optional(),
+  page: z.coerce.number().int().min(1).default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+```
+
+## Middleware
+
+```ts
+import { defineMiddleware, ForbiddenError, UnauthorizedError } from "@raiyyan/brisk";
+
+export const authenticate = defineMiddleware(async ({ req }) => {
+  const user = await verifyToken(req.get("authorization"));
+  if (!user) throw new UnauthorizedError("Invalid token", { challenge: "Bearer" });
+  return { user };
+}, "authenticate");
+
+export const requireRole = (role: "admin" | "member") =>
+  defineMiddleware(async (ctx) => {
+    const { user } = await authenticate.run(ctx);
+    if (user.role !== role) throw new ForbiddenError(`Requires role: ${role}`);
+    return { user };
+  });
+```
+
+`defineMiddleware(fn, name?)`:
+
+- **Return an object** to add typed fields to the handler's ctx (`return { user }` gives `ctx.user`).
+- **Return nothing** for a pure check.
+- **Throw an error class** to stop the request.
+- **Each middleware runs at most once per request.** `other.run(ctx)` reuses another middleware's result, so `requireRole` above does not authenticate twice. A handler can call `run(ctx)` too.
+- **Reserved names:** a middleware may not return `req`, `res`, `requestId`, `params`, `query`, `body` or `headers`; the compiler rejects them, because validated input would silently replace them. Returning `log` (such as `log.child({ userId })`) replaces the request logger for the rest of the request.
+- **Sync or async**, and `inject()` works inside.
+- Order: controller `use`, then group `use`, then route `use`, then validation. Unauthenticated requests are rejected before their input is validated. The JSON body is parsed earlier, for every request (up to `http.bodyLimit`), so malformed JSON gets 400 even without credentials.
+
+Plain Express middleware (`cors()`, `helmet()`, rate limiters, multer) goes in [`configureExpress`](#working-with-the-ecosystem).
+
+## Dependency injection
+
+```ts
+import { defineApp, defineToken, inject, injectLazy, provide } from "@raiyyan/brisk";
+
+export const Clock = defineToken<() => Date>("Clock", () => () => new Date());
+
+export class UsersRepository {
+  readonly #db = inject(Database);
+}
+
+export class UsersService {
+  readonly #users = inject(UsersRepository);
+  readonly #mailer = injectLazy(Mailer); // created on first call: this.#mailer().send(...)
+  readonly #now = inject(Clock);
+}
+
+export const app = defineApp({ controllers, providers: [provide(Clock, () => new Date("2026-01-01"))] });
+```
+
+- **A class is its own token.** It needs a no-argument constructor, takes its dependencies with `inject()` in field initializers, and is created once per app, on first use.
+- **`defineToken<T>(name, factory?)`** names anything that is not a class: config, clients, functions, interface implementations. Without a factory it must be given a value with `provide`.
+- **`provide(token, value)`** fixes a value for a token in `defineApp({ providers })`, in the `providers` of `listen`, `start`, `create` or `createTestClient` (which replace the app's own, for fakes in tests), or in `new Container([...])`. Later entries win.
+- **Classes listed in `providers`** are created at boot even when nothing injects them, so WebSocket gateways, consumers and jobs get their lifecycle hooks. Listing a class is not required to make it injectable (every class is); it means "start this at boot".
+- **`injectLazy(token)`** returns `() => T` and creates the dependency on first call: for heavy clients, or to break a circular dependency.
+- **Where `inject()` works:** wherever the app runs your code: class fields, token factories, controller setup, every request (brisk routes, middlewares, and everything in `configureExpress`, so GraphQL resolvers and tRPC procedures too), lifecycle hooks, and timers and promises started from any of those.
+- **Where it does not:** callbacks a library fires from its own events, outside any request (a gRPC handler, a queue client's message callback, a `ws` message listener). Resolve the dependency in a class field and use the field there. Outside the app entirely (a script, a REPL), use the instance's container: `instance.container.get(...)`. brisk never guesses which app you mean, so code behaves the same with one app in the process or several.
+- **`HttpServer`** exists only once the instance listens: inject it in `onReady`. Injecting it in a class field or `onInit` throws.
+- **Circular dependencies** are reported as `A -> B -> A`. Break them with `injectLazy`.
+- **Unit tests without HTTP:** build a container and call `get`. The `Logger` token has a silent default, so services that inject it need no logger provider there:
+
+  ```ts
+  import { Container, provide } from "@raiyyan/brisk";
+
+  const container = new Container([provide(Clock, () => new Date("2030-01-01"))]);
+  const users = container.get(UsersService);
+  ```
+
+## Lifecycle
+
+A provider class joins the lifecycle by implementing any of these interfaces. Each method may be sync or async, and `inject()` works inside.
+
+| Interface    | Method       | When                                                                                                     |
+| ------------ | ------------ | -------------------------------------------------------------------------------------------------------- |
+| `OnInit`     | `onInit`     | Before the server listens, dependencies first: connect databases, open pools                             |
+| `OnReady`    | `onReady`    | Once the server accepts requests: attach WebSockets (inject `HttpServer` here), start jobs and consumers |
+| `OnDrain`    | `onDrain`    | The moment shutdown starts: close WebSockets and SSE, stop consumers and timers                          |
+| `OnShutdown` | `onShutdown` | After the last in-flight request, dependents first: release clients and pools                            |
+
+```ts
+import { inject, Logger, type OnInit, type OnShutdown } from "@raiyyan/brisk";
+
+export class Database implements OnInit, OnShutdown {
+  readonly #log = inject(Logger);
+  #pool: Pool | undefined;
+
+  async onInit() {
+    this.#pool = await connect(env.DATABASE_URL);
+    this.#log.info("database connected");
+  }
+
+  async onShutdown() {
+    await this.#pool?.end();
+  }
+}
+```
+
+Startup and shutdown work always lives in a provider class. `defineApp({ hooks })` takes only per-request hooks: `onRequest(ctx)`, `onResponse(ctx, { status, durationMs, aborted })` and `onError(error, ctx)`. `onResponse` runs once for every request, including ones the client abandoned (`aborted: true`). `onError` sees client errors too; an error tracker usually wants `if (error instanceof HttpError && error.status < 500) return;`.
+
+```
+boot      providers' onInit (dependencies first) -> listen -> providers' onReady
+request   configureExpress -> JSON body -> hooks.onRequest -> middlewares -> validation -> handler
+          -> response -> hooks.onResponse            (any error -> hooks.onError -> error response)
+shutdown  SIGINT/SIGTERM -> stop accepting connections -> providers' onDrain (reverse)
+          -> in-flight requests finish, with Connection: close (sockets still open after shutdownTimeoutMs are destroyed)
+          -> providers' onShutdown (reverse) -> exit 0
+          (a different second signal is ignored; the same signal again exits 1 at once;
+           still running shutdownTimeoutMs + 10 s after the signal -> exit 1)
+crash     unhandled rejection or uncaught exception -> logged as fatal -> shutdown -> exit 1
+```
+
+A failing `onDrain` or `onShutdown` is logged and shutdown continues. `app.start()` runs the same lifecycle without an HTTP server.
+
+Each `listen`, `start` or `create` builds a new, independent instance with its own container, so one app can run in many tests at once. If startup fails (an `onInit` throws, the port is taken), brisk runs the drain and shutdown hooks for what already started, then rethrows, so pools and clients are released.
+
+## Errors
+
+Throw from anywhere: handlers, services, repositories, middlewares. Never catch an error just to build a response.
+
+```ts
+throw new NotFoundError("User not found");
+throw new ConflictError("Email already registered", { code: "EMAIL_TAKEN", details: { email } });
+throw new TooManyRequestsError("Slow down", { retryAfter: 30 }); // sends Retry-After: 30
+throw new UnauthorizedError("Login required", { challenge: "Bearer" }); // sends WWW-Authenticate
+throw new BadGatewayError("Payment provider failed", { cause: error }); // cause is logged, never sent
+```
+
+| Class                       | Status | Notes                                                            |
+| --------------------------- | ------ | ---------------------------------------------------------------- |
+| `BadRequestError`           | 400    |                                                                  |
+| `ValidationError`           | 400    | `(location, issues)`; `ValidationError.fromZod(error, location)` |
+| `UnauthorizedError`         | 401    | `challenge` option sends `WWW-Authenticate`                      |
+| `ForbiddenError`            | 403    |                                                                  |
+| `NotFoundError`             | 404    |                                                                  |
+| `MethodNotAllowedError`     | 405    | `(allowed, message?, options?)` sends `Allow`                    |
+| `NotAcceptableError`        | 406    |                                                                  |
+| `RequestTimeoutError`       | 408    |                                                                  |
+| `ConflictError`             | 409    |                                                                  |
+| `GoneError`                 | 410    |                                                                  |
+| `PreconditionFailedError`   | 412    | a stale `If-Match` in optimistic concurrency                     |
+| `PayloadTooLargeError`      | 413    |                                                                  |
+| `UnsupportedMediaTypeError` | 415    |                                                                  |
+| `UnprocessableEntityError`  | 422    |                                                                  |
+| `TooManyRequestsError`      | 429    | `retryAfter` option (seconds) sends `Retry-After`                |
+| `InternalServerError`       | 500    | its message is sent: keep it generic, put details in `cause`     |
+| `NotImplementedError`       | 501    |                                                                  |
+| `BadGatewayError`           | 502    | an upstream service answered badly                               |
+| `ServiceUnavailableError`   | 503    | `retryAfter` option sends `Retry-After`                          |
+| `GatewayTimeoutError`       | 504    | an upstream service did not answer in time                       |
+| `HttpError`                 | any    | the base class: `new HttpError(status, message, options)`        |
+
+Every class takes `(message?, options?)`:
+
+| Option    | Description                                                           |
+| --------- | --------------------------------------------------------------------- |
+| `code`    | Machine-readable code. Default: derived from the status (`NOT_FOUND`) |
+| `details` | Extra data sent to the client as `error.details`                      |
+| `cause`   | The underlying error: logged with its stack, never sent               |
+| `headers` | Response headers sent with the error                                  |
+
+Every error response has one shape: `{ "error": { "code", "message", "details", "requestId" } }`.
+
+### Domain errors
+
+```ts
+import { ConflictError, ValidationError } from "@raiyyan/brisk";
+
+export class EmailTakenError extends ConflictError {
+  constructor(email: string) {
+    super("Email already registered", { code: "EMAIL_TAKEN", details: { email } });
+  }
+}
+
+throw new ValidationError("body", [{ path: "slug", message: "Already used", code: "taken" }]);
+```
+
+### Handled automatically
+
+| Situation                                                                 | Response                                                                          |
+| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Invalid params, query, body or headers                                    | 400 `VALIDATION_FAILED` with field issues                                         |
+| `ZodError` thrown in your code                                            | 400 `VALIDATION_FAILED`, `location: "input"`                                      |
+| Malformed JSON                                                            | 400 `INVALID_JSON`                                                                |
+| Body over `http.bodyLimit`                                                | 413 `PAYLOAD_TOO_LARGE`                                                           |
+| Unsupported body charset or encoding                                      | 415 `UNSUPPORTED_MEDIA_TYPE`                                                      |
+| A body in a format nothing parsed, on a route with a `body` schema        | 415 `UNSUPPORTED_MEDIA_TYPE` (after the route's middlewares, so auth fails first) |
+| An Express middleware error following `http-errors` (`status` + `expose`) | that status; the message only when `expose` is true                               |
+| Known path, wrong method (across all controllers)                         | 405 with `Allow`; `OPTIONS` answers 204 with `Allow`                              |
+| Unknown path                                                              | 404 `ROUTE_NOT_FOUND`                                                             |
+| Handler result breaks its `response` schema                               | 500: a server bug                                                                 |
+| Error after the response started (a failing stream)                       | connection destroyed, so the client never mistakes it for a complete body         |
+| Anything else thrown                                                      | 500 `INTERNAL_SERVER_ERROR` with a generic message; full error logged             |
+| Unhandled rejection or uncaught exception                                 | logged as fatal, graceful shutdown, exit 1                                        |
+
+5xx errors are logged at `error` with stack and cause; 4xx at `debug` (the request log line already carries the status).
+
+### Error mappers and formatters
+
+```ts
+export const app = defineApp({
+  controllers,
+  errors: {
+    // Translate library errors in one place instead of try/catch in services. The first match wins.
+    mappers: [
+      (error) =>
+        error instanceof DatabaseError && error.code === "23505"
+          ? new ConflictError("Already exists")
+          : undefined,
+    ],
+    // Change the error body, for example to RFC 9457 problem details.
+    format: (error, ctx) => ({
+      type: `https://errors.example.com/${error.code}`,
+      title: error.message,
+      status: error.status,
+      instance: ctx.req.originalUrl,
+    }),
+  },
+  hooks: { onError: (error, ctx) => reportToTracker(error, ctx.requestId) },
+});
+```
+
+`defaultErrorFormatter` is exported for formatters that only add fields. A mapper or `onError` hook that throws is logged and never breaks the response.
+
+ORMs often wrap the driver's error (Drizzle keeps it in `cause`), so a mapper should walk the `cause` chain. `brisk init --db sqlite` or `--db postgres` generates one in `src/database/errors.ts` that turns a unique violation into 409 `ALREADY_EXISTS`:
+
+```ts
+export const uniqueViolation: ErrorMapper = (error) => {
+  for (let current: unknown = error; current instanceof Error; current = current.cause) {
+    if ("code" in current && current.code === "23505") {
+      return new ConflictError("Already exists", { code: "ALREADY_EXISTS", cause: error });
+    }
+  }
+  return undefined;
+};
+```
+
+## The request context
+
+Every handler and middleware receives a context:
+
+| Field       | Description                                                                               |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| `req`       | The Express request                                                                       |
+| `res`       | The Express response; write to it directly to stream or send files                        |
+| `requestId` | The caller's `x-request-id` when it is safe, otherwise a new UUID; echoed in the response |
+| `log`       | A logger for this request: every line carries the request id                              |
+
+Handlers also get every middleware's output and the validated `params`, `query`, `body` and `headers`. Destructure what you need (`({ params, user, log }) => ...`) rather than copying the whole context.
+
+Code that only has the Express `req` (plain middlewares and routes in `configureExpress`) uses `getContext(req)`:
+
+```ts
+import { getContext } from "@raiyyan/brisk";
+
+app.get("/events", (req, res) => {
+  getContext(req).log.info("stream opened");
+});
+```
+
+## Logging
+
+```ts
+import { createLogger, defineApp } from "@raiyyan/brisk";
+
+export const app = defineApp({
+  controllers,
+  logger: createLogger({ level: env.LOG_LEVEL, pretty: env.NODE_ENV === "development" }),
+});
+```
+
+- `createLogger({ level?, pretty? })` returns a [pino](https://getpino.io) logger. `level` defaults to `"info"`. `pretty: true` needs the optional `pino-pretty` package; use JSON lines in production.
+- Pass any pino logger as `logger`.
+- The app logger is injectable: `readonly #log = inject(Logger)`.
+- `ctx.log` carries the request id on every line.
+- Each request is logged once at `info` as `request` with `method`, `url`, `status` and `durationMs` (plus `aborted: true` when the client left early). Set the level to `warn` or higher to turn it off.
+- `url` is the path without the query string: query strings carry reset tokens, OAuth codes and API keys often enough that brisk never logs them. Log what you need from `ctx.req.query` in `onResponse`.
+
+## Security defaults
+
+- **Security headers** on every response: `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'`. No `x-powered-by`.
+- **Override them** with `http.securityHeaders`: `false` turns them off; an object overrides individual headers, and `false` as a value removes one:
+
+  ```ts
+  export const app = defineApp({
+    controllers,
+    http: { securityHeaders: { "content-security-policy": "default-src 'self'", "x-frame-options": false } },
+  });
+  ```
+
+- **Request ids** from callers are accepted only when short and plain (letters, digits, `_ . : -`, up to 128 characters), so they cannot forge log lines.
+- **Body limit** of `1mb` for JSON (`http.bodyLimit`).
+- **Flat query strings:** query values are strings or arrays of strings, never nested objects. If you need nested query objects, enable them with `configureExpress: (expressApp) => expressApp.set("query parser", "extended")`.
+- **No mass assignment:** unknown body fields are stripped by your schemas.
+- **`trust proxy`** stays off unless you set `http.trustProxy`. Set it only behind a proxy you control, otherwise clients can spoof `req.ip`.
+- **Internal error messages** never reach clients unless `errors.exposeInternal` is on (development only).
+- CORS and rate limiting are plain Express middlewares in `configureExpress`.
+
+## defineApp options
+
+`defineApp(options)` declares the app. Every option is optional.
+
+| Option             | Type                     | Default          | Description                                                                     |
+| ------------------ | ------------------------ | ---------------- | ------------------------------------------------------------------------------- |
+| `prefix`           | `string`                 | `"/"`            | Path every controller is mounted under, such as `/api`                          |
+| `controllers`      | `{ [name]: Controller }` | `{}`             | Controllers by name; the names are the typed client's top level                 |
+| `providers`        | `(Provider \| Class)[]`  | `[]`             | `provide(token, value)` entries, and classes to create at startup               |
+| `logger`           | `Logger`                 | `createLogger()` | The app logger; injectable as `Logger`                                          |
+| `configureExpress` | `(expressApp) => void`   | none             | Full Express access, before JSON parsing and before brisk's routes              |
+| `hooks`            | `AppHooks`               | `{}`             | `onRequest`, `onResponse`, `onError` (startup and shutdown belong in providers) |
+| `openapi`          | `OpenApiOptions`         | not served       | Serve an [OpenAPI](#openapi) document                                           |
+| `errors`           | `ErrorOptions`           | `{}`             | How errors become responses (below)                                             |
+| `http`             | `HttpOptions`            | `{}`             | HTTP-level settings (below)                                                     |
+
+`errors`:
+
+| Option           | Type             | Default                 | Description                                                  |
+| ---------------- | ---------------- | ----------------------- | ------------------------------------------------------------ |
+| `mappers`        | `ErrorMapper[]`  | `[]`                    | `(error) => HttpError \| undefined`; the first match wins    |
+| `format`         | `ErrorFormatter` | `defaultErrorFormatter` | `(error, ctx) => body` for error responses                   |
+| `exposeInternal` | `boolean`        | `false`                 | Send the real message of unexpected errors. Development only |
+
+`http`:
+
+| Option              | Type                                         | Default     | Description                                                                          |
+| ------------------- | -------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
+| `bodyLimit`         | `string`                                     | `"1mb"`     | JSON body size limit                                                                 |
+| `trustProxy`        | `boolean \| number \| string`                | not set     | Express `trust proxy` setting; only behind a proxy you control                       |
+| `securityHeaders`   | `boolean \| Record<string, string \| false>` | `true`      | Strict API headers; an object overrides individual headers, `false` removes one      |
+| `healthPath`        | `string \| false`                            | `"/health"` | Health route answering `{ "status": "ok" }`, outside the prefix; `false` disables it |
+| `shutdownTimeoutMs` | `number`                                     | `10000`     | How long shutdown waits for in-flight requests before closing remaining connections  |
+
+## App reference
+
+`defineApp` returns an `App`. It runs nothing until one of these builds an instance:
+
+| Member                   | Description                                                                                    |
+| ------------------------ | ---------------------------------------------------------------------------------------------- |
+| `listen(port, options?)` | Builds an instance, runs `onInit`, listens, runs `onReady`; resolves with the instance         |
+| `start(options?)`        | The same without an HTTP server, for workers and schedulers                                    |
+| `create(options?)`       | Builds an instance without starting it, for platforms that bring their own server (serverless) |
+| `manifest`               | The named routes as data, for the [typed client](#typed-client) (`brisk client` writes it)     |
+| `openapi()`              | The [OpenAPI](#openapi) document (`brisk openapi` writes it)                                   |
+
+Each call builds a new, independent instance with its own container. Configuration errors (a controller that leaves out a declared route, an invalid `status`) are thrown then, not at `defineApp`.
+
+| Option          | On                          | Default           | Description                                                                              |
+| --------------- | --------------------------- | ----------------- | ---------------------------------------------------------------------------------------- |
+| `providers`     | `listen`, `start`, `create` | `[]`              | Replace the app's own providers, typically with fakes                                    |
+| `manageProcess` | `listen`, `start`           | `true`            | SIGINT/SIGTERM shut down gracefully and exit 0; crashes are logged, shut down and exit 1 |
+| `host`          | `listen`                    | all interfaces    | Interface to bind, such as `0.0.0.0` in a container or `127.0.0.1` for local only        |
+| `server`        | `listen`                    | a new HTTP server | Your own `http.Server` or `https.Server`; brisk serves its requests                      |
+
+The instance (`AppInstance`):
+
+| Member       | Description                                                                          |
+| ------------ | ------------------------------------------------------------------------------------ |
+| `express`    | The Express app                                                                      |
+| `server`     | The listening Node server, or `undefined` when the instance did not listen           |
+| `container`  | The dependency container: `instance.container.get(UsersService)`                     |
+| `logger`     | The app logger                                                                       |
+| `manifest`   | The named routes as data                                                             |
+| `openapi()`  | The OpenAPI document                                                                 |
+| `init()`     | Runs the `onInit` hooks once; `listen` and `start` call it. Call it after `create()` |
+| `shutdown()` | Graceful shutdown; safe to call more than once                                       |
+
+```ts
+const instance = await app.listen(env.PORT);
+instance.server?.keepAliveTimeout; // the Node server
+await instance.shutdown();
+```
+
+## Typed client
+
+`@raiyyan/brisk/client` calls an app's named routes, typed from their schemas. It imports no server code, so it is safe in a browser bundle.
+
+```ts
+import { ApiError, createClient } from "@raiyyan/brisk/client";
+```
+
+`createClient` takes the app itself, or a route manifest plus the app's type:
+
+| Form                                   | Where                                                                                          |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `createClient(app, options)`           | Node: tests, scripts, server-to-server calls. `app` is the definition or a running instance    |
+| `createClient<Api>(manifest, options)` | Browsers: `manifest` is generated by `brisk client`, and `Api` is `typeof app` (`import type`) |
+
+The manifest is the routes as data (`{ users: { get: ["GET", "/api/users/:id"] } }`). Generate it into the frontend and run the command again after changing routes:
+
+```bash
+npx brisk client --out web/src/api.manifest.ts
+```
+
+```ts
+// web/src/api.ts
+import { createClient } from "@raiyyan/brisk/client";
+import type { Api } from "../../server/src/app.ts"; // export type Api = typeof app
+import { manifest } from "./api.manifest.ts";
+
+export const api = createClient<Api>(manifest, {
+  baseUrl: import.meta.env.VITE_API_URL,
+  headers: () => ({ authorization: `Bearer ${session.token}` }),
+});
+```
+
+`import type` brings in types only, so no server code reaches the bundle.
+
+| Option    | Type                                | Description                                                 |
+| --------- | ----------------------------------- | ----------------------------------------------------------- |
+| `baseUrl` | `string`                            | Origin of the API, such as `https://api.example.com`        |
+| `headers` | object, or a function returning one | Headers for every request; a function is called per request |
+| `fetch`   | `typeof fetch`                      | The fetch to use. Default: the global `fetch`               |
+
+### Calling routes
+
+Each named route is a function at `api.<controller>.<route>`, with groups nested under their names:
+
+```ts
+const user = await api.users.get({ params: { id } });
+const page = await api.users.list({ query: { search: "ada", limit: 20 } });
+const created = await api.users.create({
+  body: { email: "ada@example.com", name: "Ada", password: "correct-horse-battery" },
+  headers: { authorization: `Bearer ${token}` },
+});
+await api.users.remove({ params: { id } }, { signal: AbortSignal.timeout(5000) });
+```
+
+- The input has `params`, `query`, `body` and `headers`, each typed by the route's schema as clients send it (the schema's input type). A field is absent when the route has nothing for it, and optional when everything in it is optional.
+- Every call accepts extra headers, such as `authorization` for a middleware that reads it.
+- The second argument is passed to `fetch`: `signal`, `credentials`, and so on.
+- Array query values become repeated keys (`?tag=a&tag=b`); a `*splat` param takes an array of segments.
+
+A call resolves to:
+
+| The route                 | The call resolves to                                                                  |
+| ------------------------- | ------------------------------------------------------------------------------------- |
+| has a `response` schema   | the schema's output                                                                   |
+| has none                  | the handler's return value after JSON: `Date` becomes `string`, functions are dropped |
+| returns a stream or bytes | the raw `Response`, to read as you need                                               |
+| returns nothing           | `undefined` (204)                                                                     |
+
+A non-2xx response rejects with `ApiError`:
+
+| Field       | Description                                         |
+| ----------- | --------------------------------------------------- |
+| `status`    | HTTP status                                         |
+| `code`      | `error.code` from the body, or `HTTP_ERROR`         |
+| `message`   | `error.message` from the body, or a generic message |
+| `details`   | `error.details` from the body                       |
+| `requestId` | `error.requestId` from the body                     |
+| `body`      | The parsed body, whatever its shape                 |
+
+```ts
+try {
+  await api.users.create({ body, headers });
+} catch (error) {
+  if (error instanceof ApiError && error.code === "EMAIL_TAKEN") return showEmailTaken();
+  throw error;
+}
+```
+
+Types: `ApiOf<T>` (an app's routes), `Client<T>` (the client for them), `Jsonify<T>` (a type after JSON), `Manifest`.
+
+## OpenAPI
+
+brisk builds an OpenAPI 3.1 document from the routes' Zod schemas. Pass `openapi` to serve it:
+
+```ts
+export const app = defineApp({
+  controllers,
+  openapi: { title: "Shop API", version: "1.0.0" },
+});
+```
+
+| Option             | Type                      | Default            | Description                                                          |
+| ------------------ | ------------------------- | ------------------ | -------------------------------------------------------------------- |
+| `title`, `version` | `string`                  | required           | The document's `info`                                                |
+| `description`      | `string`                  | none               | The document's `info.description`                                    |
+| `servers`          | `{ url, description? }[]` | none (same origin) | Base URLs of the API                                                 |
+| `path`             | `string \| false`         | `"/openapi.json"`  | Where it is served, outside the app `prefix`; `false` serves nothing |
+
+- `app.openapi()` returns the document, with or without the option (title `API`, version `0.0.0` without it).
+- `brisk openapi --out openapi.json` writes it to a file, for client generators and API gateways.
+- The `operationId` is the route's name, `controller.route` (`users.get`, `orders.admin.remove`), and the controller's name is the tag. Routes of a controller whose setup returns nothing have no `operationId`.
+- `params`, `query` and `headers` schemas become parameters, and the `body` schema the request body, as clients send them. The `response` schema is documented under the route's success status as clients receive it. Every operation lists the error body as its `default` response.
+- Express paths are converted: `:id` and `*path` become `{id}` and `{path}`, and an optional group (`/posts{/:slug}`) gives two paths.
+- A schema JSON Schema cannot express, such as `z.date()` or a transform, is documented as "any". For dates sent as strings, end the schema in the string it produces:
+
+  ```ts
+  createdAt: z
+    .date()
+    .transform((date) => date.toISOString())
+    .pipe(z.iso.datetime()), // documented as { type: "string", format: "date-time" }
+  ```
+
+  The typed client then types the field as `string` too.
+
+## Testing
+
+```ts
+import { provide } from "@raiyyan/brisk";
+import { createTestClient, readError } from "@raiyyan/brisk/testing";
+import { afterAll, expect, it } from "vitest";
+import { app } from "../src/app.ts";
+import { Clock } from "../src/database/clock.ts";
+
+const api = await createTestClient(app, { providers: [provide(Clock, () => new Date("2026-01-01"))] });
+afterAll(() => api.close());
+
+it("creates a product", async () => {
+  const product = await api.call.products.create({ body: { name: "Desk" } }); // typed
+  expect(await api.call.products.get({ params: { id: product.id } })).toEqual(product);
+});
+
+it("rejects an invalid product", async () => {
+  const res = await api.post("/api/products", { body: { name: "" } }); // raw
+  expect(res.status).toBe(400);
+  expect(readError(res)).toMatchObject({ code: "VALIDATION_FAILED", details: { location: "body" } });
+});
+```
+
+- `createTestClient(app, { providers? })` starts a fresh instance on a random port with its full lifecycle. It returns the [typed client](#typed-client) as `call`, raw `get`, `post`, `put`, `patch` and `delete(path, { body?, headers? })`, `baseUrl`, `instance` (the running `AppInstance`, such as `api.instance.container.get(UsersService)`), and `close()` (a full graceful shutdown).
+- Each test client gets its own instance, so test files run in parallel without sharing state.
+- Use `call` for behavior (`await api.call.users.create({ body })` is typed and rejects with `ApiError` on non-2xx), and the raw methods for status codes, headers and malformed input.
+- A raw `body` is sent as JSON, except a string or `Uint8Array`, which is sent as is (webhook payloads, forms). `content-type` defaults to `application/json` when there is a body; set it in `headers` to override.
+- Raw responses are `{ status, headers, body }`; `body` is parsed JSON, text, or `undefined`, typed `unknown`. Parse it with a Zod schema or assert with `toMatchObject`.
+- `readError(res)` returns the typed `error` object and fails the test if the body is not an error response.
+- Swap dependencies with `providers`: they replace the app's own. Unit-test services without HTTP with `new Container([...]).get(Service)`.
+- To test `304 Not Modified`, use `node:http` rather than `fetch`: `fetch` adds `Cache-Control: no-cache` to requests with `If-None-Match`, which correctly disables 304.
+
+## CLI
+
+The package installs a `brisk` command. Run it from the app's root.
+
+| Command                      | What it does                                                                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `brisk init`                 | Scaffolds a runnable app in the current folder (see below), installs missing packages, then runs `brisk agents`                 |
+| `brisk g feature <name>`     | Writes `src/features/<name>/` (schema, repository, service, controller) and `test/<name>.test.ts`, and registers the controller |
+| `brisk g middleware <name>`  | Writes a typed middleware in `src/middlewares/<name>.ts`                                                                        |
+| `brisk client --out <file>`  | Writes the route manifest for a frontend's [typed client](#typed-client)                                                        |
+| `brisk openapi --out <file>` | Writes the [OpenAPI](#openapi) document as JSON                                                                                 |
+| `brisk agents`               | Adds or refreshes the brisk guide for AI coding agents in `AGENTS.md` and `CLAUDE.md`                                           |
+| `brisk help`, `--version`    | Lists commands; prints the installed version                                                                                    |
+
+### brisk init
+
+`brisk init` creates `src/env.ts`, `src/app.ts` (`export const app = defineApp(...)` with prefix `/api`, and `export type Api`), `src/main.ts` (`await app.listen(env.PORT)`), `src/features/index.ts`, `.env.example` and a `tsconfig.json` that lets Node run `.ts` directly. It never overwrites existing files. It adds `"type": "module"` and any missing `dev`, `start`, `typecheck`, `test` and `brisk` scripts to `package.json`.
+
+It also writes `vitest.config.ts` (test environment variables) and `.gitignore`. Without flags it asks about each option; flags answer the questions up front:
+
+| Flag                     | Adds                                                                                                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--db sqlite`            | A `Database` provider on Node's built-in `node:sqlite` (no dependency), opened in `onInit` and closed in `onShutdown`                                   |
+| `--db postgres`          | A `Database` provider with `pg` and Drizzle, `src/database/schema.ts`, `drizzle.config.ts`, and `db:generate` / `db:migrate` scripts                    |
+| `--db` (either)          | `src/database/errors.ts`: an error mapper that turns a unique violation into 409 `ALREADY_EXISTS`, registered in `errors.mappers`                       |
+| `--auth`                 | HS256 bearer tokens signed with `node:crypto` (`src/auth/tokens.ts`), `authenticate` and `requireRole` middlewares, and their tests                     |
+| `--docker`               | A `Dockerfile` (runs as a non-root user, with a health check), `compose.yaml` (with the database for postgres, a volume for sqlite) and `.dockerignore` |
+| `--ci`                   | A GitHub Actions workflow running typecheck and tests                                                                                                   |
+| `--web`                  | CORS, `express-rate-limit`, `express.static` for `public/`, and `pino-pretty` for development logs                                                      |
+| `--pm <pnpm\|npm\|yarn>` | The package manager. Default: the one running the CLI, else the one whose lockfile is present, else npm                                                 |
+| `--yes`, `-y`            | Take the defaults (no database, no extras) for every option not given, and ask nothing                                                                  |
+| `--no-install`           | Print the install commands instead of running them                                                                                                      |
+
+```bash
+npx brisk init --db postgres --auth --docker --ci --yes
+```
+
+Packages are installed after the files are written. If an install fails, the files stay in place and the CLI prints the commands to run again; with pnpm it also points to `pnpm approve-builds`, for packages whose build scripts pnpm blocked.
+
+### brisk g feature
+
+- `brisk g feature products` writes `products.schema.ts`, `.repository.ts`, `.service.ts` and `.controller.ts` with singular entity names (`Product`, `CreateProductBody`, `ProductResponse`), a test, and registers `products: productsController` in `src/features/index.ts`. The key is the controller's name in the typed client.
+- Names may be `kebab-case`, `camelCase`, `PascalCase` or `snake_case`; files use kebab-case.
+- `g` is short for `generate`.
+- When `oxfmt` or `prettier` is installed in the project, generated files are formatted with it, so they match your style.
+- Keep the `// @brisk:imports` and `// @brisk:controllers` markers in `src/features/index.ts`; the CLI registers new controllers there.
+
+### brisk client and brisk openapi
+
+Both import `src/app.ts` (or the module given with `--app <file>`), read its `app` export, and write `--out`. Nothing listens or starts. The module runs, so its environment must be valid, as for starting the app.
+
+## Working with the ecosystem
+
+### Not in your way
+
+brisk owns only its own routes. Everything else is plain Express on a plain Node server, so any Express middleware or Node library works as it would without brisk:
+
+- `configureExpress(expressApp)`: full Express access, before JSON parsing and before brisk's routes.
+- `instance.express`: the Express app (adapters, serverless with `app.create()`).
+- `instance.server` and the `HttpServer` token: the Node server (WebSockets, timeouts).
+- `ListenOptions.server`: your own server (HTTPS, tuned timeouts).
+- Provider lifecycle hooks: run anything alongside HTTP.
+- `app.start()`: the same app without HTTP.
+- `ctx.res`: write a raw response from any handler.
+
+Requests in `configureExpress` have a context (`getContext(req)`), and errors thrown there get the same error responses. Because it runs before JSON parsing, raw, form and multipart bodies are yours to parse; a form body parsed there reaches a brisk route's `body` schema.
+
+### Express middleware, static files, uploads, webhooks
+
+```ts
+import cors from "cors";
+import express from "express";
+import multer from "multer";
+
+export const app = defineApp({
+  controllers,
+  configureExpress: (expressApp) => {
+    expressApp.use(cors({ origin: env.WEB_ORIGIN }));
+    expressApp.use("/static", express.static("public"));
+    expressApp.post("/webhooks/stripe", express.raw({ type: "application/json" }), stripeWebhook); // raw bytes for signatures
+    expressApp.post("/upload", multer({ dest: "uploads/" }).single("file"), (req, res) => {
+      res.json({ name: req.file?.originalname });
+    });
+    expressApp.use(express.urlencoded({ extended: false })); // form bodies reach brisk `body` schemas
+  },
+});
+```
+
+### Server-Sent Events
+
+```ts
+return {
+  events: route.get("/events", ({ res, requestId }) => {
+    res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache" });
+    res.write(`data: ${requestId}\n\n`);
+  }),
+};
+```
+
+End long-lived streams from a provider's `onDrain` so shutdown does not wait for them.
+
+### WebSockets with ws
+
+```ts
+import { HttpServer, inject, type OnDrain, type OnReady } from "@raiyyan/brisk";
+import { WebSocketServer } from "ws";
+
+export class ChatGateway implements OnReady, OnDrain {
+  #wss: WebSocketServer | undefined;
+
+  onReady() {
+    this.#wss = new WebSocketServer({ server: inject(HttpServer) });
+    this.#wss.on("connection", (socket) => socket.on("message", (data) => socket.send(data)));
+  }
+
+  onDrain() {
+    for (const client of this.#wss?.clients ?? []) client.close(1001, "server shutting down");
+    this.#wss?.close();
+  }
+}
+
+export const app = defineApp({ controllers, providers: [ChatGateway] });
+```
+
+### Socket.IO
+
+```ts
+import { HttpServer, inject, type OnDrain, type OnReady } from "@raiyyan/brisk";
+import { Server } from "socket.io";
+
+export class Realtime implements OnReady, OnDrain {
+  #io: Server | undefined;
+
+  onReady() {
+    this.#io = new Server(inject(HttpServer));
+  }
+
+  async onDrain() {
+    await this.#io?.close();
+  }
+}
+
+export const app = defineApp({ controllers, providers: [Realtime] });
+```
+
+### GraphQL with Yoga
+
+```ts
+import { createSchema, createYoga } from "graphql-yoga";
+
+const yoga = createYoga({
+  schema: createSchema({
+    typeDefs: "type Query { user(id: ID!): User } type User { id: ID! name: String! }",
+    resolvers: { Query: { user: (_parent, args: { id: string }) => inject(UsersService).get(args.id) } },
+  }),
+});
+
+export const app = defineApp({
+  controllers,
+  configureExpress: (expressApp) => expressApp.use(yoga.graphqlEndpoint, yoga),
+  http: { securityHeaders: { "content-security-policy": false } }, // GraphiQL loads scripts; or set a GraphiQL-compatible policy
+});
+```
+
+Resolvers call `inject()` directly.
+
+### GraphQL with Apollo Server
+
+```ts
+import { ApolloServer } from "@apollo/server";
+import { expressMiddleware } from "@as-integrations/express5";
+import express from "express";
+
+const apollo = new ApolloServer({ typeDefs, resolvers });
+await apollo.start();
+
+export const app = defineApp({
+  controllers,
+  configureExpress: (expressApp) => expressApp.use("/graphql", express.json(), expressMiddleware(apollo)),
+});
+```
+
+`configureExpress` runs before brisk parses JSON, so the Apollo route adds `express.json()` itself.
+
+### tRPC
+
+```ts
+import { initTRPC } from "@trpc/server";
+import { createExpressMiddleware } from "@trpc/server/adapters/express";
+
+const t = initTRPC.create();
+const router = t.router({
+  user: t.procedure
+    .input(z.object({ id: z.uuid() }))
+    .query(({ input }) => inject(UsersService).get(input.id)),
+});
+
+export const app = defineApp({
+  controllers,
+  configureExpress: (expressApp) => expressApp.use("/trpc", createExpressMiddleware({ router })),
+});
+```
+
+tRPC v11 accepts Zod schemas directly, so your brisk schemas work as procedure inputs.
+
+### gRPC
+
+gRPC (`@grpc/grpc-js`) runs on its own port, as in any Node app; a provider starts and stops it. This recipe is not covered by brisk's tests.
+
+```ts
+import * as grpc from "@grpc/grpc-js";
+
+export class GrpcServer implements OnReady, OnDrain {
+  readonly #server = new grpc.Server();
+  readonly #users = inject(UsersService); // resolved here: gRPC callbacks run outside the app
+
+  onReady() {
+    this.#server.addService(usersServiceDefinition, {
+      getUser: (call, callback) => callback(null, this.#users.get(call.request.id)),
+    });
+    return new Promise<void>((resolve, reject) =>
+      this.#server.bindAsync("0.0.0.0:50051", grpc.ServerCredentials.createInsecure(), (error) =>
+        error ? reject(error) : resolve(),
+      ),
+    );
+  }
+
+  onDrain() {
+    return new Promise<void>((resolve) => {
+      const force = setTimeout(() => {
+        this.#server.forceShutdown();
+        resolve();
+      }, 5000);
+      this.#server.tryShutdown(() => {
+        clearTimeout(force);
+        resolve();
+      });
+    });
+  }
+}
+
+export const app = defineApp({ controllers, providers: [GrpcServer] });
+```
+
+### Microfrontends, frontends and BFFs
+
+Serve frontend assets and remote entries with `express.static`. brisk's strict API headers block cross-origin asset loading, so relax them and allow the shell's origin:
+
+```ts
+export const app = defineApp({
+  controllers,
+  http: {
+    securityHeaders: {
+      "content-security-policy": false, // or your policy
+      "cross-origin-resource-policy": "cross-origin",
+      "x-frame-options": false, // only when the frontend is embedded in iframes
+    },
+  },
+  configureExpress: (expressApp) => {
+    expressApp.use(cors({ origin: env.SHELL_ORIGIN }));
+    expressApp.use("/remotes/checkout", express.static("dist/checkout"));
+  },
+});
+```
+
+A backend-for-frontend is brisk controllers calling upstream services: throw `BadGatewayError` for bad upstream answers and `GatewayTimeoutError` for timeouts.
+
+A frontend calls the API through the [typed client](#typed-client), with the manifest that `brisk client` generates.
+
+### Caching
+
+- ETags and `304 Not Modified` work automatically for GET responses.
+- Set `Cache-Control` in the handler: `res.set("cache-control", "public, max-age=60")`.
+- A Redis or in-memory cache client is a provider: connect in `onInit`, quit in `onShutdown`, `inject(Cache)` where needed.
+
+### Workers, jobs and queue consumers
+
+```ts
+export class DigestJob implements OnReady, OnDrain {
+  #timer: NodeJS.Timeout | undefined;
+
+  onReady() {
+    this.#timer = setInterval(() => inject(DigestService).send(), 60_000);
+  }
+
+  onDrain() {
+    clearInterval(this.#timer);
+  }
+}
+
+export class EmailConsumer implements OnReady, OnDrain {
+  #running = false;
+  #loop: Promise<void> | undefined;
+
+  onReady() {
+    this.#running = true;
+    this.#loop = this.#consume();
+  }
+
+  async onDrain() {
+    this.#running = false;
+    await this.#loop; // finish the message in progress
+  }
+
+  async #consume() {
+    while (this.#running) await inject(EmailService).handle(await queue.next());
+  }
+}
+```
+
+Run them next to HTTP (`providers: [DigestJob, EmailConsumer]`), or in their own process with the same code and no port:
+
+```ts
+// src/worker.ts
+await defineApp({ providers: [EmailConsumer] }).start(); // no controllers, no port; signals and graceful shutdown still apply
+```
+
+### Worker threads
+
+CPU-heavy work goes to a `worker_threads` pool owned by a provider:
+
+```ts
+import { Worker } from "node:worker_threads";
+
+export class ImagePool implements OnInit, OnShutdown {
+  #worker: Worker | undefined;
+
+  onInit() {
+    this.#worker = new Worker(new URL("./resize.worker.ts", import.meta.url));
+  }
+
+  resize(input: Uint8Array): Promise<Uint8Array> {
+    const worker = this.#worker;
+    if (!worker) return Promise.reject(new Error("pool not started"));
+    return new Promise((resolve) => {
+      worker.once("message", resolve);
+      worker.postMessage(input);
+    });
+  }
+
+  async onShutdown() {
+    await this.#worker?.terminate();
+  }
+}
+```
+
+### Lazy loading
+
+- Instances are created on first use, not at boot.
+- `injectLazy(Token)` defers a dependency until its first call.
+- Load heavy code on demand inside a handler: `const { PdfService } = await import("./pdf.service.ts"); return inject(PdfService).render(id);`.
+
+### HTTPS and custom servers
+
+```ts
+import https from "node:https";
+
+await app.listen(443, { server: https.createServer({ key, cert }) });
+```
+
+Inside providers, `inject(HttpServer)` returns the server from `onReady` on.
+
+### Serverless
+
+```ts
+const instance = app.create();
+await instance.init();
+export const handler = serverlessAdapter(instance.express); // your platform's Express adapter
+```
+
+### Clusters, PM2 and Kubernetes
+
+- brisk keeps no per-process state: run one process per core with PM2, `node:cluster` or replicas.
+- Behind a load balancer, set the server's keep-alive timeout above the balancer's idle timeout (for example 65 seconds behind a 60-second idle timeout) to avoid 502s: `instance.server.keepAliveTimeout = 65_000` on the instance `listen` resolves with, or pass your own server.
+- Bind `host: "0.0.0.0"` in containers when the default does not reach the container network.
+- Point liveness and readiness probes at `/health`. SIGTERM triggers graceful shutdown; give the pod a termination grace period longer than `http.shutdownTimeoutMs`.
+
+## Production checklist
+
+- Validate every variable in `defineEnv`; keep `.env` out of version control.
+- Give every route that takes input a schema, and a `response` schema for anything that returns stored data.
+- Keep `errors.exposeInternal` off in production.
+- Set `http.trustProxy` only to match your proxy setup.
+- Add CORS with an explicit origin list and a rate limiter in `configureExpress`.
+- Use JSON logs in production (no `pretty`); report 5xx errors with `hooks.onError`.
+- Connect clients in `onInit`, close them in `onShutdown`; stop long-lived work in `onDrain`.
+- Set `http.shutdownTimeoutMs` below your orchestrator's grace period, and the keep-alive timeout above your load balancer's idle timeout.
+- Map database and SDK errors with `errors.mappers` instead of try/catch in services.
+- Run `npm audit` (or `pnpm audit`) in CI.
+
+## Performance
+
+- brisk costs about 15 to 25 µs of CPU per request over hand-wired Express doing the same work (auth, validation, response DTO, JSON errors), on a laptop CPU. That buys security headers, request ids, the request context and dependency scope.
+- The request path allocates little: sync middlewares and schemas never create promises, middleware results live on the request's own context (no `WeakMap` entries), routes sit on one flat router, and shutdown tracking costs one map entry per connection, not per request.
+- It stays stable under sustained load: 300 000 requests in a 30 s soak, heap flat after GC.
+- Graceful shutdown lets in-flight requests finish before the process exits.
+
+Numbers: [benchmarks/RESULTS.md](https://github.com/MohammadRaiyyan/brisk/blob/main/benchmarks/RESULTS.md).
+
+## AI coding agents
+
+brisk ships a complete guide for coding agents at `node_modules/@raiyyan/brisk/AGENTS.md` ([source](https://github.com/MohammadRaiyyan/brisk/blob/main/packages/brisk/AGENTS.md)).
+
+Agents read the project's own `AGENTS.md` and `CLAUDE.md`, so run:
+
+```bash
+npx brisk agents
+```
+
+It writes a brisk section between `<!-- brisk:start -->` and `<!-- brisk:end -->` in your `AGENTS.md` (refreshed in place on later runs, the rest of the file untouched), and makes `CLAUDE.md` import `@AGENTS.md` and `@node_modules/@raiyyan/brisk/AGENTS.md`. `brisk init` runs it for you.
+
+## FAQ
+
+**Can I use plain Express middleware?**
+Yes. Put it in `configureExpress` (`app.use(helmet())`, `app.use(cors())`), globally or on specific paths.
+
+**Where do I put CORS?**
+In `configureExpress`: `app.use(cors({ origin: ["https://app.example.com"] }))`. It runs before brisk's routes, so preflight requests are answered first.
+
+**How do I return a file?**
+Set headers on `res` and return a `Readable` (`return createReadStream(path)`), or call `res.sendFile(path)` or `res.download(path)` and return nothing.
+
+**How do I version an API?**
+Use the app `prefix` (`prefix: "/api/v1"`), or mount controllers with prefixes like `/v1/users` and `/v2/users` in the same app.
+
+**How do I share types with a frontend?**
+Use the [typed client](#typed-client): `brisk client` writes the route manifest into the frontend, and `createClient<Api>(manifest, { baseUrl })` types every call from the server's schemas without bundling server code.
+
+**Why no decorators?**
+Decorators need a compile step and hide wiring behind metadata. `inject()` in a field is explicit, fully typed, and runs on plain Node.
+
+**Can a handler be synchronous?**
+Yes. Handlers, middlewares, hooks and lifecycle methods can be sync or async; a synchronous `throw` and a rejected promise produce the same error response.
+
+**Can I run two apps in one process?**
+Yes. Every instance (each `listen`, `start`, `create` or test client) has its own dependencies. `inject()` resolves from the instance running the current code; outside any instance (a script, a REPL), use `instance.container.get(...)`.
+
+## Contributing
+
+The repository is [github.com/MohammadRaiyyan/brisk](https://github.com/MohammadRaiyyan/brisk). Read the [contributor guide](https://github.com/MohammadRaiyyan/brisk/blob/main/AGENTS.md) and run `pnpm verify` before opening a pull request.
+
+## License
+
+[MIT](https://github.com/MohammadRaiyyan/brisk/blob/main/LICENSE)