@raiyyan/brisk 0.0.0-stage → 0.2.0

package/dist/src/http/validation.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { ValidationError } from "../errors/http-errors.js";
+/**
+ * Zod parsing shared by routes and middlewares. Every parse is synchronous, the fast path, unless a schema has
+ * async refinements: then it switches to `safeParseAsync` and the value comes back wrapped in {@link Pending}.
+ */
+/** An input whose schema needs async validation; never a value a schema can produce. */
+export class Pending {
+    promise;
+    constructor(promise) {
+        this.promise = promise;
+    }
+}
+export const settle = (value) => (value instanceof Pending ? value.promise : value);
+export function parseInput(schema, value, location) {
+    if (!schema)
+        return value;
+    const input = value ?? {};
+    const result = safeParse(schema, input);
+    if (result instanceof Promise)
+        return new Pending(result.then((settled) => unwrapInput(settled, location)));
+    return unwrapInput(result, location);
+}
+function unwrapInput(result, location) {
+    if (result.success)
+        return result.data;
+    throw ValidationError.fromZod(result.error, location);
+}
+/** A result that breaks its own response schema is a server bug: a 500, never a 400. */
+export function serializeOutput(schema, value) {
+    if (!schema)
+        return value;
+    const result = safeParse(schema, value);
+    return result instanceof Promise ? result.then(unwrapOutput) : unwrapOutput(result);
+}
+function unwrapOutput(result) {
+    if (result.success)
+        return result.data;
+    throw new Error(`Response does not match its schema:\n${z.prettifyError(result.error)}`);
+}
+export function safeParse(schema, value) {
+    try {
+        return schema.safeParse(value);
+    }
+    catch (error) {
+        if (error instanceof z.core.$ZodAsyncError)
+            return schema.safeParseAsync(value);
+        throw error;
+    }
+}
+//# sourceMappingURL=validation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/http/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;GAGG;AAEH,wFAAwF;AACxF,MAAM,OAAO,OAAO;IACT,OAAO,CAAmB;IACnC,YAAY,OAAyB;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,KAAc,EAAW,EAAE,CAAC,CAAC,KAAK,YAAY,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAEtG,MAAM,UAAU,UAAU,CAAC,MAA6B,EAAE,KAAc,EAAE,QAAgB;IACxF,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,MAAM,KAAK,GAAG,KAAK,IAAI,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACxC,IAAI,MAAM,YAAY,OAAO;QAAE,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC5G,OAAO,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,WAAW,CAAC,MAAqC,EAAE,QAAgB;IAC1E,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IACvC,MAAM,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AACxD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,eAAe,CAAC,MAA6B,EAAE,KAAc;IAC3E,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACxC,OAAO,MAAM,YAAY,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,YAAY,CAAC,MAAqC;IACzD,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IACvC,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,MAAiB,EACjB,KAAc;IAEd,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,cAAc;YAAE,OAAO,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAChF,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * brisk: a typed layer over Express 5 and Zod. This entry exports the whole server API. Narrower entries:
+ * `@raiyyan/brisk/di`, `@raiyyan/brisk/errors`, `@raiyyan/brisk/testing`, and the browser-safe
+ * `@raiyyan/brisk/client`.
+ *
+ * @module
+ */
+export { defineApp, type App, type AppHooks, type AppInstance, type AppOptions, type ControllerMap, type CreateOptions, type ErrorOptions, type HttpOptions, type ListenOptions, type StartOptions, } from "./http/app.ts";
+export type { OpenApiOptions } from "./http/openapi.ts";
+export { HttpServer, type NodeServer } from "./http/server.ts";
+export { Container, defineToken, inject, injectLazy, provide, type InjectionToken, type Class, type OnDrain, type OnInit, type OnReady, type OnShutdown, type Provider, type ProviderEntry, type Token, } from "./di/index.ts";
+export { getContext, type RequestContext } from "./http/context.ts";
+export { defineController, type Controller, type ControllerOptions, type GroupOptions, type RouteBuilder, type RouteContext, type RouteOptions, } from "./http/controller.ts";
+export type { PathParams } from "./http/path-params.ts";
+export type { ApiOf, Client, HttpMethod, Jsonify, Manifest, Route, Routes } from "./http/routes.ts";
+export { defineEnv, type DefineEnvOptions } from "./config/env.ts";
+export { defaultErrorFormatter, ErrorTranslator, type ErrorFormatter, type ErrorMapper, } from "./http/error-handler.ts";
+export * from "./errors/index.ts";
+export { createLogger, Logger, type LoggerOptions } from "./config/logger.ts";
+export { defineMiddleware, fromExpress, type Middleware, type MiddlewareContext, type MiddlewareInput, type MiddlewareOptions, type SecurityScheme, type SecuritySchemes, } from "./http/middleware.ts";
+export { z } from "zod";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,SAAS,EACT,KAAK,GAAG,EACR,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EACL,SAAS,EACT,WAAW,EACX,MAAM,EACN,UAAU,EACV,OAAO,EACP,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,OAAO,EACZ,KAAK,MAAM,EACX,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,KAAK,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EACL,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,GACjB,MAAM,yBAAyB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,19 @@
+/**
+ * brisk: a typed layer over Express 5 and Zod. This entry exports the whole server API. Narrower entries:
+ * `@raiyyan/brisk/di`, `@raiyyan/brisk/errors`, `@raiyyan/brisk/testing`, and the browser-safe
+ * `@raiyyan/brisk/client`.
+ *
+ * @module
+ */
+export { defineApp, } from "./http/app.js";
+export { HttpServer } from "./http/server.js";
+export { Container, defineToken, inject, injectLazy, provide, } from "./di/index.js";
+export { getContext } from "./http/context.js";
+export { defineController, } from "./http/controller.js";
+export { defineEnv } from "./config/env.js";
+export { defaultErrorFormatter, ErrorTranslator, } from "./http/error-handler.js";
+export * from "./errors/index.js";
+export { createLogger, Logger } from "./config/logger.js";
+export { defineMiddleware, fromExpress, } from "./http/middleware.js";
+export { z } from "zod";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,SAAS,GAWV,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,UAAU,EAAmB,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EACL,SAAS,EACT,WAAW,EACX,MAAM,EACN,UAAU,EACV,OAAO,GAUR,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAuB,MAAM,mBAAmB,CAAC;AACpE,OAAO,EACL,gBAAgB,GAOjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,SAAS,EAAyB,MAAM,iBAAiB,CAAC;AACnE,OAAO,EACL,qBAAqB,EACrB,eAAe,GAGhB,MAAM,yBAAyB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAsB,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EACL,gBAAgB,EAChB,WAAW,GAOZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC"}

package/dist/src/testing/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Test helpers: boot an app on a random port with `createTestClient`, read error bodies with `readError`.
+ *
+ * @module
+ */
+export { createTestClient, readError, type TestClient, type TestRequest, type TestResponse, } from "./test-client.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC"}

package/dist/src/testing/index.js

@@ -0,0 +1,7 @@
+/**
+ * Test helpers: boot an app on a random port with `createTestClient`, read error bodies with `readError`.
+ *
+ * @module
+ */
+export { createTestClient, readError, } from "./test-client.js";
+//# sourceMappingURL=index.js.map

package/dist/src/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,gBAAgB,EAChB,SAAS,GAIV,MAAM,kBAAkB,CAAC"}

package/dist/src/testing/test-client.d.ts

@@ -0,0 +1,67 @@
+import type { ErrorResponse } from "../errors/http-errors.ts";
+import type { App, AppInstance, CreateOptions } from "../http/app.ts";
+import type { ApiOf, Client } from "../http/routes.ts";
+/** A response from a {@link TestClient} raw request. */
+export interface TestResponse {
+    status: number;
+    headers: Headers;
+    /** Parsed JSON for JSON responses (including `+json` types), text otherwise, `undefined` when empty. */
+    body: unknown;
+}
+/** Body and headers for a {@link TestClient} raw request. */
+export interface TestRequest {
+    /**
+     * Sent as JSON, except a string or `Uint8Array`, which is sent as is (for raw webhook payloads or forms).
+     * `content-type` defaults to `application/json` whenever there is a body; set it in `headers` to override.
+     */
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+type Send = (path: string, request?: TestRequest) => Promise<TestResponse>;
+/**
+ * A client for an instance started by {@link createTestClient}. Its type argument is the app:
+ * `TestClient<typeof app>`: the typed client as `call`, and raw requests
+ * by path for checking status codes, headers and malformed input.
+ */
+export interface TestClient<A = unknown> {
+    readonly baseUrl: string;
+    /** The running instance, for its `container` or `server`. */
+    readonly instance: AppInstance;
+    /** The typed client: `await api.call.users.get({ params: { id } })`. Rejects with `ApiError` on non-2xx. */
+    readonly call: Client<ApiOf<A>>;
+    get: Send;
+    post: Send;
+    put: Send;
+    patch: Send;
+    delete: Send;
+    /** Shuts the instance down gracefully. */
+    close(): Promise<void>;
+}
+/**
+ * Starts a fresh instance of the app on a random local port, with its full lifecycle, and returns a client for
+ * it. `providers` are added after the app's own: a value for the same token wins, so fakes replace real
+ * services, and a class is created alongside the app's. `close()` shuts the instance down gracefully.
+ *
+ * @example
+ * ```ts
+ * const api = await createTestClient(app, { providers: [provide(Clock, () => fixedDate)] });
+ *
+ * const user = await api.call.users.create({ body: { email: "a@b.co" }, headers: admin }); // typed
+ * const res = await api.post("/api/users", { body: { email: "nope" }, headers: admin });   // raw
+ * expect(res.status).toBe(400);
+ *
+ * await api.close();
+ * ```
+ */
+export declare function createTestClient<A extends App>(app: A, options?: CreateOptions): Promise<TestClient<A>>;
+/**
+ * Reads the error out of a response, failing the test when the body is not an error response.
+ *
+ * @example
+ * ```ts
+ * expect(readError(await api.get("/api/users/nope"))).toMatchObject({ code: "NOT_FOUND" });
+ * ```
+ */
+export declare function readError(response: TestResponse): ErrorResponse["error"];
+export {};
+//# sourceMappingURL=test-client.d.ts.map

package/dist/src/testing/test-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-client.d.ts","sourceRoot":"","sources":["../../../src/testing/test-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEvD,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,wGAAwG;IACxG,IAAI,EAAE,OAAO,CAAC;CACf;AAED,6DAA6D;AAC7D,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAKD,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,4GAA4G;IAC5G,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,IAAI,CAAC;IACV,KAAK,EAAE,IAAI,CAAC;IACZ,MAAM,EAAE,IAAI,CAAC;IACb,0CAA0C;IAC1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,SAAS,GAAG,EAClD,GAAG,EAAE,CAAC,EACN,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CA0CxB;AAWD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,YAAY,GAAG,aAAa,CAAC,OAAO,CAAC,CAExE"}

package/dist/src/testing/test-client.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { createClient } from "../client/client.js";
+/** `application/json`, and structured suffixes such as `application/problem+json`. */
+const JSON_TYPE = /^application\/(?:[\w.-]+\+)?json\b/i;
+/**
+ * Starts a fresh instance of the app on a random local port, with its full lifecycle, and returns a client for
+ * it. `providers` are added after the app's own: a value for the same token wins, so fakes replace real
+ * services, and a class is created alongside the app's. `close()` shuts the instance down gracefully.
+ *
+ * @example
+ * ```ts
+ * const api = await createTestClient(app, { providers: [provide(Clock, () => fixedDate)] });
+ *
+ * const user = await api.call.users.create({ body: { email: "a@b.co" }, headers: admin }); // typed
+ * const res = await api.post("/api/users", { body: { email: "nope" }, headers: admin });   // raw
+ * expect(res.status).toBe(400);
+ *
+ * await api.close();
+ * ```
+ */
+export async function createTestClient(app, options = {}) {
+    const instance = await app.listen(0, { ...options, host: "127.0.0.1", manageProcess: false });
+    const address = instance.server?.address();
+    if (!address || typeof address === "string")
+        throw new Error("Expected a TCP server address");
+    const baseUrl = `http://127.0.0.1:${address.port}`;
+    const send = (method) => async (path, request = {}) => {
+        const payload = request.body;
+        const res = await fetch(baseUrl + path, {
+            method,
+            headers: payload === undefined
+                ? { ...request.headers }
+                : { "content-type": "application/json", ...request.headers },
+            body: payload === undefined
+                ? null
+                : typeof payload === "string"
+                    ? payload
+                    : payload instanceof Uint8Array
+                        ? new Uint8Array(payload)
+                        : JSON.stringify(payload),
+        });
+        const text = await res.text();
+        const isJson = JSON_TYPE.test(res.headers.get("content-type") ?? "");
+        const body = text === "" ? undefined : isJson ? JSON.parse(text) : text;
+        return { status: res.status, headers: res.headers, body };
+    };
+    return {
+        baseUrl,
+        instance,
+        call: createClient(instance.manifest, { baseUrl }),
+        get: send("GET"),
+        post: send("POST"),
+        put: send("PUT"),
+        patch: send("PATCH"),
+        delete: send("DELETE"),
+        close: () => instance.shutdown(),
+    };
+}
+const ErrorBody = z.object({
+    error: z.object({
+        code: z.string(),
+        message: z.string(),
+        details: z.unknown().optional(),
+        requestId: z.string(),
+    }),
+});
+/**
+ * Reads the error out of a response, failing the test when the body is not an error response.
+ *
+ * @example
+ * ```ts
+ * expect(readError(await api.get("/api/users/nope"))).toMatchObject({ code: "NOT_FOUND" });
+ * ```
+ */
+export function readError(response) {
+    return ErrorBody.parse(response.body).error;
+}
+//# sourceMappingURL=test-client.js.map

package/dist/src/testing/test-client.js.map

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

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "@raiyyan/brisk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "A small, typed, opinionated layer over Express 5 and Zod: validation, DI, lifecycle and errors without the boilerplate.",
+  "keywords": [
+    "api",
+    "dependency-injection",
+    "express",
+    "framework",
+    "typescript",
+    "validation",
+    "zod"
+  ],
+  "homepage": "https://github.com/MohammadRaiyyan/brisk#readme",
+  "bugs": {
+    "url": "https://github.com/MohammadRaiyyan/brisk/issues"
+  },
+  "license": "MIT",
+  "author": "Mohammad Raiyyan <inforaiyyan@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MohammadRaiyyan/brisk.git",
+    "directory": "packages/brisk"
+  },
+  "bin": {
+    "brisk": "./dist/bin/brisk.js"
+  },
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE",
+    "starters"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./di": {
+      "types": "./dist/src/di/index.d.ts",
+      "default": "./dist/src/di/index.js"
+    },
+    "./errors": {
+      "types": "./dist/src/errors/index.d.ts",
+      "default": "./dist/src/errors/index.js"
+    },
+    "./testing": {
+      "types": "./dist/src/testing/index.d.ts",
+      "default": "./dist/src/testing/index.js"
+    },
+    "./client": {
+      "types": "./dist/src/client/index.d.ts",
+      "default": "./dist/src/client/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@types/express": "^5.0.6",
+    "express": "^5.3.0",
+    "pino": "^10.4.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@trpc/server": "^11.28.1",
+    "@types/ws": "^8.18.2",
+    "graphql": "^17.1.0",
+    "graphql-yoga": "^6.1.0",
+    "pino-pretty": "^13.2.0",
+    "ws": "^8.23.0"
+  },
+  "peerDependencies": {
+    "pino-pretty": "^13.2.0"
+  },
+  "peerDependenciesMeta": {
+    "pino-pretty": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  }
 }

package/starters/minimal/.env.example

@@ -0,0 +1,3 @@
+NODE_ENV=development
+PORT=3000
+LOG_LEVEL=info

package/starters/minimal/.oxfmtrc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 110,
+  "ignorePatterns": ["templates", "node_modules", "coverage"]
+}

package/starters/minimal/.oxlintrc.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "import", "unicorn", "oxc", "vitest"],
+  "categories": {
+    "correctness": "error",
+    "suspicious": "warn"
+  },
+  "rules": {
+    "typescript/no-floating-promises": "error",
+    "typescript/no-misused-promises": "error",
+    "import/no-cycle": "error"
+  },
+  "ignorePatterns": ["templates", "node_modules", "coverage"]
+}

package/starters/minimal/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+<!-- brisk:start -->
+
+## Building with brisk
+
+This app uses [brisk](https://www.npmjs.com/package/@raiyyan/brisk), a typed layer over Express 5 and Zod.
+Before writing or changing server code, read the full guide: `node_modules/@raiyyan/brisk/AGENTS.md`.
+
+Essentials:
+
+- The app is declared once in `src/app.ts` with `defineApp`; `app.listen(port)` runs it, `createTestClient(app, { providers })` tests it.
+- Routes are named: a controller's setup returns `{ list: route.get(...), create: route.post(...) }`. The names form the typed client (`api.users.create({ body })`).
+- Validate every input with a Zod schema on the route; set `response` to a DTO schema so internal fields never leak.
+- New code follows this project's own templates: `npx brisk g feature <name>` renders `templates/feature/`. Edit the templates when the project's conventions change.
+- Dependencies: `readonly #repo = inject(Repository)` in class fields. No decorators, no constructor wiring.
+- Errors: `throw new NotFoundError("…")` (or another error class) anywhere. Never try/catch to build responses; never call `next()`.
+- Shared request logic: `defineMiddleware` returning an object types `ctx`; declare `params` or `query` it reads to get them validated first. Express middleware such as multer goes in a route's `use` through `fromExpress()`.
+- App-wide middleware goes in `defineApp({ use })` (`fromExpress(cors())` included); handlers that are not brisk routes (static files, GraphQL, webhooks) go in `defineApp({ mount })`. Express settings go in `http.settings`.
+- Long-lived work (WebSockets, jobs, consumers, pools) is a provider class with `onInit`, `onReady`, `onDrain`, `onShutdown`; a feature lists its own in `defineController({ providers })`.
+- Test with `createTestClient` from `@raiyyan/brisk/testing`: `api.call.<controller>.<route>(input)` is typed; `api.post(path)` checks raw HTTP.
+
+<!-- brisk:end -->

package/starters/minimal/CLAUDE.md

@@ -0,0 +1,2 @@
+@AGENTS.md
+@node_modules/@raiyyan/brisk/AGENTS.md

package/starters/minimal/README.md

@@ -0,0 +1,53 @@
+# minimal
+
+An API built with [brisk](https://github.com/MohammadRaiyyan/brisk) on Express 5 and Zod. It has no database: the example feature keeps its records in memory. Created with `npx brisk init` (the `minimal` starter).
+
+## Run it
+
+```bash
+cp .env.example .env
+npm run dev
+```
+
+The API listens on port 3000 under `/api`. `GET /health` is the health check and `GET /openapi.json` the OpenAPI document.
+
+| Script                    | What it does                               |
+| ------------------------- | ------------------------------------------ |
+| `dev`                     | Runs the server and restarts it on changes |
+| `start`                   | Runs the server                            |
+| `test`                    | Runs the tests (vitest)                    |
+| `typecheck`               | Checks types (`tsc --noEmit`)              |
+| `lint`                    | oxlint                                     |
+| `format` / `format:check` | oxfmt                                      |
+| `brisk g <kind> <name>`   | Generates code from `templates/<kind>/`    |
+
+Node 24 or later runs the TypeScript sources directly; there is no build step.
+
+## Layout
+
+| Path             | What it holds                                                                               |
+| ---------------- | ------------------------------------------------------------------------------------------- |
+| `src/env.ts`     | Environment variables, validated at startup                                                 |
+| `src/app.ts`     | The app: controllers, logger, OpenAPI, error settings. `export type Api` for a typed client |
+| `src/main.ts`    | Starts the server                                                                           |
+| `src/schemas.ts` | Shared schema helpers: `isoDate()`, `PageQuery`, `page(item)`                               |
+| `src/features/`  | One folder per feature (schema, repository, service, controller), registered in `index.ts`  |
+| `templates/`     | What `brisk g` renders: `feature` and `middleware`. Yours to edit                           |
+| `test/`          | HTTP tests with `createTestClient`, and service tests without HTTP                          |
+
+## Add a feature
+
+```bash
+npx brisk g feature products
+```
+
+This writes `src/features/products/`, its tests, and registers the controller in `src/features/index.ts` (keep the `@brisk:` marker lines there). The repository stores records in a `Map`; replace it with your database and the service does not change.
+
+`npx brisk g middleware tenant` writes `src/middlewares/tenant.ts`. To change what new code looks like, edit the files in `templates/`; any folder you add there becomes a new `brisk g` kind.
+
+The `notes` feature is an example generated from `templates/feature`. Delete `src/features/notes/`, `test/notes.test.ts`, `test/notes.service.test.ts` and its two lines in `src/features/index.ts` when you no longer need it.
+
+## Learn more
+
+- [brisk documentation](https://github.com/MohammadRaiyyan/brisk#readme)
+- `AGENTS.md` and `CLAUDE.md` point coding agents at the brisk guide (`npx brisk agents` refreshes them).

package/starters/minimal/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+.env
+coverage

package/starters/minimal/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "starter-minimal",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch src/main.ts",
+    "start": "node src/main.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "brisk": "brisk",
+    "lint": "oxlint --type-aware",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check"
+  },
+  "dependencies": {
+    "@raiyyan/brisk": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "oxfmt": "^0.78.0",
+    "oxlint": "^1.93.0",
+    "oxlint-tsgolint": "^7.0.2007",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/starters/minimal/src/app.ts

@@ -0,0 +1,14 @@
+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: `createClient<Api>(manifest, { baseUrl })`. */
+export type Api = typeof app;

package/starters/minimal/src/env.ts

@@ -0,0 +1,7 @@
+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),
+  LOG_LEVEL: z.enum(["fatal", "error", "warn", "info", "debug", "trace", "silent"]).default("info"),
+});

package/starters/minimal/src/features/index.ts

@@ -0,0 +1,8 @@
+import { notesController } from "./notes/notes.controller.ts";
+// @brisk:imports
+
+/** Every controller by name. The names are the typed client's top level: `api.notes.get(...)`. */
+export const controllers = {
+  notes: notesController,
+  // @brisk:controllers
+};

package/starters/minimal/src/features/notes/notes.controller.ts

@@ -0,0 +1,38 @@
+import { defineController, inject } from "@raiyyan/brisk";
+import { page } from "../../schemas.ts";
+import {
+  CreateNoteBody,
+  NoteIdParams,
+  NoteResponse,
+  ListNotesQuery,
+  UpdateNoteBody,
+} from "./notes.schema.ts";
+import { NotesService } from "./notes.service.ts";
+
+export const notesController = defineController({ prefix: "/notes" }, (route) => {
+  const notes = inject(NotesService);
+
+  return {
+    list: route.get("/", { query: ListNotesQuery, response: page(NoteResponse) }, ({ query }) =>
+      notes.list(query),
+    ),
+
+    get: route.get("/:id", { params: NoteIdParams, response: NoteResponse }, ({ params }) =>
+      notes.get(params.id),
+    ),
+
+    create: route.post("/", { body: CreateNoteBody, response: NoteResponse }, ({ body }) =>
+      notes.create(body),
+    ),
+
+    update: route.patch(
+      "/:id",
+      { params: NoteIdParams, body: UpdateNoteBody, response: NoteResponse },
+      ({ params, body }) => notes.update(params.id, body),
+    ),
+
+    remove: route.delete("/:id", { params: NoteIdParams }, async ({ params }) => {
+      await notes.remove(params.id);
+    }),
+  };
+});

package/starters/minimal/src/features/notes/notes.repository.ts

@@ -0,0 +1,36 @@
+export interface Note {
+  id: string;
+  name: string;
+  createdAt: Date;
+}
+
+/**
+ * In-memory storage behind an async interface, the shape a database gives: swap the map for your database and
+ * the service does not change. Rows are lost on restart.
+ */
+export class NotesRepository {
+  readonly #rows = new Map<string, Note>();
+
+  async list({ page, limit }: { page: number; limit: number }): Promise<{ items: Note[]; total: number }> {
+    const rows = [...this.#rows.values()].toReversed();
+    return { items: rows.slice((page - 1) * limit, page * limit), total: rows.length };
+  }
+
+  async findById(id: string): Promise<Note | undefined> {
+    return this.#rows.get(id);
+  }
+
+  async insert(row: Note): Promise<Note> {
+    this.#rows.set(row.id, row);
+    return row;
+  }
+
+  async update(row: Note): Promise<Note> {
+    this.#rows.set(row.id, row);
+    return row;
+  }
+
+  async delete(id: string): Promise<boolean> {
+    return this.#rows.delete(id);
+  }
+}