@velajs/vela 1.9.0 → 1.10.0

package/dist/websocket/websocket.types.d.ts

@@ -0,0 +1,86 @@
+import type { ExecutionContext, WsArgumentsHost } from '../pipeline/types';
+export type { WsArgumentsHost };
+/** The JSON envelope carried over the raw WebSocket. `id` is an optional client correlation id echoed on the reply. */
+export interface WsMessage<T = unknown> {
+    id?: string;
+    event: string;
+    data?: T;
+}
+/** A handler's structured reply. Returning one frames `{ event, data }` back to the sender. */
+export interface WsResponse<T = unknown> {
+    event: string;
+    data: T;
+}
+/**
+ * A single connected socket, normalized across runtimes. Per-connection state
+ * lives in `data`; mutations to `data`/room membership are persisted by
+ * `commit()` (on Cloudflare this writes the hibernation attachment).
+ */
+export interface WsClient<TData = Record<string, unknown>> {
+    readonly id: string;
+    readonly rooms: ReadonlySet<string>;
+    data: TData;
+    /** Frame and send `{ event, data }` (optionally correlated by `id`) to this socket. */
+    send(event: string, data?: unknown, id?: string): void;
+    /** Send an already-serialized string. Escape hatch for custom framing. */
+    sendRaw(payload: string): void;
+    join(room: string): void | Promise<void>;
+    leave(room: string): void | Promise<void>;
+    /** Persist `data`/room mutations made during a handler. */
+    commit(): void | Promise<void>;
+    close(code?: number, reason?: string): void;
+    /** The native socket (`WSContext` on node/bun/deno, `WebSocket` in a Cloudflare DO). */
+    readonly raw: unknown;
+}
+/** Fluent broadcast builder. Terminal `.emit()` produces a `BroadcastCommand`. */
+export interface BroadcastOperator {
+    to(room: string): BroadcastOperator;
+    in(room: string): BroadcastOperator;
+    except(room: string): BroadcastOperator;
+    emit(event: string, data?: unknown): void | Promise<void>;
+}
+/** The server handle injected via `@WebSocketServer()`. Server-origin broadcasts never exclude anyone. */
+export interface WsServer {
+    emit(event: string, data?: unknown): void | Promise<void>;
+    to(room: string): BroadcastOperator;
+    in(room: string): BroadcastOperator;
+    except(room: string): BroadcastOperator;
+}
+/** An `ExecutionContext` whose transport is a WebSocket gateway. `switchToWs()` is guaranteed present. */
+export interface WsExecutionContext extends ExecutionContext {
+    switchToWs(): WsArgumentsHost;
+}
+export interface OnGatewayInit {
+    afterInit(server: WsServer): void | Promise<void>;
+}
+export interface OnGatewayConnection {
+    handleConnection(client: WsClient): void | Promise<void>;
+}
+export interface OnGatewayDisconnect {
+    handleDisconnect(client: WsClient): void | Promise<void>;
+}
+export interface WebSocketGatewayOptions {
+    /** Route path the upgrade is served on (e.g. `/rooms/:id/ws`). */
+    path?: string;
+    /** Cloudflare Durable Object binding name that hosts this gateway's sockets. */
+    binding?: string;
+}
+/** Stored per `@SubscribeMessage` — a flat class-level list, mirroring `@OnEvent`. */
+export interface SubscribeMessageMetadata {
+    event: string;
+    methodName: string;
+}
+/**
+ * A fully serializable broadcast instruction. Crosses isolate / Durable-Object /
+ * Redis boundaries as JSON, so every sync driver speaks the same command.
+ */
+export interface BroadcastCommand {
+    /** Target rooms. An empty array means GLOBAL (every connection). */
+    rooms: string[];
+    exceptRooms?: string[];
+    exceptIds?: string[];
+    /** The exact bytes written to each socket: `JSON.stringify({ event, data })`. */
+    frame: string;
+    /** Origin instance/DO id — lets pub/sub drivers drop their own echo. */
+    origin?: string;
+}

package/dist/websocket/websocket.types.js

@@ -0,0 +1,4 @@
+/**
+ * A fully serializable broadcast instruction. Crosses isolate / Durable-Object /
+ * Redis boundaries as JSON, so every sync driver speaks the same command.
+ */ export { };

package/dist/websocket/ws-argument-resolver.d.ts

@@ -0,0 +1,13 @@
+import type { PipeTransform } from '../pipeline/types';
+import type { ParameterMetadata } from '../registry/types';
+import type { WsClient } from './websocket.types';
+/**
+ * Builds handler arguments for a gateway message. WS sibling of the HTTP
+ * `ArgumentResolver`, but sourced from the envelope (`data`) and the socket
+ * (`client`) instead of the Hono `Context`.
+ *
+ * With no parameter decorators the handler receives `(client, data)` — the
+ * NestJS gateway convention. Pipes run only over `@MessageBody()` values, where
+ * validation/transformation is meaningful.
+ */
+export declare function resolveWsArgs(paramMeta: ParameterMetadata[], client: WsClient, data: unknown, pipes: PipeTransform[], paramTypes?: unknown[]): Promise<unknown[]>;

package/dist/websocket/ws-argument-resolver.js

@@ -0,0 +1,40 @@
+import { WsParamType } from "./websocket.tokens.js";
+/**
+ * Builds handler arguments for a gateway message. WS sibling of the HTTP
+ * `ArgumentResolver`, but sourced from the envelope (`data`) and the socket
+ * (`client`) instead of the Hono `Context`.
+ *
+ * With no parameter decorators the handler receives `(client, data)` — the
+ * NestJS gateway convention. Pipes run only over `@MessageBody()` values, where
+ * validation/transformation is meaningful.
+ */ export async function resolveWsArgs(paramMeta, client, data, pipes, paramTypes) {
+    if (paramMeta.length === 0) {
+        return [
+            client,
+            data
+        ];
+    }
+    const maxIndex = paramMeta[paramMeta.length - 1].index;
+    const args = new Array(maxIndex + 1).fill(undefined);
+    for (const param of paramMeta){
+        if (param.type === WsParamType.SOCKET) {
+            args[param.index] = client;
+            continue;
+        }
+        if (param.type === WsParamType.BODY) {
+            let value = data;
+            const metadata = {
+                type: param.type,
+                data: param.name,
+                metatype: paramTypes?.[param.index]
+            };
+            for (const pipe of pipes){
+                value = await pipe.transform(value, metadata);
+            }
+            args[param.index] = value;
+            continue;
+        }
+        args[param.index] = undefined;
+    }
+    return args;
+}

package/dist/websocket/ws-dispatcher.d.ts

@@ -0,0 +1,33 @@
+import { Container } from '../container/container';
+import { RouteManager } from '../http/route.manager';
+import type { OnApplicationBootstrap } from '../lifecycle/index';
+import type { WsClient, WsServer } from './websocket.types';
+/**
+ * Discovers `@WebSocketGateway` classes at bootstrap (same `container.getTokens()`
+ * scan as `EventEmitterSubscriber` / `ScheduleRegistry`) and routes inbound
+ * messages to `@SubscribeMessage` handlers. Transports call `handleOpen`,
+ * `dispatchMessage`, `handleClose`, and `handleError`; the guard → pipe →
+ * interceptor → filter pipeline (including `APP_*` global components) is reused
+ * from `ComponentManager`.
+ */
+export declare class WsDispatcher implements OnApplicationBootstrap {
+    private readonly container;
+    private readonly server?;
+    private readonly routeManager?;
+    private readonly gateways;
+    constructor(container: Container, server?: WsServer | undefined, routeManager?: RouteManager | undefined);
+    /** Paths of every discovered `@WebSocketGateway` — used by transports to register routes. */
+    get gatewayPaths(): string[];
+    onApplicationBootstrap(): Promise<void>;
+    handleOpen(path: string, client: WsClient): Promise<void>;
+    handleClose(path: string, client: WsClient, _code: number, _reason: string): Promise<void>;
+    handleError(path: string, _client: WsClient, err: unknown): Promise<void>;
+    dispatchMessage(path: string, client: WsClient, raw: string | ArrayBuffer): Promise<void>;
+    private reply;
+    private runFilters;
+    private trySend;
+    private reportBootstrapError;
+    private parse;
+    private resolveGateway;
+    private buildGatewayEntry;
+}

package/dist/websocket/ws-dispatcher.js

@@ -0,0 +1,253 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Container } from "../container/container.js";
+import { Inject, Injectable, Optional } from "../container/decorators.js";
+import { instantiateMany } from "../http/instantiate.js";
+import { RouteManager } from "../http/route.manager.js";
+import { ComponentManager } from "../pipeline/component.manager.js";
+import { shouldFilterCatch } from "../pipeline/decorators.js";
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+import { resolveWsArgs } from "./ws-argument-resolver.js";
+import { buildWsExecutionContext } from "./ws-execution-context.js";
+import { toErrorFrame, WsException } from "./ws-exception.js";
+import { WS_GATEWAY_METADATA, WS_SERVER, WS_SUBSCRIBE_METADATA } from "./websocket.tokens.js";
+function hasAfterInit(x) {
+    return typeof x?.afterInit === 'function';
+}
+function hasHandleConnection(x) {
+    return typeof x?.handleConnection === 'function';
+}
+function hasHandleDisconnect(x) {
+    return typeof x?.handleDisconnect === 'function';
+}
+function isWsResponse(x) {
+    return typeof x === 'object' && x !== null && typeof x.event === 'string';
+}
+export class WsDispatcher {
+    container;
+    server;
+    routeManager;
+    gateways = new Map();
+    constructor(container, server, routeManager){
+        this.container = container;
+        this.server = server;
+        this.routeManager = routeManager;
+    }
+    /** Paths of every discovered `@WebSocketGateway` — used by transports to register routes. */ get gatewayPaths() {
+        return [
+            ...this.gateways.keys()
+        ];
+    }
+    async onApplicationBootstrap() {
+        for (const token of this.container.getTokens()){
+            if (typeof token !== 'function') continue;
+            const options = MetadataRegistry.getCustomClassMeta(token, WS_GATEWAY_METADATA);
+            if (!options) continue;
+            const instance = this.resolveGateway(token);
+            if (!instance) continue;
+            const entry = this.buildGatewayEntry(token, options, instance);
+            // Two gateways on the same path (or both defaulting to '') would silently
+            // overwrite each other in the routing Map — surface it instead.
+            if (this.gateways.has(entry.path)) {
+                const msg = `[vela] duplicate @WebSocketGateway path '${entry.path}' ` + `(${token.name}); keeping the first. Give each gateway a distinct path.`;
+                if (this.container.getDiagnostics() === 'throw') throw new Error(msg);
+                console.warn(msg);
+                continue;
+            }
+            this.gateways.set(entry.path, entry);
+            if (this.server && hasAfterInit(instance)) {
+                try {
+                    await instance.afterInit(this.server);
+                } catch (err) {
+                    this.reportBootstrapError(token.name, err);
+                }
+            }
+        }
+    }
+    async handleOpen(path, client) {
+        const entry = this.gateways.get(path);
+        if (entry && hasHandleConnection(entry.instance)) {
+            await entry.instance.handleConnection(client);
+        }
+    }
+    async handleClose(path, client, _code, _reason) {
+        const entry = this.gateways.get(path);
+        if (entry && hasHandleDisconnect(entry.instance)) {
+            await entry.instance.handleDisconnect(client);
+        }
+    }
+    async handleError(path, _client, err) {
+        if (this.container.getDiagnostics() !== 'silent') {
+            console.warn(`[vela] websocket error on gateway ${path}:`, err);
+        }
+    }
+    async dispatchMessage(path, client, raw) {
+        const entry = this.gateways.get(path);
+        if (!entry) return;
+        let message;
+        try {
+            message = this.parse(raw);
+        } catch  {
+            this.trySend(client, 'exception', {
+                message: 'Invalid message'
+            });
+            return;
+        }
+        const handler = entry.handlers.get(message.event);
+        if (!handler) return; // unknown event — ignored (NestJS parity)
+        const ctx = buildWsExecutionContext(client, message.data, entry.gatewayClass, handler.methodName, message.event);
+        // App-wide global components (APP_* provider tokens + imperative
+        // app.useGlobalX()) run first, then controller/handler-tier — mirroring the
+        // HTTP HandlerExecutor so global guards/pipes/interceptors/filters protect
+        // gateway messages too. Read live so late registrations propagate.
+        const globals = this.routeManager?.getGlobalComponents();
+        const guards = [
+            ...instantiateMany(globals?.guards ?? [], this.container),
+            ...instantiateMany(handler.guards, this.container)
+        ];
+        const pipes = [
+            ...instantiateMany(globals?.pipes ?? [], this.container),
+            ...instantiateMany(handler.pipes, this.container)
+        ];
+        const interceptors = [
+            ...instantiateMany(globals?.interceptors ?? [], this.container),
+            ...instantiateMany(handler.interceptors, this.container)
+        ];
+        // Handler/controller filters first (closest), then global filters last.
+        const filters = [
+            ...instantiateMany(handler.filters, this.container),
+            ...instantiateMany(globals?.filters ?? [], this.container)
+        ];
+        try {
+            for (const guard of guards){
+                if (!await guard.canActivate(ctx)) {
+                    throw new WsException('Forbidden');
+                }
+            }
+            const args = await resolveWsArgs(handler.paramMeta, client, message.data, pipes, handler.paramTypes);
+            const method = entry.instance[handler.methodName];
+            const core = async ()=>method.apply(entry.instance, args);
+            const result = await ComponentManager.runInterceptorChain(interceptors, ctx, core);
+            this.reply(client, message, result);
+        } catch (error) {
+            await this.runFilters(client, message, error, filters, ctx);
+        }
+    }
+    reply(client, message, result) {
+        if (result === undefined || result === null) return;
+        if (isWsResponse(result)) {
+            this.trySend(client, result.event, result.data, message.id);
+        } else {
+            this.trySend(client, message.event, result, message.id);
+        }
+    }
+    async runFilters(client, message, error, filters, ctx) {
+        for (const filter of filters){
+            if (shouldFilterCatch(filter, error)) {
+                try {
+                    const handled = await filter.catch(error, ctx);
+                    if (isWsResponse(handled)) {
+                        this.trySend(client, handled.event, handled.data, message.id);
+                    }
+                } catch  {
+                    // A throwing filter falls back to the default error frame (mirrors HandlerExecutor).
+                    const frame = toErrorFrame(error);
+                    this.trySend(client, frame.event, frame.data, message.id);
+                }
+                return;
+            }
+        }
+        const errorFrame = toErrorFrame(error);
+        this.trySend(client, errorFrame.event, errorFrame.data, message.id);
+    }
+    // Outbound sends are best-effort: the socket may have closed mid-dispatch.
+    trySend(client, event, data, id) {
+        try {
+            client.send(event, data, id);
+        } catch  {
+        // socket closed — nothing to do
+        }
+    }
+    reportBootstrapError(name, err) {
+        const mode = this.container.getDiagnostics();
+        if (mode === 'throw') throw err;
+        if (mode === 'log') console.warn(`[vela] websocket gateway ${name} afterInit failed:`, err);
+    }
+    parse(raw) {
+        const text = typeof raw === 'string' ? raw : new TextDecoder().decode(raw);
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== 'object' || typeof parsed.event !== 'string') {
+            throw new Error('Invalid WebSocket message envelope');
+        }
+        return parsed;
+    }
+    resolveGateway(token) {
+        try {
+            return this.container.resolve(token);
+        } catch (err) {
+            const mode = this.container.getDiagnostics();
+            if (mode === 'throw') throw err;
+            if (mode === 'log') {
+                const name = typeof token === 'function' ? token.name : String(token);
+                console.warn(`[vela] websocket gateway discovery: cannot resolve ${name}:`, err);
+            }
+            return undefined;
+        }
+    }
+    buildGatewayEntry(gatewayClass, options, instance) {
+        const ctor = gatewayClass;
+        const subs = MetadataRegistry.getCustomClassMeta(ctor, WS_SUBSCRIBE_METADATA) ?? [];
+        const allParams = MetadataRegistry.getParameters(ctor);
+        const handlers = new Map();
+        for (const { event, methodName } of subs){
+            const paramMeta = [
+                ...allParams.get(methodName) ?? []
+            ].sort((a, b)=>a.index - b.index);
+            const paramTypes = Reflect.getMetadata('design:paramtypes', gatewayClass.prototype, methodName);
+            handlers.set(event, {
+                methodName,
+                paramMeta,
+                paramTypes,
+                guards: ComponentManager.getComponents('guard', ctor, methodName),
+                pipes: ComponentManager.getComponents('pipe', ctor, methodName),
+                interceptors: ComponentManager.getComponents('interceptor', ctor, methodName),
+                // Handler → controller → global, so the closest filter runs first (mirrors HandlerExecutor).
+                filters: [
+                    ...ComponentManager.getComponents('filter', ctor, methodName)
+                ].reverse()
+            });
+        }
+        return {
+            path: options.path ?? '',
+            instance,
+            gatewayClass,
+            handlers
+        };
+    }
+}
+WsDispatcher = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(Container)),
+    _ts_param(1, Optional()),
+    _ts_param(1, Inject(WS_SERVER)),
+    _ts_param(2, Optional()),
+    _ts_param(2, Inject(RouteManager)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof Container === "undefined" ? Object : Container,
+        typeof WsServer === "undefined" ? Object : WsServer,
+        typeof RouteManager === "undefined" ? Object : RouteManager
+    ])
+], WsDispatcher);

package/dist/websocket/ws-exception.d.ts

@@ -0,0 +1,16 @@
+/**
+ * WebSocket analogue of `HttpException`. Thrown from guards/pipes/handlers to
+ * signal a client-facing error; the dispatcher serializes it to an
+ * `{ event: 'exception', data }` frame unless a matching exception filter
+ * handles it first.
+ */
+export declare class WsException extends Error {
+    private readonly err;
+    constructor(err: string | Record<string, unknown>);
+    getError(): string | Record<string, unknown>;
+}
+/** Default serialization of an uncaught error into the outbound exception frame. */
+export declare function toErrorFrame(error: unknown): {
+    event: 'exception';
+    data: unknown;
+};

package/dist/websocket/ws-exception.js

@@ -0,0 +1,32 @@
+/**
+ * WebSocket analogue of `HttpException`. Thrown from guards/pipes/handlers to
+ * signal a client-facing error; the dispatcher serializes it to an
+ * `{ event: 'exception', data }` frame unless a matching exception filter
+ * handles it first.
+ */ export class WsException extends Error {
+    err;
+    constructor(err){
+        super(typeof err === 'string' ? err : String(err.message ?? 'WsException')), this.err = err;
+        this.name = 'WsException';
+    }
+    getError() {
+        return this.err;
+    }
+}
+/** Default serialization of an uncaught error into the outbound exception frame. */ export function toErrorFrame(error) {
+    if (error instanceof WsException) {
+        const e = error.getError();
+        return {
+            event: 'exception',
+            data: typeof e === 'string' ? {
+                message: e
+            } : e
+        };
+    }
+    return {
+        event: 'exception',
+        data: {
+            message: 'Internal server error'
+        }
+    };
+}

package/dist/websocket/ws-execution-context.d.ts

@@ -0,0 +1,9 @@
+import type { Type } from '../container/types';
+import type { WsClient, WsExecutionContext } from './websocket.types';
+/**
+ * WebSocket sibling of `buildExecutionContext` (`http/execution-context.ts`).
+ * Guards/pipes/interceptors/filters that read `getClass()`/`getHandler()` or
+ * call `switchToWs()` reuse unchanged; the HTTP-only accessors throw rather
+ * than fabricate a fake `Request`.
+ */
+export declare function buildWsExecutionContext(client: WsClient, data: unknown, controller: Type, handlerName: string | symbol, pattern: string): WsExecutionContext;

package/dist/websocket/ws-execution-context.js

@@ -0,0 +1,24 @@
+const HTTP_ON_WS = (accessor)=>()=>{
+        throw new Error(`${accessor} called on a WebSocket ExecutionContext. This handler runs over a gateway message, not HTTP — use switchToWs().`);
+    };
+/**
+ * WebSocket sibling of `buildExecutionContext` (`http/execution-context.ts`).
+ * Guards/pipes/interceptors/filters that read `getClass()`/`getHandler()` or
+ * call `switchToWs()` reuse unchanged; the HTTP-only accessors throw rather
+ * than fabricate a fake `Request`.
+ */ export function buildWsExecutionContext(client, data, controller, handlerName, pattern) {
+    const host = {
+        getClient: ()=>client,
+        getData: ()=>data,
+        getPattern: ()=>pattern
+    };
+    return {
+        getType: ()=>'ws',
+        getClass: ()=>controller,
+        getHandler: ()=>handlerName,
+        getContext: HTTP_ON_WS('getContext()'),
+        getRequest: HTTP_ON_WS('getRequest()'),
+        switchToHttp: HTTP_ON_WS('switchToHttp()'),
+        switchToWs: ()=>host
+    };
+}

package/dist/websocket/ws-server.d.ts

@@ -0,0 +1,31 @@
+import type { SyncDriver } from './ws-sync';
+import type { BroadcastOperator, WsServer } from './websocket.types';
+/**
+ * Accumulates `{ rooms, exceptRooms, exceptIds }` across a fluent chain and, on
+ * `.emit()`, produces a serializable `BroadcastCommand` handed to the active
+ * `SyncDriver`. The driver decides local-vs-remote delivery.
+ */
+export declare class BroadcastOperatorImpl implements BroadcastOperator {
+    private readonly driver;
+    private readonly rooms;
+    private readonly exceptRooms;
+    private readonly exceptIds;
+    constructor(driver: SyncDriver, rooms?: Set<string>, exceptRooms?: Set<string>, exceptIds?: Set<string>);
+    to(room: string): this;
+    in(room: string): this;
+    except(room: string): this;
+    emit(event: string, data?: unknown): void | Promise<void>;
+}
+/**
+ * The `@WebSocketServer()`-injected handle. Server-origin broadcasts never
+ * pre-exclude anyone (a client-origin `client.to()` seeds `exceptIds` with the
+ * sender — that lives in the transport's client, not here).
+ */
+export declare class WsServerImpl implements WsServer {
+    private readonly driver;
+    constructor(driver: SyncDriver);
+    emit(event: string, data?: unknown): void | Promise<void>;
+    to(room: string): BroadcastOperator;
+    in(room: string): BroadcastOperator;
+    except(room: string): BroadcastOperator;
+}

package/dist/websocket/ws-server.js

@@ -0,0 +1,74 @@
+/**
+ * Accumulates `{ rooms, exceptRooms, exceptIds }` across a fluent chain and, on
+ * `.emit()`, produces a serializable `BroadcastCommand` handed to the active
+ * `SyncDriver`. The driver decides local-vs-remote delivery.
+ */ export class BroadcastOperatorImpl {
+    driver;
+    rooms;
+    exceptRooms;
+    exceptIds;
+    constructor(driver, rooms = new Set(), exceptRooms = new Set(), exceptIds = new Set()){
+        this.driver = driver;
+        this.rooms = rooms;
+        this.exceptRooms = exceptRooms;
+        this.exceptIds = exceptIds;
+    }
+    to(room) {
+        this.rooms.add(room);
+        return this;
+    }
+    in(room) {
+        return this.to(room);
+    }
+    except(room) {
+        this.exceptRooms.add(room);
+        return this;
+    }
+    emit(event, data) {
+        const cmd = {
+            rooms: [
+                ...this.rooms
+            ],
+            exceptRooms: this.exceptRooms.size ? [
+                ...this.exceptRooms
+            ] : undefined,
+            exceptIds: this.exceptIds.size ? [
+                ...this.exceptIds
+            ] : undefined,
+            frame: JSON.stringify({
+                event,
+                data
+            })
+        };
+        return this.driver.dispatch(cmd);
+    }
+}
+/**
+ * The `@WebSocketServer()`-injected handle. Server-origin broadcasts never
+ * pre-exclude anyone (a client-origin `client.to()` seeds `exceptIds` with the
+ * sender — that lives in the transport's client, not here).
+ */ export class WsServerImpl {
+    driver;
+    constructor(driver){
+        this.driver = driver;
+    }
+    emit(event, data) {
+        // Empty `rooms` means GLOBAL.
+        return this.driver.dispatch({
+            rooms: [],
+            frame: JSON.stringify({
+                event,
+                data
+            })
+        });
+    }
+    to(room) {
+        return new BroadcastOperatorImpl(this.driver).to(room);
+    }
+    in(room) {
+        return this.to(room);
+    }
+    except(room) {
+        return new BroadcastOperatorImpl(this.driver).except(room);
+    }
+}

package/dist/websocket/ws-sync.d.ts

@@ -0,0 +1,47 @@
+import type { BroadcastCommand, WsClient } from './websocket.types';
+/**
+ * Owns LOCAL room membership and local fan-out for the connections a single
+ * node/isolate holds. The Cloudflare transport backs this with hibernation
+ * tags + attachment; node/bun/deno back it with the in-memory implementation
+ * below. Always edge-safe (no `node:*`).
+ */
+export interface RoomRegistry {
+    /** Register a connection (called on connect) so global broadcasts can reach it. */
+    register(client: WsClient): void;
+    join(client: WsClient, room: string): void | Promise<void>;
+    leave(client: WsClient, room: string): void | Promise<void>;
+    /** Remove a connection and all its room memberships (called on disconnect). */
+    leaveAll(client: WsClient): void | Promise<void>;
+    /** Deliver a command to the sockets THIS node holds, applying every exclusion. */
+    deliverLocal(cmd: BroadcastCommand): void | Promise<void>;
+    localIdsInRoom(room: string): string[];
+}
+/**
+ * Pluggable cross-instance transport for broadcast commands. `local()` is the
+ * zero-config single-instance default; `durableObject()` (Cloudflare) and
+ * `redis()` (node) are additive and chosen at the composition root.
+ */
+export interface SyncDriver {
+    readonly kind: string;
+    /** Wire the local registry so the driver can deliver to locally-held sockets. */
+    bind(registry: RoomRegistry): void;
+    /** Route a command so every node that may hold a matching socket delivers it. */
+    dispatch(cmd: BroadcastCommand): void | Promise<void>;
+    countRoom?(room: string): Promise<number>;
+    start?(): void | Promise<void>;
+    stop?(): void | Promise<void>;
+}
+/** Single-instance default: deliver straight to the local registry, no cross-node hop. */
+export declare function local(): SyncDriver;
+/** In-memory `RoomRegistry` for node/bun/deno and tests. Edge-safe (plain Maps). */
+export declare class InMemoryRoomRegistry implements RoomRegistry {
+    private readonly rooms;
+    private readonly clientRooms;
+    private readonly clients;
+    register(client: WsClient): void;
+    join(client: WsClient, room: string): void;
+    leave(client: WsClient, room: string): void;
+    leaveAll(client: WsClient): void;
+    localIdsInRoom(room: string): string[];
+    deliverLocal(cmd: BroadcastCommand): void;
+}