@velajs/vela 1.19.0 → 1.19.1

package/dist/websocket/websocket.decorators.js

@@ -1,80 +0,0 @@
-import { Scope } from "../constants.js";
-import { Inject } from "../container/decorators.js";
-import { createDiscoverableDecorator } from "../discovery/index.js";
-import { MetadataRegistry } from "../registry/metadata.registry.js";
-import { RESERVED_WS_EVENT_PREFIX, WS_GATEWAY_METADATA, WS_RESERVED_METADATA, WS_SERVER, WS_SUBSCRIBE_METADATA, WsParamType } from "./websocket.tokens.js";
-/**
- * Marks a class as a WebSocket gateway. Mirrors `@Controller` for the socket
- * transport: registers the class as an injectable singleton and stores its
- * routing options (`path`, Cloudflare `binding`).
- *
- * @example
- * ```ts
- * @WebSocketGateway({ path: '/rooms/:id/ws', binding: 'CHAT_ROOM' })
- * class ChatGateway {}
- * ```
- */ export function WebSocketGateway(options = {}) {
-    return (target)=>{
-        const ctor = target;
-        MetadataRegistry.setCustomClassMeta(ctor, WS_GATEWAY_METADATA, options);
-        MetadataRegistry.markInjectable(ctor);
-        MetadataRegistry.setScope(ctor, Scope.SINGLETON);
-    };
-}
-/**
- * Binds a gateway method to an inbound event. Stackable — one class-level list,
- * exactly like `@OnEvent` (`event-emitter.decorators.ts`).
- */ export function SubscribeMessage(event) {
-    return (target, propertyKey)=>{
-        MetadataRegistry.appendCustomClassMeta(target.constructor, WS_SUBSCRIBE_METADATA, {
-            event,
-            methodName: String(propertyKey)
-        });
-    };
-}
-const ReservedWsEventMeta = createDiscoverableDecorator(WS_RESERVED_METADATA);
-/**
- * Claims a reserved (`$`-prefixed) envelope event for a framework-module
- * provider (see `ReservedWsEventHandler`). Reserved frames route to the
- * decorated provider across every gateway path — gateways themselves may not
- * subscribe to `$…` events. Stack with `@Injectable()` like `@Processor`.
- *
- * @example
- * ```ts
- * @ReservedWsEvent('$live')
- * @Injectable()
- * class LiveEngine implements ReservedWsEventHandler { … }
- * ```
- */ export function ReservedWsEvent(event) {
-    if (!event.startsWith(RESERVED_WS_EVENT_PREFIX)) {
-        throw new Error(`@ReservedWsEvent('${event}') must claim a '${RESERVED_WS_EVENT_PREFIX}'-prefixed event — ` + 'unprefixed events belong to app gateways (@SubscribeMessage).');
-    }
-    return ReservedWsEventMeta({
-        event
-    });
-}
-function wsParamDecorator(type) {
-    return ()=>(target, propertyKey, parameterIndex)=>{
-            if (propertyKey === undefined) {
-                throw new Error('WebSocket parameter decorators can only be used on method parameters');
-            }
-            MetadataRegistry.addParameter(target.constructor, propertyKey, {
-                index: parameterIndex,
-                type
-            });
-        };
-}
-/** Injects the inbound message payload (the envelope's `data`) into a handler parameter. */ export const MessageBody = wsParamDecorator(WsParamType.BODY);
-/** Injects the connected socket (`WsClient`) into a handler parameter. */ export const ConnectedSocket = wsParamDecorator(WsParamType.SOCKET);
-/**
- * Injects the gateway server handle (`WsServer`). Constructor injection only —
- * the container has no property-injection pass, so this is sugar for
- * `@Inject(WS_SERVER)` on a constructor parameter.
- *
- * @example
- * ```ts
- * constructor(@WebSocketServer() private server: WsServer) {}
- * ```
- */ export function WebSocketServer() {
-    return Inject(WS_SERVER);
-}

package/dist/websocket/websocket.module.d.ts

@@ -1,35 +0,0 @@
-import { type RoomRegistry, type SyncDriver } from './ws-sync';
-export interface WebSocketModuleOptions {
-    /**
-     * Cross-instance sync driver. Defaults to `local()` (single instance). Use
-     * `durableObject()` from `@velajs/cloudflare` or `redis()` from
-     * `@velajs/vela/websocket-node` for horizontal scale.
-     */
-    sync?: SyncDriver;
-    /**
-     * Local room registry the transport reads/writes. Defaults to the in-memory
-     * implementation (node/bun/deno); the Cloudflare transport supplies its own.
-     */
-    registry?: RoomRegistry;
-}
-/**
- * Registers the WebSocket gateway machinery: the message dispatcher (discovers
- * `@WebSocketGateway` classes via DiscoveryService at bootstrap), the room
- * registry, the sync driver, and the `@WebSocketServer()`-injected server
- * handle.
- *
- * Construction lives in chained provider factories — registry → driver
- * (bound to THAT registry) → server — so the single shared registry instance
- * is preserved and everything materializes at bootstrap's eager
- * instantiation, before any lifecycle hook or message dispatch.
- *
- * The instance key derives from the sync driver kind: two `forRoot()` calls
- * with the same driver kind dedup (HMR-idempotent); pass an explicit `key`
- * to run multiple same-kind instances side by side.
- */
-declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<WebSocketModuleOptions, "forRoot", "create", {
-    isGlobal?: boolean;
-}>;
-export declare class WebSocketModule extends ConfigurableModuleClass {
-}
-export {};

package/dist/websocket/websocket.module.js

@@ -1,63 +0,0 @@
-import { defineModule } from "../module/define-module.js";
-import { WsDispatcher } from "./ws-dispatcher.js";
-import { WsServerImpl } from "./ws-server.js";
-import { InMemoryRoomRegistry, local } from "./ws-sync.js";
-import { WS_MODULE_OPTIONS, WS_ROOM_REGISTRY, WS_SERVER, WS_SYNC_DRIVER } from "./websocket.tokens.js";
-/**
- * Registers the WebSocket gateway machinery: the message dispatcher (discovers
- * `@WebSocketGateway` classes via DiscoveryService at bootstrap), the room
- * registry, the sync driver, and the `@WebSocketServer()`-injected server
- * handle.
- *
- * Construction lives in chained provider factories — registry → driver
- * (bound to THAT registry) → server — so the single shared registry instance
- * is preserved and everything materializes at bootstrap's eager
- * instantiation, before any lifecycle hook or message dispatch.
- *
- * The instance key derives from the sync driver kind: two `forRoot()` calls
- * with the same driver kind dedup (HMR-idempotent); pass an explicit `key`
- * to run multiple same-kind instances side by side.
- */ const { ConfigurableModuleClass } = defineModule({
-    name: 'WebSocket',
-    optionsToken: WS_MODULE_OPTIONS,
-    key: (options)=>`ws#${options.sync?.kind ?? 'local'}`,
-    setup: ({ OPTIONS })=>({
-            providers: [
-                {
-                    provide: WS_ROOM_REGISTRY,
-                    useFactory: (o)=>o.registry ?? new InMemoryRoomRegistry(),
-                    inject: [
-                        OPTIONS
-                    ]
-                },
-                {
-                    provide: WS_SYNC_DRIVER,
-                    useFactory: (o, registry)=>{
-                        const driver = o.sync ?? local();
-                        driver.bind(registry);
-                        return driver;
-                    },
-                    inject: [
-                        OPTIONS,
-                        WS_ROOM_REGISTRY
-                    ]
-                },
-                {
-                    provide: WS_SERVER,
-                    useFactory: (driver)=>new WsServerImpl(driver),
-                    inject: [
-                        WS_SYNC_DRIVER
-                    ]
-                },
-                WsDispatcher
-            ],
-            exports: [
-                WS_SERVER,
-                WS_SYNC_DRIVER,
-                WS_ROOM_REGISTRY,
-                WsDispatcher
-            ]
-        })
-});
-export class WebSocketModule extends ConfigurableModuleClass {
-}

package/dist/websocket/websocket.tokens.d.ts

@@ -1,30 +0,0 @@
-import { InjectionToken } from '../container/types';
-import type { WebSocketModuleOptions } from './websocket.module';
-import type { RoomRegistry, SyncDriver } from './ws-sync';
-import type { WsServer } from './websocket.types';
-export declare const WS_GATEWAY_METADATA = "vela:ws-gateway";
-export declare const WS_SUBSCRIBE_METADATA = "vela:ws-subscribe";
-export declare const WS_RESERVED_METADATA = "vela:ws-reserved";
-/**
- * Event names starting with this prefix are RESERVED for framework modules
- * (`$live`, …): app gateways may not subscribe to them, and inbound frames
- * carrying them route to `@ReservedWsEvent` handlers instead of gateways.
- */
-export declare const RESERVED_WS_EVENT_PREFIX = "$";
-export declare const WsParamType: {
-    readonly SOCKET: "ws_socket";
-    readonly BODY: "ws_body";
-    readonly SERVER: "ws_server";
-};
-export type WsParamType = (typeof WsParamType)[keyof typeof WsParamType];
-/**
- * The connected gateway server handle. Injected into gateways/controllers via
- * `@WebSocketServer()` (constructor injection only — the container has no
- * property-injection pass) or `@Inject(WS_SERVER)`.
- */
-export declare const WS_SERVER: InjectionToken<WsServer>;
-/** The active cross-instance sync driver (`local()` by default). */
-export declare const WS_SYNC_DRIVER: InjectionToken<SyncDriver>;
-/** The local room-membership registry a transport reads/writes. */
-export declare const WS_ROOM_REGISTRY: InjectionToken<RoomRegistry>;
-export declare const WS_MODULE_OPTIONS: InjectionToken<WebSocketModuleOptions>;

package/dist/websocket/websocket.tokens.js

@@ -1,27 +0,0 @@
-import { InjectionToken } from "../container/types.js";
-// Free-form metadata keys — same string-token convention as ON_EVENT_METADATA / CRON_METADATA.
-export const WS_GATEWAY_METADATA = 'vela:ws-gateway';
-export const WS_SUBSCRIBE_METADATA = 'vela:ws-subscribe';
-export const WS_RESERVED_METADATA = 'vela:ws-reserved';
-/**
- * Event names starting with this prefix are RESERVED for framework modules
- * (`$live`, …): app gateways may not subscribe to them, and inbound frames
- * carrying them route to `@ReservedWsEvent` handlers instead of gateways.
- */ export const RESERVED_WS_EVENT_PREFIX = '$';
-// WebSocket parameter-decorator kinds — parallel to `ParamType` for HTTP, keyed
-// by the WS argument resolver rather than the Hono-bound HTTP one.
-export const WsParamType = {
-    SOCKET: 'ws_socket',
-    BODY: 'ws_body',
-    SERVER: 'ws_server'
-};
-/**
- * The connected gateway server handle. Injected into gateways/controllers via
- * `@WebSocketServer()` (constructor injection only — the container has no
- * property-injection pass) or `@Inject(WS_SERVER)`.
- */ export const WS_SERVER = new InjectionToken('WS_SERVER');
-/** The active cross-instance sync driver (`local()` by default). */ export const WS_SYNC_DRIVER = new InjectionToken('WS_SYNC_DRIVER');
-/** The local room-membership registry a transport reads/writes. */ export const WS_ROOM_REGISTRY = new InjectionToken('WS_ROOM_REGISTRY');
-// forRoot() options carrier — a typed InjectionToken like every other module
-// options token (the raw-string form was the odd one out).
-export const WS_MODULE_OPTIONS = new InjectionToken('WS_MODULE_OPTIONS');

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

@@ -1,102 +0,0 @@
-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;
-}
-/** Class-level meta written by `@ReservedWsEvent(event)`. */
-export interface ReservedWsEventMetadata {
-    /** The reserved (`$`-prefixed) envelope event this provider handles. */
-    event: string;
-}
-/**
- * A provider claiming a reserved (`$`-prefixed) envelope event across EVERY
- * gateway path. Discovered by `WsDispatcher` at bootstrap via the
- * `@ReservedWsEvent` decorator; inbound frames for the event route here
- * (after app-wide guards), never to gateways. `handleSocketClose` fires for
- * every closing socket so the handler can drop per-connection state.
- */
-export interface ReservedWsEventHandler {
-    handleReservedEvent(path: string, client: WsClient, message: WsMessage): void | Promise<void>;
-    handleSocketClose?(path: string, client: WsClient): void | Promise<void>;
-}
-/**
- * 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

@@ -1,4 +0,0 @@
-/**
- * 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

@@ -1,13 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,54 +0,0 @@
-import { Container } from '../container/container';
-import { DiscoveryService } from '../discovery/discovery.service';
-import type { ContributesEntrypoints, Entrypoint } from '../entrypoint/entrypoint.types';
-import { RouteManager } from '../http/route.manager';
-import type { OnApplicationBootstrap } from '../lifecycle/index';
-import type { WsClient, WsServer } from './websocket.types';
-/** Metadata carried by each `'websocket'` entrypoint a transport consumes. */
-export interface WsEntrypointMeta {
-    /** The gateway's route path (from `@WebSocketGateway({ path })`). */
-    path: string;
-    /** The dispatcher that routes frames for this gateway. */
-    dispatcher: WsDispatcher;
-}
-/**
- * Discovers `@WebSocketGateway` classes at bootstrap (via `DiscoveryService`)
- * and routes inbound messages to `@SubscribeMessage` handlers. Transports read
- * the gateways from `app.entrypoints.ofKind('websocket')` (this dispatcher
- * contributes them) and call `handleOpen`, `dispatchMessage`, `handleClose`,
- * and `handleError`; the guard → pipe → interceptor → filter pipeline
- * (including `APP_*` global components) runs through the shared
- * `PipelineRunner`.
- */
-export declare class WsDispatcher implements OnApplicationBootstrap, ContributesEntrypoints {
-    private readonly container;
-    private readonly discovery;
-    private readonly server?;
-    private readonly routeManager?;
-    private readonly gateways;
-    private readonly reserved;
-    constructor(container: Container, discovery: DiscoveryService, server?: WsServer | undefined, routeManager?: RouteManager | undefined);
-    /** Paths of every discovered `@WebSocketGateway` — used by transports to register routes. */
-    get gatewayPaths(): string[];
-    onApplicationBootstrap(): Promise<void>;
-    /** One `'websocket'` entrypoint per discovered gateway (authoritative). */
-    collectEntrypoints(): Entrypoint<WsEntrypointMeta>[];
-    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>;
-    /**
-     * Route a reserved (`$…`) frame to its claiming handler. App-wide (`APP_*` /
-     * `useGlobalGuards`) guards protect reserved frames exactly like gateway
-     * messages — guards-first, WS convention; handler/class-tier components are
-     * the claiming module's own concern (e.g. live resolvers run their scoped
-     * guards at subscribe).
-     */
-    private dispatchReserved;
-    private reply;
-    private runFilters;
-    private trySend;
-    private reportBootstrapError;
-    private parse;
-    private buildGatewayEntry;
-}