@velajs/vela 1.9.0 → 1.12.0

package/dist/seeder/seeder.module.js

@@ -0,0 +1,41 @@
+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;
+}
+import { Module } from "../module/decorators.js";
+import { defineModule } from "../module/define-module.js";
+import { stableHash } from "../module/stable-hash.js";
+import { SeederRegistry } from "./seeder.registry.js";
+const { ConfigurableModuleClass } = defineModule({
+    name: 'Seeder',
+    // Class references aren't value-hashable — key on the seeder names, the same
+    // identity the hand-rolled forRoot used.
+    key: (options)=>stableHash({
+            seeders: (options.seeders ?? []).map((s)=>s.name)
+        }),
+    setup: ({ options })=>({
+            // Register seeder classes as providers so they're discovered at bootstrap.
+            // (Seeders declared in other modules' providers are also discovered — this
+            // is just a convenience to co-locate them.)
+            providers: [
+                ...options.seeders ?? []
+            ]
+        })
+});
+export class SeederModule extends ConfigurableModuleClass {
+}
+SeederModule = _ts_decorate([
+    Module({
+        providers: [
+            SeederRegistry
+        ],
+        exports: [
+            SeederRegistry
+        ]
+    })
+], SeederModule);
+/** Convenience runner: resolve the registry from a built app and run all seeders. */ export function runSeeders(app, options) {
+    return app.get(SeederRegistry).runAll(options);
+}

package/dist/seeder/seeder.registry.d.ts

@@ -0,0 +1,23 @@
+import { Container } from '../container/container';
+import type { OnApplicationBootstrap } from '../lifecycle/index';
+import type { RegisteredSeeder, SeederResult } from './seeder.types';
+/**
+ * Discovers `@Seeder()` providers at bootstrap and runs them on demand.
+ * Mirrors `ScheduleRegistry`'s discovery (scan container tokens → read metadata).
+ */
+export declare class SeederRegistry implements OnApplicationBootstrap {
+    private readonly container;
+    private seeders;
+    constructor(container: Container);
+    onApplicationBootstrap(): void;
+    /** Registered seeders in run order. */
+    list(): RegisteredSeeder[];
+    /**
+     * Run every seeder in order, each in its own request-scoped child container so
+     * request-scoped dependencies resolve. Returns a per-seeder result; when
+     * `stopOnError` is true (default) the run aborts on the first failure.
+     */
+    runAll(options?: {
+        stopOnError?: boolean;
+    }): Promise<SeederResult[]>;
+}

package/dist/seeder/seeder.registry.js

@@ -0,0 +1,83 @@
+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 } from "../container/index.js";
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+import { SEEDER_METADATA } from "./seeder.tokens.js";
+export class SeederRegistry {
+    container;
+    seeders = [];
+    constructor(container){
+        this.container = container;
+    }
+    onApplicationBootstrap() {
+        for (const token of this.container.getTokens()){
+            if (typeof token !== 'function') continue;
+            const meta = MetadataRegistry.getCustomClassMeta(token, SEEDER_METADATA);
+            if (!meta) continue;
+            this.seeders.push({
+                target: token,
+                name: meta.name ?? token.name,
+                order: meta.order ?? 0
+            });
+        }
+        this.seeders.sort((a, b)=>a.order - b.order);
+    }
+    /** Registered seeders in run order. */ list() {
+        return [
+            ...this.seeders
+        ];
+    }
+    /**
+   * Run every seeder in order, each in its own request-scoped child container so
+   * request-scoped dependencies resolve. Returns a per-seeder result; when
+   * `stopOnError` is true (default) the run aborts on the first failure.
+   */ async runAll(options = {}) {
+        const stopOnError = options.stopOnError ?? true;
+        const results = [];
+        for (const seeder of this.seeders){
+            const child = this.container.createChild();
+            let failed = false;
+            try {
+                const instance = child.resolve(seeder.target);
+                await instance.run();
+                results.push({
+                    name: seeder.name,
+                    ok: true
+                });
+            } catch (error) {
+                results.push({
+                    name: seeder.name,
+                    ok: false,
+                    error
+                });
+                failed = true;
+            } finally{
+                // Dispose the per-seeder child so its request-scoped disposables clean up.
+                await child.dispose();
+            }
+            if (failed && stopOnError) break;
+        }
+        return results;
+    }
+}
+SeederRegistry = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(Container)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof Container === "undefined" ? Object : Container
+    ])
+], SeederRegistry);

package/dist/seeder/seeder.tokens.d.ts

@@ -0,0 +1,2 @@
+/** Custom class-metadata key for `@Seeder()` (read during bootstrap discovery). */
+export declare const SEEDER_METADATA = "vela:seeder";

package/dist/seeder/seeder.tokens.js

@@ -0,0 +1 @@
+/** Custom class-metadata key for `@Seeder()` (read during bootstrap discovery). */ export const SEEDER_METADATA = 'vela:seeder';

package/dist/seeder/seeder.types.d.ts

@@ -0,0 +1,20 @@
+/** A database seeder. Implement `run()` and tag the class with `@Seeder()`. */
+export interface Seeder {
+    run(): void | Promise<void>;
+}
+export interface SeederMetadata {
+    /** Display name (defaults to the class name). */
+    name?: string;
+    /** Ascending run order (default 0). */
+    order?: number;
+}
+export interface RegisteredSeeder {
+    name: string;
+    order: number;
+    target: new (...args: any[]) => Seeder;
+}
+export interface SeederResult {
+    name: string;
+    ok: boolean;
+    error?: unknown;
+}

package/dist/seeder/seeder.types.js

@@ -0,0 +1 @@
+/** A database seeder. Implement `run()` and tag the class with `@Seeder()`. */ export { };

package/dist/storage/index.d.ts

@@ -0,0 +1,4 @@
+export { signUrl, verifySignedUrl } from './signed-url';
+export type { SignedUrlOptions } from './signed-url';
+export { expandPathTemplate, joinStoragePath } from './path-template';
+export type { StorageBody, StorageDriver, PresignMethod, UploadOptions, UploadResult, DownloadResult, PresignedUrlResult, } from './storage.types';

package/dist/storage/index.js

@@ -0,0 +1,2 @@
+export { signUrl, verifySignedUrl } from "./signed-url.js";
+export { expandPathTemplate, joinStoragePath } from "./path-template.js";

package/dist/storage/path-template.d.ts

@@ -0,0 +1,9 @@
+export declare function expandPathTemplate(template: string, now?: Date): string;
+/**
+ * Join a (templated) root with a relative path into a storage key. Segments are
+ * sanitized: `.`, `..`, and empty segments are dropped, so a caller-supplied
+ * `relativePath` containing `..` can never traverse above the disk root (a real
+ * hazard for the presign proxy, where the key flows through `new URL()` which
+ * would otherwise normalize `..`). Backslashes are treated as separators too.
+ */
+export declare function joinStoragePath(root: string | undefined, relativePath: string, now?: Date): string;

package/dist/storage/path-template.js

@@ -0,0 +1,20 @@
+// Expand path-template variables in a disk root / key. Supported tokens:
+//   {date}  → YYYY-MM-DD    {year} → YYYY    {month} → MM    {day} → DD
+//   {uuid}  → crypto.randomUUID()
+// `now` is injectable for deterministic tests.
+export function expandPathTemplate(template, now = new Date()) {
+    const yyyy = now.getUTCFullYear().toString();
+    const mm = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+    const dd = now.getUTCDate().toString().padStart(2, '0');
+    return template.replace(/\{date\}/g, `${yyyy}-${mm}-${dd}`).replace(/\{year\}/g, yyyy).replace(/\{month\}/g, mm).replace(/\{day\}/g, dd).replace(/\{uuid\}/g, ()=>crypto.randomUUID());
+}
+/**
+ * Join a (templated) root with a relative path into a storage key. Segments are
+ * sanitized: `.`, `..`, and empty segments are dropped, so a caller-supplied
+ * `relativePath` containing `..` can never traverse above the disk root (a real
+ * hazard for the presign proxy, where the key flows through `new URL()` which
+ * would otherwise normalize `..`). Backslashes are treated as separators too.
+ */ export function joinStoragePath(root, relativePath, now) {
+    const expandedRoot = root ? expandPathTemplate(root, now) : '';
+    return `${expandedRoot}/${relativePath}`.split(/[/\\]+/).filter((segment)=>segment !== '' && segment !== '.' && segment !== '..').join('/');
+}

package/dist/storage/signed-url.d.ts

@@ -0,0 +1,12 @@
+export interface SignedUrlOptions {
+    /** Time-to-live in seconds; a matching `expires` param is added + enforced. */
+    expiresIn?: number;
+}
+/**
+ * Sign a URL (or path) with HMAC-SHA256, appending `signature` (and `expires`).
+ * The signature covers `pathname + search` (minus the signature param). Returns
+ * the full URL for absolute inputs, or `pathname?search` for relative ones.
+ */
+export declare function signUrl(url: string, secret: string, options?: SignedUrlOptions): Promise<string>;
+/** Verify a signed URL (timing-safe) and enforce `expires`. */
+export declare function verifySignedUrl(url: string, secret: string): Promise<boolean>;

package/dist/storage/signed-url.js

@@ -0,0 +1,55 @@
+// Signed-URL utilities using HMAC-SHA256 via the Web Crypto API (edge-safe;
+// no node:crypto). Verification uses crypto.subtle.verify for timing-safety.
+// Pattern: https://developers.cloudflare.com/workers/examples/signing-requests/
+async function importKey(secret) {
+    return crypto.subtle.importKey('raw', new TextEncoder().encode(secret), {
+        name: 'HMAC',
+        hash: 'SHA-256'
+    }, false, [
+        'sign',
+        'verify'
+    ]);
+}
+function toBase64Url(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let binary = '';
+    for (const byte of bytes)binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromBase64Url(value) {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const binary = atob(base64);
+    const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+    for(let i = 0; i < binary.length; i++)bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/**
+ * Sign a URL (or path) with HMAC-SHA256, appending `signature` (and `expires`).
+ * The signature covers `pathname + search` (minus the signature param). Returns
+ * the full URL for absolute inputs, or `pathname?search` for relative ones.
+ */ export async function signUrl(url, secret, options) {
+    const parsed = new URL(url, 'https://placeholder.local');
+    const key = await importKey(secret);
+    if (options?.expiresIn) {
+        const expires = Math.floor(Date.now() / 1000) + options.expiresIn;
+        parsed.searchParams.set('expires', String(expires));
+    }
+    const dataToSign = `${parsed.pathname}?${parsed.searchParams.toString()}`;
+    const signatureBuffer = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(dataToSign));
+    parsed.searchParams.set('signature', toBase64Url(signatureBuffer));
+    return url.startsWith('http') ? parsed.toString() : `${parsed.pathname}?${parsed.searchParams.toString()}`;
+}
+/** Verify a signed URL (timing-safe) and enforce `expires`. */ export async function verifySignedUrl(url, secret) {
+    const parsed = new URL(url, 'https://placeholder.local');
+    const signature = parsed.searchParams.get('signature');
+    if (!signature) return false;
+    const expires = parsed.searchParams.get('expires');
+    if (expires) {
+        const expiryTime = parseInt(expires, 10);
+        if (Number.isNaN(expiryTime) || Math.floor(Date.now() / 1000) > expiryTime) return false;
+    }
+    parsed.searchParams.delete('signature');
+    const dataToVerify = `${parsed.pathname}?${parsed.searchParams.toString()}`;
+    const key = await importKey(secret);
+    return crypto.subtle.verify('HMAC', key, fromBase64Url(signature), new TextEncoder().encode(dataToVerify));
+}

package/dist/storage/storage.types.d.ts

@@ -0,0 +1,41 @@
+/** Body payloads accepted by uploads. */
+export type StorageBody = ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null;
+export type PresignMethod = 'GET' | 'PUT' | 'DELETE' | 'HEAD';
+export interface UploadOptions {
+    size?: number;
+    mimeType?: string;
+    metadata?: Record<string, string>;
+}
+export interface UploadResult {
+    path: string;
+    disk: string;
+    size?: number;
+    mimeType: string;
+    uploadedAt: Date;
+}
+export interface DownloadResult {
+    toStream(): ReadableStream;
+    toArrayBuffer(): Promise<ArrayBuffer>;
+    toText(): Promise<string>;
+    contentType: string;
+    size: number;
+    metadata?: Record<string, string>;
+}
+export interface PresignedUrlResult {
+    url: string;
+    method: PresignMethod;
+    expiresIn: number;
+    expiresAt: Date;
+}
+/**
+ * Runtime-agnostic storage driver contract. Implement per backend (R2 in
+ * `@velajs/cloudflare`, and e.g. S3/GCS elsewhere) so the manager/service and
+ * multi-disk logic stay driver-independent.
+ */
+export interface StorageDriver {
+    upload(body: StorageBody, path: string, options: UploadOptions): Promise<UploadResult>;
+    download(path: string): Promise<DownloadResult>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getPresignedUrl(path: string, method: PresignMethod, expiresIn: number): Promise<PresignedUrlResult>;
+}

package/dist/storage/storage.types.js

@@ -0,0 +1,5 @@
+/** Body payloads accepted by uploads. */ /**
+ * Runtime-agnostic storage driver contract. Implement per backend (R2 in
+ * `@velajs/cloudflare`, and e.g. S3/GCS elsewhere) so the manager/service and
+ * multi-disk logic stay driver-independent.
+ */ export { };

package/dist/throttler/throttler.module.d.ts

@@ -1,10 +1,7 @@
-import type { AsyncModuleOptions, DynamicModule } from '../module/types';
 import type { ThrottlerModuleOptions } from './throttler.types';
-export declare class ThrottlerModule {
-    static forRoot(options: ThrottlerModuleOptions & {
-        key?: string;
-    }): DynamicModule;
-    static forRootAsync(options: AsyncModuleOptions<ThrottlerModuleOptions> & {
-        key?: string;
-    }): DynamicModule;
+declare const ConfigurableModuleClass: import("..").ConfigurableModuleClassType<ThrottlerModuleOptions, "forRoot", "create", {
+    isGlobal?: boolean;
+}>;
+export declare class ThrottlerModule extends ConfigurableModuleClass {
 }
+export {};

package/dist/throttler/throttler.module.js

@@ -1,48 +1,29 @@
-import { stableHash } from "../module/stable-hash.js";
+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;
+}
+import { Module } from "../module/decorators.js";
+import { ConfigurableModuleBuilder } from "../module/configurable-module.builder.js";
 import { APP_GUARD } from "../pipeline/tokens.js";
 import { ThrottlerGuard } from "./throttler.guard.js";
 import { ThrottlerStorage } from "./throttler.storage.js";
 import { THROTTLER_OPTIONS, THROTTLER_STORAGE } from "./throttler.tokens.js";
-export class ThrottlerModule {
-    static forRoot(options) {
-        const providers = [
-            {
-                provide: THROTTLER_OPTIONS,
-                useValue: options
-            },
-            {
-                provide: THROTTLER_STORAGE,
-                useValue: options.storage ?? new ThrottlerStorage()
-            },
-            ThrottlerGuard,
-            {
-                provide: APP_GUARD,
-                useExisting: ThrottlerGuard
-            }
-        ];
-        return {
-            module: ThrottlerModule,
-            key: options.key ?? stableHash(options),
-            providers,
-            exports: [
-                THROTTLER_OPTIONS,
-                THROTTLER_STORAGE,
-                ThrottlerGuard
-            ]
-        };
-    }
-    static forRootAsync(options) {
-        const providers = [
-            {
-                provide: THROTTLER_OPTIONS,
-                useFactory: options.useFactory,
-                inject: options.inject ?? []
-            },
+const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN } = new ConfigurableModuleBuilder({
+    moduleName: 'Throttler',
+    optionsInjectionToken: THROTTLER_OPTIONS
+}).build();
+export class ThrottlerModule extends ConfigurableModuleClass {
+}
+ThrottlerModule = _ts_decorate([
+    Module({
+        providers: [
             {
                 provide: THROTTLER_STORAGE,
-                useFactory: (opts)=>opts.storage ?? new ThrottlerStorage(),
+                useFactory: (options)=>options.storage ?? new ThrottlerStorage(),
                 inject: [
-                    THROTTLER_OPTIONS
+                    MODULE_OPTIONS_TOKEN
                 ]
             },
             ThrottlerGuard,
@@ -50,20 +31,11 @@ export class ThrottlerModule {
                 provide: APP_GUARD,
                 useExisting: ThrottlerGuard
             }
-        ];
-        return {
-            module: ThrottlerModule,
-            key: options.key ?? stableHash({
-                inject: options.inject,
-                useFactory: options.useFactory
-            }),
-            imports: options.imports ?? [],
-            providers,
-            exports: [
-                THROTTLER_OPTIONS,
-                THROTTLER_STORAGE,
-                ThrottlerGuard
-            ]
-        };
-    }
-}
+        ],
+        exports: [
+            THROTTLER_OPTIONS,
+            THROTTLER_STORAGE,
+            ThrottlerGuard
+        ]
+    })
+], ThrottlerModule);

package/dist/websocket/index.d.ts

@@ -0,0 +1,12 @@
+export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer, } from './websocket.decorators';
+export { WebSocketModule } from './websocket.module';
+export type { WebSocketModuleOptions } from './websocket.module';
+export { WsDispatcher, type WsEntrypointMeta } from './ws-dispatcher';
+export { WsServerImpl, BroadcastOperatorImpl } from './ws-server';
+export { InMemoryRoomRegistry, local } from './ws-sync';
+export type { SyncDriver, RoomRegistry } from './ws-sync';
+export { buildWsExecutionContext } from './ws-execution-context';
+export { WsException, toErrorFrame } from './ws-exception';
+export { resolveWsArgs } from './ws-argument-resolver';
+export { WS_SERVER, WS_SYNC_DRIVER, WS_ROOM_REGISTRY, WS_MODULE_OPTIONS, WS_GATEWAY_METADATA, WS_SUBSCRIBE_METADATA, WsParamType, } from './websocket.tokens';
+export type { WsClient, WsServer, WsMessage, WsResponse, BroadcastCommand, BroadcastOperator, WebSocketGatewayOptions, SubscribeMessageMetadata, WsExecutionContext, WsArgumentsHost, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect, } from './websocket.types';

package/dist/websocket/index.js

@@ -0,0 +1,16 @@
+// Decorators
+export { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WebSocketServer } from "./websocket.decorators.js";
+// Module
+export { WebSocketModule } from "./websocket.module.js";
+// Dispatcher (injected/called by transports) + the 'websocket' entrypoint meta
+export { WsDispatcher } from "./ws-dispatcher.js";
+// Server handle + rooms + sync
+export { WsServerImpl, BroadcastOperatorImpl } from "./ws-server.js";
+export { InMemoryRoomRegistry, local } from "./ws-sync.js";
+// Execution context + exceptions
+export { buildWsExecutionContext } from "./ws-execution-context.js";
+export { WsException, toErrorFrame } from "./ws-exception.js";
+// Argument resolution (used by transports building custom dispatch)
+export { resolveWsArgs } from "./ws-argument-resolver.js";
+// Tokens
+export { WS_SERVER, WS_SYNC_DRIVER, WS_ROOM_REGISTRY, WS_MODULE_OPTIONS, WS_GATEWAY_METADATA, WS_SUBSCRIBE_METADATA, WsParamType } from "./websocket.tokens.js";

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

@@ -0,0 +1,33 @@
+import type { WebSocketGatewayOptions } from './websocket.types';
+/**
+ * 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 declare function WebSocketGateway(options?: WebSocketGatewayOptions): ClassDecorator;
+/**
+ * Binds a gateway method to an inbound event. Stackable — one class-level list,
+ * exactly like `@OnEvent` (`event-emitter.decorators.ts`).
+ */
+export declare function SubscribeMessage(event: string): MethodDecorator;
+/** Injects the inbound message payload (the envelope's `data`) into a handler parameter. */
+export declare const MessageBody: () => ParameterDecorator;
+/** Injects the connected socket (`WsClient`) into a handler parameter. */
+export declare const ConnectedSocket: () => ParameterDecorator;
+/**
+ * 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 declare function WebSocketServer(): ParameterDecorator;

package/dist/websocket/websocket.decorators.js

@@ -0,0 +1,58 @@
+import { Scope } from "../constants.js";
+import { Inject } from "../container/decorators.js";
+import { MetadataRegistry } from "../registry/metadata.registry.js";
+import { WS_GATEWAY_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)
+        });
+    };
+}
+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

@@ -0,0 +1,35 @@
+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 {};