@gravito/ripple 3.0.1 → 4.0.0

package/dist/ripple/src/drivers/RedisDriver.d.ts

@@ -1,63 +1,170 @@
 /**
  * @fileoverview Redis driver for @gravito/ripple
  *
- * Enables horizontal scaling across multiple server instances using
- * Redis Pub/Sub for message broadcasting.
- *
  * @module @gravito/ripple/drivers
  */
-import type { RippleDriver } from '../types';
+import type { RippleLogger } from '../logging/Logger';
+import type { DriverStatus, PresenceUserInfo, RippleDriver } from '../types';
 /**
- * Redis-based driver for multi-server deployments
+ * Configuration for the RedisDriver.
+ */
+export interface RedisDriverConfig {
+    /** Redis server hostname (default: 'localhost') */
+    host?: string;
+    /** Redis server port (default: 6379) */
+    port?: number;
+    /** Redis password for authentication */
+    password?: string;
+    /** Redis database index (default: 0) */
+    db?: number;
+    /** Prefix for Ripple Redis channels (default: 'ripple:') */
+    keyPrefix?: string;
+    /** Custom logger instance */
+    logger?: RippleLogger;
+    /** Connection timeout in milliseconds (default: 5000) */
+    connectTimeout?: number;
+    /** Command timeout in milliseconds (default: 3000) */
+    commandTimeout?: number;
+    /** Whether to enable ready check (default: true) */
+    enableReadyCheck?: boolean;
+    /** Whether to connect lazily (default: false) */
+    lazyConnect?: boolean;
+}
+/**
+ * Redis driver for Ripple, enabling horizontal scaling via Redis Pub/Sub.
  *
- * This driver uses Redis Pub/Sub to broadcast messages across multiple
- * server instances, enabling horizontal scaling of WebSocket connections.
+ * This driver distributes messages across multiple server instances, allowing
+ * clients connected to different servers to receive the same broadcasts.
  *
  * @example
  * ```typescript
- * const ripple = new RippleServer({
+ * import { RippleServer, RedisDriver } from '@gravito/ripple'
+ *
+ * const server = new RippleServer({
  *   driver: 'redis',
  *   redis: {
  *     host: 'localhost',
- *     port: 6379
+ *     port: 6379,
+ *     password: 'secret_password'
  *   }
  * })
  * ```
  */
 export declare class RedisDriver implements RippleDriver {
     private config;
+    /** Driver name identifier */
     readonly name = "redis";
-    private redis;
-    private subscriber;
+    /** Redis client for publishing messages */
+    private redis?;
+    /** Redis client for subscribing to messages */
+    private subscriber?;
+    /** Prefix for Redis channels to avoid collisions */
     private channelPrefix;
+    /** Local subscription map: channel -> callbacks */
     private subscriptions;
+    private _initialized;
+    private _connected;
+    private _lastError?;
+    private logger;
+    /**
+     * Create a new RedisDriver.
+     *
+     * @param config - Redis connection and behavior configuration
+     */
     constructor(config?: RedisDriverConfig);
+    /**
+     * Check if the driver has been initialized.
+     */
+    get isInitialized(): boolean;
+    /**
+     * Initialize the Redis connections (Publisher and Subscriber).
+     *
+     * This method performs dynamic import of 'ioredis' to avoid mandatory
+     * dependency on users who only use the local driver.
+     *
+     * @throws {RippleDriverError} If 'ioredis' is not installed or connection fails
+     */
     init(): Promise<void>;
+    /**
+     * Publish a message to Redis Pub/Sub.
+     *
+     * @param channel - Target channel name
+     * @param event - Event name
+     * @param data - Event payload
+     * @throws {RippleDriverError} If driver is not initialized
+     */
     publish(channel: string, event: string, data: unknown): Promise<void>;
+    /**
+     * Subscribe to a channel via Redis Pub/Sub.
+     *
+     * Multiple calls for the same channel will only result in one Redis subscription,
+     * while maintaining all local callbacks.
+     *
+     * @param channel - Channel name
+     * @param callback - Function called when a message is received from Redis
+     * @throws {RippleDriverError} If driver is not initialized
+     */
     subscribe(channel: string, callback: (event: string, data: unknown) => void): Promise<void>;
+    /**
+     * Unsubscribe from a channel via Redis Pub/Sub.
+     *
+     * If no local callbacks remain for the channel, the actual Redis unsubscription
+     * is performed.
+     *
+     * @param channel - Channel name
+     */
     unsubscribe(channel: string): Promise<void>;
+    /**
+     * Shutdown the Redis driver and close all connections.
+     */
     shutdown(): Promise<void>;
     /**
-     * Handle incoming Redis messages
+     * Get the current status of the Redis driver.
+     */
+    getStatus(): DriverStatus;
+    /**
+     * Track a presence member in a channel.
+     *
+     * Stores presence information in Redis Hash for cross-node sharing.
+     * Sets TTL on the hash to prevent stale data.
+     *
+     * @param channel - Presence channel name
+     * @param userInfo - User information to track
+     * @since 3.6.0
+     */
+    trackPresence(channel: string, userInfo: PresenceUserInfo): Promise<void>;
+    /**
+     * Remove a presence member from a channel.
+     *
+     * @param channel - Presence channel name
+     * @param userId - User ID to remove
+     * @since 3.6.0
+     */
+    untrackPresence(channel: string, userId: string | number): Promise<void>;
+    /**
+     * Get all presence members for a channel.
+     *
+     * Retrieves all members from the Redis Hash.
+     *
+     * @param channel - Presence channel name
+     * @returns Array of presence user information
+     * @since 3.6.0
+     */
+    getPresenceMembers(channel: string): Promise<PresenceUserInfo[]>;
+    /**
+     * Handle an incoming message from Redis Pub/Sub.
+     *
+     * Dispatches the message to all local callbacks registered for the channel.
      */
     private handleMessage;
     /**
-     * Dynamically import ioredis to avoid bundling it if not used
+     * Handle Redis client errors.
+     */
+    private handleError;
+    /**
+     * Dynamically import ioredis to check if it's available.
+     *
+     * @throws {RippleDriverError} If ioredis package is missing
      */
     private getRedisClient;
 }
-/**
- * Configuration options for RedisDriver
- */
-export interface RedisDriverConfig {
-    /** Redis host (default: 'localhost') */
-    host?: string;
-    /** Redis port (default: 6379) */
-    port?: number;
-    /** Redis password (optional) */
-    password?: string;
-    /** Redis database number (default: 0) */
-    db?: number;
-    /** Key prefix for channels (default: 'ripple:') */
-    keyPrefix?: string;
-}

package/dist/ripple/src/drivers/index.d.ts

@@ -1,2 +1,3 @@
 export * from './LocalDriver';
+export * from './NATSDriver';
 export * from './RedisDriver';

package/dist/ripple/src/engines/BunEngine.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @fileoverview Bun native WebSocket engine implementation
+ *
+ * Wraps Bun's native WebSocket API to implement the IRippleEngine interface.
+ * This is the default and highest-performance engine for Ripple.
+ *
+ * @module @gravito/ripple/engines
+ * @since 5.0.0
+ */
+import type { Server, ServerWebSocket } from 'bun';
+import type { ClientData } from '../types';
+import type { IRippleEngine, RippleSocket } from './IRippleEngine';
+/**
+ * Wrapper around Bun's ServerWebSocket to implement RippleSocket interface.
+ *
+ * This is a zero-overhead wrapper that delegates all operations to the native
+ * Bun WebSocket object. No proxies or additional allocations.
+ */
+export declare class BunRippleSocket implements RippleSocket {
+    private ws;
+    constructor(ws: ServerWebSocket<ClientData>);
+    get id(): string;
+    get data(): ClientData;
+    send(data: string | Uint8Array, compress?: boolean): void;
+    close(code?: number, reason?: string): void;
+    getBufferedAmount(): number;
+    subscribe(topic: string): void;
+    unsubscribe(topic: string): void;
+    publish(topic: string, data: string | Uint8Array): void;
+    get raw(): ServerWebSocket<ClientData>;
+}
+/**
+ * Configuration for BunEngine.
+ */
+export interface BunEngineConfig {
+    /** Port to listen on */
+    port?: number;
+    /** Hostname to bind to */
+    hostname?: string;
+    /** TLS configuration */
+    tls?: {
+        cert: string;
+        key: string;
+    };
+    /** Development mode (enables verbose logging) */
+    development?: boolean;
+}
+/**
+ * Bun native WebSocket engine.
+ *
+ * Leverages Bun's high-performance WebSocket implementation with native pub/sub support.
+ * This engine provides the best performance and is the default choice for Bun runtime.
+ *
+ * @example
+ * ```typescript
+ * const engine = new BunEngine({ port: 3000 })
+ *
+ * engine.onConnection((socket) => {
+ *   console.log('Client connected:', socket.id)
+ * })
+ *
+ * await engine.listen(3000)
+ * ```
+ */
+export declare class BunEngine implements IRippleEngine {
+    private config;
+    readonly name = "bun";
+    private server?;
+    private connectionHandler?;
+    private disconnectionHandler?;
+    private messageHandler?;
+    private sockets;
+    constructor(config?: BunEngineConfig);
+    onConnection(handler: (socket: RippleSocket) => void): void;
+    onDisconnection(handler: (socket: RippleSocket, code: number, reason: string) => void): void;
+    onMessage(handler: (socket: RippleSocket, message: string | Uint8Array) => void): void;
+    listen(port: number): Promise<void>;
+    close(): Promise<void>;
+    broadcast(topic: string, data: string | Uint8Array, excludeSocketId?: string): void;
+    /**
+     * Upgrade an HTTP request to a WebSocket connection.
+     *
+     * This method is called by RippleServer to handle WebSocket upgrade requests.
+     *
+     * @param req - HTTP request
+     * @param options - Upgrade options (userId, reconnectionToken)
+     * @returns true if upgrade succeeded, false otherwise
+     */
+    upgrade(req: Request, options?: {
+        userId?: string;
+        reconnectionToken?: string;
+    }): boolean;
+    /**
+     * Get the underlying Bun server instance.
+     * Useful for advanced use cases.
+     */
+    getServer(): Server<ClientData> | undefined;
+}

package/dist/ripple/src/engines/IRippleEngine.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Core abstraction layer for Ripple WebSocket engines
+ *
+ * Defines the interface that all WebSocket engines must implement to work with Ripple.
+ * This abstraction allows Ripple to run on different runtimes (Bun, Node.js with uWS, Node.js with ws).
+ *
+ * @module @gravito/ripple/engines
+ * @since 5.0.0
+ */
+import type { ClientData } from '../types';
+/**
+ * Runtime-agnostic WebSocket connection interface.
+ *
+ * Provides a unified API across different WebSocket implementations (Bun, uWS, ws).
+ * Each engine wraps its native WebSocket type to implement this interface.
+ *
+ * @example
+ * ```typescript
+ * // Engine implementations wrap their native WebSocket
+ * class BunRippleSocket implements RippleSocket {
+ *   constructor(private ws: ServerWebSocket<ClientData>) {}
+ *
+ *   send(data: string | Uint8Array) {
+ *     this.ws.send(data)
+ *   }
+ *
+ *   get data() {
+ *     return this.ws.data
+ *   }
+ * }
+ * ```
+ */
+export interface RippleSocket {
+    /** Unique socket identifier */
+    id: string;
+    /** Client session data */
+    data: ClientData;
+    /**
+     * Send data to the client.
+     *
+     * @param data - Message payload (string or binary)
+     * @param compress - Whether to compress the message (optional, engine-dependent)
+     */
+    send(data: string | Uint8Array, compress?: boolean): void;
+    /**
+     * Close the WebSocket connection.
+     *
+     * @param code - WebSocket close code (default: 1000)
+     * @param reason - Human-readable close reason
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Get the number of bytes buffered for sending.
+     * Used for backpressure management.
+     *
+     * @returns Buffered bytes count
+     */
+    getBufferedAmount(): number;
+    /**
+     * Subscribe to a pub/sub topic.
+     *
+     * For engines with native pub/sub (Bun, uWS), this uses the native API.
+     * For engines without (ws), this is tracked in-memory by the engine.
+     *
+     * @param topic - Topic name to subscribe to
+     */
+    subscribe(topic: string): void;
+    /**
+     * Unsubscribe from a pub/sub topic.
+     *
+     * @param topic - Topic name to unsubscribe from
+     */
+    unsubscribe(topic: string): void;
+    /**
+     * Publish a message to a topic.
+     *
+     * For engines with native pub/sub, this broadcasts at the C++ layer.
+     * For engines without, this is handled by the engine's broadcast logic.
+     *
+     * @param topic - Topic name
+     * @param data - Message payload
+     */
+    publish(topic: string, data: string | Uint8Array): void;
+    /**
+     * Access to the underlying native WebSocket object.
+     *
+     * This is an escape hatch for engine-specific features not covered by the interface.
+     * Use with caution as it breaks runtime portability.
+     *
+     * @example
+     * ```typescript
+     * // Access Bun-specific features
+     * if (socket.raw && 'remoteAddress' in socket.raw) {
+     *   console.log('Client IP:', socket.raw.remoteAddress)
+     * }
+     * ```
+     */
+    raw?: any;
+}
+/**
+ * WebSocket engine interface for Ripple.
+ *
+ * Engines handle the low-level WebSocket I/O and lifecycle management.
+ * RippleServer delegates all runtime-specific operations to the engine.
+ *
+ * @example
+ * ```typescript
+ * // Example: Custom engine implementation
+ * class MyCustomEngine implements IRippleEngine {
+ *   private server?: any
+ *   private connectionHandler?: (socket: RippleSocket) => void
+ *
+ *   async listen(port: number): Promise<void> {
+ *     this.server = createServer(port)
+ *     this.server.on('connection', (ws) => {
+ *       const socket = new MyRippleSocket(ws)
+ *       this.connectionHandler?.(socket)
+ *     })
+ *   }
+ *
+ *   onConnection(handler: (socket: RippleSocket) => void): void {
+ *     this.connectionHandler = handler
+ *   }
+ *
+ *   // ... implement other methods
+ * }
+ * ```
+ */
+export interface IRippleEngine {
+    /** Engine name for logging and debugging */
+    readonly name: string;
+    /**
+     * Start the WebSocket server.
+     *
+     * @param port - Port number to listen on
+     * @throws If the port is already in use or binding fails
+     */
+    listen(port: number): Promise<void>;
+    /**
+     * Stop the WebSocket server and close all connections.
+     */
+    close(): Promise<void>;
+    /**
+     * Register handler for new WebSocket connections.
+     *
+     * Called by RippleServer to hook into the connection lifecycle.
+     * The engine should call this handler whenever a new WebSocket connection is established.
+     *
+     * @param handler - Callback invoked when a client connects
+     */
+    onConnection(handler: (socket: RippleSocket) => void): void;
+    /**
+     * Register handler for WebSocket disconnections.
+     *
+     * Called by RippleServer to hook into the disconnection lifecycle.
+     * The engine should call this handler whenever a WebSocket connection closes.
+     *
+     * @param handler - Callback invoked when a client disconnects
+     */
+    onDisconnection(handler: (socket: RippleSocket, code: number, reason: string) => void): void;
+    /**
+     * Register handler for incoming WebSocket messages.
+     *
+     * Called by RippleServer to hook into the message lifecycle.
+     * The engine should call this handler whenever a message is received.
+     *
+     * @param handler - Callback invoked when a message is received
+     */
+    onMessage(handler: (socket: RippleSocket, message: string | Uint8Array) => void): void;
+    /**
+     * Broadcast a message to all subscribers of a topic.
+     *
+     * For engines with native pub/sub (Bun, uWS), this should use the native broadcast API
+     * for maximum performance (C++ layer broadcast, no JS callback overhead).
+     *
+     * For engines without native pub/sub (ws), this should iterate over subscribers
+     * and send the message to each.
+     *
+     * @param topic - Topic/channel name
+     * @param data - Message payload
+     * @param excludeSocketId - Optional socket ID to exclude from broadcast
+     */
+    broadcast(topic: string, data: string | Uint8Array, excludeSocketId?: string): void;
+    /**
+     * Upgrade an HTTP request to a WebSocket connection.
+     *
+     * This is optional and only needed for engines that integrate with HTTP servers
+     * (Bun, uWS). For standalone WebSocket servers, this can be omitted.
+     *
+     * @param req - HTTP request object
+     * @param options - Upgrade options (e.g., user ID for authentication)
+     * @returns true if upgrade was successful, false otherwise
+     */
+    upgrade?(req: Request, options?: {
+        userId?: string;
+        reconnectionToken?: string;
+    }): boolean;
+}
+/**
+ * Factory function type for creating engine instances.
+ *
+ * @param config - Engine-specific configuration
+ * @returns Engine instance
+ */
+export type EngineFactory = (config: any) => IRippleEngine;

package/dist/ripple/src/engines/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Ripple WebSocket Engine exports
+ *
+ * Provides runtime-agnostic WebSocket engine implementations for Ripple.
+ *
+ * @module @gravito/ripple/engines
+ * @since 5.0.0
+ */
+export type { BunEngineConfig } from './BunEngine';
+export { BunEngine, BunRippleSocket } from './BunEngine';
+export type { EngineFactory, IRippleEngine, RippleSocket } from './IRippleEngine';

package/dist/ripple/src/errors/RippleError.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Ripple error types
+ *
+ * @module @gravito/ripple/errors
+ */
+/**
+ * Base error class for Ripple module.
+ *
+ * Provides structured error handling with error codes and messages.
+ *
+ * @example
+ * ```typescript
+ * throw new RippleError('INVALID_FORMAT', 'Invalid message format')
+ * ```
+ */
+export declare class RippleError extends Error {
+    readonly code: string;
+    /**
+     * Creates a new RippleError instance.
+     *
+     * @param code - The error code.
+     * @param message - The error message.
+     */
+    constructor(code: string, message: string);
+}
+/**
+ * Error class for driver-related issues.
+ *
+ * Used specifically for errors that occur in driver implementations
+ * (LocalDriver, RedisDriver).
+ *
+ * @example
+ * ```typescript
+ * throw new RippleDriverError(
+ *   'REDIS_NOT_INSTALLED',
+ *   'ioredis is required for RedisDriver'
+ * )
+ * ```
+ */
+export declare class RippleDriverError extends RippleError {
+    /**
+     * Creates a new RippleDriverError instance.
+     *
+     * @param code - The error code.
+     * @param message - The error message.
+     */
+    constructor(code: string, message: string);
+}

package/dist/ripple/src/errors/index.d.ts

@@ -0,0 +1 @@
+export * from './RippleError';

package/dist/ripple/src/events/BroadcastEvent.d.ts

@@ -31,21 +31,93 @@ import type { Channel } from '../types';
  */
 export declare abstract class BroadcastEvent {
     /**
-     * The channels to broadcast this event on
+     * Define which channel(s) this event should be broadcast on.
+     *
+     * @returns Single Channel or array of Channels for multi-channel broadcasting
+     *
+     * @example
+     * ```typescript
+     * // Broadcast to a single private channel
+     * broadcastOn() {
+     *   return new PrivateChannel(`orders.${this.order.userId}`)
+     * }
+     *
+     * // Broadcast to multiple channels
+     * broadcastOn() {
+     *   return [
+     *     new PrivateChannel(`user.${this.userId}`),
+     *     new PublicChannel('notifications')
+     *   ]
+     * }
+     * ```
      */
     abstract broadcastOn(): Channel | Channel[];
     /**
-     * The event name to use when broadcasting
-     * Defaults to the class name
+     * Define the event name for client listeners.
+     *
+     * @returns The event name (defaults to class name if not overridden)
+     *
+     * @example
+     * ```typescript
+     * // Use class name (default behavior)
+     * class OrderShipped extends BroadcastEvent {
+     *   // Event name will be 'OrderShipped'
+     * }
+     *
+     * // Custom event name
+     * broadcastAs() {
+     *   return 'order.shipped' // dot notation style
+     * }
+     * ```
      */
     broadcastAs(): string;
     /**
-     * Socket IDs to exclude from the broadcast
+     * Exclude specific socket IDs from receiving this broadcast.
+     *
+     * @returns Array of socket IDs to exclude (empty array by default)
+     *
+     * @example
+     * ```typescript
+     * // Exclude the sender
+     * class MessageSent extends BroadcastEvent {
+     *   constructor(
+     *     public message: Message,
+     *     public senderSocketId: string
+     *   ) { super() }
+     *
+     *   broadcastExcept() {
+     *     return [this.senderSocketId] // Don't send back to sender
+     *   }
+     * }
+     * ```
      */
     broadcastExcept(): string[];
     /**
-     * Get the event data payload
-     * Override to customize the broadcast payload
+     * Define the event payload data sent to clients.
+     *
+     * @returns The data object to broadcast (all public properties by default)
+     *
+     * @example
+     * ```typescript
+     * // Default: All public properties are included
+     * class OrderShipped extends BroadcastEvent {
+     *   constructor(public order: Order) { super() }
+     *   // Broadcasts: { order: { id, status, ... } }
+     * }
+     *
+     * // Custom payload
+     * class OrderShipped extends BroadcastEvent {
+     *   constructor(public order: Order) { super() }
+     *
+     *   broadcastWith() {
+     *     return {
+     *       orderId: this.order.id,
+     *       trackingNumber: this.order.trackingNumber,
+     *       // Exclude sensitive data
+     *     }
+     *   }
+     * }
+     * ```
      */
     broadcastWith(): Record<string, unknown>;
 }