@getsoda/core 0.2.2 → 0.3.0

package/dist/testing/index.js

@@ -0,0 +1,49 @@
+/**
+ * @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 { createApp } from '../app/app.js';
+/**
+ * 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 const createTestApp = async (root, options = {}) => {
+    const app = await createApp(root, { logger: false, ...options });
+    const server = await app.listen({ port: 0, hostname: '127.0.0.1' });
+    const close = () => app.close();
+    return {
+        app,
+        url: server.url,
+        get: (token) => app.container.get(token),
+        request: (path, { json, ...init } = {}) => {
+            if (json === undefined) {
+                return fetch(new URL(path, server.url), init);
+            }
+            const headers = new Headers(init.headers);
+            headers.set('content-type', 'application/json');
+            return fetch(new URL(path, server.url), { ...init, headers, body: JSON.stringify(json) });
+        },
+        close,
+        [Symbol.asyncDispose]: close,
+    };
+};
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAqBzC;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAAE,IAAkB,EAAE,OAAO,GAAe,EAAE,EAAoB,EAAE;IACpG,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;IAChE,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAA;IACnE,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,CAAA;IAE/B,OAAO;QACL,GAAG;QACH,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;QACxC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE;YACxC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAA;YAC/C,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YAEzC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAA;YAE/C,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAC3F,CAAC;QACD,KAAK;QACL,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,KAAK;KAC7B,CAAA;AACH,CAAC,CAAA"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module
+ * Error utilities.
+ */
+/**
+ * Removes the frames of the framework from the stack of an error about the
+ * application's code (a missing provider, an invalid route): the runtime then
+ * points at the application, not at the framework, and the message says the rest.
+ */
+export declare const hideFrameworkFrames: (error: Error) => void;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,UAAW,KAAK,KAAG,IASlD,CAAA"}

package/dist/utils/errors.js

@@ -0,0 +1,22 @@
+/**
+ * @module
+ * Error utilities.
+ */
+import { fileURLToPath } from 'node:url';
+/** Where the framework's own files are: `src/` from sources, `dist/` once built. */
+const FRAMEWORK = fileURLToPath(new URL('../', import.meta.url));
+/**
+ * Removes the frames of the framework from the stack of an error about the
+ * application's code (a missing provider, an invalid route): the runtime then
+ * points at the application, not at the framework, and the message says the rest.
+ */
+export const hideFrameworkFrames = (error) => {
+    if (error.stack === undefined) {
+        return;
+    }
+    error.stack = error.stack
+        .split('\n')
+        .filter((line) => !(line.trimStart().startsWith('at ') && line.includes(FRAMEWORK)))
+        .join('\n');
+};
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,oFAAoF;AACpF,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAA;AAEhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAY,EAAQ,EAAE;IACxD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAM;IACR,CAAC;IAED,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK;SACtB,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;SACnF,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC,CAAA"}

package/dist/utils/object.d.ts

@@ -11,4 +11,8 @@
  * ```
  */
 export declare const createNullObject: <T extends object>() => T;
+/**
+ * Public method names along the prototype chain, most derived first, without duplicates.
+ */
+export declare const methodNames: (instance: object) => string[];
 //# sourceMappingURL=object.d.ts.map

package/dist/utils/object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/utils/object.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,OAAK,CAA6B,CAAA"}
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../../src/utils/object.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,OAAK,CAA6B,CAAA;AAEnF;;GAEG;AACH,eAAO,MAAM,WAAW,aAAc,MAAM,KAAG,MAAM,EAkBpD,CAAA"}

package/dist/utils/object.js

@@ -11,4 +11,20 @@
  * ```
  */
 export const createNullObject = () => Object.create(null);
+/**
+ * Public method names along the prototype chain, most derived first, without duplicates.
+ */
+export const methodNames = (instance) => {
+    const names = [];
+    const seen = new Set(['constructor']);
+    for (let prototype = Object.getPrototypeOf(instance); prototype !== null && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)) {
+        for (const name of Object.getOwnPropertyNames(prototype)) {
+            if (!seen.has(name)) {
+                seen.add(name);
+                names.push(name);
+            }
+        }
+    }
+    return names;
+};
 //# sourceMappingURL=object.js.map

package/dist/utils/object.js.map

@@ -1 +1 @@
-{"version":3,"file":"object.js","sourceRoot":"","sources":["../../src/utils/object.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAwB,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAM,CAAA"}
+{"version":3,"file":"object.js","sourceRoot":"","sources":["../../src/utils/object.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAwB,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAM,CAAA;AAEnF;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAgB,EAAY,EAAE;IACxD,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,CAAC,aAAa,CAAC,CAAC,CAAA;IAE7C,KACE,IAAI,SAAS,GAAkB,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,EAC9D,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,MAAM,CAAC,SAAS,EACpD,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,EAC5C,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,EAAE,CAAC;YACzD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;gBACd,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA"}

package/dist/websocket/decorators.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module
+ * Decorators of WebSocket gateways, as in `@nestjs/websockets`.
+ */
+import type { Constructor } from '../di/index.ts';
+/**
+ * Declares a gateway: WebSocket connections upgraded from `GET path`. List it
+ * in the `controllers` of its module: like a controller, it is an entry point
+ * the framework creates, and its guards run on the handshake.
+ *
+ * ```ts
+ * @WebSocketGateway('/chat')
+ * @UseGuards(JwtGuard)
+ * class ChatGateway {
+ *   @SubscribeMessage('message')
+ *   message(data: unknown, socket: GatewaySocket) {
+ *     return { event: 'message', data }
+ *   }
+ * }
+ * ```
+ */
+export declare const WebSocketGateway: (path: string) => (target: Constructor<unknown>, _context: ClassDecoratorContext<Constructor<unknown>>) => void;
+/**
+ * Handles the frames `{ "event": event, "data": ... }` of a gateway. The
+ * method receives `(data, socket)`; what it returns, unless `undefined`, is
+ * sent back as JSON.
+ */
+export declare const SubscribeMessage: (event: string) => <This, M extends (this: This, ...args: any[]) => unknown>(method: M, context: ClassMethodDecoratorContext<This, M>) => void;
+export declare const getGatewayPath: (target: Constructor<unknown>) => string | undefined;
+export declare const getSubscribedEvent: (method: object) => string | undefined;
+//# sourceMappingURL=decorators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../../src/websocket/decorators.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAMjD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,SACpB,MAAM,cACJ,WAAW,CAAC,OAAO,CAAC,YAAY,qBAAqB,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,KAAG,IAMtF,CAAA;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,UACnB,MAAM,MACb,IAAI,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,UAAU,CAAC,WAAW,2BAA2B,CAAC,IAAI,EAAE,CAAC,CAAC,KAAG,IAMpH,CAAA;AAEH,eAAO,MAAM,cAAc,WAAY,WAAW,CAAC,OAAO,CAAC,KAAG,MAAM,GAAG,SAAiC,CAAA;AAExG,eAAO,MAAM,kBAAkB,WAAY,MAAM,KAAG,MAAM,GAAG,SAA+B,CAAA"}

package/dist/websocket/decorators.js

@@ -0,0 +1,43 @@
+/**
+ * @module
+ * Decorators of WebSocket gateways, as in `@nestjs/websockets`.
+ */
+import { ControllerError } from '../http/errors.js';
+const gateways = new WeakMap();
+const events = new WeakMap();
+/**
+ * Declares a gateway: WebSocket connections upgraded from `GET path`. List it
+ * in the `controllers` of its module: like a controller, it is an entry point
+ * the framework creates, and its guards run on the handshake.
+ *
+ * ```ts
+ * @WebSocketGateway('/chat')
+ * @UseGuards(JwtGuard)
+ * class ChatGateway {
+ *   @SubscribeMessage('message')
+ *   message(data: unknown, socket: GatewaySocket) {
+ *     return { event: 'message', data }
+ *   }
+ * }
+ * ```
+ */
+export const WebSocketGateway = (path) => (target, _context) => {
+    if (!path.startsWith('/') || /[:*?]/.test(path)) {
+        throw new ControllerError('INVALID_PATH', `@WebSocketGateway('${path}'): a gateway path is static and starts with "/"`);
+    }
+    gateways.set(target, path);
+};
+/**
+ * Handles the frames `{ "event": event, "data": ... }` of a gateway. The
+ * method receives `(data, socket)`; what it returns, unless `undefined`, is
+ * sent back as JSON.
+ */
+export const SubscribeMessage = (event) => (method, context) => {
+    if (context.static || context.private) {
+        throw new ControllerError('INVALID_HANDLER', `@SubscribeMessage('${event}') must decorate a public instance method`);
+    }
+    events.set(method, event);
+};
+export const getGatewayPath = (target) => gateways.get(target);
+export const getSubscribedEvent = (method) => events.get(method);
+//# sourceMappingURL=decorators.js.map

package/dist/websocket/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../src/websocket/decorators.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAEnD,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAgC,CAAA;AAC5D,MAAM,MAAM,GAAG,IAAI,OAAO,EAAkB,CAAA;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,CAAC,IAAY,EAAE,EAAE,CACjB,CAAC,MAA4B,EAAE,QAAqD,EAAQ,EAAE;IAC5F,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,sBAAsB,IAAI,kDAAkD,CAAC,CAAA;IACzH,CAAC;IAED,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;AAC5B,CAAC,CAAA;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,CAAC,KAAa,EAAE,EAAE,CAClB,CAA0D,MAAS,EAAE,OAA6C,EAAQ,EAAE;IAC1H,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACtC,MAAM,IAAI,eAAe,CAAC,iBAAiB,EAAE,sBAAsB,KAAK,2CAA2C,CAAC,CAAA;IACtH,CAAC;IAED,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AAC3B,CAAC,CAAA;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAA4B,EAAsB,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;AAExG,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAc,EAAsB,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA"}

package/dist/websocket/gateway.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @module
+ * Serving a gateway: the handshake goes through the route pipeline (guards
+ * and exception filters of the gateway), then frames are dispatched to its
+ * `@SubscribeMessage()` methods.
+ *
+ * The protocol is the one of Nest's `WsAdapter`: text frames holding
+ * `{ "event": string, "data": any }`. Frames that are not JSON, not such an
+ * object, or name no handled event are dropped silently, as anyone can send
+ * them; errors of the gateway's own code are reported.
+ */
+import type { ControllerEntry } from '../di/index.ts';
+import type { Context } from '../http/context.ts';
+import type { FilterStep, GuardStep } from '../http/pipeline.ts';
+/** What a gateway socket carries. */
+export interface GatewaySocketData {
+    /** Context of the handshake request: what its guards set is read with `context.get(key)`. */
+    readonly context: Context;
+    /** @internal */
+    readonly gateway: GatewayRuntime;
+}
+/** A connection of a gateway: Bun's `ServerWebSocket`, with `subscribe()`, `publish()`... */
+export type GatewaySocket = Bun.ServerWebSocket<GatewaySocketData>;
+/** `handleConnection(socket)`: called when a client is connected. */
+export interface OnGatewayConnection {
+    handleConnection(socket: GatewaySocket): unknown;
+}
+/** `handleDisconnect(socket, code, reason)`: called when a connection is closed. */
+export interface OnGatewayDisconnect {
+    handleDisconnect(socket: GatewaySocket, code: number, reason: string): unknown;
+}
+/** The live part of a gateway: its sockets and handlers. */
+export declare class GatewayRuntime {
+    #private;
+    constructor(instance: object, onError: (error: unknown, req: Request) => void);
+    get events(): readonly string[];
+    open(socket: GatewaySocket): void;
+    message(socket: GatewaySocket, message: string | Buffer): void;
+    close(socket: GatewaySocket, code: number, reason: string): void;
+    /** Closes every connection, as the application shuts down. */
+    closeAll(): void;
+}
+/** Bun's handlers for every gateway of a server: each socket knows its gateway. */
+export declare const websocketHandler: Bun.WebSocketHandler<GatewaySocketData>;
+export interface GatewayParts {
+    readonly entry: ControllerEntry;
+    readonly path: string;
+    readonly guards: readonly GuardStep[];
+    readonly filters: readonly FilterStep[];
+    readonly metadata: ReadonlyMap<symbol, unknown>;
+    readonly onError: (error: unknown, req: Request) => void;
+}
+/** A gateway ready to serve: its native route and its runtime. */
+export interface BuiltGateway {
+    readonly path: string;
+    readonly runtime: GatewayRuntime;
+    /** The native route of the handshake, for `Bun.serve({ routes })`. */
+    readonly handle: (req: Bun.BunRequest, server: Bun.Server<GatewaySocketData>) => Response | undefined | Promise<Response | undefined>;
+}
+export declare const buildGateway: (parts: GatewayParts) => BuiltGateway;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/websocket/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/websocket/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,oBAAoB,CAAA;AAE5D,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAKhE,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,gBAAgB;IAChB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CACjC;AAED,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,eAAe,CAAC,iBAAiB,CAAC,CAAA;AAElE,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAA;CACjD;AAED,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;CAC/E;AAoBD,4DAA4D;AAC5D,qBAAa,cAAc;;IAMzB,YAAY,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,EAY5E;IAED,IAAI,MAAM,IAAI,SAAS,MAAM,EAAE,CAE9B;IAED,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAGhC;IAED,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiB7D;IAED,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAG/D;IAED,8DAA8D;IAC9D,QAAQ,IAAI,IAAI,CAIf;CAqBF;AAkBD,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,EAAE,GAAG,CAAC,gBAAgB,CAAC,iBAAiB,CAIpE,CAAA;AAKD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAA;IACvC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/C,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CACzD;AAED,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,KAAK,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAA;CACtI;AAED,eAAO,MAAM,YAAY,UAAW,YAAY,KAAG,YA2BlD,CAAA"}

package/dist/websocket/gateway.js

@@ -0,0 +1,142 @@
+/**
+ * @module
+ * Serving a gateway: the handshake goes through the route pipeline (guards
+ * and exception filters of the gateway), then frames are dispatched to its
+ * `@SubscribeMessage()` methods.
+ *
+ * The protocol is the one of Nest's `WsAdapter`: text frames holding
+ * `{ "event": string, "data": any }`. Frames that are not JSON, not such an
+ * object, or name no handled event are dropped silently, as anyone can send
+ * them; errors of the gateway's own code are reported.
+ */
+import { parseJson } from '../http/body.js';
+import { createPipeline } from '../http/pipeline.js';
+import { methodNames } from '../utils/object.js';
+import { isThenable } from '../utils/promise.js';
+import { getSubscribedEvent } from './decorators.js';
+/** Code of the close frame sent when the application shuts down. */
+const GOING_AWAY = 1001;
+/** Runs `fn`, reporting a synchronous or asynchronous failure. */
+const settle = (fn, report, then) => {
+    try {
+        const result = fn();
+        if (isThenable(result)) {
+            Promise.resolve(result).then(then, report);
+        }
+        else {
+            then?.(result);
+        }
+    }
+    catch (error) {
+        report(error);
+    }
+};
+/** The live part of a gateway: its sockets and handlers. */
+export class GatewayRuntime {
+    #instance;
+    #handlers = new Map();
+    #sockets = new Set();
+    #onError;
+    constructor(instance, onError) {
+        this.#instance = instance;
+        this.#onError = onError;
+        for (const name of methodNames(instance)) {
+            const method = this.#instance[name];
+            const event = getSubscribedEvent(method);
+            if (event !== undefined) {
+                this.#handlers.set(event, method);
+            }
+        }
+    }
+    get events() {
+        return [...this.#handlers.keys()];
+    }
+    open(socket) {
+        this.#sockets.add(socket);
+        this.#call('handleConnection', socket, [socket]);
+    }
+    message(socket, message) {
+        const frame = typeof message === 'string' ? parseFrame(message) : undefined;
+        const handler = frame === undefined ? undefined : this.#handlers.get(frame.event);
+        if (handler === undefined) {
+            return;
+        }
+        settle(() => handler.call(this.#instance, frame.data, socket), (error) => this.#onError(error, socket.data.context.req), (result) => {
+            if (result !== undefined) {
+                this.#send(socket, result);
+            }
+        });
+    }
+    close(socket, code, reason) {
+        this.#sockets.delete(socket);
+        this.#call('handleDisconnect', socket, [socket, code, reason]);
+    }
+    /** Closes every connection, as the application shuts down. */
+    closeAll() {
+        for (const socket of this.#sockets) {
+            socket.close(GOING_AWAY, 'Server shutting down');
+        }
+    }
+    #call(hook, socket, args) {
+        const fn = this.#instance[hook];
+        if (typeof fn === 'function') {
+            settle(() => fn.apply(this.#instance, args), (error) => this.#onError(error, socket.data.context.req));
+        }
+    }
+    #send(socket, value) {
+        try {
+            // JSON.stringify throws on cycles and bigints: an application error, reported.
+            socket.send(JSON.stringify(value));
+        }
+        catch (error) {
+            this.#onError(error, socket.data.context.req);
+        }
+    }
+}
+const parseFrame = (message) => {
+    let frame;
+    try {
+        frame = parseJson(message);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof frame !== 'object' || frame === null || typeof frame.event !== 'string') {
+        return undefined;
+    }
+    return frame;
+};
+/** Bun's handlers for every gateway of a server: each socket knows its gateway. */
+export const websocketHandler = {
+    open: (socket) => socket.data.gateway.open(socket),
+    message: (socket, message) => socket.data.gateway.message(socket, message),
+    close: (socket, code, reason) => socket.data.gateway.close(socket, code, reason),
+};
+/** Result of the handshake once the connection is upgraded: Bun wants no response then. */
+const UPGRADED = Symbol('upgraded');
+export const buildGateway = (parts) => {
+    const runtime = new GatewayRuntime(parts.entry.instance, parts.onError);
+    const route = { controller: parts.entry.controller, handler: 'handshake', method: 'GET', path: parts.path, metadata: parts.metadata };
+    // The pipeline is built once; the server of each request is found here.
+    const servers = new WeakMap();
+    const pipeline = createPipeline({
+        route,
+        guards: parts.guards,
+        interceptors: [],
+        filters: parts.filters,
+        invoke: (ctx) => servers.get(ctx.req).upgrade(ctx.req, { data: { context: ctx, gateway: runtime } })
+            ? UPGRADED
+            : new Response('Expected a WebSocket upgrade', { status: 426, headers: { upgrade: 'websocket' } }),
+        respond: (value) => (value === UPGRADED ? undefined : value),
+        onError: parts.onError,
+    });
+    return {
+        path: parts.path,
+        runtime,
+        handle: (req, server) => {
+            servers.set(req, server);
+            return pipeline(req, {});
+        },
+    };
+};
+//# sourceMappingURL=gateway.js.map

package/dist/websocket/gateway.js.map

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

package/dist/websocket/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @module
+ * WebSocket gateways, as in `@nestjs/websockets`.
+ */
+export { SubscribeMessage, WebSocketGateway } from './decorators.ts';
+export type { GatewaySocket, GatewaySocketData, OnGatewayConnection, OnGatewayDisconnect } from './gateway.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/websocket/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACpE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA"}

package/dist/websocket/index.js

@@ -0,0 +1,6 @@
+/**
+ * @module
+ * WebSocket gateways, as in `@nestjs/websockets`.
+ */
+export { SubscribeMessage, WebSocketGateway } from './decorators.js';
+//# sourceMappingURL=index.js.map

package/dist/websocket/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/websocket/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getsoda/core",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Class-based web framework for Bun: modules, dependency injection and decorators like Nest, on Bun's native router",
   "keywords": [
     "bun",
@@ -32,6 +32,14 @@
       "types": "./dist/jwt/index.d.ts",
       "default": "./dist/jwt/index.js"
     },
+    "./openapi": {
+      "types": "./dist/openapi/index.d.ts",
+      "default": "./dist/openapi/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
@@ -47,5 +55,8 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "prepublishOnly": "cd ../.. && bun run lint && bun run typecheck && bun run test && cd packages/core && bun run build"
+  },
+  "devDependencies": {
+    "zod": "4.6.7"
   }
 }