@raiyyan/brisk 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,1746 @@
-# 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, a typed client and an OpenAPI document. Choices such as the database, the auth scheme and the tooling stay yours: they live in starters and in your project's own templates.
+
+```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)
+- [Starters](#starters)
+- [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)
+- [Templates](#templates)
+- [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.
+- **Mechanisms, not choices.** brisk provides routing, validation, dependency injection, lifecycle, errors, the typed client, OpenAPI, the test client, and a CLI that renders templates. The database, the auth scheme, lint and format tools, Docker, CI, folder conventions and pagination shape come from a [starter](#starters) and live in your project, where you can change them.
+
+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, pnpm or yarn.
+- 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
+```
+
+```bash
+pnpm add @raiyyan/brisk
+```
+
+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`.
+
+Without a starter, also add `typescript`, `@types/node` and a test runner such as `vitest` as dev dependencies. `brisk init` adds what its starter needs.
+
+## Quick start
+
+In an empty folder, with npm:
+
+```bash
+npm init -y
+npm install @raiyyan/brisk
+npx brisk init
+cp .env.example .env
+npx brisk g feature products
+npm run typecheck
+npm test
+npm run dev
+```
+
+With pnpm:
+
+```bash
+pnpm init
+pnpm add @raiyyan/brisk
+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` copies the `minimal` [starter](#starters) into the folder, adds its scripts and dependencies to `package.json`, installs them and writes the guide for AI coding agents. It never overwrites a file, so it is safe in an existing project. `brisk g feature products` renders the project's own `templates/feature/` (see [Templates](#templates)).
+
+### Adding brisk to an existing Express project
+
+Mount your existing Express router, and put its app-wide middlewares in `use`. Routers, middlewares and routes keep working unchanged, and new features are written as brisk controllers next to them:
+
+```ts
+export const app = defineApp({
+  controllers,
+  use: [fromExpress(cors({ origin: env.WEB_ORIGIN }))],
+  mount: { "/": [express.json(), legacyRouter] }, // brisk does not parse mount bodies; your routes read req.body
+});
+```
+
+brisk's routes answer first, and the legacy router gets every request they did not match.
+
+Then migrate route by route: write the new route in a controller, delete the old one.
+
+## Starters
+
+A starter is a complete, tested app that makes the choices brisk leaves to you: storage, auth, tooling, Docker. `brisk init --starter <name>` copies one into your project; from then on the code is yours. `brisk init --starter list` lists them.
+
+| Starter       | What it brings                                                                                                                                                                                                                                                                                    |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `minimal`     | The app, env and test setup, and a feature template that stores records in memory. No database                                                                                                                                                                                                    |
+| `sqlite-auth` | Node's built-in `node:sqlite` with migrations applied at startup, accounts with scrypt password hashes and HS256 bearer tokens, an admin created from `ADMIN_EMAIL` / `ADMIN_PASSWORD`, CORS, rate limiting, static files, and a Dockerfile and `compose.yaml` that keep the database in a volume |
+
+Both starters:
+
+- ship oxlint and oxfmt, with `lint`, `format` and `format:check` scripts, and `dev`, `start`, `typecheck`, `test` and `brisk` scripts;
+- require Node 24 or later (`engines`);
+- include a `notes` feature generated from their own `templates/feature/`, as a working example; delete it when you no longer need it (its folder, its test files and its line in `src/features/index.ts`; in `sqlite-auth` also its migration, before anything ships);
+- keep shared schema helpers in `src/schemas.ts`: `isoDate()` (a timestamp sent as an ISO string), `PageQuery` and `page(item)` (paged lists). These are starter code, not brisk exports: change the page shape there.
+
+The sources are in [starters/](https://github.com/MohammadRaiyyan/brisk/tree/main/starters).
+
+## Project structure
+
+The `minimal` starter, after `brisk g feature products`:
+
+```
+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)
+  schemas.ts                    isoDate(), PageQuery, page(item): shared schema helpers
+  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
+templates/
+  feature/                      what `brisk g feature <name>` renders
+  middleware/                   what `brisk g middleware <name>` renders
+test/
+  products.test.ts              HTTP tests with createTestClient
+  products.service.test.ts      service tests without HTTP
+.env.example
+.oxlintrc.json, .oxfmtrc.json   lint and format settings (they ignore templates/)
+tsconfig.json                   lets Node run .ts directly
+vitest.config.ts                test environment variables
+AGENTS.md, CLAUDE.md            guide for AI coding agents (brisk agents)
+```
+
+`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 }),
+  openapi: { title: "API", version: "0.1.0" },
+  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>();
+
+  async findById(id: string): Promise<Product | undefined> {
+    return this.#rows.get(id);
+  }
+
+  async insert(row: Product): Promise<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);
+
+  async get(id: string): Promise<Product> {
+    const row = await this.#repository.findById(id);
+    if (!row) throw new NotFoundError("Product not found");
+    return row;
+  }
+
+  create(input: CreateProductBody): Promise<Product> {
+    return this.#repository.insert({ 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                           |
+| `providers` | `(Provider \| Class)[]` | Providers the feature brings, such as its WebSocket gateway: created at startup with the app (below) |
+
+A controller's `providers` are created at startup like the app's own, so removing the controller removes them. They come before the app's providers, so a value the app or a test provides for the same token wins.
+
+`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. Two routes with the same method and path (paths that differ only in parameter names, such as `/:id` and `/:userId`, count as the same) are an error naming both, thrown when an instance is built.
+
+### 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,
+  inject,
+  UnauthorizedError,
+  type SecuritySchemes,
+} from "@raiyyan/brisk";
+
+const bearer = { bearer: { type: "http", scheme: "bearer", bearerFormat: "JWT" } } satisfies SecuritySchemes;
+
+export const authenticate = defineMiddleware({ security: bearer }, async ({ req, log }) => {
+  const user = await inject(Sessions).verify(req.get("authorization"));
+  if (!user) throw new UnauthorizedError("Invalid token", { challenge: "Bearer" });
+  return { user, log: log.child({ userId: user.id }) };
+});
+
+export const requireRole = (role: "admin" | "member") =>
+  defineMiddleware({ security: bearer }, async (ctx) => {
+    const { user } = await authenticate.run(ctx);
+    if (user.role !== role) throw new ForbiddenError(`Requires role: ${role}`);
+    return { user };
+  });
+```
+
+`defineMiddleware(fn)` or `defineMiddleware(options, fn)`:
+
+- **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 the route's 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.
+
+| Option     | Type              | Description                                                                                            |
+| ---------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
+| `params`   | Zod schema        | Path params the middleware reads: validated before it runs (400 `VALIDATION_FAILED`), typed on its ctx |
+| `query`    | Zod schema        | Query fields the middleware reads, validated and typed the same way                                    |
+| `security` | `SecuritySchemes` | The OpenAPI security schemes it enforces, such as `{ bearer: { type: "http", scheme: "bearer" } }`     |
+
+### Middleware that needs input
+
+A permission check often depends on the request, such as the project a route belongs to. Declare what the middleware reads, and it gets validated, typed input before it runs; async refinements work:
+
+```ts
+export const requireProjectRole = (role: ProjectRole) =>
+  defineMiddleware({ params: z.object({ projectId: z.uuid() }), security: bearer }, async (ctx) => {
+    const { user } = await authenticate.run(ctx);
+    const projectRole = await inject(ProjectAccess).require(user.id, ctx.params.projectId, role);
+    return { projectRole };
+  });
+```
+
+`ProjectAccess` is a plain service, so the WebSocket gateway and GraphQL resolvers use the same rules ([shared access rules](#shared-access-rules)).
+
+### Security schemes
+
+Every route behind a middleware with `security` lists those schemes under `security` in the [OpenAPI](#openapi) document, and the document lists them under `components.securitySchemes`. Routes without such a middleware stay public. `middleware.security` reads the schemes back.
+
+### Express middleware on one route
+
+App-wide Express middleware (`cors()`, `helmet()`, rate limiters) goes in the app's [`use`](#use-mount-and-a-routes-use). For Express middleware that only some routes need, such as multer, wrap it with `fromExpress` and put it in `use`; it runs in order with the others, so it runs after authentication:
+
+```ts
+import { fromExpress } from "@raiyyan/brisk";
+import multer from "multer";
+
+const upload = fromExpress(multer({ dest: "uploads/", limits: { fileSize: 5_000_000 } }).single("file"));
+
+return {
+  attach: route.post("/:taskId/attachments", { use: [authenticate, upload] }, ({ req, params }) =>
+    attachments.save(params.taskId, req.file),
+  ),
+};
+```
+
+- An error the Express middleware passes to `next` goes to the app's error handler: an `http-errors` `status` and `expose` are honored, and `errors.mappers` apply.
+- If the Express middleware ends the response itself, the route stops there.
+- The route path is declared once, in the controller.
+
+## 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 `defineController({ providers })`, in the `providers` of `listen`, `start`, `create` or `createTestClient`, or in `new Container([...])`. Later entries win. The order is: controllers' providers, then the app's, then those given to `listen`, `start`, `create` or `createTestClient`. Those last ones are added to the app's own, not swapped in for them: a value for the same token wins, and every listed class is still created.
+- **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, the app's `use` and every `mount`, 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: `onResponse(ctx, { status, durationMs, aborted })` and `onError(error, ctx)`. Logic that can reject a request is a middleware in the app's `use`. `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   security headers -> request id -> /health and /openapi.json -> app use
+          -> brisk route: JSON body -> middlewares -> validation -> handler -> response
+          -> 405 / OPTIONS -> mount -> 404
+          (any error -> error response -> hooks.onError; hooks.onResponse when the response closes)
+shutdown  SIGINT/SIGTERM -> /health answers 503 -> 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` or `onReady` throws, the port is taken), brisk logs it at `fatal` as `startup failed`, with `provider` and `hook` fields naming the class and hook that threw. It then runs the drain and shutdown hooks for what already started, so pools and clients are released, and rethrows the error.
+
+## 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. This one turns a Postgres unique violation into 409 `ALREADY_EXISTS`; the `sqlite-auth` starter has the SQLite version in `src/database/errors.ts`:
+
+```ts
+import { ConflictError, type ErrorMapper } from "@raiyyan/brisk";
+
+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;
+};
+```
+
+### Errors outside brisk's routes
+
+Code that answers outside a brisk route, such as a GraphQL error mask or a WebSocket close, can translate an error the way a route would with the `ErrorTranslator` token. It returns `{ status, code, message, details }` with `errors.mappers` applied, and hides the message of unexpected errors unless `errors.exposeInternal` is on:
+
+```ts
+import { ErrorTranslator, inject, NotFoundError } from "@raiyyan/brisk";
+
+const translate = inject(ErrorTranslator); // inside the app: a request, a class field, a lifecycle hook
+translate(new NotFoundError("Project not found")); // { status: 404, code: "NOT_FOUND", message: "Project not found", details: undefined }
+translate(new Error("password=hunter2")); // { status: 500, code: "INTERNAL_SERVER_ERROR", message: "Internal server error", ... }
+```
+
+Inside a request (a mount, a GraphQL resolver or `maskError`) call `inject(ErrorTranslator)` directly. In callbacks a library fires on its own, such as a `ws` message listener, resolve it in a class field. Outside the app, use `instance.container.get(ErrorTranslator)`.
+
+## 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` (Express middlewares and mounts) 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 `http: { settings: { "query parser": "extended" } }`.
+- **No mass assignment:** unknown body fields are stripped by your schemas.
+- **`trust proxy`** stays off unless you set it in `http.settings` (`{ "trust proxy": 1 }`). 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 the app's `use`.
+
+## 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`                                                                                                             |
+| `use`         | `Middleware[]`                                   | `[]`             | Middlewares for every request after `/health` and `/openapi.json`, before brisk's routes and mounts ([use and mount](#use-mount-and-a-routes-use)) |
+| `mount`       | `{ [path]: RequestHandler \| RequestHandler[] }` | `{}`             | Express handlers that answer what brisk's routes did not: static files, GraphQL, webhooks                                                          |
+| `hooks`       | `AppHooks`                                       | `{}`             | `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                                                                                                                                          |
+| `settings`          | `Record<string, unknown>`                    | `{}`        | Express app settings, applied with `app.set(name, value)` after brisk's defaults: `{ "trust proxy": 1 }`, `{ etag: false }`, `{ "query parser": "extended" }` |
+| `securityHeaders`   | `boolean \| Record<string, string \| false>` | `true`      | Strict API headers; an object overrides individual headers, `false` removes one                                                                               |
+| `healthPath`        | `string \| false`                            | `"/health"` | Health route, outside the prefix: `{ "status": "ok" }`, or 503 `{ "status": "shutting down" }` once shutdown begins; `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` | `[]`              | Added after the app's own providers: a value for the same token wins, typically a fake   |
+| `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.
+- `params` and `query` fields also accept the schema's output type when a URL can carry it: a `z.stringbool()` field takes `true` as well as `"true"`, and a `z.coerce.number()` field takes `2`.
+- 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 `FormData`, `Blob`, `URLSearchParams`, `ArrayBuffer` (or typed array) or `ReadableStream` body is sent as it is, so `fetch` sets the content type and multipart boundary. Any other body, strings included, is sent as JSON.
+
+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;
+}
+```
+
+### Raw responses
+
+Every call also has `.raw(input, init?)`, which sends the same request and resolves to the `Response` whatever its status, without throwing. Use it for downloads, uploads and anything that is not JSON. The client's `headers` are still applied, and a string body is sent as it is. Its `body` accepts the route's body type or any `RawBody`:
+
+```ts
+const form = new FormData();
+form.append("file", file);
+const res = await api.tasks.attach.raw({ params: { taskId }, body: form });
+if (!res.ok) throw new Error(`Upload failed with ${res.status}`);
+
+const report = await api.reports.download.raw({ params: { id } });
+const blob = await report.blob();
+```
+
+Types from `@raiyyan/brisk/client`: `ApiOf<T>` (an app's routes), `Client<T>` (the client for them), `Call<I, O>` (one route as a function, with `.raw`), `RawBody` (a body `.raw` sends as it is), `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 route behind a middleware declared with `security` lists those schemes (several middlewares: all of them, together), and the document lists every scheme under `components.securitySchemes`. Routes without one stay public. See [security schemes](#security-schemes).
+- 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. The starters' `isoDate()` in `src/schemas.ts` does this and also accepts an ISO string.
+
+## 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 are added after the app's own, so a value for the same token wins, and the app's listed classes still start. Unit-test services without HTTP with `new Container([...]).get(Service)`.
+- To test `304 Not Modified`, use `node:http`, or send `cache-control: max-age=0` with the request. `fetch`, and so the test client's raw methods, adds `Cache-Control: no-cache` to a request that carries `If-None-Match` and no `Cache-Control`, which correctly disables 304.
+
+## CLI
+
+The package installs a `brisk` command. Run it from the app's root.
+
+| Command                      | What it does                                                                                      |
+| ---------------------------- | ------------------------------------------------------------------------------------------------- |
+| `brisk init`                 | Copies a [starter](#starters) into the current folder, installs its packages, runs `brisk agents` |
+| `brisk g <kind> <name>`      | Renders the project's `templates/<kind>/` for `<name>` (see [Templates](#templates))              |
+| `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
+
+```bash
+npx brisk init [--starter <name>] [--pm pnpm|npm|yarn] [--no-install]
+```
+
+| Flag                     | Effect                                                                                                  |
+| ------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `--starter <name>`       | The starter to copy. Default: `minimal`. `--starter list` lists the starters                            |
+| `--pm <pnpm\|npm\|yarn>` | The package manager. Default: the one running the CLI, else the one whose lockfile is present, else npm |
+| `--no-install`           | Print the install command instead of running it                                                         |
+
+What it does:
+
+- Copies the starter's files. A file that already exists is kept, never overwritten, and listed as `kept`.
+- Skips `node_modules`, `dist`, `coverage`, `.env`, database and log files, and `AGENTS.md` / `CLAUDE.md` (written next by `brisk agents`).
+- Merges the starter's `package.json` into yours: `type`, `engines`, scripts and dependencies are added where yours has none; your own values win. `@raiyyan/brisk` is pinned to the version that is running. The `test` script `npm init` writes (which only fails) is replaced.
+- Writes the agent guide (`brisk agents`).
+- Installs the packages. If the install fails, the files stay in place and the CLI says what to run again; with pnpm it also points to `pnpm approve-builds`, for packages whose build scripts pnpm blocked.
+
+### brisk g
+
+```bash
+npx brisk g feature products
+npx brisk g middleware tenant
+```
+
+`brisk g <kind> <name>` renders the project's own `templates/<kind>/` folder; `g` is short for `generate`. The starters ship `feature` and `middleware`; any folder you add under `templates/` is a new kind. Names may be `kebab-case`, `camelCase`, `PascalCase` or `snake_case`.
+
+### 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.
+
+## Templates
+
+Templates are files in your project, not in brisk: `brisk g <kind> <name>` copies `templates/<kind>/` into the project root, rendering each file's path and contents. Edit them when your conventions change, and every later feature follows.
+
+| Token             | `brisk g feature blog-posts` gives |
+| ----------------- | ---------------------------------- |
+| `{{kebab}}`       | `blog-posts`                       |
+| `{{camel}}`       | `blogPosts`                        |
+| `{{pascal}}`      | `BlogPosts`                        |
+| `{{snake}}`       | `blog_posts`                       |
+| `{{entity}}`      | `BlogPost` (singular)              |
+| `{{entityCamel}}` | `blogPost`                         |
+
+- **New files:** every file in the folder is written to the same relative path, with tokens replaced in both the path and the contents.
+- **Additions to existing files:** a file named `<target>.<marker>.insert` is not copied. Its text is inserted into the existing `<target>`, right before the line that contains `@brisk:<marker>`. This is how a feature registers its controller (`// @brisk:imports` and `// @brisk:controllers` in `src/features/index.ts`) and, in `sqlite-auth`, its table (`// @brisk:migrations` in `src/database/migrations.ts`). Keep the marker lines.
+- **All or nothing:** everything is checked before anything is written. An unknown token, a file that already exists, or a missing target or marker stops the command with nothing changed.
+- **Formatting:** when the project has `oxfmt`, `prettier` or `biome` installed, the written files are formatted with it, so they match your style.
+
+A worked example: a `job` kind that writes a scheduled job and lists it in `src/jobs/index.ts`.
+
+```
+templates/job/
+  src/jobs/{{kebab}}.job.ts
+  src/jobs/index.ts.imports.insert
+  src/jobs/index.ts.jobs.insert
+```
+
+```ts
+// templates/job/src/jobs/{{kebab}}.job.ts
+import type { OnDrain, OnReady } from "@raiyyan/brisk";
+
+export class {{pascal}}Job implements OnReady, OnDrain {
+  #timer: NodeJS.Timeout | undefined;
+
+  onReady() {
+    this.#timer = setInterval(() => {
+      // the job's work
+    }, 60_000);
+  }
+
+  onDrain() {
+    clearInterval(this.#timer);
+  }
+}
+```
+
+```ts
+// templates/job/src/jobs/index.ts.imports.insert
+import { {{pascal}}Job } from "./{{kebab}}.job.ts";
+```
+
+```ts
+// templates/job/src/jobs/index.ts.jobs.insert
+  {{pascal}}Job,
+```
+
+```ts
+// src/jobs/index.ts, written once by hand; list it in defineApp({ providers: [...jobs] })
+// @brisk:imports
+
+export const jobs = [
+  // @brisk:jobs
+];
+```
+
+`brisk g job nightly-digest` then writes `src/jobs/nightly-digest.job.ts` and adds `NightlyDigestJob` to the list.
+
+Template files are not valid TypeScript until rendered, so keep `templates/` out of lint, format, typecheck and test runs; the starters' configs already do.
+
+## 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:
+
+- `use` with `fromExpress(handler)`: any Express middleware for every request, before brisk's routes.
+- `mount`: Express handlers that are not brisk routes (static files, GraphQL, tRPC, webhooks, a legacy router).
+- `http.settings`: Express app settings (`trust proxy`, `etag`, `query parser`).
+- `fromExpress(handler)`: any Express middleware in one route's `use`, in order with brisk's middlewares.
+- `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.
+
+### use, mount and a route's use
+
+- **The app's `use`** runs for every request: brisk routes, mounts and 404s. `/health` and `/openapi.json` are answered before it, so a rate limiter or an auth check there never blocks a probe. `fromExpress(...)` entries run as plain Express middleware, so CORS preflights are answered before routing. A `defineMiddleware` entry runs once per request, stops the request by throwing, and adds its `security` to every OpenAPI operation.
+- **`mount`** holds Express handlers that are not brisk routes. They answer only what brisk's routes did not, so a mount never shadows a route and `mount: { "/": spaFallback }` works as a fallback. Paths are absolute (the `prefix` does not apply) and must start with `/`; Express strips the path from `req.url`. brisk does not parse their bodies: add `express.json()` or `express.raw()` to the mount that needs one. Mounts get the request context (`getContext(req)`), `inject()` and the same error responses, and the startup log lists them as `MOUNT /path`.
+- **A route's `use`** (controller, group or route) holds middlewares for those routes only. Their output is typed on the handler's `ctx`.
+
+Controllers are declared before the app, so the output of a `defineMiddleware` in the app's `use` is not typed on handler `ctx`. To type it, list the middleware in the controller's `use` as well (it still runs once per request), or read it with `await middleware.run(ctx)`.
+
+brisk parses JSON only on its own routes. A form body parsed in the app's `use` reaches a brisk route's `body` schema.
+
+### Express middleware, static files, webhooks
+
+```ts
+import cors from "cors";
+import express from "express";
+
+export const app = defineApp({
+  controllers,
+  use: [
+    fromExpress(cors({ origin: env.WEB_ORIGIN })),
+    fromExpress(express.urlencoded({ extended: false })), // form bodies reach brisk `body` schemas
+  ],
+  mount: {
+    "/static": express.static("public"),
+    "/webhooks/stripe": [express.raw({ type: "application/json" }), stripeWebhook], // raw bytes for signatures
+  },
+});
+```
+
+### Uploads
+
+Parse multipart bodies on the route that takes them, after authentication, with `fromExpress`:
+
+```ts
+import { BadRequestError, defineController, fromExpress, inject } from "@raiyyan/brisk";
+import multer from "multer";
+
+const upload = fromExpress(multer({ dest: "uploads/", limits: { fileSize: 5_000_000 } }).single("file"));
+
+export const attachmentsController = defineController(
+  { prefix: "/tasks/:taskId/attachments", use: [authenticate] },
+  (route) => {
+    const attachments = inject(AttachmentsService);
+
+    return {
+      create: route.post("/", { use: [upload] }, ({ req, params }) => {
+        if (!req.file) throw new BadRequestError("Send the file in the `file` field");
+        return attachments.save(params.taskId, req.file);
+      }),
+    };
+  },
+);
+```
+
+An unauthenticated upload is rejected before multer reads a byte. Errors multer passes on reach `errors.mappers`, so a mapper can turn its file-size error into `PayloadTooLargeError`. Clients send the file with [`.raw`](#raw-responses) and a `FormData` body. Files written to local disk exist only on the instance that received them; use object storage when you run more than one.
+
+### 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] });
+```
+
+### Shared access rules
+
+Put authorization rules in a service, and call it from every entry point: the HTTP middleware, the WebSocket gateway and the GraphQL resolvers. Each one then enforces the same rules instead of its own copy.
+
+```ts
+// src/features/projects/project-access.ts
+import { ForbiddenError, inject, NotFoundError } from "@raiyyan/brisk";
+
+export type ProjectRole = "viewer" | "editor" | "owner";
+const RANK: Record<ProjectRole, number> = { viewer: 0, editor: 1, owner: 2 };
+
+/** Who may do what in a project. */
+export class ProjectAccess {
+  readonly #members = inject(MembersRepository);
+
+  /** The user's role in the project, or `undefined` when they are not a member. */
+  async roleIn(userId: string, projectId: string): Promise<ProjectRole | undefined> {
+    return (await this.#members.find(projectId, userId))?.role;
+  }
+
+  /** The user's role, or an error: 404 for a non-member, so project ids do not leak; 403 for too low a role. */
+  async require(userId: string, projectId: string, role: ProjectRole): Promise<ProjectRole> {
+    const actual = await this.roleIn(userId, projectId);
+    if (!actual) throw new NotFoundError("Project not found");
+    if (RANK[actual] < RANK[role]) throw new ForbiddenError(`Requires the ${role} role`);
+    return actual;
+  }
+}
+```
+
+HTTP routes use it through a middleware that declares the param it reads ([middleware that needs input](#middleware-that-needs-input)):
+
+```ts
+export const tasksController = defineController({ prefix: "/projects/:projectId/tasks" }, (route) => {
+  const tasks = inject(TasksService);
+
+  return {
+    list: route.get("/", { use: [requireProjectRole("viewer")] }, ({ params }) =>
+      tasks.list(params.projectId),
+    ),
+    create: route.post(
+      "/",
+      { use: [requireProjectRole("editor")], body: CreateTaskBody },
+      ({ params, body }) => tasks.create(params.projectId, body),
+    ),
+  };
+});
+```
+
+A WebSocket gateway resolves it in a class field, because `ws` callbacks run outside the app:
+
+```ts
+import type { IncomingMessage } from "node:http";
+import { HttpServer, inject, type OnDrain, type OnReady } from "@raiyyan/brisk";
+import { WebSocketServer, type WebSocket } from "ws";
+
+export class ProjectsGateway implements OnReady, OnDrain {
+  readonly #access = inject(ProjectAccess);
+  readonly #sessions = inject(Sessions);
+  #wss: WebSocketServer | undefined;
+
+  onReady() {
+    this.#wss = new WebSocketServer({ server: inject(HttpServer), path: "/ws" });
+    this.#wss.on("connection", (socket, req) => void this.#admit(socket, req));
+  }
+
+  async #admit(socket: WebSocket, req: IncomingMessage) {
+    const user = await this.#sessions.verify(req.headers.authorization);
+    const projectId = new URL(req.url ?? "/", "http://localhost").searchParams.get("projectId");
+    if (!user || !projectId || !(await this.#access.roleIn(user.id, projectId))) {
+      socket.close(4403, "forbidden");
+      return;
+    }
+    // subscribe the socket to the project's events
+  }
+
+  onDrain() {
+    for (const client of this.#wss?.clients ?? []) client.close(1001, "server shutting down");
+    this.#wss?.close();
+  }
+}
+```
+
+GraphQL resolvers call `inject(ProjectAccess).require(...)` (next section).
+
+### GraphQL with Yoga
+
+```ts
+// src/graphql.ts
+import { ErrorTranslator, inject, UnauthorizedError } from "@raiyyan/brisk";
+import type { Request, Response } from "express";
+import { GraphQLError } from "graphql";
+import { createSchema, createYoga } from "graphql-yoga";
+
+interface GraphQLContext {
+  user: User | undefined;
+}
+
+export const yoga = createYoga<{ req: Request; res: Response }, GraphQLContext>({
+  schema: createSchema<GraphQLContext>({
+    typeDefs: "type Query { project(id: ID!): Project } type Project { id: ID! name: String! }",
+    resolvers: {
+      Query: {
+        project: async (_parent, args: { id: string }, { user }) => {
+          if (!user) throw new UnauthorizedError("Sign in first");
+          await inject(ProjectAccess).require(user.id, args.id, "viewer");
+          return inject(ProjectsService).get(args.id);
+        },
+      },
+    },
+  }),
+  context: async ({ req }) => ({ user: await inject(Sessions).verify(req.get("authorization")) }),
+  maskError: (error) => {
+    if (error instanceof GraphQLError && !error.originalError) return error; // query syntax and validation errors
+    const cause = error instanceof GraphQLError ? error.originalError : error;
+    const { status, code, message } = inject(ErrorTranslator)(cause);
+    return new GraphQLError(message, { extensions: { code, status } });
+  },
+});
+```
+
+```ts
+// src/app.ts
+export const app = defineApp({
+  controllers,
+  mount: { [yoga.graphqlEndpoint]: (req, res) => yoga(req, res) },
+  http: { securityHeaders: { "content-security-policy": false } }, // GraphiQL loads scripts; or set a GraphiQL-compatible policy
+});
+```
+
+- Resolvers, the context factory and `maskError` call `inject()` directly: they run inside the request.
+- Mount Yoga through a function, as above: Yoga's own type is not an Express `RequestHandler`.
+- `maskError` gives GraphQL clients the same status, code and message a route would send: `errors.mappers` apply and internal messages stay hidden.
+
+### 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,
+  mount: { "/graphql": [express.json(), expressMiddleware(apollo)] },
+});
+```
+
+brisk does not parse mount bodies, so the Apollo mount 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,
+  mount: { "/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
+    },
+  },
+  use: [fromExpress(cors({ origin: env.SHELL_ORIGIN }))],
+  mount: { "/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 (to test them, see the 304 note under [Testing](#testing)).
+- 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. Your own in-process state (an in-memory event bus, files uploaded to local disk, an in-memory rate limit) does not span them; move it to shared services first.
+- 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`. It answers 503 once shutdown begins, so load balancers stop sending traffic. 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 `trust proxy` in `http.settings` only to match your proxy setup.
+- Add CORS with an explicit origin list and a rate limiter in the app's `use`.
+- 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.
+- Before running more than one instance, move in-process state to shared services: event buses, uploaded files on local disk and in-memory rate limits each see only their own instance.
+- 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. App-wide middleware goes in the app's `use` (`use: [fromExpress(helmet()), fromExpress(cors())]`). Middleware for some routes only, such as multer, goes in the route's `use` through `fromExpress(...)`.
+
+**Where do I put CORS?**
+In the app's `use`: `use: [fromExpress(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)