@raiyyan/brisk 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,535 @@
+# Building apps with brisk
+
+Guide for AI coding agents working in an app that depends on `@raiyyan/brisk`. brisk is a thin, typed layer over Express 5 and Zod: Express stays fully reachable, and brisk removes the wiring (validation, DTOs, errors, typed context, env, DI, lifecycle).
+
+```ts
+import { defineApp, defineController, inject, z, NotFoundError } from "@raiyyan/brisk";
+import { createTestClient, readError } from "@raiyyan/brisk/testing";
+import { ApiError, createClient } from "@raiyyan/brisk/client"; // browser-safe: no server code
+```
+
+`@raiyyan/brisk/di` and `@raiyyan/brisk/errors` are narrower entries; everything in them is also exported from `@raiyyan/brisk`.
+
+`z` is re-exported Zod 4. Use it so schemas and brisk use the same Zod. Requires Node 24 or later. `pino-pretty` is an optional peer dependency: install it to use `createLogger({ pretty: true })`.
+
+Full documentation: https://github.com/MohammadRaiyyan/brisk#readme
+
+## Starting a project
+
+- brisk owns mechanisms (routing, validation, DI, lifecycle, errors, typed client, OpenAPI, test client, template rendering). Choices (database, auth scheme, lint and format tools, Docker, CI, folder layout, pagination shape) live in the project: in the starter it began from and in its own `templates/`. Follow the project's existing choices; do not look for them in brisk.
+- New app: install `@raiyyan/brisk`, then `npx brisk init [--starter <name>] [--pm pnpm|npm|yarn] [--no-install]`. Starters: `minimal` (default; in-memory feature template, no database) and `sqlite-auth` (`node:sqlite` with migrations at startup, scrypt passwords, HS256 bearer tokens, admin seeded from env, CORS, rate limit, static files, Dockerfile and compose). `--starter list` lists them.
+- `brisk init` copies the starter without overwriting any file, merges `type`, `engines`, scripts and dependencies into `package.json` (pinning brisk to the running version), installs, and runs `brisk agents`. There are no other init flags.
+- Both starters ship oxlint and oxfmt (`lint`, `format`, `format:check` scripts), `typecheck`, `test`, `dev`, and a deletable `notes` example feature.
+- `src/schemas.ts` in a starter holds `isoDate()`, `PageQuery` and `page(item)`. They are project code, not brisk exports.
+- Then: `cp .env.example .env`, `npx brisk g feature <name>`, `npm run dev`.
+- `npx brisk agents` adds or refreshes a brisk section (between `<!-- brisk:start -->` and `<!-- brisk:end -->`) in the project's `AGENTS.md` and makes `CLAUDE.md` import `@AGENTS.md` and `@node_modules/@raiyyan/brisk/AGENTS.md`. Run it again after upgrading brisk.
+
+## 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. The escape hatches:
+
+- `use: [fromExpress(cors()), ...]` in `defineApp`: any Express middleware for every request, before brisk's routes (after `/health` and `/openapi.json`, so it never blocks them).
+- `mount: { "/path": handler }` in `defineApp`: Express handlers that are not brisk routes (static files, GraphQL, tRPC, webhooks, a legacy router, a SPA fallback). They answer only what brisk's routes did not.
+- `http.settings`: Express app settings (`{ "trust proxy": 1 }`, `{ "query parser": "extended" }`).
+- `fromExpress(handler)`: any Express middleware in one route's `use`, in order with brisk's middlewares.
+- `instance.express`: the Express app itself (for adapters; serverless uses `app.create()`).
+- `instance.server` and the `HttpServer` token: the Node server, for WebSockets and timeouts.
+- `ListenOptions.server`: bring your own server (HTTPS, tuned timeouts).
+- Provider lifecycle (`OnInit`, `OnReady`, `OnDrain`, `OnShutdown`): run anything alongside HTTP.
+- `app.start()`: the same app without HTTP, for workers and schedulers.
+- `ctx.res`: write a raw response from any handler.
+
+## Project layout and generators
+
+```
+src/
+  env.ts                       defineEnv(...)
+  app.ts                       export const app = defineApp({...}); export type Api = typeof app
+  main.ts                      await app.listen(env.PORT)
+  schemas.ts                   isoDate(), PageQuery, page(item)
+  middlewares/<name>.ts        defineMiddleware(...)
+  features/
+    index.ts                   export const controllers = { users: usersController }  (keep the @brisk markers)
+    <name>/
+      <name>.schema.ts         Zod request and response schemas
+      <name>.repository.ts     data access only
+      <name>.service.ts        business rules, throws error classes
+      <name>.controller.ts     defineController(...): HTTP only, delegates to the service
+templates/<kind>/              what `brisk g <kind> <name>` renders; owned by the project
+test/<name>.test.ts
+```
+
+- Create new code with `npx brisk g <kind> <name>` (`feature`, `middleware`, or any folder in `templates/`), then edit it. When the project's conventions change, change the templates too.
+- `brisk g` renders `templates/<kind>/` into the project root. Tokens in paths and contents: `{{kebab}}` (`blog-posts`), `{{camel}}` (`blogPosts`), `{{pascal}}` (`BlogPosts`), `{{snake}}` (`blog_posts`), `{{entity}}` (`BlogPost`), `{{entityCamel}}` (`blogPost`).
+- A template file named `<target>.<marker>.insert` is inserted into the existing `<target>` before the line containing `@brisk:<marker>`: `// @brisk:imports` and `// @brisk:controllers` in `src/features/index.ts`, `// @brisk:migrations` in `sqlite-auth`'s `src/database/migrations.ts`. Never delete marker lines.
+- Everything is checked before anything is written: an unknown token, an existing file or a missing marker fails with nothing changed. Output is formatted with the project's oxfmt, prettier or biome when installed.
+- Keep `templates/` out of lint, format, typecheck and tests (the starters' configs do).
+
+## Environment
+
+```ts
+export const env = defineEnv({
+  PORT: z.coerce.number().int().positive().default(3000),
+  DATABASE_URL: z.url(),
+});
+```
+
+Loads `.env` if present, validates `process.env`, returns a frozen typed object. Invalid config prints every problem and exits (throws under `NODE_ENV=test`, or when `{ source }` is passed).
+
+## Controllers
+
+```ts
+export const usersController = defineController({ prefix: "/users", use: [authenticate] }, (route) => {
+  const users = inject(UsersService);
+
+  return {
+    me: route.get("/me", { response: UserResponse }, ({ user }) => users.get(user.id)),
+    get: route.get("/:id", { params: UserIdParams, response: UserResponse }, ({ params }) =>
+      users.get(params.id),
+    ),
+    admin: route.group("/", { use: [requireRole("admin")] }, (admin) => ({
+      create: admin.post("/", { body: CreateUserBody, response: UserResponse }, ({ body }) =>
+        users.create(body),
+      ),
+      remove: admin.delete("/:id", { params: UserIdParams }, ({ params }) => {
+        users.remove(params.id);
+      }),
+    })),
+  };
+});
+```
+
+- Always return every route by name from `setup`. The names are the typed client (`api.users.get`, `api.users.admin.create`) and the OpenAPI `operationId` (`users.admin.create`). If `setup` returns an object that leaves out a declared route, building an instance fails. A `setup` that returns nothing works but its controller is missing from the typed client.
+- Methods: `route.get | post | put | patch | delete`, each `(path, handler)` or `(path, options, handler)`, each returning the route. `route.group(path, setup)` or `route.group(path, { use }, setup)` nests routes and returns what its `setup` returns.
+- Options: `params`, `query`, `body`, `headers` (Zod schemas; validated values are typed on `ctx`), `response` (Zod schema; the result is parsed through it so unlisted fields never leak, and the handler's return type is checked against it), `use` (route middlewares, after the controller's and group's), `status` (2xx or 3xx only; throw an error class for failures).
+- Without a `params` schema, path params are typed from the full path: `"/:orgId/users/:id"` gives `{ orgId: string; id: string }`, `"/files/*path"` gives `{ path: string[] }`, `"/posts{/:slug}"` gives `{ slug?: string }`. A `params` schema must list every param of the full path, prefix included, or it is stripped.
+- Express matches routes in declaration order: declare wildcard and optional-segment routes after the specific routes they would catch.
+- Params, query and env values are strings. Booleans: `z.stringbool()`, never `z.coerce.boolean()` (it makes `"false"` true). Async refinements are supported.
+- Handler context: `req`, `res`, `requestId`, `log` (request logger carrying the request id), every middleware's output, and `params`, `query`, `body`, `headers`. Destructure what you need.
+- The return value is the response:
+  - `undefined`: 204 (or `status`)
+  - a Node `Readable`: streamed with backpressure
+  - a `Buffer` / `Uint8Array`: sent as bytes
+  - anything else: JSON, through `response` when set
+  - success status: 201 for POST, 200 otherwise; `res.status(code)` in the handler overrides the default, and the `status` option overrides both
+  - writing to `res` yourself also works; brisk then sends nothing.
+- `setup` runs once per instance, when it is built (`listen`, `start`, `create`, `createTestClient`); `inject()` works there and in handlers. Configuration errors (a route left out of the returned object, an invalid `status`) are thrown then, not at `defineApp`.
+- Dates in a `response` schema: `z.date().transform((d) => d.toISOString()).pipe(z.iso.datetime())` (the starters' `isoDate()`), so the client type and OpenAPI say `string` (`date-time`).
+- Two routes with the same method and path (parameter names aside) fail when an instance is built.
+- `defineController({ prefix, use, providers })`: `providers` are created at startup with the app (a feature's WebSocket gateway, cache invalidator). They come before the app's providers, so the app's and tests' values for the same token win.
+
+## Middlewares
+
+`defineMiddleware(fn)` or `defineMiddleware({ params?, query?, security? }, fn)`. There is no name argument.
+
+```ts
+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 requireProjectRole = (role: ProjectRole) =>
+  defineMiddleware({ params: z.object({ projectId: z.uuid() }), security: bearer }, async (ctx) => {
+    const { user } = await authenticate.run(ctx);
+    return { projectRole: await inject(ProjectAccess).require(user.id, ctx.params.projectId, role) };
+  });
+```
+
+- Return an object to add typed fields to the handler's `ctx`, return nothing for a pure check, throw an error class to stop the request. Sync or async.
+- Each middleware runs at most once per request: another middleware or a handler can `await other.run(ctx)` to reuse its result.
+- A middleware may not return `req`, `res`, `requestId`, `params`, `query`, `body` or `headers` (compile error). Returning `log` replaces the request logger.
+- Order: controller `use`, group `use`, route `use`, then the route's validation. Authentication therefore rejects before input is validated.
+- `params` / `query` options: validated before the middleware runs (400 `VALIDATION_FAILED`, async refinements work) and typed on its ctx. Use them for per-resource authorization such as project membership.
+- `security`: OpenAPI security scheme objects. Every route behind the middleware gets `security` in OpenAPI and the document gets `components.securitySchemes`; routes without it stay public. `middleware.security` reads it back.
+- `fromExpress(handler)` runs Express middleware inside `use`, in order: `use: [authenticate, fromExpress(multer(...).single("file"))]` parses uploads only after authentication. Errors passed to `next` reach the app's error handler (`http-errors` `status`/`expose` honored, `errors.mappers` apply); if it ends the response, the route stops there.
+- App-wide middleware (CORS, helmet, rate limits, an audit log) goes in the app's `use`: `defineApp({ use: [fromExpress(cors({ origin })), audit] })`. A `defineMiddleware` there runs once per request, stops it by throwing, and adds its `security` to every OpenAPI operation, but its output is not typed on handler ctx: to type it, list it in the controller's `use` as well (it still runs once), or read it with `await audit.run(ctx)`.
+
+## Dependency injection
+
+- A class with a no-argument constructor is its own token and a singleton per app: `readonly #repo = inject(UsersRepository)` in a field.
+- `defineToken<T>(name, factory?)` names anything else: config, clients, functions. Without a factory it must be provided.
+- `provide(token, value)` fixes a value: `defineApp({ providers: [provide(Clock, () => fixedDate)] })`. Later entries win; the order is controllers' providers, the app's, then those passed to `createTestClient` / `listen` / `start` / `create`. Those last are added to the app's, not swapped in: a value for the same token wins, and every listed class is still created.
+- A class listed in `providers` is created at boot even if nothing injects it (WebSocket gateways, consumers, jobs) so its lifecycle hooks run.
+- `injectLazy(token)` returns `() => T` and creates on first call: for heavy clients or to break a circular dependency.
+- `inject()` works in class fields, token factories, controller setup, middlewares, handlers, lifecycle hooks, and timers or loops started from them. Cycles are reported as `A -> B -> A`.
+- `inject()` works for the whole request, including the app's `use` and every `mount` (GraphQL resolvers, tRPC procedures). It does not work in callbacks a library fires on its own outside a request (gRPC handlers, queue client callbacks, `ws` message listeners): resolve the dependency in a class field and use the field. Outside the app, use an instance's container: `instance.container.get(...)`. In unit tests with `new Container([...])`, call `container.get(...)`.
+- `HttpServer` exists only once the instance listens: inject it in `onReady`, never in a field or `onInit` (that throws).
+- Unit tests without HTTP: `new Container([provide(Clock, fake)]).get(UsersService)`. `Logger` has a silent default there, so no logger provider is needed.
+
+## Lifecycle
+
+```
+boot      providers' onInit (dependencies first) -> listen -> providers' onReady
+request   security headers -> request id -> /health, /openapi.json -> app use
+          -> brisk route: JSON body -> controller/group/route middlewares -> Zod validation -> handler -> response
+          -> 405 / OPTIONS -> mount -> 404
+          (any throw -> error handler -> hooks.onError; hooks.onResponse when the response closes)
+shutdown  SIGINT/SIGTERM -> /health answers 503 -> stop accepting -> providers' onDrain (reverse)
+          -> in-flight requests finish with Connection: close (sockets still open after http.shutdownTimeoutMs are destroyed)
+          -> providers' onShutdown (reverse) -> exit 0
+crash     unhandled rejection / uncaught exception -> logged fatal -> shutdown -> exit 1
+startup failure (a hook throws, port taken) -> logged fatal "startup failed" with provider and hook -> shutdown -> rethrown
+```
+
+Implement `OnInit`, `OnReady`, `OnDrain`, `OnShutdown` on a provider class. `onDrain` is where long-lived work stops (close WebSockets and SSE, stop consumers and timers); `onShutdown` releases resources (database pools, clients). Hook failures are logged and shutdown continues. All hooks may be sync or async.
+
+## The app
+
+```ts
+// src/app.ts: declares the app; nothing runs at import time
+export const app = defineApp({
+  prefix: "/api",
+  controllers, // { users: usersController }, from src/features/index.ts
+  providers: [AdminSeed],
+  logger: createLogger({ level: env.LOG_LEVEL, pretty: env.NODE_ENV === "development" }),
+  openapi: { title: "Shop API", version: "1.0.0" },
+  errors: { mappers: [uniqueViolation], exposeInternal: env.NODE_ENV === "development" },
+  use: [fromExpress(cors({ origin: env.WEB_ORIGIN }))],
+  mount: { "/static": express.static("public", { maxAge: "1h" }) },
+});
+export type Api = typeof app;
+
+// src/main.ts
+await app.listen(env.PORT);
+```
+
+| Option        | Purpose                                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------------------ |
+| `prefix`      | Mount path for all controllers, such as `/api`                                                         |
+| `controllers` | Controllers by name: `{ users: usersController }`; the names are the typed client's top level          |
+| `providers`   | `provide(token, value)` entries and classes to create at startup                                       |
+| `logger`      | A pino logger (`createLogger({ level, pretty })`); injectable as `Logger`                              |
+| `use`         | Middlewares for every request after `/health` and `/openapi.json`, before brisk's routes and mounts    |
+| `mount`       | `{ "/path": handler \| [handlers] }`: Express handlers that answer what brisk's routes did not         |
+| `hooks`       | `onResponse`, `onError` only; startup and shutdown work goes in provider classes                       |
+| `openapi`     | `{ title, version, description?, servers?, path? }`: serve the OpenAPI document                        |
+| `errors`      | `{ mappers, format, exposeInternal }`: translate library errors, change the error body, dev messages   |
+| `http`        | `{ bodyLimit, settings, securityHeaders, healthPath, shutdownTimeoutMs }`; health is 503 when draining |
+
+Mounts: paths are absolute (the `prefix` does not apply) and start with `/`; Express strips the path from `req.url`. brisk does not parse their bodies, so add a parser to the mount when it needs one (`[express.json(), handler]`). They get `getContext(req)`, `inject()`, the app's `use` and the error handler, and appear in the startup log as `MOUNT /path`. A mount never shadows a brisk route, so `mount: { "/": spaFallback }` is a fallback. brisk parses JSON only on its own routes.
+
+`http.settings` is applied with `app.set(name, value)` after brisk's defaults: `{ "trust proxy": 1 }` only behind a proxy you control, `{ "query parser": "extended" }` for nested query objects (the default is flat).
+
+- `app.listen(port, { host?, server?, manageProcess?, providers? })` builds a fresh instance, starts it and resolves with it. `app.start({ manageProcess?, providers? })` does the same without HTTP (workers). `app.create({ providers? })` returns an unstarted instance (serverless: `const instance = app.create(); await instance.init();`, then hand `instance.express` to the adapter).
+- Every call builds a new, independent instance; `providers` there are added after the app's own.
+- `app.manifest` and `app.openapi()` work on the definition, without starting anything.
+- The instance: `express`, `server`, `container`, `logger`, `manifest`, `openapi()`, `init()`, `shutdown()`.
+- `inject(ErrorTranslator)(error)` returns `{ status, code, message, details }` as a route would answer, `errors.mappers` applied and internal messages hidden: for GraphQL `maskError` or WebSocket close codes. Call it directly inside a request (resolvers, mounts), resolve it in a class field for library callbacks (`ws` message listeners), and use `instance.container.get(ErrorTranslator)` outside the app.
+- `manageProcess` (default `true`) installs signal and crash handling.
+
+## Errors
+
+Throw from anywhere; never catch just to respond.
+
+| Class                       | Status | Extra                                                              |
+| --------------------------- | ------ | ------------------------------------------------------------------ |
+| `BadRequestError`           | 400    |                                                                    |
+| `UnauthorizedError`         | 401    | `{ challenge }` sends `WWW-Authenticate`                           |
+| `ForbiddenError`            | 403    |                                                                    |
+| `NotFoundError`             | 404    |                                                                    |
+| `MethodNotAllowedError`     | 405    | `(allowed, message?)` sends `Allow`                                |
+| `NotAcceptableError`        | 406    |                                                                    |
+| `RequestTimeoutError`       | 408    |                                                                    |
+| `ConflictError`             | 409    |                                                                    |
+| `GoneError`                 | 410    |                                                                    |
+| `PreconditionFailedError`   | 412    |                                                                    |
+| `PayloadTooLargeError`      | 413    |                                                                    |
+| `UnsupportedMediaTypeError` | 415    |                                                                    |
+| `UnprocessableEntityError`  | 422    |                                                                    |
+| `TooManyRequestsError`      | 429    | `{ retryAfter }` sends `Retry-After`                               |
+| `InternalServerError`       | 500    | message is sent; put details in `cause`                            |
+| `NotImplementedError`       | 501    |                                                                    |
+| `BadGatewayError`           | 502    |                                                                    |
+| `ServiceUnavailableError`   | 503    | `{ retryAfter }` sends `Retry-After`                               |
+| `GatewayTimeoutError`       | 504    |                                                                    |
+| `ValidationError`           | 400    | `(location, issues)` or `ValidationError.fromZod(error, location)` |
+| `HttpError`                 | any    | `(status, message, options)`                                       |
+
+Every class takes `(message?, { code?, details?, cause?, headers? })`; `code` defaults from the status (`NOT_FOUND`). Domain errors are subclasses:
+
+```ts
+export class EmailTakenError extends ConflictError {
+  constructor(email: string) {
+    super("Email already registered", { code: "EMAIL_TAKEN", details: { email } });
+  }
+}
+```
+
+Error body: `{ "error": { "code", "message", "details", "requestId" } }`.
+
+Handled automatically:
+
+| Situation                                       | Response                                                           |
+| ----------------------------------------------- | ------------------------------------------------------------------ |
+| Invalid params, query, body or headers          | 400 `VALIDATION_FAILED`, `details.issues[{ path, message, code }]` |
+| `ZodError` thrown anywhere in app code          | 400 `VALIDATION_FAILED`, `location: "input"`                       |
+| Malformed JSON                                  | 400 `INVALID_JSON`                                                 |
+| Body over `http.bodyLimit`                      | 413 `PAYLOAD_TOO_LARGE`                                            |
+| Body sent to a `body` route that no parser read | 415 `UNSUPPORTED_MEDIA_TYPE`                                       |
+| Express middleware error with `status`+`expose` | that status; the message only when `expose` is true                |
+| Known path, wrong method                        | 405 with `Allow`; `OPTIONS` gets 204 with `Allow`                  |
+| Unknown path                                    | 404 `ROUTE_NOT_FOUND`                                              |
+| Result breaks its `response` schema             | 500 (a server bug)                                                 |
+| Anything else                                   | 500 generic message; full error and cause logged                   |
+
+## Typed client
+
+- `createClient(app, { baseUrl })` in Node (the definition or an instance); in a browser `createClient<Api>(manifest, { baseUrl, headers?, fetch? })` from `@raiyyan/brisk/client`, with the manifest written by `brisk client --out web/src/api.manifest.ts` (run it again after changing routes). `Api` is `typeof app` (`export type Api = typeof app` in `src/app.ts`), imported with `import type`.
+- Calls: `await api.users.get({ params, query, body, headers })`. Inputs are typed by the route's schemas; `params` and `query` also take the schema's output when a URL carries it (`z.stringbool()` takes `true`, `z.coerce.number()` takes `2`). Every call accepts extra headers (such as `authorization`); a second argument is passed to `fetch` (`signal`).
+- `FormData`, `Blob`, `URLSearchParams`, `ArrayBuffer`/typed arrays and `ReadableStream` bodies are sent as they are (fetch sets the content type and multipart boundary); other bodies, strings included, are JSON.
+- `api.files.upload.raw(input, init?)` sends the same request and resolves to the raw `Response` whatever its status, with the client's headers applied and string bodies sent as they are: for downloads, uploads (`body: formData`) and non-JSON. Its body type is `RawBody` or the route's body.
+- A call resolves to the `response` schema's output, else the handler's return value after JSON (`Date` becomes `string`); a stream or bytes come back as the raw `Response`, nothing as `undefined`.
+- Non-2xx rejects with `ApiError` (`status`, `code`, `message`, `details`, `requestId`, `body`). Branch on `error.code`, not the message.
+
+## OpenAPI
+
+- `defineApp({ openapi: { title, version, description?, servers?, path? } })` serves an OpenAPI 3.1 document at `/openapi.json` (`path: false` serves nothing). `app.openapi()` returns it; `brisk openapi --out openapi.json` writes it.
+- `operationId` is `controller.route`, tags are controller names; request schemas are documented as clients send them, `response` as clients receive it.
+- Transforms and `z.date()` are documented as "any": end response schemas in the type they produce (`.pipe(z.iso.datetime())`).
+- Routes behind a middleware with `security` list its schemes; the document lists them under `components.securitySchemes`.
+- `/openapi.json` and `/health` are answered before the app's `use`.
+
+## Testing
+
+```ts
+import { app } from "../src/app.ts";
+
+const api = await createTestClient(app, { providers: [provide(Clock, () => new Date("2026-01-01"))] });
+afterAll(() => api.close());
+
+it("validates the body", async () => {
+  const res = await api.post("/api/users", { headers: { authorization: "Bearer t" }, body: { email: "x" } });
+  expect(res.status).toBe(400);
+  expect(readError(res).details).toMatchObject({ location: "body" });
+});
+```
+
+`createTestClient(app, { providers? })` starts a fresh instance on a random port with the full lifecycle (`providers` are added after the app's own; a value for the same token wins) and returns `call` (the typed client: `await api.call.users.create({ body, headers })`, rejecting with `ApiError`), raw `get | post | put | patch | delete(path, { body, headers })`, `baseUrl`, `instance` (the running `AppInstance`: `api.instance.container.get(X)`) and `close()`. Use `call` for behavior and the raw methods for status codes, headers and malformed input. A raw string or `Uint8Array` body is sent as is. `res.body` is `unknown`: parse it with Zod or use `toMatchObject`. `readError(res)` returns the typed error object.
+
+`fetch`, and so the test client's raw methods, adds `Cache-Control: no-cache` to a request carrying `If-None-Match`, which disables 304. Test 304s with `node:http`, or send `cache-control: max-age=0`.
+
+## Recipes
+
+Shared access rules: put the rules in one service and call it from every entry point (the middleware with declared `params` above, WebSocket gateways, GraphQL resolvers). Never re-implement them per transport.
+
+```ts
+export class ProjectAccess {
+  readonly #members = inject(MembersRepository);
+  async roleIn(userId: string, projectId: string): Promise<ProjectRole | undefined> {
+    return (await this.#members.find(projectId, userId))?.role;
+  }
+  /** 404 for a non-member (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;
+  }
+}
+```
+
+A gateway resolves it in a class field (`readonly #access = inject(ProjectAccess)`), because `ws` callbacks run outside the app; a resolver calls `inject(ProjectAccess).require(...)`.
+
+Uploads: parse multipart on the route that takes it, after authentication. Clients send it with `.raw` and a `FormData` body:
+
+```ts
+const upload = fromExpress(multer({ dest: "uploads/", limits: { fileSize: 5_000_000 } }).single("file"));
+// in a controller with use: [authenticate]
+create: route.post("/:taskId/attachments", { use: [upload] }, ({ req, params }) => {
+  if (!req.file) throw new BadRequestError("Send the file in the `file` field");
+  return attachments.save(params.taskId, req.file);
+}),
+```
+
+WebSocket gateway (`ws`, works the same with Socket.IO):
+
+```ts
+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] });
+```
+
+Plain Express (CORS, static files, SSE, webhooks, form bodies) through `use` and `mount`:
+
+```ts
+export const app = defineApp({
+  controllers,
+  use: [fromExpress(cors({ origin: env.WEB_ORIGIN })), fromExpress(express.urlencoded({ extended: false }))],
+  mount: {
+    "/static": express.static("public"),
+    "/webhooks/stripe": [express.raw({ type: "application/json" }), stripeWebhook], // raw bytes for signatures
+    "/events": (req, res) => {
+      res.writeHead(200, { "content-type": "text/event-stream" });
+      res.write(`data: ${getContext(req).requestId}\n\n`);
+    },
+  },
+  http: { securityHeaders: { "content-security-policy": "default-src 'self'" } },
+});
+```
+
+Mounts have a context (`getContext(req)`) and thrown errors use the app's error handler. A form body parsed in `use` reaches a brisk route's `body` schema.
+
+Worker thread pool for CPU-heavy work:
+
+```ts
+export class ImagePool implements OnInit, OnShutdown {
+  #worker: Worker | undefined;
+  onInit() {
+    this.#worker = new Worker(new URL("./resize.worker.ts", import.meta.url));
+  }
+  run(input: Job): Promise<Result> {
+    /* postMessage and await the reply */
+  }
+  async onShutdown() {
+    await this.#worker?.terminate();
+  }
+}
+```
+
+Scheduled job: start the timer in `onReady` (`inject()` works inside it), clear it in `onDrain`, list the class in `providers`.
+
+Queue consumer, in its own process with the same code and providers:
+
+```ts
+// worker.ts
+await defineApp({ providers: [EmailConsumer] }).start(); // no controllers, no HTTP; signals and graceful shutdown still apply
+```
+
+In `onDrain`, stop taking messages and await the one in progress.
+
+Caching: Express ETags and 304s work automatically for GET; set `Cache-Control` with `res.set(...)` in the handler. A Redis client is a provider: connect in `onInit`, quit in `onShutdown`.
+
+Lazy loading: `injectLazy(HeavyClient)` defers creation; heavy code loads on demand with `const { PdfService } = await import("./pdf.service.ts"); inject(PdfService).render(...)` inside a handler.
+
+Database clients: a class with `async onInit()` that connects and `onShutdown()` that disconnects. Translate driver errors once with `errors.mappers` (for example unique violation to `ConflictError`).
+
+GraphQL with Yoga. Resolvers, the context factory and `maskError` call `inject()`. Mount it through a function (Yoga's own type is not an Express `RequestHandler`):
+
+```ts
+export const yoga = createYoga<{ req: Request; res: Response }, { user: User | undefined }>({
+  schema, // resolvers: inject(ProjectAccess).require(user.id, args.id, "viewer"), then the service
+  context: async ({ req }) => ({ user: await inject(Sessions).verify(req.get("authorization")) }),
+  maskError: (error) => {
+    if (error instanceof GraphQLError && !error.originalError) return error; // 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 } });
+  },
+});
+export const app = defineApp({
+  controllers,
+  mount: { [yoga.graphqlEndpoint]: (req, res) => yoga(req, res) },
+  http: { securityHeaders: { "content-security-policy": false } }, // GraphiQL needs scripts; or set a GraphiQL-compatible policy
+});
+```
+
+GraphQL with Apollo Server. brisk does not parse mount bodies, so the mount adds `express.json()`:
+
+```ts
+await apollo.start();
+export const app = defineApp({
+  controllers,
+  mount: { "/graphql": [express.json(), expressMiddleware(apollo, { context })] },
+});
+```
+
+tRPC. Procedures call `inject()`, and tRPC v11 accepts Zod schemas directly:
+
+```ts
+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 }) },
+});
+```
+
+gRPC with `@grpc/grpc-js` runs on its own HTTP/2 port, as in any Node app (this recipe is not covered by brisk's test suite):
+
+```ts
+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] });
+```
+
+Socket.IO: `this.#io = new Server(inject(HttpServer))` in `onReady`, `await this.#io.close()` in `onDrain`, and list the class in `providers`.
+
+Microfrontends and serving frontends: serve static assets and remote entries with `express.static` in `mount`. 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 just brisk controllers calling upstream services; throw `BadGatewayError` for bad upstream answers and `GatewayTimeoutError` for timeouts.
+
+Custom or HTTPS server: `await app.listen(443, { server: https.createServer(tlsOptions) })`. Inside providers use `inject(HttpServer)` from `onReady`.
+
+Serverless: `const instance = app.create(); await instance.init();`, then pass `instance.express` to the platform adapter.
+
+Cluster, PM2, Kubernetes: brisk keeps no per-process state; run one process per core. The app's own in-process state (event buses, uploads on local disk, in-memory rate limits) does not span instances: move it to shared services first. `/health` answers 503 once shutdown begins. Behind a load balancer set `server.keepAliveTimeout` above the balancer's idle timeout (via `instance.server` on the instance `listen` resolves with, or your own server) to avoid 502s. Bind `host: "0.0.0.0"` in containers when needed.
+
+## Do and don't
+
+- Do return every route by name from a controller's setup; the names are the typed client and the OpenAPI operation ids.
+- Do throw error classes from services; don't wrap handlers in try/catch and don't call `next()`.
+- Do destructure what you need from `ctx` (`({ params, user, log }) => ...`) rather than copying the whole context.
+- Do keep services and repositories free of Express types; take plain values, return plain values.
+- Do give every route that takes input a schema, and a `response` schema for anything returning stored data.
+- Do add app-wide middleware through the app's `use`, non-brisk handlers through `mount`, and per-route Express middleware through `fromExpress` in a route's `use`; don't add routes to `instance.express` afterwards (they would land after the 404 handler).
+- Do generate new features and middlewares with `brisk g`, and update `templates/` when conventions change; don't hand-copy a feature.
+- Do keep authorization rules in a service shared by middlewares, gateways and resolvers.
+- Do use `provide()` in tests to swap dependencies (test providers are added after the app's own); don't mutate singletons.
+- Do declare the app once (`export const app = defineApp(...)`) and import it everywhere; each `listen`, `start`, `create` or `createTestClient` builds its own instance. Don't write a `buildApp()` factory.
+- Do put long-lived connections behind `onDrain`, and resources behind `onShutdown`. Startup and shutdown work lives in provider classes; `defineApp({ hooks })` is per-request only.
+- Don't call `inject()` inside callbacks a library fires on its own (`ws` message listeners, gRPC handlers, queue clients); resolve the dependency in a class field.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Raiyyan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.