@veloxts/events 0.6.51

package/dist/drivers/ws.d.ts

@@ -0,0 +1,41 @@
+/**
+ * WebSocket Driver
+ *
+ * Real-time event broadcasting using WebSocket connections.
+ * Supports optional Redis pub/sub for horizontal scaling.
+ */
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer } from 'ws';
+import type { BroadcastDriver, EventsWsOptions } from '../types.js';
+/**
+ * Create a WebSocket broadcast driver.
+ *
+ * @param config - WebSocket driver configuration
+ * @returns Broadcast driver implementation
+ *
+ * @example
+ * ```typescript
+ * const driver = await createWsDriver({
+ *   driver: 'ws',
+ *   path: '/ws',
+ *   redis: process.env.REDIS_URL, // Optional for scaling
+ * });
+ *
+ * await driver.broadcast({
+ *   channel: 'orders.123',
+ *   event: 'order.shipped',
+ *   data: { trackingNumber: 'TRACK123' },
+ * });
+ * ```
+ */
+export declare function createWsDriver(config: EventsWsOptions, _server?: {
+    server: unknown;
+}): Promise<BroadcastDriver & {
+    wss: WebSocketServer;
+    handleUpgrade: (request: IncomingMessage, socket: Duplex, head: Buffer) => void;
+}>;
+/**
+ * WebSocket driver name.
+ */
+export declare const DRIVER_NAME: "ws";

package/dist/drivers/ws.js

@@ -0,0 +1,401 @@
+/**
+ * WebSocket Driver
+ *
+ * Real-time event broadcasting using WebSocket connections.
+ * Supports optional Redis pub/sub for horizontal scaling.
+ */
+import { randomUUID } from 'node:crypto';
+import { WebSocketServer } from 'ws';
+/**
+ * Default WebSocket driver configuration.
+ */
+const DEFAULT_CONFIG = {
+    path: '/ws',
+    pingInterval: 30000,
+    connectionTimeout: 60000,
+    maxPayloadSize: 1024 * 1024, // 1MB
+};
+/**
+ * Create a type-safe pub/sub adapter from ioredis clients.
+ * This wraps the Redis clients to provide a clean async interface without type assertions.
+ */
+function createRedisPubSubAdapter(subscriberClient, publisherClient) {
+    const subscriber = {
+        async subscribe(channel) {
+            await subscriberClient.subscribe(channel);
+        },
+        onMessage(handler) {
+            subscriberClient.on('message', handler);
+        },
+        async publish() {
+            throw new Error('Cannot publish on subscriber connection');
+        },
+        async quit() {
+            await subscriberClient.quit();
+        },
+    };
+    const publisher = {
+        async subscribe() {
+            throw new Error('Cannot subscribe on publisher connection');
+        },
+        onMessage() {
+            throw new Error('Cannot receive messages on publisher connection');
+        },
+        async publish(channel, message) {
+            await publisherClient.publish(channel, message);
+        },
+        async quit() {
+            await publisherClient.quit();
+        },
+    };
+    return {
+        subscriber,
+        publisher,
+        quit: async () => {
+            await Promise.all([subscriber.quit(), publisher.quit()]);
+        },
+    };
+}
+/**
+ * Create a WebSocket broadcast driver.
+ *
+ * @param config - WebSocket driver configuration
+ * @returns Broadcast driver implementation
+ *
+ * @example
+ * ```typescript
+ * const driver = await createWsDriver({
+ *   driver: 'ws',
+ *   path: '/ws',
+ *   redis: process.env.REDIS_URL, // Optional for scaling
+ * });
+ *
+ * await driver.broadcast({
+ *   channel: 'orders.123',
+ *   event: 'order.shipped',
+ *   data: { trackingNumber: 'TRACK123' },
+ * });
+ * ```
+ */
+export async function createWsDriver(config, _server) {
+    const options = { ...DEFAULT_CONFIG, ...config };
+    const { pingInterval, maxPayloadSize, redis } = options;
+    // Generate unique instance ID for filtering self-messages in Redis pub/sub
+    const instanceId = randomUUID();
+    // Create WebSocket server
+    const wss = new WebSocketServer({
+        noServer: true,
+        maxPayload: maxPayloadSize,
+    });
+    // Connection tracking
+    const connections = new Map();
+    // Channel subscriptions: channel -> Set of socket IDs
+    const channelSubscriptions = new Map();
+    // Presence data: channel -> Map of socket ID -> PresenceMember
+    const presenceData = new Map();
+    // Redis pub/sub for horizontal scaling
+    let redisPubSub = null;
+    if (redis) {
+        const { Redis: RedisClient } = await import('ioredis');
+        const subscriberClient = new RedisClient(redis);
+        const publisherClient = new RedisClient(redis);
+        const adapter = createRedisPubSubAdapter(subscriberClient, publisherClient);
+        // Subscribe to broadcast channel
+        await adapter.subscriber.subscribe('velox:broadcast');
+        adapter.subscriber.onMessage((_channel, message) => {
+            try {
+                const parsed = JSON.parse(message);
+                // Skip messages from this instance to prevent duplicates
+                if (parsed.__origin === instanceId) {
+                    return;
+                }
+                // Extract the event without the origin field
+                const { __origin: _, ...event } = parsed;
+                // Only broadcast locally, don't re-publish
+                broadcastLocal(event);
+            }
+            catch {
+                // Ignore invalid messages
+            }
+        });
+        redisPubSub = adapter;
+    }
+    /**
+     * Generate a unique socket ID.
+     */
+    function generateSocketId() {
+        return `${Date.now().toString(36)}.${Math.random().toString(36).slice(2, 10)}`;
+    }
+    /**
+     * Maximum buffered amount before applying backpressure (64KB).
+     * If the WebSocket buffer exceeds this, we skip non-critical messages.
+     */
+    const MAX_BUFFERED_AMOUNT = 64 * 1024;
+    /**
+     * Send a message to a client with backpressure handling.
+     * Returns true if message was sent, false if backpressure was applied.
+     */
+    function send(ws, message) {
+        if (ws.readyState !== ws.OPEN) {
+            return false;
+        }
+        // Apply backpressure: skip non-critical messages if buffer is full
+        // This prevents memory buildup under high load
+        if (ws.bufferedAmount > MAX_BUFFERED_AMOUNT) {
+            // Allow critical messages (connection, subscription, errors) through
+            if (message.type === 'event' && message.event !== 'connected') {
+                return false; // Drop non-critical event, client can recover
+            }
+        }
+        ws.send(JSON.stringify(message));
+        return true;
+    }
+    /**
+     * Broadcast an event locally to connected clients.
+     */
+    function broadcastLocal(event) {
+        const subscribers = channelSubscriptions.get(event.channel);
+        if (!subscribers)
+            return;
+        const message = {
+            type: 'event',
+            channel: event.channel,
+            event: event.event,
+            data: event.data,
+        };
+        for (const socketId of subscribers) {
+            if (event.except && socketId === event.except)
+                continue;
+            const ws = connections.get(socketId);
+            if (ws) {
+                send(ws, message);
+            }
+        }
+    }
+    /**
+     * Subscribe a client to a channel.
+     */
+    function subscribe(ws, channel, member) {
+        // Add to connection's channels
+        ws.channels.add(channel);
+        // Add to channel subscriptions
+        let subscribers = channelSubscriptions.get(channel);
+        if (!subscribers) {
+            subscribers = new Set();
+            channelSubscriptions.set(channel, subscribers);
+        }
+        subscribers.add(ws.id);
+        // Handle presence channel
+        if (member && channel.startsWith('presence-')) {
+            let members = presenceData.get(channel);
+            if (!members) {
+                members = new Map();
+                presenceData.set(channel, members);
+            }
+            members.set(ws.id, member);
+            ws.presenceInfo.set(channel, member);
+            // Notify others of new member
+            broadcastLocal({
+                channel,
+                event: 'member_added',
+                data: member,
+                except: ws.id,
+            });
+        }
+        // Send success message
+        send(ws, {
+            type: 'subscription_succeeded',
+            channel,
+            data: member && channel.startsWith('presence-')
+                ? { members: Array.from(presenceData.get(channel)?.values() ?? []) }
+                : undefined,
+        });
+    }
+    /**
+     * Unsubscribe a client from a channel.
+     */
+    function unsubscribe(ws, channel) {
+        // Remove from connection's channels
+        ws.channels.delete(channel);
+        // Remove from channel subscriptions
+        const subscribers = channelSubscriptions.get(channel);
+        if (subscribers) {
+            subscribers.delete(ws.id);
+            if (subscribers.size === 0) {
+                channelSubscriptions.delete(channel);
+            }
+        }
+        // Handle presence channel
+        if (channel.startsWith('presence-')) {
+            const members = presenceData.get(channel);
+            if (members) {
+                const member = members.get(ws.id);
+                members.delete(ws.id);
+                ws.presenceInfo.delete(channel);
+                if (members.size === 0) {
+                    presenceData.delete(channel);
+                }
+                // Notify others of member leaving
+                if (member) {
+                    broadcastLocal({
+                        channel,
+                        event: 'member_removed',
+                        data: member,
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Handle client disconnection.
+     */
+    function handleDisconnect(ws) {
+        // Unsubscribe from all channels
+        for (const channel of ws.channels) {
+            unsubscribe(ws, channel);
+        }
+        // Remove from connections
+        connections.delete(ws.id);
+    }
+    /**
+     * Handle incoming client message.
+     */
+    function handleMessage(ws, data) {
+        try {
+            const message = JSON.parse(data);
+            ws.isAlive = true;
+            switch (message.type) {
+                case 'subscribe':
+                    if (message.channel) {
+                        // For now, auto-authorize. Plugin will add proper authorization.
+                        subscribe(ws, message.channel, message.data);
+                    }
+                    break;
+                case 'unsubscribe':
+                    if (message.channel) {
+                        unsubscribe(ws, message.channel);
+                    }
+                    break;
+                case 'ping':
+                    send(ws, { type: 'pong' });
+                    break;
+                case 'message':
+                    // Client-to-server events (for presence channels mainly)
+                    if (message.channel && message.event) {
+                        broadcastLocal({
+                            channel: message.channel,
+                            event: message.event,
+                            data: message.data,
+                            except: ws.id,
+                        });
+                    }
+                    break;
+            }
+        }
+        catch {
+            send(ws, { type: 'error', error: 'Invalid message format' });
+        }
+    }
+    // Connection handling
+    wss.on('connection', (ws) => {
+        const extWs = ws;
+        extWs.id = generateSocketId();
+        extWs.isAlive = true;
+        extWs.channels = new Set();
+        extWs.presenceInfo = new Map();
+        connections.set(extWs.id, extWs);
+        // Send connection info
+        send(extWs, {
+            type: 'event',
+            event: 'connected',
+            data: { socketId: extWs.id },
+        });
+        extWs.on('message', (data) => {
+            handleMessage(extWs, data.toString());
+        });
+        extWs.on('close', () => {
+            handleDisconnect(extWs);
+        });
+        extWs.on('pong', () => {
+            extWs.isAlive = true;
+        });
+        extWs.on('error', () => {
+            handleDisconnect(extWs);
+        });
+    });
+    // Ping interval for connection health
+    const pingIntervalId = setInterval(() => {
+        for (const ws of connections.values()) {
+            if (!ws.isAlive) {
+                ws.terminate();
+                handleDisconnect(ws);
+                continue;
+            }
+            ws.isAlive = false;
+            ws.ping();
+        }
+    }, pingInterval);
+    /**
+     * Handle HTTP upgrade to WebSocket.
+     *
+     * @param request - The incoming HTTP request
+     * @param socket - The underlying TCP socket (Duplex stream)
+     * @param head - The first packet of the upgraded stream
+     */
+    function handleUpgrade(request, socket, head) {
+        wss.handleUpgrade(request, socket, head, (ws) => {
+            wss.emit('connection', ws, request);
+        });
+    }
+    const driver = {
+        wss,
+        handleUpgrade,
+        async broadcast(event) {
+            // Broadcast locally
+            broadcastLocal(event);
+            // Publish to Redis for other instances
+            if (redisPubSub) {
+                // Include instance ID to prevent self-echo
+                await redisPubSub.publisher.publish('velox:broadcast', JSON.stringify({ ...event, __origin: instanceId }));
+            }
+        },
+        async getSubscribers(channel) {
+            const subscribers = channelSubscriptions.get(channel);
+            return subscribers ? Array.from(subscribers) : [];
+        },
+        async getPresenceMembers(channel) {
+            const members = presenceData.get(channel);
+            return members ? Array.from(members.values()) : [];
+        },
+        async getConnectionCount(channel) {
+            const subscribers = channelSubscriptions.get(channel);
+            return subscribers?.size ?? 0;
+        },
+        async getChannels() {
+            return Array.from(channelSubscriptions.keys());
+        },
+        async close() {
+            clearInterval(pingIntervalId);
+            // Close all connections
+            for (const ws of connections.values()) {
+                ws.close(1000, 'Server shutting down');
+            }
+            connections.clear();
+            channelSubscriptions.clear();
+            presenceData.clear();
+            // Close Redis connections
+            if (redisPubSub) {
+                await redisPubSub.quit();
+            }
+            // Close WebSocket server
+            await new Promise((resolve) => {
+                wss.close(() => resolve());
+            });
+        },
+    };
+    return driver;
+}
+/**
+ * WebSocket driver name.
+ */
+export const DRIVER_NAME = 'ws';

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @veloxts/events
+ *
+ * Real-time event broadcasting for VeloxTS framework.
+ *
+ * Features:
+ * - WebSocket driver with ws library
+ * - SSE driver for fallback
+ * - Channel authorization (public, private, presence)
+ * - Redis pub/sub for horizontal scaling
+ * - Fastify plugin with BaseContext extension
+ *
+ * @example
+ * ```typescript
+ * import { eventsPlugin } from '@veloxts/events';
+ *
+ * // Register the plugin
+ * app.register(eventsPlugin, {
+ *   driver: 'ws',
+ *   path: '/ws',
+ *   redis: process.env.REDIS_URL,
+ * });
+ *
+ * // In a procedure
+ * const createOrder = procedure
+ *   .input(CreateOrderSchema)
+ *   .mutation(async ({ input, ctx }) => {
+ *     const order = await ctx.db.order.create({ data: input });
+ *
+ *     // Broadcast to subscribers
+ *     await ctx.events.broadcast(`orders.${order.userId}`, 'order.created', order);
+ *
+ *     return order;
+ *   });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { type ChannelAuthSigner, createChannelAuthSigner } from './auth.js';
+export { createSseDriver, DRIVER_NAME as SSE_DRIVER } from './drivers/sse.js';
+export { createWsDriver, DRIVER_NAME as WS_DRIVER } from './drivers/ws.js';
+export { createEventsManager, createManagerFromDriver, type EventsManager, events, } from './manager.js';
+export { _resetStandaloneEvents, eventsPlugin, getEvents, getEventsFromInstance, } from './plugin.js';
+export { ClientMessageSchema, formatValidationErrors, PresenceMemberSchema, SseSubscribeBodySchema, SseUnsubscribeBodySchema, type ValidationResult, validateBody, WsAuthBodySchema, } from './schemas.js';
+export type { BroadcastDriver, BroadcastEvent, Channel, ChannelAuthorizer, ChannelAuthResult, ChannelType, ClientConnection, ClientMessage, EventsBaseOptions, EventsDefaultOptions, EventsManagerOptions, EventsPluginOptions, EventsSseOptions, EventsWsOptions, PresenceMember, ServerMessage, Subscription, } from './types.js';

package/dist/index.js

@@ -0,0 +1,49 @@
+/**
+ * @veloxts/events
+ *
+ * Real-time event broadcasting for VeloxTS framework.
+ *
+ * Features:
+ * - WebSocket driver with ws library
+ * - SSE driver for fallback
+ * - Channel authorization (public, private, presence)
+ * - Redis pub/sub for horizontal scaling
+ * - Fastify plugin with BaseContext extension
+ *
+ * @example
+ * ```typescript
+ * import { eventsPlugin } from '@veloxts/events';
+ *
+ * // Register the plugin
+ * app.register(eventsPlugin, {
+ *   driver: 'ws',
+ *   path: '/ws',
+ *   redis: process.env.REDIS_URL,
+ * });
+ *
+ * // In a procedure
+ * const createOrder = procedure
+ *   .input(CreateOrderSchema)
+ *   .mutation(async ({ input, ctx }) => {
+ *     const order = await ctx.db.order.create({ data: input });
+ *
+ *     // Broadcast to subscribers
+ *     await ctx.events.broadcast(`orders.${order.userId}`, 'order.created', order);
+ *
+ *     return order;
+ *   });
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Auth
+export { createChannelAuthSigner } from './auth.js';
+// Drivers
+export { createSseDriver, DRIVER_NAME as SSE_DRIVER } from './drivers/sse.js';
+export { createWsDriver, DRIVER_NAME as WS_DRIVER } from './drivers/ws.js';
+// Manager
+export { createEventsManager, createManagerFromDriver, events, } from './manager.js';
+// Plugin
+export { _resetStandaloneEvents, eventsPlugin, getEvents, getEventsFromInstance, } from './plugin.js';
+// Schemas (for validation)
+export { ClientMessageSchema, formatValidationErrors, PresenceMemberSchema, SseSubscribeBodySchema, SseUnsubscribeBodySchema, validateBody, WsAuthBodySchema, } from './schemas.js';

package/dist/manager.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Events Manager
+ *
+ * High-level API for real-time event broadcasting.
+ * Wraps the underlying driver with a clean, Laravel-inspired interface.
+ */
+import type { BroadcastDriver, EventsManager, EventsPluginOptions } from './types.js';
+/**
+ * Create an events manager with the specified driver.
+ *
+ * @param options - Events configuration with driver selection
+ * @returns Events manager instance
+ *
+ * @example
+ * ```typescript
+ * // WebSocket driver (default)
+ * const events = await createEventsManager({
+ *   driver: 'ws',
+ *   path: '/ws',
+ *   redis: process.env.REDIS_URL, // For scaling
+ * });
+ *
+ * // SSE driver (fallback)
+ * const events = await createEventsManager({
+ *   driver: 'sse',
+ *   path: '/events',
+ * });
+ *
+ * // Broadcast an event
+ * await events.broadcast('orders.123', 'order.shipped', {
+ *   trackingNumber: 'TRACK123',
+ * });
+ * ```
+ */
+export declare function createEventsManager(options?: EventsPluginOptions): Promise<EventsManager & {
+    driver: BroadcastDriver;
+}>;
+/**
+ * Create an events manager from an existing driver.
+ *
+ * @param driver - Broadcast driver instance
+ * @returns Events manager instance
+ */
+export declare function createManagerFromDriver(driver: BroadcastDriver): EventsManager & {
+    driver: BroadcastDriver;
+};
+/**
+ * Alias for createEventsManager for Laravel-style API.
+ */
+export declare const events: typeof createEventsManager;
+/**
+ * Re-export manager type.
+ */
+export type { EventsManager };

package/dist/manager.js

@@ -0,0 +1,104 @@
+/**
+ * Events Manager
+ *
+ * High-level API for real-time event broadcasting.
+ * Wraps the underlying driver with a clean, Laravel-inspired interface.
+ */
+/**
+ * Create an events manager with the specified driver.
+ *
+ * @param options - Events configuration with driver selection
+ * @returns Events manager instance
+ *
+ * @example
+ * ```typescript
+ * // WebSocket driver (default)
+ * const events = await createEventsManager({
+ *   driver: 'ws',
+ *   path: '/ws',
+ *   redis: process.env.REDIS_URL, // For scaling
+ * });
+ *
+ * // SSE driver (fallback)
+ * const events = await createEventsManager({
+ *   driver: 'sse',
+ *   path: '/events',
+ * });
+ *
+ * // Broadcast an event
+ * await events.broadcast('orders.123', 'order.shipped', {
+ *   trackingNumber: 'TRACK123',
+ * });
+ * ```
+ */
+export async function createEventsManager(options = {}) {
+    let driver;
+    if (options.driver === 'sse') {
+        const sseOptions = options;
+        const { createSseDriver } = await import('./drivers/sse.js');
+        driver = createSseDriver(sseOptions);
+    }
+    else {
+        // WebSocket driver (default)
+        const wsOptions = (options.driver === 'ws' ? options : { ...options, driver: 'ws' });
+        const { createWsDriver } = await import('./drivers/ws.js');
+        driver = await createWsDriver(wsOptions);
+    }
+    return createManagerFromDriver(driver);
+}
+/**
+ * Create an events manager from an existing driver.
+ *
+ * @param driver - Broadcast driver instance
+ * @returns Events manager instance
+ */
+export function createManagerFromDriver(driver) {
+    const manager = {
+        driver,
+        async broadcast(channel, event, data, except) {
+            const broadcastEvent = {
+                channel,
+                event,
+                data,
+                except,
+            };
+            await driver.broadcast(broadcastEvent);
+        },
+        async broadcastToMany(channels, event, data) {
+            await Promise.all(channels.map((channel) => driver.broadcast({
+                channel,
+                event,
+                data,
+            })));
+        },
+        async toOthers(channel, event, data, except) {
+            await driver.broadcast({
+                channel,
+                event,
+                data,
+                except,
+            });
+        },
+        async subscriberCount(channel) {
+            return driver.getConnectionCount(channel);
+        },
+        async presenceMembers(channel) {
+            return driver.getPresenceMembers(channel);
+        },
+        async hasSubscribers(channel) {
+            const count = await driver.getConnectionCount(channel);
+            return count > 0;
+        },
+        async channels() {
+            return driver.getChannels();
+        },
+        async close() {
+            await driver.close();
+        },
+    };
+    return manager;
+}
+/**
+ * Alias for createEventsManager for Laravel-style API.
+ */
+export const events = createEventsManager;