@velajs/vela 1.8.8 → 1.10.0

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;
+}

package/dist/websocket/ws-sync.js

@@ -0,0 +1,74 @@
+/** Single-instance default: deliver straight to the local registry, no cross-node hop. */ export function local() {
+    let registry;
+    return {
+        kind: 'local',
+        bind (r) {
+            registry = r;
+        },
+        dispatch (cmd) {
+            return registry?.deliverLocal(cmd);
+        }
+    };
+}
+/** In-memory `RoomRegistry` for node/bun/deno and tests. Edge-safe (plain Maps). */ export class InMemoryRoomRegistry {
+    rooms = new Map();
+    clientRooms = new Map();
+    clients = new Map();
+    register(client) {
+        this.clients.set(client.id, client);
+    }
+    join(client, room) {
+        this.register(client);
+        let members = this.rooms.get(room);
+        if (!members) {
+            members = new Set();
+            this.rooms.set(room, members);
+        }
+        members.add(client);
+        let joined = this.clientRooms.get(client.id);
+        if (!joined) {
+            joined = new Set();
+            this.clientRooms.set(client.id, joined);
+        }
+        joined.add(room);
+    }
+    leave(client, room) {
+        const members = this.rooms.get(room);
+        members?.delete(client);
+        if (members && members.size === 0) this.rooms.delete(room);
+        this.clientRooms.get(client.id)?.delete(room);
+    }
+    leaveAll(client) {
+        for (const room of this.clientRooms.get(client.id) ?? []){
+            const members = this.rooms.get(room);
+            members?.delete(client);
+            if (members && members.size === 0) this.rooms.delete(room);
+        }
+        this.clientRooms.delete(client.id);
+        this.clients.delete(client.id);
+    }
+    localIdsInRoom(room) {
+        return [
+            ...this.rooms.get(room) ?? []
+        ].map((c)=>c.id);
+    }
+    deliverLocal(cmd) {
+        const excludeIds = new Set(cmd.exceptIds ?? []);
+        const excludeRooms = cmd.exceptRooms ?? [];
+        // Empty `rooms` => GLOBAL: every registered connection. Otherwise the union
+        // of the targeted rooms' members (deduped per connection).
+        const candidates = cmd.rooms.length === 0 ? new Set(this.clients.values()) : (()=>{
+            const set = new Set();
+            for (const room of cmd.rooms){
+                for (const client of this.rooms.get(room) ?? [])set.add(client);
+            }
+            return set;
+        })();
+        for (const client of candidates){
+            if (excludeIds.has(client.id)) continue;
+            const joined = this.clientRooms.get(client.id);
+            if (excludeRooms.some((room)=>joined?.has(room))) continue;
+            client.sendRaw(cmd.frame);
+        }
+    }
+}

package/dist/websocket-node/index.d.ts

@@ -0,0 +1,4 @@
+export { NodeWsClient } from './node-ws-client';
+export { registerWebSocketGateways } from './register-gateways';
+export { redis } from './redis-sync';
+export type { RedisPubSubClient, RedisSyncOptions } from './redis-sync';

package/dist/websocket-node/index.js

@@ -0,0 +1,5 @@
+// Node / Bun / Deno WebSocket adapter for the Vela WebSocketModule.
+// Transport uses Hono's own `upgradeWebSocket` (no Durable Object hibernation).
+export { NodeWsClient } from "./node-ws-client.js";
+export { registerWebSocketGateways } from "./register-gateways.js";
+export { redis } from "./redis-sync.js";

package/dist/websocket-node/node-ws-client.d.ts

@@ -0,0 +1,24 @@
+import type { WSContext } from 'hono/ws';
+import type { RoomRegistry, WsClient } from '../websocket/index';
+/**
+ * Core `WsClient` over Hono's `WSContext` (node/bun/deno — no hibernation).
+ * Room membership is mirrored into the shared `RoomRegistry` so broadcasts from
+ * the `WsServer` reach this connection.
+ */
+export declare class NodeWsClient<TData extends Record<string, unknown> = Record<string, unknown>> implements WsClient<TData> {
+    private readonly ws;
+    private readonly registry;
+    readonly path: string;
+    readonly id: string;
+    data: TData;
+    private readonly _rooms;
+    constructor(ws: WSContext, registry: RoomRegistry, path: string);
+    get rooms(): ReadonlySet<string>;
+    get raw(): unknown;
+    send(event: string, data?: unknown, id?: string): void;
+    sendRaw(payload: string): void;
+    join(room: string): void | Promise<void>;
+    leave(room: string): void | Promise<void>;
+    commit(): void;
+    close(code?: number, reason?: string): void;
+}

package/dist/websocket-node/node-ws-client.js

@@ -0,0 +1,49 @@
+/**
+ * Core `WsClient` over Hono's `WSContext` (node/bun/deno — no hibernation).
+ * Room membership is mirrored into the shared `RoomRegistry` so broadcasts from
+ * the `WsServer` reach this connection.
+ */ export class NodeWsClient {
+    ws;
+    registry;
+    path;
+    id = crypto.randomUUID();
+    data = {};
+    _rooms = new Set();
+    constructor(ws, registry, path){
+        this.ws = ws;
+        this.registry = registry;
+        this.path = path;
+    }
+    get rooms() {
+        return this._rooms;
+    }
+    get raw() {
+        return this.ws;
+    }
+    send(event, data, id) {
+        this.ws.send(JSON.stringify(id !== undefined ? {
+            id,
+            event,
+            data
+        } : {
+            event,
+            data
+        }));
+    }
+    sendRaw(payload) {
+        this.ws.send(payload);
+    }
+    join(room) {
+        this._rooms.add(room);
+        return this.registry.join(this, room);
+    }
+    leave(room) {
+        this._rooms.delete(room);
+        return this.registry.leave(this, room);
+    }
+    // In-memory registry mutates eagerly; nothing deferred to persist.
+    commit() {}
+    close(code, reason) {
+        this.ws.close(code, reason);
+    }
+}

package/dist/websocket-node/redis-sync.d.ts

@@ -0,0 +1,33 @@
+import type { SyncDriver } from '../websocket/index';
+/**
+ * Minimal Redis pub/sub surface (satisfied by `ioredis` / `node-redis`). Pub and
+ * sub MUST be separate connections — a subscribed Redis connection cannot publish.
+ * `off`/`removeListener`/`unsubscribe` are optional and used only by `stop()`.
+ */
+export interface RedisPubSubClient {
+    publish(channel: string, message: string): unknown;
+    subscribe(channel: string): unknown;
+    on(event: 'message', listener: (channel: string, message: string) => void): unknown;
+    off?(event: 'message', listener: (channel: string, message: string) => void): unknown;
+    removeListener?(event: 'message', listener: (channel: string, message: string) => void): unknown;
+    unsubscribe?(channel: string): unknown;
+}
+export interface RedisSyncOptions {
+    /** Connection used to publish broadcast commands. */
+    pub: RedisPubSubClient;
+    /** Separate connection used to subscribe (kept in subscriber mode). */
+    sub: RedisPubSubClient;
+    /** Channel prefix. Default `vela:ws`. */
+    prefix?: string;
+}
+/**
+ * Cross-instance sync driver for node/bun via Redis pub/sub. Local-first: every
+ * `dispatch` delivers to this instance's sockets immediately, then fans the
+ * command out to peers on a single broadcast channel; each peer's registry
+ * filters delivery to its own local room members. The publishing instance drops
+ * its own echo via an `origin` stamp.
+ *
+ * Guarantees: at-most-once, no ordering across publishers, no replay — a fan-out
+ * bus, not a log. Pass it to `WebSocketModule.forRoot({ sync: redis({ pub, sub }) })`.
+ */
+export declare function redis(options: RedisSyncOptions): SyncDriver;

package/dist/websocket-node/redis-sync.js

@@ -0,0 +1,56 @@
+const swallow = (op)=>{
+    // Redis client calls return promises that reject on transport failure; a
+    // fan-out miss must never become an unhandled rejection that crashes the app.
+    void Promise.resolve(op).catch(()=>{});
+};
+/**
+ * Cross-instance sync driver for node/bun via Redis pub/sub. Local-first: every
+ * `dispatch` delivers to this instance's sockets immediately, then fans the
+ * command out to peers on a single broadcast channel; each peer's registry
+ * filters delivery to its own local room members. The publishing instance drops
+ * its own echo via an `origin` stamp.
+ *
+ * Guarantees: at-most-once, no ordering across publishers, no replay — a fan-out
+ * bus, not a log. Pass it to `WebSocketModule.forRoot({ sync: redis({ pub, sub }) })`.
+ */ export function redis(options) {
+    const prefix = options.prefix ?? 'vela:ws';
+    const channel = `${prefix}:broadcast`;
+    const origin = crypto.randomUUID();
+    let registry;
+    let bound = false;
+    const onMessage = (ch, message)=>{
+        if (ch !== channel) return;
+        let cmd;
+        try {
+            cmd = JSON.parse(message);
+        } catch  {
+            return;
+        }
+        if (cmd.origin === origin) return; // our own publish — already delivered locally
+        swallow(registry?.deliverLocal(cmd));
+    };
+    return {
+        kind: 'redis',
+        bind (reg) {
+            registry = reg;
+            if (bound) return; // idempotent — never stack duplicate 'message' listeners on re-bind
+            bound = true;
+            swallow(options.sub.subscribe(channel));
+            options.sub.on('message', onMessage);
+        },
+        dispatch (cmd) {
+            swallow(registry?.deliverLocal(cmd));
+            swallow(options.pub.publish(channel, JSON.stringify({
+                ...cmd,
+                origin
+            })));
+        },
+        stop () {
+            if (!bound) return;
+            bound = false;
+            options.sub.off?.('message', onMessage);
+            options.sub.removeListener?.('message', onMessage);
+            swallow(options.sub.unsubscribe?.(channel));
+        }
+    };
+}

package/dist/websocket-node/register-gateways.d.ts

@@ -0,0 +1,20 @@
+import type { UpgradeWebSocket } from 'hono/ws';
+import type { VelaApplication } from '../application';
+/**
+ * Registers every `@WebSocketGateway` on the app's Hono instance using the
+ * runtime's Hono `upgradeWebSocket` factory — the same call works on node
+ * (`@hono/node-ws` / `@hono/node-server` v2), Bun (`hono/bun`), and Deno
+ * (`hono/deno`). Each connection auto-joins the room from a `:id` route param
+ * (or the route path), mirroring the Cloudflare DO-per-room model.
+ *
+ * @example
+ * ```ts
+ * // Node
+ * const app = await VelaFactory.create(AppModule);
+ * const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app: app.getHonoApp() });
+ * registerWebSocketGateways(app, upgradeWebSocket);
+ * const server = serve({ fetch: app.fetch, port: 3000 });
+ * injectWebSocket(server);
+ * ```
+ */
+export declare function registerWebSocketGateways(app: VelaApplication, upgradeWebSocket: UpgradeWebSocket): void;

package/dist/websocket-node/register-gateways.js

@@ -0,0 +1,61 @@
+import { WsDispatcher, WS_ROOM_REGISTRY } from "../websocket/index.js";
+import { NodeWsClient } from "./node-ws-client.js";
+function toText(data) {
+    if (typeof data === 'string') return data;
+    if (data instanceof ArrayBuffer) return new TextDecoder().decode(data);
+    // Blob / SharedArrayBuffer — binary is out of scope for the JSON envelope protocol.
+    return undefined;
+}
+/**
+ * Registers every `@WebSocketGateway` on the app's Hono instance using the
+ * runtime's Hono `upgradeWebSocket` factory — the same call works on node
+ * (`@hono/node-ws` / `@hono/node-server` v2), Bun (`hono/bun`), and Deno
+ * (`hono/deno`). Each connection auto-joins the room from a `:id` route param
+ * (or the route path), mirroring the Cloudflare DO-per-room model.
+ *
+ * @example
+ * ```ts
+ * // Node
+ * const app = await VelaFactory.create(AppModule);
+ * const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app: app.getHonoApp() });
+ * registerWebSocketGateways(app, upgradeWebSocket);
+ * const server = serve({ fetch: app.fetch, port: 3000 });
+ * injectWebSocket(server);
+ * ```
+ */ export function registerWebSocketGateways(app, upgradeWebSocket) {
+    const hono = app.getHonoApp();
+    const dispatcher = app.get(WsDispatcher);
+    const registry = app.get(WS_ROOM_REGISTRY);
+    for (const path of dispatcher.gatewayPaths){
+        hono.get(path, upgradeWebSocket((c)=>{
+            const roomId = c.req.param('id') ?? path;
+            let client;
+            // Connection-setup barrier: messages queue behind join + handleConnection
+            // so an auth check in handleConnection runs before any message dispatches.
+            let ready = Promise.resolve();
+            const onSetupError = (err)=>{
+                void dispatcher.handleError(path, client, err);
+            };
+            return {
+                onOpen: (_evt, ws)=>{
+                    client = new NodeWsClient(ws, registry, path);
+                    registry.register(client);
+                    ready = Promise.resolve(client.join(roomId)).then(()=>dispatcher.handleOpen(path, client)).catch(onSetupError);
+                },
+                onMessage: (evt)=>{
+                    const text = toText(evt.data);
+                    if (text === undefined) return;
+                    void ready.then(()=>dispatcher.dispatchMessage(path, client, text)).catch(onSetupError);
+                },
+                onClose: (evt)=>{
+                    const code = evt.code || 1000;
+                    const reason = evt.reason || '';
+                    void Promise.resolve(dispatcher.handleClose(path, client, code, reason)).catch(onSetupError).finally(()=>registry.leaveAll(client));
+                },
+                onError: (evt)=>{
+                    void dispatcher.handleError(path, client, evt);
+                }
+            };
+        }));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/vela",
-  "version": "1.8.8",
+  "version": "1.10.0",
   "description": "NestJS-compatible framework for edge runtimes, powered by Hono",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,6 +21,26 @@
     "./schedule-node": {
       "types": "./dist/schedule-node/index.d.ts",
       "import": "./dist/schedule-node/index.js"
+    },
+    "./websocket": {
+      "types": "./dist/websocket/index.d.ts",
+      "import": "./dist/websocket/index.js"
+    },
+    "./websocket-node": {
+      "types": "./dist/websocket-node/index.d.ts",
+      "import": "./dist/websocket-node/index.js"
+    },
+    "./i18n": {
+      "types": "./dist/i18n/index.d.ts",
+      "import": "./dist/i18n/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js"
+    },
+    "./seeder": {
+      "types": "./dist/seeder/index.d.ts",
+      "import": "./dist/seeder/index.js"
     }
   },
   "files": [
@@ -62,6 +82,14 @@
   "dependencies": {
     "hono": "^4.12.26"
   },
+  "peerDependencies": {
+    "intl-messageformat": ">=10"
+  },
+  "peerDependenciesMeta": {
+    "intl-messageformat": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.16.18",
     "@swc/cli": "^0.8.1",
@@ -69,6 +97,7 @@
     "@types/bun": "latest",
     "@vitest/runner": "^4.1.9",
     "@vitest/snapshot": "^4.1.9",
+    "intl-messageformat": "^11.2.9",
     "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",
     "vitest": "^4.1.9",
@@ -78,6 +107,7 @@
     "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
     "test": "vitest run",
     "test:workers": "vitest run --config vitest.config.workers.ts",
+    "test:workers:als": "vitest run --config vitest.config.workers-als.ts",
     "typecheck": "tsc --noEmit"
   }
 }