@voltrix/websocket 0.3.0

package/dist/pipeline/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pipeline/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAE5B;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACJ,WAAW,GAA0B,EAAE,CAAC;IAEzD;;OAEG;IACH,GAAG,CAAC,UAA+B;QACjC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CACP,MAAuB,EACvB,KAAa,EACb,OAAY,EACZ,OAAqE;QAErE,MAAM,OAAO,GAA4B;YACvC,MAAM;YACN,KAAK;YACL,OAAO;SACR,CAAC;QAEF,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;QAEf,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAS,EAAiB,EAAE;YAClD,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;gBACf,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;YACpE,CAAC;YACD,KAAK,GAAG,CAAC,CAAC;YAEV,iFAAiF;YACjF,IAAI,CAAC,KAAK,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC;gBAClC,MAAM,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC/C,OAAO;YACT,CAAC;YAED,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC;YACxC,MAAM,UAAU,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;gBACnC,MAAM,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACxB,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,MAAM,QAAQ,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;CACF"}

package/dist/pipeline/parser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 📨 Normalization interface for WebSocket packets
+ */
+export interface WsPacket {
+    readonly event: string;
+    readonly data: any;
+}
+/**
+ * ⚙️ High-performance packet parser/serializer.
+ */
+export declare class WsPacketParser {
+    /**
+     * Parses a raw string or ArrayBuffer payload into a normalized WsPacket.
+     * Returns null if the payload does not conform to the expected format.
+     */
+    static parse(payload: string | ArrayBuffer | Buffer): WsPacket | null;
+    /**
+     * Serializes an event and data object into a JSON string payload.
+     */
+    static serialize(event: string, data: any): string;
+}

package/dist/pipeline/parser.js

@@ -0,0 +1,46 @@
+/**
+ * ⚙️ High-performance packet parser/serializer.
+ */
+export class WsPacketParser {
+    /**
+     * Parses a raw string or ArrayBuffer payload into a normalized WsPacket.
+     * Returns null if the payload does not conform to the expected format.
+     */
+    static parse(payload) {
+        let rawStr;
+        if (payload instanceof ArrayBuffer) {
+            rawStr = Buffer.from(payload).toString('utf8');
+        }
+        else if (Buffer.isBuffer(payload)) {
+            rawStr = payload.toString('utf8');
+        }
+        else {
+            rawStr = payload;
+        }
+        const trimmed = rawStr.trim();
+        // Quick early boundary validation: Must look like a JSON object
+        if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && typeof parsed.event === 'string') {
+                return {
+                    event: parsed.event,
+                    data: parsed.data !== undefined ? parsed.data : null
+                };
+            }
+        }
+        catch {
+            // Fail gracefully on invalid JSON structure
+        }
+        return null;
+    }
+    /**
+     * Serializes an event and data object into a JSON string payload.
+     */
+    static serialize(event, data) {
+        return JSON.stringify({ event, data });
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/pipeline/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../../src/pipeline/parser.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,MAAM,OAAO,cAAc;IACzB;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,OAAsC;QACjD,IAAI,MAAc,CAAC;QAEnB,IAAI,OAAO,YAAY,WAAW,EAAE,CAAC;YACnC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjD,CAAC;aAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,OAAO,CAAC;QACnB,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;QAE9B,gEAAgE;QAChE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACvD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACnC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC7E,OAAO;oBACL,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;iBACrD,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,KAAa,EAAE,IAAS;QACvC,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/processors/websocket.processor.d.ts

@@ -0,0 +1,12 @@
+import { DIContainer } from '@voltrix/injector';
+/**
+ * 🚀 Voltrix WebSocket Processor (The Compiler)
+ * Discovers gateways, binds dependency injection, and pre-compiles execution pipelines.
+ */
+export declare class WebSocketProcessor {
+    /**
+     * Compiles and registers all decorated WebSocket Gateways within the Voltrix application.
+     * Auto-resolves dependencies from the DI Container and attaches to the uWS server instance.
+     */
+    static process(container: DIContainer, uwsApp?: any, port?: number): void;
+}

package/dist/processors/websocket.processor.js

@@ -0,0 +1,108 @@
+import { Metadata } from '@voltrix/core';
+import { WS_KEYS } from '../decorators/index.js';
+import { UwsWebSocketAdapter } from '../adapters/uws-adapter.js';
+/**
+ * 🚀 Voltrix WebSocket Processor (The Compiler)
+ * Discovers gateways, binds dependency injection, and pre-compiles execution pipelines.
+ */
+export class WebSocketProcessor {
+    /**
+     * Compiles and registers all decorated WebSocket Gateways within the Voltrix application.
+     * Auto-resolves dependencies from the DI Container and attaches to the uWS server instance.
+     */
+    static process(container, uwsApp, port = 3000) {
+        // 1. Scan the global metadata index for tracked classes
+        const classes = Metadata.getTrackedClasses();
+        for (const ctor of classes) {
+            const meta = Metadata.get(ctor);
+            const gatewayOptions = meta[WS_KEYS.GATEWAY];
+            // Skip classes that do not declare `@WebSocketGateway()`
+            if (!gatewayOptions)
+                continue;
+            // 2. Resolve the Gateway instance from the DI Container with full dependency injection
+            const gatewayInstance = container.resolve(ctor);
+            if (!gatewayInstance) {
+                throw new Error(`Failed to resolve WebSocket Gateway: ${ctor.name}`);
+            }
+            // 3. Configure Handshake Guard if defined
+            const path = gatewayOptions.path || '/ws';
+            let onUpgradeHook = undefined;
+            if (gatewayOptions.guard) {
+                const guardInstance = container.resolve(gatewayOptions.guard);
+                if (!guardInstance) {
+                    throw new Error(`Failed to resolve WebSocket Guard: ${gatewayOptions.guard.name}`);
+                }
+                onUpgradeHook = async (req, res) => {
+                    let resolvedUser = null;
+                    const context = {
+                        getRequest: () => req,
+                        getResponse: () => res,
+                        setUser: (user) => { resolvedUser = user; },
+                        getUser: () => resolvedUser
+                    };
+                    const canActivate = await guardInstance.canActivate(context);
+                    if (!canActivate)
+                        return false;
+                    return resolvedUser || true;
+                };
+            }
+            // 4. Instantiate Adapter and create the server WebSocket listener
+            const adapter = new UwsWebSocketAdapter();
+            const server = adapter.create(port, {
+                app: uwsApp,
+                path,
+                onUpgrade: onUpgradeHook
+            });
+            // 5. Bind Connection events and lifecycles
+            const onConnectKey = meta[WS_KEYS.ON_CONNECT];
+            const onDisconnectKey = meta[WS_KEYS.ON_DISCONNECT];
+            adapter.bindClientConnect(server, async (socket) => {
+                // Trigger OnConnect lifecycle hook if declared
+                if (onConnectKey) {
+                    const paramsMeta = Metadata.get(ctor, onConnectKey)[WS_KEYS.PARAMS] || [];
+                    const args = new Array(paramsMeta.length);
+                    paramsMeta.forEach((p) => {
+                        if (p.type === 'socket')
+                            args[p.index] = socket;
+                    });
+                    await gatewayInstance[onConnectKey](...args);
+                }
+                // Trigger OnDisconnect lifecycle hook if declared
+                if (onDisconnectKey) {
+                    adapter.bindClientDisconnect(socket, async (client, code, reason) => {
+                        const paramsMeta = Metadata.get(ctor, onDisconnectKey)[WS_KEYS.PARAMS] || [];
+                        const args = new Array(paramsMeta.index + 1 || paramsMeta.length);
+                        paramsMeta.forEach((p) => {
+                            if (p.type === 'socket')
+                                args[p.index] = client;
+                        });
+                        await gatewayInstance[onDisconnectKey](...args);
+                    });
+                }
+            });
+            // 6. Compile and bind message handlers
+            const eventsList = meta[WS_KEYS.EVENTS] || [];
+            const handlers = eventsList.map((e) => {
+                const methodKey = e.propertyKey;
+                const paramsMeta = Metadata.get(ctor, methodKey)[WS_KEYS.PARAMS] || [];
+                return {
+                    event: e.event,
+                    handler: async (client, data) => {
+                        // Build the arguments array programmatically in O(1)
+                        const args = new Array(paramsMeta.length);
+                        paramsMeta.forEach((p) => {
+                            if (p.type === 'socket')
+                                args[p.index] = client;
+                            else if (p.type === 'body')
+                                args[p.index] = data;
+                        });
+                        await gatewayInstance[methodKey](...args);
+                    }
+                };
+            });
+            // Bind all pre-compiled handlers globally on the adapter
+            adapter.bindMessageHandlers(server, handlers);
+        }
+    }
+}
+//# sourceMappingURL=websocket.processor.js.map

package/dist/processors/websocket.processor.js.map

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

package/dist/pubsub/index.d.ts

@@ -0,0 +1,3 @@
+export * from '../types/index.js';
+export * from './memory-engine.js';
+export * from './redis-engine.js';

package/dist/pubsub/index.js

@@ -0,0 +1,4 @@
+export * from '../types/index.js';
+export * from './memory-engine.js';
+export * from './redis-engine.js';
+//# sourceMappingURL=index.js.map

package/dist/pubsub/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pubsub/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

package/dist/pubsub/memory-engine.d.ts

@@ -0,0 +1,16 @@
+import type { IPubSubEngine, WsSocket } from '../types/index.js';
+/**
+ * 📡 In-Memory Pub/Sub Engine using native C++ uWebSockets.js capabilities.
+ * Delivers extreme performance and near-zero memory footprint.
+ */
+export declare class MemoryEngine implements IPubSubEngine {
+    private readonly app;
+    /**
+     * @param app The raw uWS TemplatedApp instance.
+     */
+    constructor(app: any);
+    subscribe(client: WsSocket, topic: string): void;
+    unsubscribe(client: WsSocket, topic: string): void;
+    publish(topic: string, message: any, isBinary?: boolean): void;
+    broadcast(message: any, isBinary?: boolean): void;
+}

package/dist/pubsub/memory-engine.js

@@ -0,0 +1,29 @@
+/**
+ * 📡 In-Memory Pub/Sub Engine using native C++ uWebSockets.js capabilities.
+ * Delivers extreme performance and near-zero memory footprint.
+ */
+export class MemoryEngine {
+    app;
+    /**
+     * @param app The raw uWS TemplatedApp instance.
+     */
+    constructor(app) {
+        this.app = app;
+    }
+    subscribe(client, topic) {
+        client.subscribe(topic);
+    }
+    unsubscribe(client, topic) {
+        client.unsubscribe(topic);
+    }
+    publish(topic, message, isBinary) {
+        const payload = typeof message === 'string' ? message : JSON.stringify(message);
+        this.app.publish(topic, payload, isBinary ?? false);
+    }
+    broadcast(message, isBinary) {
+        // Standardized global room for broadcasts
+        const payload = typeof message === 'string' ? message : JSON.stringify(message);
+        this.app.publish('global', payload, isBinary ?? false);
+    }
+}
+//# sourceMappingURL=memory-engine.js.map

package/dist/pubsub/memory-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-engine.js","sourceRoot":"","sources":["../../src/pubsub/memory-engine.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,YAAY;IAIM;IAH7B;;OAEG;IACH,YAA6B,GAAQ;QAAR,QAAG,GAAH,GAAG,CAAK;IAAG,CAAC;IAEzC,SAAS,CAAC,MAAgB,EAAE,KAAa;QACvC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,WAAW,CAAC,MAAgB,EAAE,KAAa;QACzC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,CAAC,KAAa,EAAE,OAAY,EAAE,QAAkB;QACrD,MAAM,OAAO,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAChF,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,IAAI,KAAK,CAAC,CAAC;IACtD,CAAC;IAED,SAAS,CAAC,OAAY,EAAE,QAAkB;QACxC,0CAA0C;QAC1C,MAAM,OAAO,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAChF,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,KAAK,CAAC,CAAC;IACzD,CAAC;CACF"}

package/dist/pubsub/redis-engine.d.ts

@@ -0,0 +1,31 @@
+import { type RedisOptions } from 'ioredis';
+import type { IPubSubEngine, WsSocket } from '../types/index.js';
+/**
+ * 📡 Distributed Redis Pub/Sub Engine.
+ * Syncs Rooms/Topics in real-time across a cluster of multiple Voltrix server instances.
+ */
+export declare class RedisEngine implements IPubSubEngine {
+    private readonly localEngine;
+    private readonly pubClient;
+    private readonly subClient;
+    private readonly prefix;
+    private isSubscribed;
+    /**
+     * @param app The raw uWS TemplatedApp instance.
+     * @param redisConfig Either a Redis URL string or full connection options.
+     */
+    constructor(app: any, redisConfig: string | RedisOptions);
+    subscribe(client: WsSocket, topic: string): void;
+    unsubscribe(client: WsSocket, topic: string): void;
+    publish(topic: string, message: any, isBinary?: boolean): Promise<void>;
+    broadcast(message: any, isBinary?: boolean): Promise<void>;
+    /**
+     * 🚏 Clustered pattern subscription bridge.
+     * Listens to Redis channels and pipes messages into local uWS channels natively.
+     */
+    private setupSubscriptionBridge;
+    /**
+     * Securely disconnects the Redis client connections
+     */
+    close(): Promise<void>;
+}

package/dist/pubsub/redis-engine.js

@@ -0,0 +1,99 @@
+import { Redis } from 'ioredis';
+import { MemoryEngine } from './memory-engine.js';
+/**
+ * 📡 Distributed Redis Pub/Sub Engine.
+ * Syncs Rooms/Topics in real-time across a cluster of multiple Voltrix server instances.
+ */
+export class RedisEngine {
+    localEngine;
+    pubClient;
+    subClient;
+    prefix = 'vltx:ws:';
+    isSubscribed = false;
+    /**
+     * @param app The raw uWS TemplatedApp instance.
+     * @param redisConfig Either a Redis URL string or full connection options.
+     */
+    constructor(app, redisConfig) {
+        this.localEngine = new MemoryEngine(app);
+        // Initialize Redis clients for Publishing and Subscribing
+        if (typeof redisConfig === 'string') {
+            this.pubClient = new Redis(redisConfig, { maxRetriesPerRequest: null });
+            this.subClient = new Redis(redisConfig, { maxRetriesPerRequest: null });
+        }
+        else {
+            this.pubClient = new Redis({ ...redisConfig, maxRetriesPerRequest: null });
+            this.subClient = new Redis({ ...redisConfig, maxRetriesPerRequest: null });
+        }
+        // Suppress unhandled connection errors to prevent crashes if Redis is offline
+        this.pubClient.on('error', () => { });
+        this.subClient.on('error', () => { });
+        this.setupSubscriptionBridge();
+    }
+    subscribe(client, topic) {
+        this.localEngine.subscribe(client, topic);
+        if (topic !== 'global') {
+            this.localEngine.subscribe(client, 'global');
+        }
+    }
+    unsubscribe(client, topic) {
+        this.localEngine.unsubscribe(client, topic);
+    }
+    async publish(topic, message, isBinary) {
+        this.localEngine.publish(topic, message, isBinary);
+        const payload = typeof message === 'string' ? message : JSON.stringify(message);
+        const packet = JSON.stringify({
+            message: payload,
+            isBinary: isBinary ?? false
+        });
+        try {
+            await this.pubClient.publish(`${this.prefix}${topic}`, packet);
+        }
+        catch (err) {
+            // Degrade gracefully if Redis publisher is offline
+        }
+    }
+    async broadcast(message, isBinary) {
+        await this.publish('global', message, isBinary);
+    }
+    /**
+     * 🚏 Clustered pattern subscription bridge.
+     * Listens to Redis channels and pipes messages into local uWS channels natively.
+     */
+    setupSubscriptionBridge() {
+        if (this.isSubscribed)
+            return;
+        this.isSubscribed = true;
+        // Pattern subscribe to all voltrix ws channels
+        this.subClient.psubscribe(`${this.prefix}*`).catch(() => {
+            this.isSubscribed = false;
+        });
+        this.subClient.on('pmessage', (_pattern, channel, message) => {
+            const topic = channel.slice(this.prefix.length);
+            try {
+                const data = JSON.parse(message);
+                if (data && data.message !== undefined) {
+                    this.localEngine.publish(topic, data.message, data.isBinary);
+                }
+            }
+            catch (err) {
+                // Suppress parsing errors
+            }
+        });
+    }
+    /**
+     * Securely disconnects the Redis client connections
+     */
+    async close() {
+        try {
+            await Promise.all([
+                this.pubClient.quit(),
+                this.subClient.quit()
+            ]);
+        }
+        catch {
+            // Safe exit
+        }
+    }
+}
+//# sourceMappingURL=redis-engine.js.map

package/dist/pubsub/redis-engine.js.map

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

package/dist/types/index.d.ts

@@ -0,0 +1,134 @@
+import type { IRequest, IResponse } from '@voltrix/core';
+/**
+ * 🔌 Core WsSocket normalization interface wrapper.
+ * Encapsulates client socket operations for engine-agnostic code.
+ */
+export interface WsSocket<TUser = any, TRawSocket = any> {
+    /**
+     * Unique connection ID.
+     */
+    readonly id: string;
+    /**
+     * Authenticated user object/context.
+     */
+    user?: TUser;
+    /**
+     * Send a message to this specific client.
+     */
+    send(message: string | ArrayBufferView | ArrayBuffer, isBinary?: boolean): void;
+    /**
+     * Subscribe this client to a room/topic.
+     */
+    subscribe(topic: string): void;
+    /**
+     * Unsubscribe this client from a room/topic.
+     */
+    unsubscribe(topic: string): void;
+    /**
+     * Publish a message to a topic.
+     */
+    publish(topic: string, message: string | ArrayBufferView | ArrayBuffer, isBinary?: boolean): void;
+    /**
+     * Close the connection securely.
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * The raw underlying engine socket instance (e.g. uWS.WebSocket).
+     */
+    readonly raw: TRawSocket;
+}
+/**
+ * 🎯 Structure of a registered message handler.
+ */
+export interface WsMessageHandler<TClient extends WsSocket = WsSocket> {
+    readonly event: string;
+    readonly handler: (client: TClient, data: any) => void | Promise<void>;
+}
+/**
+ * 🔌 Pluggable WebSocket Adapter Contract.
+ */
+export interface IWebSocketAdapter<TServer = any, TClient extends WsSocket = WsSocket, TOptions = any> {
+    /**
+     * Creates the WebSocket server.
+     */
+    create(port: number, options?: TOptions): TServer;
+    /**
+     * Binds callback to client connection events.
+     */
+    bindClientConnect(server: TServer, callback: (client: TClient) => void | Promise<void>): void;
+    /**
+     * Binds callback to client disconnection events.
+     */
+    bindClientDisconnect(client: TClient, callback: (client: TClient, code: number, reason: ArrayBuffer) => void | Promise<void>): void;
+    /**
+     * Binds handlers for events sent by the client.
+     */
+    bindMessageHandlers(client: TClient, handlers: WsMessageHandler<TClient>[]): void;
+    /**
+     * Closes the server.
+     */
+    close(): void | Promise<void>;
+}
+/**
+ * 📡 Pluggable Pub/Sub and Distributed Broadcasting Engine.
+ */
+export interface IPubSubEngine<TClient extends WsSocket = WsSocket, TPayload = any> {
+    /**
+     * Subscribes a client to a topic.
+     */
+    subscribe(client: TClient, topic: string): void | Promise<void>;
+    /**
+     * Unsubscribes a client from a topic.
+     */
+    unsubscribe(client: TClient, topic: string): void | Promise<void>;
+    /**
+     * Publishes a message to a topic.
+     */
+    publish(topic: string, message: TPayload, isBinary?: boolean): void | Promise<void>;
+    /**
+     * Broadcasts a message globally to all connections.
+     */
+    broadcast(message: TPayload, isBinary?: boolean): void | Promise<void>;
+}
+/**
+ * 🔒 Handshake Context for Pre-Upgrade Authentication.
+ */
+export interface HandshakeContext<TUser = any> {
+    /**
+     * Returns the underlying HTTP Request interface.
+     */
+    getRequest(): IRequest;
+    /**
+     * Returns the underlying HTTP Response interface.
+     */
+    getResponse(): IResponse;
+    /**
+     * Sets the resolved/authenticated user metadata.
+     */
+    setUser(user: TUser): void;
+    /**
+     * Gets the active user metadata.
+     */
+    getUser(): TUser | undefined;
+}
+/**
+ * 📨 WebSocket Message Context for Pipelines.
+ */
+export interface WsMessageContext<TUser = any> {
+    /**
+     * The client socket that sent the message.
+     */
+    readonly client: WsSocket<TUser>;
+    /**
+     * The event name.
+     */
+    readonly event: string;
+    /**
+     * The parsed payload.
+     */
+    payload: any;
+}
+/**
+ * ⚙️ Interceptor / Middleware for message events.
+ */
+export type WsMiddleware<TUser = any> = (context: WsMessageContext<TUser>, next: (err?: Error) => void | Promise<void>) => void | Promise<void>;

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@voltrix/websocket",
+  "version": "0.3.0",
+  "description": "High-performance, programmatic-first and decorator-driven WebSocket package with pluggable adapters and distributed pub/sub for Voltrix",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "voltrix",
+    "websocket",
+    "uWebSockets.js",
+    "pubsub",
+    "redis",
+    "realtime",
+    "gateway"
+  ],
+  "author": "Voltrix Team",
+  "license": "MIT",
+  "dependencies": {
+    "ioredis": "^5.4.1",
+    "reflect-metadata": "^0.2.2",
+    "tslib": "^2.8.1",
+    "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.60.0",
+    "@voltrix/core": "0.3.0",
+    "@voltrix/injector": "0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.0",
+    "ws": "^8.18.0",
+    "@types/ws": "^8.5.10",
+    "@voltrix/decorator": "0.2.2",
+    "@voltrix/server": "0.2.1"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  }
+}