@gravito/ripple 3.0.1 → 3.1.0

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

@@ -1,29 +1,61 @@
 /**
  * @fileoverview Local (in-memory) driver for @gravito/ripple
  *
- * Suitable for single-instance deployments. For horizontal scaling,
- * use the Redis driver.
- *
  * @module @gravito/ripple/drivers
  */
-import type { RippleDriver } from '../types';
+import type { DriverStatus, RippleDriver } from '../types';
 /**
- * In-memory driver for single-instance deployments
+ * Local (in-memory) driver for Ripple.
+ *
+ * This driver is intended for development and single-server deployments.
+ * It distributes messages directly within the current process memory.
  *
- * This driver keeps all state in memory and is suitable for:
- * - Development
- * - Single-server deployments
- * - Serverless functions (with caveats)
+ * @example
+ * ```typescript
+ * import { RippleServer, LocalDriver } from '@gravito/ripple'
  *
- * For multi-server deployments, use RedisDriver instead.
+ * const server = new RippleServer({
+ *   driver: 'local' // Uses LocalDriver internally
+ * })
+ * ```
  */
 export declare class LocalDriver implements RippleDriver {
+    /** Driver name identifier */
     readonly name = "local";
-    /** Event callbacks per channel */
+    /** In-memory map of channel subscribers: channel -> set of callbacks */
     private listeners;
+    private _initialized;
+    /**
+     * Publish a message to a channel within the current process.
+     *
+     * @param channel - Target channel name
+     * @param event - Event name
+     * @param data - Event payload
+     */
     publish(channel: string, event: string, data: unknown): Promise<void>;
+    /**
+     * Subscribe to a channel in memory.
+     *
+     * @param channel - Channel name
+     * @param callback - Function called when a message is published to this channel
+     */
     subscribe(channel: string, callback: (event: string, data: unknown) => void): Promise<void>;
+    /**
+     * Unsubscribe from a channel in memory.
+     *
+     * @param channel - Channel name
+     */
     unsubscribe(channel: string): Promise<void>;
+    /**
+     * Initialize the local driver.
+     */
     init(): Promise<void>;
+    /**
+     * Shutdown the local driver and clear all listeners.
+     */
     shutdown(): Promise<void>;
+    /**
+     * Get the current status of the local driver.
+     */
+    getStatus(): DriverStatus;
 }

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

@@ -1,63 +1,141 @@
 /**
  * @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, RippleDriver } from '../types';
+/**
+ * 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-based driver for multi-server deployments
+ * 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;
+    /**
+     * 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/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>;
 }

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

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Broadcast manager for Ripple
+ *
+ * @module @gravito/ripple/events
+ */
+import type { RippleServer } from '../RippleServer';
+import type { BroadcastEvent } from './BroadcastEvent';
+/**
+ * Modern broadcast manager with dependency injection.
+ *
+ * BroadcastManager is the recommended way to broadcast events in Ripple applications.
+ * It accepts RippleServer explicitly through the constructor (dependency injection),
+ * making it testable and avoiding global state.
+ *
+ * @example
+ * ```typescript
+ * // Setup with dependency injection
+ * const ripple = new RippleServer({ path: '/ws' })
+ * const manager = new BroadcastManager(ripple)
+ *
+ * // Or bind to IoC container
+ * container.bind('broadcast').toValue(new BroadcastManager(ripple))
+ *
+ * // Broadcast BroadcastEvent instances
+ * manager.broadcast(new OrderShipped(order))
+ *
+ * // Fluent API for direct broadcasting
+ * manager.to('news').emit('article.published', { id: 123 })
+ * manager.toPrivate('orders.456').emit('order.updated', { status: 'shipped' })
+ * manager.toPresence('chat.lobby').except('socket-1').emit('message', { text: 'Hi!' })
+ * ```
+ */
+export declare class BroadcastManager {
+    private readonly server;
+    constructor(server: RippleServer);
+    /**
+     * Broadcast a BroadcastEvent to its designated channels.
+     *
+     * @param event - The BroadcastEvent instance to broadcast
+     *
+     * @example
+     * ```typescript
+     * class OrderShipped extends BroadcastEvent {
+     *   constructor(public order: Order) { super() }
+     *   broadcastOn() { return new PrivateChannel(`orders.${this.order.userId}`) }
+     *   broadcastAs() { return 'OrderShipped' }
+     * }
+     *
+     * manager.broadcast(new OrderShipped(order))
+     * ```
+     */
+    broadcast(event: BroadcastEvent): void;
+    /**
+     * Broadcast to a public channel.
+     *
+     * @param channel - The channel name (without prefix)
+     * @returns ChannelBroadcaster for chaining
+     */
+    to(channel: string): ChannelBroadcaster;
+    /**
+     * Broadcast to a private channel.
+     *
+     * @param channel - The channel name (will be prefixed with 'private-')
+     * @returns ChannelBroadcaster for chaining
+     */
+    toPrivate(channel: string): ChannelBroadcaster;
+    /**
+     * Broadcast to a presence channel.
+     *
+     * @param channel - The channel name (will be prefixed with 'presence-')
+     * @returns ChannelBroadcaster for chaining
+     */
+    toPresence(channel: string): ChannelBroadcaster;
+}
+/**
+ * Fluent broadcaster for channel-specific operations.
+ *
+ * Returned by BroadcastManager's `to()`, `toPrivate()`, and `toPresence()` methods.
+ * Provides a chainable API for broadcasting with optional exclusions.
+ */
+export declare class ChannelBroadcaster {
+    private readonly server;
+    private readonly channel;
+    private _except;
+    constructor(server: RippleServer, channel: string);
+    /**
+     * Exclude specific socket IDs from the broadcast.
+     *
+     * @param socketIds - Single socket ID or array of IDs to exclude
+     * @returns this for method chaining
+     */
+    except(socketIds: string | string[]): this;
+    /**
+     * Emit the event to the channel.
+     *
+     * @param event - The event name
+     * @param data - The event payload (must be JSON-serializable)
+     */
+    emit(event: string, data: unknown): void;
+}