@zmdb/web 1.0.0-beta.1

package/dist/pipeline/index.d.ts

@@ -0,0 +1,141 @@
+import '@zmdb/app';
+import type { Constructor } from '@zmdb/app/di';
+import type { Observability } from '@zmdb/app/observability';
+import { type QueryValues } from '../context/index.js';
+import type { CompiledHttpContract, SecurityRequirement } from '../contract/index.js';
+import type { Guard } from '../middleware/index.js';
+import { type VersionStrategy } from '../versioning/index.js';
+import { type GuardRegistry } from './guards.js';
+export type { Ctx } from '../context/index.js';
+export type { SecurityRequirement } from '../contract/index.js';
+export type { GuardRegistry } from './guards.js';
+/** A minimal, framework-neutral request. */
+export interface WebRequest {
+    readonly method: string;
+    readonly path: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly rawBody?: unknown;
+    readonly query?: QueryValues;
+    readonly scheme?: string;
+}
+/** A minimal, framework-neutral response body. */
+export type ResponseBody = {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'bytes';
+    readonly value: Uint8Array<ArrayBuffer>;
+} | {
+    readonly kind: 'stream';
+    readonly value: ReadableStream<Uint8Array<ArrayBuffer>>;
+    readonly length: number | undefined;
+};
+/** A minimal, framework-neutral response. */
+export interface WebResponse {
+    readonly status: number;
+    readonly body: ResponseBody;
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** Per-handler pipeline, guard and OpenAPI options. */
+export interface RouteOptions {
+    readonly validateBody?: (raw: unknown) => unknown;
+    readonly guards?: readonly Guard[];
+    readonly security?: readonly SecurityRequirement[];
+    readonly deprecated?: true;
+}
+/** Router-wide guard configuration shared with OpenAPI generation. */
+export interface RouterOptions extends Observability {
+    readonly guardRegistry?: GuardRegistry;
+    readonly versioning?: VersionStrategy;
+}
+/** Status and headers a response factory accepts. */
+export interface ResponseOptions {
+    readonly status?: number;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Options for a streamed response. */
+export interface StreamOptions extends ResponseOptions {
+    readonly length?: number;
+    readonly onError: (error: unknown) => void;
+}
+/** Options for a response streamed from a known file path. */
+export interface FileResponseOptions extends ResponseOptions {
+    readonly contentType?: string;
+    readonly onError: (error: unknown) => void;
+}
+/**
+ * A JSON response with an explicit status and/or extra headers.
+ *
+ * `return json(created, { status: 201, headers: { location } })`
+ */
+export declare function json(value: unknown, options?: ResponseOptions): WebResponse;
+/**
+ * A `text/plain` response, returned byte-for-byte as given.
+ *
+ * `return text(ctx.params.id)`
+ */
+export declare function text(body: string, options?: ResponseOptions): WebResponse;
+/**
+ * A response with full control and no assumed content type — for HTML, CSV, a
+ * redirect, or a `204` with no body. Nothing is added to `headers`, so set
+ * `content-type` yourself if the body has one.
+ *
+ * `return respond({ status: 302, headers: { location: '/login' } })`
+ */
+export declare function respond(init: {
+    readonly status?: number;
+    readonly body?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}): WebResponse;
+/** A byte response with no implicit content type. */
+export declare function bytes(value: Uint8Array<ArrayBuffer>, options?: ResponseOptions): WebResponse;
+/** A streaming response whose failures are reported exactly once. */
+export declare function stream(value: ReadableStream<Uint8Array<ArrayBuffer>>, options: StreamOptions): WebResponse;
+/** Stream one known file path. Path confinement belongs to the static-file handler. */
+export declare function file(path: string, options: FileResponseOptions): Promise<WebResponse>;
+/** Decode a response body for assertions and other in-process consumers. */
+export declare function bodyText(response: WebResponse): Promise<string>;
+export interface Router {
+    register(controller: object, options?: Readonly<Record<string, RouteOptions>>): void;
+    registerContract(contract: CompiledHttpContract, controllers: readonly object[], options?: Readonly<Record<string, Readonly<Record<string, RouteOptions>>>>): void;
+    registerDeferred(controller: Constructor<object>, instance: () => Promise<object>): void;
+    handle(req: WebRequest): Promise<WebResponse>;
+}
+/** Create a router. Routes and their effective guards are resolved once at register time. */
+export declare function createRouter(routerOptions?: RouterOptions): Router;
+interface NodeReqLike {
+    readonly method?: string;
+    readonly url?: string;
+    readonly headers: Readonly<Record<string, string | string[] | undefined>>;
+    readonly socket?: {
+        readonly encrypted?: boolean;
+    };
+    on(event: string, listener: (chunk: unknown) => void): void;
+    setEncoding?(encoding: string): void;
+}
+interface NodeResLike {
+    statusCode: number;
+    setHeader(name: string, value: string): void;
+    writeHead?(status: number, headers: Readonly<Record<string, string>>): unknown;
+    write(chunk: Uint8Array<ArrayBuffer>): boolean;
+    once(event: string, listener: () => void): void;
+    destroy(error?: Error): void;
+    end(body?: string | Uint8Array<ArrayBuffer>): void;
+}
+/** Request-body limits shared by the Node and Fetch adapters. */
+export interface AdapterOptions {
+    readonly maxBodyBytes: number;
+}
+/**
+ * Adapt a router to a node:http `(req, res)` handler.
+ *
+ * This is the path real consumers take, so its per-request cost is the
+ * framework's real cost. The benchmark harness hand-writes its responses and so
+ * never measured this; when it was measured (keep-alive on, 8 workers, c=256,
+ * median of 5) the adapter served 294,067 req/s against the hand-written app's
+ * 395,983 — 1.35x slower, entirely in the four things below.
+ */
+export declare function toNodeHandler(router: Router, options?: AdapterOptions): (req: NodeReqLike, res: NodeResLike) => void;
+/** Adapt a router to a Fetch `(Request) => Promise<Response>` handler. */
+export declare function toFetchHandler(router: Router, options?: AdapterOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pipeline/index.ts"],"names":[],"mappings":"AAKA,OAAO,WAAW,CAAC;AAInB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,yBAAyB,CAAC;AAG3E,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,oBAAoB,EAAmB,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEvG,OAAO,KAAK,EAAE,KAAK,EAAsB,MAAM,wBAAwB,CAAC;AAExE,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,YAAY,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,4CAA4C;AAC5C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,kDAAkD;AAClD,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,CAAA;CAAE,GACnE;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,CAAC;AAEN,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,KAAK,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;CAC5B;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;CACvC;AA6gBD,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,uCAAuC;AACvC,MAAM,WAAW,aAAc,SAAQ,eAAe;IACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C;AAED,8DAA8D;AAC9D,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C;AAaD;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,WAAW,CAM/E;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,WAAW,CAM7E;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD,GAAG,WAAW,CAEd;AAED,qDAAqD;AACrD,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,EAAE,OAAO,GAAE,eAAoB,GAAG,WAAW,CAMhG;AAED,qEAAqE;AACrE,wBAAgB,MAAM,CAAC,KAAK,EAAE,cAAc,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,GAAG,WAAW,CAa1G;AAED,uFAAuF;AACvF,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CAuB3F;AAED,4EAA4E;AAC5E,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CASrE;AAiFD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,GAAG,IAAI,CAAC;IACrF,gBAAgB,CACd,QAAQ,EAAE,oBAAoB,EAC9B,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,GACzE,IAAI,CAAC;IACR,gBAAgB,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACzF,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC/C;AAED,6FAA6F;AAC7F,wBAAgB,YAAY,CAAC,aAAa,GAAE,aAAkB,GAAG,MAAM,CAimBtE;AA0HD,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACnD,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAC5D,WAAW,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AACD,UAAU,WAAW;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC;IAC/E,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC;IAC/C,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAChD,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;CACpD;AAED,iEAAiE;AACjE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAyD,GACjE,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,KAAK,IAAI,CA6D9C;AAsKD,0EAA0E;AAC1E,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,cAAyD,GACjE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAgCzC"}