@raiyyan/brisk 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,467 @@
+# 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
+
+- New app: install `@raiyyan/brisk` (and `typescript`, `@types/node`, `vitest` as dev dependencies), then run `npx brisk init`. It creates `src/env.ts`, `src/app.ts` (`export const app = defineApp(...)` with prefix `/api`, and `export type Api = typeof app`), `src/main.ts` (`await app.listen(env.PORT)`), `src/features/index.ts`, `.env.example` and a `tsconfig.json` that lets Node run `.ts` directly. It never overwrites existing files, adds `"type": "module"` and missing `dev`, `start`, `typecheck`, `test` and `brisk` scripts, then runs `brisk agents`.
+- `brisk init` asks about each option, or takes flags: `--db none|sqlite|postgres` (a `Database` provider and a unique-violation mapper to 409 `ALREADY_EXISTS`; postgres uses `pg` + Drizzle), `--auth` (HS256 bearer tokens, `authenticate` and `requireRole` middlewares), `--docker`, `--ci` (GitHub Actions), `--web` (CORS, rate limiting, static `public/`, pretty dev logs), `--pm`, `--yes`/`-y` (defaults, no questions), `--no-install`. It installs missing packages with the detected package manager after writing files.
+- Then: `cp .env.example .env`, `pnpm brisk g feature <name>`, `pnpm 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:
+
+- `configureExpress(expressApp)`: full Express access, before JSON parsing and before brisk's routes.
+- `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
+
+```
+src/
+  env.ts                       defineEnv(...)
+  app.ts                       export const app = defineApp({...}); export type Api = typeof app
+  main.ts                      await app.listen(env.PORT)
+  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
+test/<name>.test.ts
+```
+
+Generate a feature with `pnpm brisk g feature <name>`; it writes the four files (singular entity names: `products` gives `Product`, `CreateProductBody`) and a test, registers the controller as `products: productsController` at the `// @brisk:imports` and `// @brisk:controllers` markers in `src/features/index.ts`, and runs the project's formatter (oxfmt or Prettier) on the result. `pnpm brisk g middleware <name>` writes a middleware. `pnpm brisk help` lists commands.
+
+## 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())`, so the client type and OpenAPI say `string` (`date-time`).
+
+## Middlewares
+
+- A middleware may not return `req`, `res`, `requestId`, `params`, `query`, `body` or `headers` (compile error). Returning `log` replaces the request logger.
+
+```ts
+export const authenticate = defineMiddleware(async ({ req }) => {
+  const user = await verify(req.get("authorization"));
+  if (!user) throw new UnauthorizedError("Invalid token", { challenge: "Bearer" });
+  return { user };
+});
+
+export const requireRole = (role: Role) =>
+  defineMiddleware(async (ctx) => {
+    const { user } = await authenticate.run(ctx);
+    if (user.role !== role) throw new ForbiddenError();
+    return { user };
+  });
+```
+
+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. Each middleware runs at most once per request: another middleware or a handler can `await other.run(ctx)` to reuse its result. Sync or async both work.
+
+## 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)] })`, or `createTestClient(app, { providers: [...] })` to replace them in a test.
+- 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 everything in `configureExpress` (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 -> configureExpress -> JSON body -> hooks.onRequest
+          -> controller/group/route middlewares -> Zod validation -> handler -> response -> hooks.onResponse
+          (any throw -> error handler -> hooks.onError)
+shutdown  SIGINT/SIGTERM -> 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
+```
+
+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" },
+  configureExpress: (expressApp) => expressApp.use(cors({ origin: env.WEB_ORIGIN })),
+});
+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`                            |
+| `configureExpress` | `(expressApp) => void` with full Express access, before JSON parsing and before brisk routes         |
+| `hooks`            | `onRequest`, `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, trustProxy, securityHeaders, healthPath, shutdownTimeoutMs }`                          |
+
+Name the `configureExpress` parameter `expressApp`: `app` would shadow the exported `app`.
+
+- `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 replace 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()`.
+- `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`                                       |
+| 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; every call accepts extra headers (such as `authorization`); a second argument is passed to `fetch` (`signal`).
+- 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())`).
+
+## 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` replace the app's own) 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.
+
+## Recipes
+
+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 (static files, SSE, uploads, webhooks, proxies) through `configureExpress`, which runs before JSON parsing:
+
+```ts
+export const app = defineApp({
+  controllers,
+  configureExpress: (expressApp) => {
+    expressApp.use(cors({ origin: env.WEB_ORIGIN }));
+    expressApp.use("/static", express.static("public"));
+    expressApp.post("/webhooks/stripe", express.raw({ type: "application/json" }), stripeWebhook);
+    expressApp.post("/upload", multer().single("file"), upload);
+    expressApp.use(express.urlencoded({ extended: false }));
+    expressApp.get("/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'" } },
+});
+```
+
+Requests there have a context (`getContext(req)`) and thrown errors use the app's error handler. A form body parsed there 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 call `inject()`:
+
+```ts
+const yoga = createYoga({
+  schema: createSchema({
+    typeDefs: "type Query { user(id: ID!): User }",
+    resolvers: { Query: { user: (_, { id }) => inject(UsersService).get(id) } },
+  }),
+});
+export const app = defineApp({
+  controllers,
+  configureExpress: (expressApp) => expressApp.use(yoga.graphqlEndpoint, yoga),
+  http: { securityHeaders: { "content-security-policy": false } }, // GraphiQL needs scripts; or set a GraphiQL-compatible policy
+});
+```
+
+GraphQL with Apollo Server. `configureExpress` runs before brisk's JSON parser, so the Apollo route adds `express.json()` itself:
+
+```ts
+await apollo.start();
+export const app = defineApp({
+  controllers,
+  configureExpress: (expressApp) =>
+    expressApp.use("/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,
+  configureExpress: (expressApp) => expressApp.use("/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 `configureExpress`. brisk's strict API headers block cross-origin asset loading, so relax them and allow the shell's origin:
+
+```ts
+export const app = defineApp({
+  controllers,
+  http: {
+    securityHeaders: {
+      "content-security-policy": false, // or your policy
+      "cross-origin-resource-policy": "cross-origin",
+      "x-frame-options": false, // only when the frontend is embedded in iframes
+    },
+  },
+  configureExpress: (expressApp) => {
+    expressApp.use(cors({ origin: env.SHELL_ORIGIN }));
+    expressApp.use("/remotes/checkout", express.static("dist/checkout"));
+  },
+});
+```
+
+A backend-for-frontend is 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. 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 plain Express pieces through `configureExpress`; don't add routes to `instance.express` afterwards (they would land after the 404 handler).
+- Do use `provide()` in tests to swap dependencies; 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.