@getsoda/core 0.2.2 → 0.3.0

package/dist/http/sse.js

@@ -0,0 +1,89 @@
+/**
+ * @module
+ * Server-sent events: a route decorated with `@Sse()` returns an async
+ * iterable of messages, streamed as `text/event-stream`, as Nest's `@Sse()`
+ * streams an observable.
+ *
+ * ```ts
+ * @Sse('ticks')
+ * async *ticks(): AsyncGenerator<SseMessage> {
+ *   for (let i = 0; ; i++) {
+ *     yield { data: { tick: i } }
+ *     await Bun.sleep(1000)
+ *   }
+ * }
+ * ```
+ *
+ * When the client disconnects, the iterator is returned: a generator runs its
+ * `finally` blocks. An error thrown while streaming ends the stream and is logged.
+ */
+/** Headers of Nest's SSE responses: no caching, no buffering by nginx. */
+const SSE_HEADERS = [
+    ['content-type', 'text/event-stream'],
+    ['cache-control', 'private, no-cache, no-store, must-revalidate, max-age=0, no-transform'],
+    ['x-accel-buffering', 'no'],
+];
+const NEWLINE = /\r\n|\r|\n/;
+const encoder = new TextEncoder();
+const assertSingleLine = (name, value) => {
+    if (NEWLINE.test(value)) {
+        throw new TypeError(`SSE ${name} must not contain line breaks: ${JSON.stringify(value)}`);
+    }
+};
+/** A message in the event stream format, one `data:` line per line of data. */
+export const formatSseMessage = (message) => {
+    const data = typeof message.data === 'string' ? message.data : JSON.stringify(message.data);
+    let text = '';
+    if (message.event !== undefined) {
+        assertSingleLine('event', message.event);
+        text += `event: ${message.event}\n`;
+    }
+    if (message.id !== undefined) {
+        assertSingleLine('id', message.id);
+        text += `id: ${message.id}\n`;
+    }
+    if (message.retry !== undefined) {
+        text += `retry: ${Math.trunc(message.retry)}\n`;
+    }
+    for (const line of (data ?? '').split(NEWLINE)) {
+        text += `data: ${line}\n`;
+    }
+    return `${text}\n`;
+};
+const isAsyncIterable = (value) => typeof value === 'object' && value !== null && Symbol.asyncIterator in value;
+/**
+ * Creates the function streaming what an `@Sse()` route returns. `headers`
+ * come from `@Header()`; errors while streaming go to `onError`.
+ */
+export const createSseResponder = (headers, onError) => {
+    const init = { status: 200, headers: [...SSE_HEADERS, ...headers] };
+    return (value, ctx) => {
+        if (!isAsyncIterable(value)) {
+            throw new TypeError(`${ctx.route.controller.name}.${ctx.route.handler} is an @Sse() route: it must return an async iterable`);
+        }
+        const iterator = value[Symbol.asyncIterator]();
+        const body = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const next = await iterator.next();
+                    if (next.done === true) {
+                        controller.close();
+                    }
+                    else {
+                        controller.enqueue(encoder.encode(formatSseMessage(next.value)));
+                    }
+                }
+                catch (error) {
+                    onError(error, ctx.req);
+                    controller.close();
+                }
+            },
+            // The client went away: let the source clean up.
+            async cancel() {
+                await iterator.return?.();
+            },
+        });
+        return new Response(body, init);
+    };
+};
+//# sourceMappingURL=sse.js.map

package/dist/http/sse.js.map

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

package/dist/index.d.ts

@@ -36,4 +36,5 @@ export * from './di/index.ts';
 export * from './http/index.ts';
 export * from './logger/index.ts';
 export * from './routing/index.ts';
+export * from './websocket/index.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA"}

package/dist/index.js

@@ -36,4 +36,5 @@ export * from './di/index.js';
 export * from './http/index.js';
 export * from './logger/index.js';
 export * from './routing/index.js';
+export * from './websocket/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,sBAAsB,CAAA"}

package/dist/openapi/decorators.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module
+ * Decorators describing routes in the OpenAPI document, as `@nestjs/swagger` does.
+ */
+import type { ClassOrMethodDecorator } from '../http/enhancers.ts';
+import type { StandardSchemaV1 } from '../http/schema.ts';
+export interface ApiOperationOptions {
+    readonly summary?: string;
+    readonly description?: string;
+    readonly deprecated?: boolean;
+}
+export interface ApiResponseOptions {
+    readonly description: string;
+    /** Schema of the JSON body; needs a library implementing Standard JSON Schema, such as zod. */
+    readonly schema?: StandardSchemaV1;
+}
+/** Summary, description and deprecation of an operation. */
+export declare const ApiOperation: (options: ApiOperationOptions) => ClassOrMethodDecorator;
+/** Tags grouping operations, on a controller or a method (which wins). */
+export declare const ApiTags: (...names: string[]) => ClassOrMethodDecorator;
+/**
+ * Responses of an operation, by status. Without it, the operation has the
+ * status of its route (`200`, `201` for `POST`, or `@HttpCode()`).
+ *
+ * ```ts
+ * @ApiResponses({ 200: { description: 'The user', schema: User }, 404: { description: 'No such user' } })
+ * ```
+ */
+export declare const ApiResponses: (byStatus: Readonly<Record<number, ApiResponseOptions>>) => ClassOrMethodDecorator;
+/** Operations need `Authorization: Bearer <token>`, as `JwtGuard` reads. */
+export declare const ApiBearerAuth: () => ClassOrMethodDecorator;
+/** Leaves a controller or a method out of the document. */
+export declare const ApiExclude: () => ClassOrMethodDecorator;
+export declare const KEYS: {
+    readonly operation: symbol;
+    readonly tags: symbol;
+    readonly responses: symbol;
+    readonly bearer: symbol;
+    readonly exclude: symbol;
+};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/openapi/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/openapi/decorators.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEzD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAA;CACnC;AAQD,4DAA4D;AAC5D,eAAO,MAAM,YAAY,YAAa,mBAAmB,KAAG,sBAA4C,CAAA;AAExG,0EAA0E;AAC1E,eAAO,MAAM,OAAO,aAAc,MAAM,EAAE,KAAG,sBAAqC,CAAA;AAElF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,aAAc,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,KAAG,sBAA6C,CAAA;AAEnI,4EAA4E;AAC5E,eAAO,MAAM,aAAa,QAAO,sBAAsC,CAAA;AAEvE,2DAA2D;AAC3D,eAAO,MAAM,UAAU,QAAO,sBAAuC,CAAA;AAErE,eAAO,MAAM,IAAI;aAAK,SAAS;aAAiB,IAAI;aAAY,SAAS;aAAiB,MAAM;aAAc,OAAO;CAAwB,CAAA"}

package/dist/openapi/decorators.js

@@ -0,0 +1,29 @@
+/**
+ * @module
+ * Decorators describing routes in the OpenAPI document, as `@nestjs/swagger` does.
+ */
+import { createDecorator } from '../http/enhancers.js';
+const operation = createDecorator('ApiOperation');
+const tags = createDecorator('ApiTags');
+const responses = createDecorator('ApiResponses');
+const bearer = createDecorator('ApiBearerAuth');
+const exclude = createDecorator('ApiExclude');
+/** Summary, description and deprecation of an operation. */
+export const ApiOperation = (options) => operation(options);
+/** Tags grouping operations, on a controller or a method (which wins). */
+export const ApiTags = (...names) => tags(names);
+/**
+ * Responses of an operation, by status. Without it, the operation has the
+ * status of its route (`200`, `201` for `POST`, or `@HttpCode()`).
+ *
+ * ```ts
+ * @ApiResponses({ 200: { description: 'The user', schema: User }, 404: { description: 'No such user' } })
+ * ```
+ */
+export const ApiResponses = (byStatus) => responses(byStatus);
+/** Operations need `Authorization: Bearer <token>`, as `JwtGuard` reads. */
+export const ApiBearerAuth = () => bearer(true);
+/** Leaves a controller or a method out of the document. */
+export const ApiExclude = () => exclude(true);
+export const KEYS = { operation: operation.key, tags: tags.key, responses: responses.key, bearer: bearer.key, exclude: exclude.key };
+//# sourceMappingURL=decorators.js.map

package/dist/openapi/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../src/openapi/decorators.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAgBtD,MAAM,SAAS,GAAG,eAAe,CAAsB,cAAc,CAAC,CAAA;AACtE,MAAM,IAAI,GAAG,eAAe,CAAoB,SAAS,CAAC,CAAA;AAC1D,MAAM,SAAS,GAAG,eAAe,CAA+C,cAAc,CAAC,CAAA;AAC/F,MAAM,MAAM,GAAG,eAAe,CAAU,eAAe,CAAC,CAAA;AACxD,MAAM,OAAO,GAAG,eAAe,CAAU,YAAY,CAAC,CAAA;AAEtD,4DAA4D;AAC5D,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAA4B,EAA0B,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;AAExG,0EAA0E;AAC1E,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,GAAG,KAAe,EAA0B,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAElF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAsD,EAA0B,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;AAEnI,4EAA4E;AAC5E,MAAM,CAAC,MAAM,aAAa,GAAG,GAA2B,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;AAEvE,2DAA2D;AAC3D,MAAM,CAAC,MAAM,UAAU,GAAG,GAA2B,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;AAErE,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,EAAW,CAAA"}

package/dist/openapi/document.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module
+ * Building an OpenAPI 3.1 document from the routes of an application.
+ *
+ * Schemas come from what validates requests: argument parsers (`int()`,
+ * `uuid()`...) and Standard Schemas implementing Standard JSON Schema, as zod
+ * does. Paths with optional parameters give one path per form, as OpenAPI has
+ * no optional path parameters; `@All()` routes are left out, OpenAPI has no
+ * such method.
+ */
+import type { MappedController } from '../http/routes.ts';
+export type JsonSchema = Readonly<Record<string, unknown>>;
+export interface OpenApiOptions {
+    readonly info: {
+        readonly title: string;
+        readonly version: string;
+        readonly description?: string;
+    };
+    readonly servers?: readonly {
+        readonly url: string;
+        readonly description?: string;
+    }[];
+}
+export interface OpenApiParameter {
+    readonly name: string;
+    readonly in: 'path' | 'query' | 'header' | 'cookie';
+    readonly required: boolean;
+    readonly schema: JsonSchema;
+}
+export interface OpenApiOperation {
+    readonly operationId: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly deprecated?: boolean;
+    readonly tags?: readonly string[];
+    readonly parameters?: readonly OpenApiParameter[];
+    readonly requestBody?: {
+        readonly required: boolean;
+        readonly content: Readonly<Record<string, {
+            readonly schema: JsonSchema;
+        }>>;
+    };
+    readonly responses: Readonly<Record<string, {
+        readonly description: string;
+        readonly content?: Readonly<Record<string, {
+            readonly schema: JsonSchema;
+        }>>;
+    }>>;
+    readonly security?: readonly Readonly<Record<string, readonly string[]>>[];
+}
+export interface OpenApiDocument {
+    readonly openapi: '3.1.0';
+    readonly info: OpenApiOptions['info'];
+    readonly servers?: OpenApiOptions['servers'];
+    readonly paths: Readonly<Record<string, Readonly<Record<string, OpenApiOperation>>>>;
+    readonly components?: {
+        readonly securitySchemes: Readonly<Record<string, JsonSchema>>;
+    };
+}
+/** The OpenAPI document of `controllers`, as `inject(ROUTES).controllers` lists them. */
+export declare const createOpenApiDocument: (controllers: readonly MappedController[], options: OpenApiOptions) => OpenApiDocument;
+//# sourceMappingURL=document.d.ts.map

package/dist/openapi/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/openapi/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAe,MAAM,mBAAmB,CAAA;AAQtE,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAE1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAClG,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CACtF;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACnD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;YAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;SAAE,CAAC,CAAC,CAAA;KAAE,CAAA;IAClI,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;YAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;SAAE,CAAC,CAAC,CAAA;KAAE,CAAC,CAAC,CAAA;IAC5J,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,EAAE,CAAA;CAC3E;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAA;IAC5C,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAA;IACpF,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;KAAE,CAAA;CACzF;AAqJD,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,gBAAiB,SAAS,gBAAgB,EAAE,WAAW,cAAc,KAAG,eAiBzG,CAAA"}

package/dist/openapi/document.js

@@ -0,0 +1,135 @@
+/**
+ * @module
+ * Building an OpenAPI 3.1 document from the routes of an application.
+ *
+ * Schemas come from what validates requests: argument parsers (`int()`,
+ * `uuid()`...) and Standard Schemas implementing Standard JSON Schema, as zod
+ * does. Paths with optional parameters give one path per form, as OpenAPI has
+ * no optional path parameters; `@All()` routes are left out, OpenAPI has no
+ * such method.
+ */
+import { isStandardSchema } from '../http/schema.js';
+import { expandOptional, parsePath } from '../routing/path.js';
+import { KEYS } from './decorators.js';
+const METHODS = new Set(['GET', 'PUT', 'POST', 'DELETE', 'OPTIONS', 'HEAD', 'PATCH', 'TRACE']);
+const IN = { query: 'query', header: 'header', cookie: 'cookie' };
+const STRING = { type: 'string' };
+const FORM_TYPES = ['multipart/form-data', 'application/x-www-form-urlencoded'];
+/** JSON Schema of what a parser or schema accepts, `{}` when it cannot tell. */
+const toJsonSchema = (source) => {
+    if (source === undefined) {
+        return STRING;
+    }
+    if (!isStandardSchema(source)) {
+        return source.jsonSchema ?? STRING;
+    }
+    const converter = source['~standard'].jsonSchema;
+    if (converter === undefined) {
+        return {};
+    }
+    const { $schema: _, ...schema } = converter.input({ target: 'draft-2020-12' });
+    return schema;
+};
+/** A value may be missing when its parser says so, or its schema accepts `undefined`. */
+const isOptional = (source) => {
+    if (source === undefined) {
+        return true;
+    }
+    if (!isStandardSchema(source)) {
+        return source.optional === true;
+    }
+    const result = source['~standard'].validate(undefined);
+    return !(result instanceof Promise) && result.issues === undefined;
+};
+const toOpenApiPath = (segments) => `/${segments
+    .map((segment) => segment.type === 'static' ? decodeURIComponent(segment.value) : `{${segment.type === 'param' ? segment.name : (segment.name ?? 'wildcard')}}`)
+    .join('/')}`;
+const pathParameters = (segments, args) => {
+    const parameters = [];
+    for (const segment of segments) {
+        if (segment.type === 'static') {
+            continue;
+        }
+        const name = segment.type === 'param' ? segment.name : (segment.name ?? 'wildcard');
+        const declared = args.find((arg) => arg.kind === 'param' && arg.name === name);
+        const pattern = segment.type === 'param' && segment.pattern !== undefined ? { pattern: `^(?:${segment.pattern})$` } : {};
+        parameters.push({ name, in: 'path', required: true, schema: { ...toJsonSchema(declared?.source), ...pattern } });
+    }
+    return parameters;
+};
+const requestBody = (args) => {
+    const body = args.find((arg) => arg.kind === 'body');
+    if (body === undefined) {
+        return undefined;
+    }
+    const schema = body.source === undefined ? {} : toJsonSchema(body.source);
+    const types = body.multipart === true ? FORM_TYPES : ['application/json'];
+    return { required: !isOptional(body.source), content: Object.fromEntries(types.map((type) => [type, { schema }])) };
+};
+const responsesOf = (route) => {
+    const declared = route.info.metadata.get(KEYS.responses);
+    if (declared === undefined) {
+        return route.sse
+            ? { 200: { description: 'Event stream', content: { 'text/event-stream': { schema: STRING } } } }
+            : { [route.status]: { description: 'Success' } };
+    }
+    return Object.fromEntries(Object.entries(declared).map(([status, response]) => [
+        status,
+        response.schema === undefined
+            ? { description: response.description }
+            : { description: response.description, content: { 'application/json': { schema: toJsonSchema(response.schema) } } },
+    ]));
+};
+const operationOf = (route, segments, suffix) => {
+    const { info } = route;
+    const args = route.args ?? [];
+    const parameters = pathParameters(segments, args);
+    for (const arg of args) {
+        if (arg.kind === 'query' || arg.kind === 'header' || arg.kind === 'cookie') {
+            parameters.push({ name: arg.name, in: IN[arg.kind], required: !isOptional(arg.source), schema: toJsonSchema(arg.source) });
+        }
+    }
+    const options = info.metadata.get(KEYS.operation) ?? {};
+    const tags = info.metadata.get(KEYS.tags);
+    const body = requestBody(args);
+    return {
+        operationId: `${info.controller.name}_${info.handler}${suffix}`,
+        ...options,
+        ...(tags === undefined ? {} : { tags }),
+        ...(parameters.length === 0 ? {} : { parameters }),
+        ...(body === undefined ? {} : { requestBody: body }),
+        responses: responsesOf(route),
+        ...(info.metadata.get(KEYS.bearer) === true ? { security: [{ bearer: [] }] } : {}),
+    };
+};
+/** Adds the operations of `route` to `paths`, one per form of its path; `false` when it is left out. */
+const addRoute = (paths, route) => {
+    const { info } = route;
+    if (!METHODS.has(info.method) || info.metadata.get(KEYS.exclude) === true) {
+        return false;
+    }
+    for (const [index, segments] of expandOptional(info.path, parsePath(info.path)).entries()) {
+        const path = toOpenApiPath(segments);
+        paths[path] ??= {};
+        paths[path][info.method.toLowerCase()] = operationOf(route, segments, index === 0 ? '' : `_${index}`);
+    }
+    return true;
+};
+/** The OpenAPI document of `controllers`, as `inject(ROUTES).controllers` lists them. */
+export const createOpenApiDocument = (controllers, options) => {
+    const paths = {};
+    let bearer = false;
+    for (const controller of controllers) {
+        for (const route of controller.routes) {
+            bearer = (addRoute(paths, route) && route.info.metadata.get(KEYS.bearer) === true) || bearer;
+        }
+    }
+    return {
+        openapi: '3.1.0',
+        info: options.info,
+        ...(options.servers === undefined ? {} : { servers: options.servers }),
+        paths,
+        ...(bearer ? { components: { securitySchemes: { bearer: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' } } } } : {}),
+    };
+};
+//# sourceMappingURL=document.js.map

package/dist/openapi/document.js.map

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

package/dist/openapi/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module
+ * OpenAPI documents of an application, and a Swagger UI page, as `@nestjs/swagger`.
+ */
+export { ApiBearerAuth, ApiExclude, ApiOperation, ApiResponses, ApiTags } from './decorators.ts';
+export type { ApiOperationOptions, ApiResponseOptions } from './decorators.ts';
+export { createOpenApiDocument } from './document.ts';
+export type { JsonSchema, OpenApiDocument, OpenApiOperation, OpenApiOptions, OpenApiParameter } from './document.ts';
+export { OpenApiModule } from './module.ts';
+export type { OpenApiModuleOptions } from './module.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openapi/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAChG,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAC9E,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACpH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA"}

package/dist/openapi/index.js

@@ -0,0 +1,8 @@
+/**
+ * @module
+ * OpenAPI documents of an application, and a Swagger UI page, as `@nestjs/swagger`.
+ */
+export { ApiBearerAuth, ApiExclude, ApiOperation, ApiResponses, ApiTags } from './decorators.js';
+export { createOpenApiDocument } from './document.js';
+export { OpenApiModule } from './module.js';
+//# sourceMappingURL=index.js.map

package/dist/openapi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/openapi/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAEhG,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAErD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA"}

package/dist/openapi/module.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module
+ * `OpenApiModule`: serves the OpenAPI document of the application, and a
+ * Swagger UI page, as `SwaggerModule.setup()` of `@nestjs/swagger` does.
+ */
+import type { DynamicModule } from '../di/index.ts';
+import type { OpenApiOptions } from './document.ts';
+export interface OpenApiModuleOptions extends OpenApiOptions {
+    /** Path of the JSON document. Defaults to `/openapi.json`. */
+    readonly path?: string;
+    /** Path of a Swagger UI page reading the document, such as `/docs`. None by default. */
+    readonly ui?: string;
+}
+/**
+ * ```ts
+ * @Module({ imports: [OpenApiModule.forRoot({ info: { title: 'Shop', version: '1.0.0' }, ui: '/docs' })] })
+ * class AppModule {}
+ * ```
+ *
+ * The document is built on the first request, from every route of the
+ * application (these two excepted), and kept.
+ */
+export declare class OpenApiModule {
+    static forRoot(options: OpenApiModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/openapi/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/openapi/module.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAKnD,OAAO,KAAK,EAAmB,cAAc,EAAE,MAAM,eAAe,CAAA;AAEpE,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CACrB;AAqBD;;;;;;;;GAQG;AACH,qBACa,aAAa;IACxB,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CA0C3D;CACF"}

package/dist/openapi/module.js

@@ -0,0 +1,73 @@
+/**
+ * @module
+ * `OpenApiModule`: serves the OpenAPI document of the application, and a
+ * Swagger UI page, as `SwaggerModule.setup()` of `@nestjs/swagger` does.
+ */
+import { inject, Module } from '../di/index.js';
+import { Controller, Get } from '../http/decorators.js';
+import { ROUTES } from '../http/routes.js';
+import { ApiExclude } from './decorators.js';
+import { createOpenApiDocument } from './document.js';
+/** Swagger UI, from a CDN at a fixed version. */
+const SWAGGER_UI = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.34.0';
+const page = (title, documentUrl) => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${Bun.escapeHTML(title)}</title>
+<link rel="stylesheet" href="${SWAGGER_UI}/swagger-ui.css">
+</head>
+<body>
+<div id="docs"></div>
+<script src="${SWAGGER_UI}/swagger-ui-bundle.js" crossorigin></script>
+<script>SwaggerUIBundle({ url: ${JSON.stringify(documentUrl)}, dom_id: '#docs' })</script>
+</body>
+</html>
+`;
+/**
+ * ```ts
+ * @Module({ imports: [OpenApiModule.forRoot({ info: { title: 'Shop', version: '1.0.0' }, ui: '/docs' })] })
+ * class AppModule {}
+ * ```
+ *
+ * The document is built on the first request, from every route of the
+ * application (these two excepted), and kept.
+ */
+@Module({})
+export class OpenApiModule {
+    static forRoot(options) {
+        const documentPath = options.path ?? '/openapi.json';
+        @Controller()
+        @ApiExclude()
+        class OpenApiController {
+            #routes = inject(ROUTES);
+            #document;
+            @Get(documentPath)
+            document() {
+                this.#document ??= createOpenApiDocument(this.#routes.controllers, options);
+                return this.#document;
+            }
+        }
+        const controllers = [OpenApiController];
+        if (options.ui !== undefined) {
+            const ui = options.ui;
+            @Controller()
+            @ApiExclude()
+            class OpenApiUiController {
+                #routes = inject(ROUTES);
+                @Get(ui)
+                page() {
+                    // The document's own path, global prefix included.
+                    const documentUrl = this.#routes.controllers.find((mapped) => mapped.controller === OpenApiController)?.routes[0]?.info.path;
+                    return new Response(page(options.info.title, documentUrl ?? documentPath), {
+                        headers: { 'content-type': 'text/html;charset=utf-8' },
+                    });
+                }
+            }
+            controllers.push(OpenApiUiController);
+        }
+        return { module: OpenApiModule, controllers };
+    }
+}
+//# sourceMappingURL=module.js.map

package/dist/openapi/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../src/openapi/module.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAE/C,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAUrD,iDAAiD;AACjD,MAAM,UAAU,GAAG,qDAAqD,CAAA;AAExE,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,WAAmB,EAAU,EAAE,CAAC;;;;;SAKpD,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC;+BACC,UAAU;;;;eAI1B,UAAU;iCACQ,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC;;;CAG3D,CAAA;AAED;;;;;;;;GAQG;AACH,CAAC,MAAM,CAAC,EAAE,CAAC;AACX,MAAM,OAAO,aAAa;IACxB,MAAM,CAAC,OAAO,CAAC,OAA6B;QAC1C,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,IAAI,eAAe,CAAA;QAEpD,CAAC,UAAU,EAAE;QACb,CAAC,UAAU,EAAE;cACP,iBAAiB;YACZ,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;YACjC,SAAS,CAA6B;YAEtC,CAAC,GAAG,CAAC,YAAY,CAAC;YAClB,QAAQ;gBACN,IAAI,CAAC,SAAS,KAAK,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;gBAE3E,OAAO,IAAI,CAAC,SAAS,CAAA;YACvB,CAAC;SACF;QAED,MAAM,WAAW,GAA0B,CAAC,iBAAiB,CAAC,CAAA;QAE9D,IAAI,OAAO,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,CAAA;YAErB,CAAC,UAAU,EAAE;YACb,CAAC,UAAU,EAAE;kBACP,mBAAmB;gBACd,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;gBAEjC,CAAC,GAAG,CAAC,EAAE,CAAC;gBACR,IAAI;oBACF,mDAAmD;oBACnD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,KAAK,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAA;oBAE5H,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,IAAI,YAAY,CAAC,EAAE;wBACzE,OAAO,EAAE,EAAE,cAAc,EAAE,yBAAyB,EAAE;qBACvD,CAAC,CAAA;gBACJ,CAAC;aACF;YAED,WAAW,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA;QACvC,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,CAAA;IAC/C,CAAC;CACF"}

package/dist/routing/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/routing/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,gBAAgB,GAAG,UAAU,GAAG,aAAa,CAAA;AAErF;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,KAAK;IAIjC,QAAQ,CAAC,IAAI,EAAE,cAAc;IAH/B,SAAkB,IAAI,gBAAe;IAErC,YACW,IAAI,EAAE,cAAc,EAC7B,OAAO,EAAE,MAAM,EAGhB;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/routing/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,gBAAgB,GAAG,UAAU,GAAG,aAAa,CAAA;AAErF;;;;GAIG;AACH,qBAAa,UAAW,SAAQ,KAAK;IAIjC,QAAQ,CAAC,IAAI,EAAE,cAAc;IAH/B,SAAkB,IAAI,gBAAe;IAErC,YACW,IAAI,EAAE,cAAc,EAC7B,OAAO,EAAE,MAAM,EAIhB;CACF"}

package/dist/routing/errors.js

@@ -2,6 +2,7 @@
  * @module
  * Errors raised by the route compiler.
  */
+import { hideFrameworkFrames } from '../utils/errors.js';
 /**
  * Error thrown by `compileRoutes`.
  *
@@ -13,6 +14,7 @@ export class RouteError extends Error {
     constructor(code, message) {
         super(message);
         this.code = code;
+        hideFrameworkFrames(this);
     }
 }
 //# sourceMappingURL=errors.js.map

package/dist/routing/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/routing/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAIxB,IAAI;IAHG,IAAI,GAAG,YAAY,CAAA;IAErC,YACW,IAAoB,EAC7B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAA;oBAHL,IAAI;IAIf,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/routing/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAYxD;;;;GAIG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAIxB,IAAI;IAHG,IAAI,GAAG,YAAY,CAAA;IAErC,YACW,IAAoB,EAC7B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAA;oBAHL,IAAI;QAIb,mBAAmB,CAAC,IAAI,CAAC,CAAA;IAC3B,CAAC;CACF"}

package/dist/testing/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @module
+ * Testing an application over HTTP, as Nest's `Test.createTestingModule()`
+ * with supertest does, on a real Bun server bound to a free port.
+ *
+ * ```ts
+ * import { createTestApp } from '@getsoda/core/testing'
+ *
+ * const app = await createTestApp(AppModule, {
+ *   overrides: [provide(UsersRepository, { useValue: new MemoryUsersRepository() })],
+ * })
+ *
+ * afterAll(() => app.close())
+ *
+ * test('creates a user', async () => {
+ *   const response = await app.request('/users', { method: 'POST', json: { name: 'Bo' } })
+ *
+ *   expect(response.status).toBe(201)
+ * })
+ * ```
+ *
+ * A single service needs no server: `createContainer(Module, { overrides })`.
+ */
+import type { App, AppOptions } from '../app/app.ts';
+import type { ModuleImport, Token } from '../di/index.ts';
+export interface TestRequestInit extends RequestInit {
+    /** Sent as the JSON body, with `Content-Type: application/json`. */
+    readonly json?: unknown;
+}
+/** A started application, closed by `close()` or at the end of an `await using` block. */
+export interface TestApp extends AsyncDisposable {
+    readonly app: App;
+    /** Where the application listens, on a free port of localhost. */
+    readonly url: URL;
+    /** `app.container.get()`: a provider as the root module sees it. */
+    get<T>(token: Token<T>): T;
+    /** Sends a request to `path`, relative to the application. */
+    request(path: string, init?: TestRequestInit): Promise<Response>;
+    close(): Promise<void>;
+}
+/**
+ * Creates `root` and serves it on a free port. Options are those of
+ * `createApp`: `overrides` replace providers; the logger is silent unless one is given.
+ */
+export declare const createTestApp: (root: ModuleImport, options?: AppOptions) => Promise<TestApp>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAEzD,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,0FAA0F;AAC1F,MAAM,WAAW,OAAQ,SAAQ,eAAe;IAC9C,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IACjB,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IACjB,oEAAoE;IACpE,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAC1B,8DAA8D;IAC9D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,SAAgB,YAAY,YAAW,UAAU,KAAQ,OAAO,CAAC,OAAO,CAuBjG,CAAA"}