@gravito/ripple 3.0.0 → 3.1.0

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

@@ -0,0 +1,264 @@
+/**
+ * @fileoverview Broadcaster for sending events to channels
+ *
+ * @module @gravito/ripple/events
+ */
+import type { RippleServer } from '../RippleServer';
+import type { BroadcastEvent } from './BroadcastEvent';
+/**
+ * Set the global RippleServer instance.
+ *
+ * **⚠️ DEPRECATED**: This function is deprecated and will be removed in v4.0.
+ * Use dependency injection with `BroadcastManager` instead.
+ *
+ * @deprecated Use BroadcastManager with dependency injection instead. Will be removed in v4.0.
+ * @param server - The RippleServer instance to use globally
+ *
+ * @example
+ * ```typescript
+ * // ❌ Old way (deprecated)
+ * import { setRippleServer } from '@gravito/ripple'
+ * const ripple = new RippleServer({ path: '/ws' })
+ * setRippleServer(ripple)
+ *
+ * // ✅ New way (recommended)
+ * import { BroadcastManager } from '@gravito/ripple'
+ * const ripple = new RippleServer({ path: '/ws' })
+ * const manager = new BroadcastManager(ripple)
+ * // Or with dependency injection:
+ * container.bind('broadcast').toValue(new BroadcastManager(ripple))
+ * ```
+ *
+ * @see {@link BroadcastManager} - Recommended replacement
+ */
+export declare function setRippleServer(server: RippleServer): void;
+/**
+ * Get the global RippleServer instance.
+ *
+ * **⚠️ DEPRECATED**: This function is deprecated and will be removed in v4.0.
+ * Use dependency injection with `BroadcastManager` instead.
+ *
+ * @deprecated Use BroadcastManager with dependency injection instead. Will be removed in v4.0.
+ * @returns The globally configured RippleServer instance, or null if not configured
+ *
+ * @example
+ * ```typescript
+ * // ❌ Old way (deprecated)
+ * import { getRippleServer } from '@gravito/ripple'
+ * const ripple = getRippleServer()
+ * if (ripple) {
+ *   ripple.broadcast('news', 'article.published', data)
+ * }
+ *
+ * // ✅ New way (recommended)
+ * import { BroadcastManager } from '@gravito/ripple'
+ * const manager = container.make<BroadcastManager>('broadcast')
+ * manager.to('news').emit('article.published', data)
+ * ```
+ *
+ * @see {@link BroadcastManager} - Recommended replacement
+ */
+export declare function getRippleServer(): RippleServer | null;
+/**
+ * Broadcast a BroadcastEvent to its designated channels.
+ *
+ * **⚠️ DEPRECATED**: This function is deprecated and will be removed in v4.0.
+ * Use `BroadcastManager.broadcast()` with dependency injection instead.
+ *
+ * This function uses a global RippleServer instance. In modern applications,
+ * prefer dependency injection with BroadcastManager for better testability
+ * and cleaner architecture.
+ *
+ * @deprecated Use BroadcastManager.broadcast() instead. Will be removed in v4.0.
+ * @param event - The BroadcastEvent to send (determines channels via broadcastOn())
+ *
+ * @example
+ * ```typescript
+ * // ❌ Old way (deprecated)
+ * import { broadcast } from '@gravito/ripple'
+ *
+ * class OrderShipped extends BroadcastEvent {
+ *   constructor(public order: Order) { super() }
+ *   broadcastOn() { return new PrivateChannel(`orders.${this.order.userId}`) }
+ *   broadcastAs() { return 'OrderShipped' }
+ * }
+ *
+ * broadcast(new OrderShipped(order))
+ *
+ * // ✅ New way (recommended)
+ * import { BroadcastManager } from '@gravito/ripple'
+ *
+ * class OrderShipped extends BroadcastEvent {
+ *   constructor(public order: Order) { super() }
+ *   broadcastOn() { return new PrivateChannel(`orders.${this.order.userId}`) }
+ *   broadcastAs() { return 'OrderShipped' }
+ * }
+ *
+ * const manager = container.make<BroadcastManager>('broadcast')
+ * manager.broadcast(new OrderShipped(order))
+ * ```
+ *
+ * @see {@link BroadcastManager.broadcast} - Recommended replacement
+ * @see {@link BroadcastEvent} - For creating broadcast events
+ */
+export declare function broadcast(event: BroadcastEvent): void;
+/**
+ * Fluent API for broadcasting events to channels.
+ *
+ * **⚠️ DEPRECATED**: This class is deprecated and will be removed in v4.0.
+ * Use `BroadcastManager` with dependency injection for a cleaner, more testable approach.
+ *
+ * The Broadcaster class uses a global RippleServer instance, which makes testing difficult
+ * and creates hidden dependencies. BroadcastManager accepts the server explicitly through
+ * dependency injection.
+ *
+ * @deprecated Use BroadcastManager instead. Will be removed in v4.0.
+ *
+ * @example
+ * ```typescript
+ * // ❌ Old way (deprecated)
+ * import { Broadcaster } from '@gravito/ripple'
+ *
+ * Broadcaster.to('news').emit('article.published', { id: 123 })
+ * Broadcaster.toPrivate('orders.456').emit('order.shipped', data)
+ * Broadcaster.toPresence('chat.lobby')
+ *   .except(['socket-id-1', 'socket-id-2'])
+ *   .emit('message', { text: 'Hello!' })
+ *
+ * // ✅ New way (recommended)
+ * import { BroadcastManager } from '@gravito/ripple'
+ *
+ * const manager = container.make<BroadcastManager>('broadcast')
+ * manager.to('news').emit('article.published', { id: 123 })
+ * manager.to('private-orders.456').emit('order.shipped', data)
+ * manager.to('presence-chat.lobby')
+ *   .except(['socket-id-1', 'socket-id-2'])
+ *   .emit('message', { text: 'Hello!' })
+ * ```
+ *
+ * @see {@link BroadcastManager} - Recommended replacement with dependency injection
+ */
+export declare class Broadcaster {
+    private _channel;
+    private _except;
+    private constructor();
+    /**
+     * Create a broadcaster for a public channel.
+     *
+     * **⚠️ DEPRECATED**: Use `BroadcastManager.to()` instead.
+     *
+     * @deprecated Use BroadcastManager.to() instead. Will be removed in v4.0.
+     * @param channel - The public channel name (without prefix)
+     * @returns A Broadcaster instance for the channel
+     *
+     * @example
+     * ```typescript
+     * // ❌ Deprecated
+     * Broadcaster.to('news').emit('article.published', data)
+     *
+     * // ✅ Recommended
+     * manager.to('news').emit('article.published', data)
+     * ```
+     */
+    static to(channel: string): Broadcaster;
+    /**
+     * Create a broadcaster for a private channel.
+     *
+     * Automatically prefixes the channel name with 'private-'.
+     *
+     * **⚠️ DEPRECATED**: Use `BroadcastManager.to()` with manual prefix instead.
+     *
+     * @deprecated Use BroadcastManager.to() instead. Will be removed in v4.0.
+     * @param channel - The channel name (will be prefixed with 'private-')
+     * @returns A Broadcaster instance for the private channel
+     *
+     * @example
+     * ```typescript
+     * // ❌ Deprecated
+     * Broadcaster.toPrivate('orders.123').emit('order.shipped', data)
+     *
+     * // ✅ Recommended
+     * manager.to('private-orders.123').emit('order.shipped', data)
+     * ```
+     */
+    static toPrivate(channel: string): Broadcaster;
+    /**
+     * Create a broadcaster for a presence channel.
+     *
+     * Automatically prefixes the channel name with 'presence-'.
+     *
+     * **⚠️ DEPRECATED**: Use `BroadcastManager.to()` with manual prefix instead.
+     *
+     * @deprecated Use BroadcastManager.to() instead. Will be removed in v4.0.
+     * @param channel - The channel name (will be prefixed with 'presence-')
+     * @returns A Broadcaster instance for the presence channel
+     *
+     * @example
+     * ```typescript
+     * // ❌ Deprecated
+     * Broadcaster.toPresence('chat.lobby').emit('message', { text: 'Hello!' })
+     *
+     * // ✅ Recommended
+     * manager.to('presence-chat.lobby').emit('message', { text: 'Hello!' })
+     * ```
+     */
+    static toPresence(channel: string): Broadcaster;
+    /**
+     * Exclude specific socket IDs from receiving the broadcast.
+     *
+     * Useful for preventing the sender from receiving their own message
+     * or excluding specific users from a broadcast.
+     *
+     * **⚠️ DEPRECATED**: Use `BroadcastManager.to().except()` instead.
+     *
+     * @deprecated Use BroadcastManager instead. Will be removed in v4.0.
+     * @param socketIds - Single socket ID or array of socket IDs to exclude
+     * @returns The Broadcaster instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // ❌ Deprecated
+     * Broadcaster.to('chat.room1')
+     *   .except('socket-id-sender')
+     *   .emit('message', { text: 'Hello!' })
+     *
+     * Broadcaster.to('chat.room1')
+     *   .except(['socket-id-1', 'socket-id-2'])
+     *   .emit('notification', { type: 'info' })
+     *
+     * // ✅ Recommended
+     * manager.to('chat.room1')
+     *   .except('socket-id-sender')
+     *   .emit('message', { text: 'Hello!' })
+     * ```
+     */
+    except(socketIds: string | string[]): this;
+    /**
+     * Emit an event to the configured channel.
+     *
+     * Sends the event to all subscribers of the channel, excluding any socket IDs
+     * specified via the `except()` method.
+     *
+     * **⚠️ DEPRECATED**: Use `BroadcastManager.to().emit()` instead.
+     *
+     * @deprecated Use BroadcastManager instead. Will be removed in v4.0.
+     * @param event - The event name that clients will listen for
+     * @param data - The event payload (must be JSON-serializable)
+     *
+     * @example
+     * ```typescript
+     * // ❌ Deprecated
+     * Broadcaster.to('news').emit('article.published', {
+     *   id: 123,
+     *   title: 'Breaking News'
+     * })
+     *
+     * // ✅ Recommended
+     * manager.to('news').emit('article.published', {
+     *   id: 123,
+     *   title: 'Breaking News'
+     * })
+     * ```
+     */
+    emit(event: string, data: unknown): void;
+}

package/dist/{events → ripple/src/events}/index.d.ts

@@ -1,3 +1,3 @@
 export * from './BroadcastEvent';
 export * from './Broadcaster';
-//# sourceMappingURL=index.d.ts.map
+export * from './BroadcastManager';

package/dist/ripple/src/health/HealthChecker.d.ts

@@ -0,0 +1,93 @@
+import type { RippleServer } from '../RippleServer';
+import type { RippleDriver } from '../types';
+/**
+ * Health status levels for individual components or the overall system.
+ */
+export type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
+/**
+ * Health information for a specific system component.
+ */
+export interface ComponentHealth {
+    /** Current health status */
+    status: HealthStatus;
+    /** Descriptive message about the health state */
+    message?: string;
+    /** ISO 8601 timestamp of the last check */
+    lastCheck: string;
+}
+/**
+ * Result of a system-wide health check.
+ */
+export interface HealthCheckResult {
+    /** Overall system health status */
+    status: HealthStatus;
+    /** ISO 8601 timestamp of the check */
+    timestamp: string;
+    /** Server uptime in milliseconds */
+    uptime: number;
+    /** Health status of individual components */
+    checks: {
+        /** WebSocket server health */
+        websocket: ComponentHealth;
+        /** Message distribution driver health */
+        driver: ComponentHealth;
+    };
+    /** Real-time performance statistics */
+    stats: {
+        /** Current number of active client connections */
+        activeConnections: number;
+        /** Total number of active channels */
+        totalChannels: number;
+        /** Average message throughput (messages per second) */
+        messagesPerSecond: number;
+    };
+}
+/**
+ * HealthChecker monitors the Ripple server and its driver.
+ *
+ * It provides real-time health diagnostics, performance metrics (MPS),
+ * and tracks server uptime.
+ */
+export declare class HealthChecker {
+    private readonly server;
+    private readonly driver;
+    private startTime;
+    private messageCount;
+    private lastMessageCountReset;
+    /**
+     * Create a new HealthChecker.
+     *
+     * @param server - The Ripple server instance to monitor
+     * @param driver - The message driver instance to monitor
+     */
+    constructor(server: RippleServer, driver: RippleDriver);
+    /**
+     * Record a message being processed.
+     *
+     * Used to calculate messages-per-second (MPS) metrics.
+     */
+    recordMessage(): void;
+    /**
+     * Perform a full system health check.
+     *
+     * Resets the message counter and calculates MPS since the last check.
+     *
+     * @returns Detailed health check result
+     */
+    check(): Promise<HealthCheckResult>;
+    /**
+     * Check the health of the WebSocket server layer.
+     */
+    private checkWebSocket;
+    /**
+     * Check the health of the message distribution driver.
+     */
+    private checkDriver;
+    /**
+     * Determine the overall status based on component statuses.
+     *
+     * @param statuses - Array of component health statuses
+     * @returns The most severe status found
+     */
+    private determineOverallStatus;
+}

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

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

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

@@ -0,0 +1,60 @@
+/**
+ * @gravito/ripple - Bun-native WebSocket broadcasting for Gravito.
+ *
+ * Ripple is a high-performance, real-time broadcasting module designed for the Gravito ecosystem.
+ * It provides channel-based WebSocket communication (Public, Private, Presence) powered by
+ * Bun's native WebSocket implementation for maximum speed and minimal overhead.
+ *
+ * Key features:
+ * - **Bun Native**: Leveraging `Bun.serve({ websocket })` for sub-millisecond latency.
+ * - **Channel System**: Built-in support for Public, Private (authenticated), and Presence (user tracking) channels.
+ * - **Scalable Drivers**: Includes `LocalDriver` for single-server and `RedisDriver` for horizontal scaling.
+ * - **Type-Safe**: Fully typed events and channel management.
+ *
+ * @example
+ * ```typescript
+ * // 1. Setup Server
+ * import { OrbitRipple } from '@gravito/ripple'
+ *
+ * core.install(new OrbitRipple({
+ *   path: '/ws',
+ *   authorizer: async (channel, userId) => {
+ *     // Return true/false for private channels
+ *     // Return user info object for presence channels
+ *     return userId !== undefined
+ *   }
+ * }))
+ *
+ * // 2. Define Event
+ * import { BroadcastEvent, PrivateChannel } from '@gravito/ripple'
+ *
+ * class OrderUpdated extends BroadcastEvent {
+ *   constructor(public orderId: string, public status: string) { super() }
+ *
+ *   broadcastOn() {
+ *     return new PrivateChannel(`orders.${this.orderId}`)
+ *   }
+ * }
+ *
+ * // 3. Broadcast
+ * import { broadcast } from '@gravito/ripple'
+ *
+ * broadcast(new OrderUpdated('123', 'shipped'))
+ * ```
+ *
+ * @module @gravito/ripple
+ */
+export { CHANNEL_PREFIXES, ChannelManager, createChannel, PresenceChannel, PrivateChannel, PublicChannel, requiresAuth, } from './channels';
+export { LocalDriver, RedisDriver } from './drivers';
+export { RippleDriverError, RippleError } from './errors';
+export { BroadcastEvent, Broadcaster, BroadcastManager, broadcast, getRippleServer, setRippleServer, } from './events';
+export type { ComponentHealth, HealthCheckResult, HealthStatus } from './health/HealthChecker';
+export { HealthChecker } from './health/HealthChecker';
+export type { LogContext, LogLevel, RippleLogger } from './logging/Logger';
+export { ConsoleLogger, createLogger } from './logging/Logger';
+export { OrbitRipple } from './OrbitRipple';
+export { RippleServer } from './RippleServer';
+export type { ConnectionEvent, ConnectionTracker } from './tracking/ConnectionTracker';
+export { DefaultConnectionTracker } from './tracking/ConnectionTracker';
+export type { BroadcastEventInterface, Channel, ChannelAuthorizer, ChannelType, ClientData, ClientMessage, DriverStatus, ErrorServerMessage, PresenceUserInfo, RippleBunServer, RippleConfig, RippleDriver, RippleErrorCode, RippleWebSocket, ServerMessage, WebSocketHandlerConfig, } from './types';
+export { MessageSerializer } from './utils/MessageSerializer';

package/dist/ripple/src/logging/Logger.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Supported log levels for Ripple.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Structured log context containing metadata for logs.
+ */
+export interface LogContext {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Log level */
+    level: LogLevel;
+    /** Module name where the log originated */
+    module: string;
+    /** Unique client identifier if applicable */
+    clientId?: string;
+    /** Channel name if applicable */
+    channel?: string;
+    /** Event name if applicable */
+    event?: string;
+    /** Error code if applicable */
+    errorCode?: string;
+    /** Additional dynamic metadata */
+    [key: string]: unknown;
+}
+/**
+ * Interface for Ripple logging implementations.
+ *
+ * Developers can implement this interface to integrate Ripple with their
+ * preferred logging systems (e.g., Winston, Pino, Datadog).
+ *
+ * @example
+ * ```typescript
+ * const myLogger: RippleLogger = {
+ *   debug: (msg, ctx) => console.log('[DEBUG]', msg, ctx),
+ *   info: (msg, ctx) => console.log('[INFO]', msg, ctx),
+ *   warn: (msg, ctx) => console.warn('[WARN]', msg, ctx),
+ *   error: (msg, ctx) => console.error('[ERROR]', msg, ctx)
+ * }
+ * ```
+ */
+export interface RippleLogger {
+    /** Log a debug message */
+    debug(message: string, context?: Partial<LogContext>): void;
+    /** Log an info message */
+    info(message: string, context?: Partial<LogContext>): void;
+    /** Log a warning message */
+    warn(message: string, context?: Partial<LogContext>): void;
+    /** Log an error message */
+    error(message: string, context?: Partial<LogContext>): void;
+}
+/**
+ * Default JSON-based console logger for Ripple.
+ *
+ * Formats logs as JSON strings to the console, suitable for cloud log aggregators.
+ */
+export declare class ConsoleLogger implements RippleLogger {
+    private readonly module;
+    private readonly minLevel;
+    /**
+     * Create a new ConsoleLogger.
+     *
+     * @param module - Module name for identification
+     * @param minLevel - Minimum level to log (default: 'info')
+     */
+    constructor(module: string, minLevel?: LogLevel);
+    /**
+     * Check if a message should be logged based on its level.
+     */
+    private shouldLog;
+    /**
+     * Format the log context with standard metadata.
+     */
+    private formatContext;
+    /**
+     * Log a debug message as JSON.
+     */
+    debug(message: string, context?: Partial<LogContext>): void;
+    /**
+     * Log an info message as JSON.
+     */
+    info(message: string, context?: Partial<LogContext>): void;
+    /**
+     * Log a warning message as JSON.
+     */
+    warn(message: string, context?: Partial<LogContext>): void;
+    /**
+     * Log an error message as JSON.
+     */
+    error(message: string, context?: Partial<LogContext>): void;
+}
+/**
+ * Utility function to create a new ConsoleLogger.
+ *
+ * @param module - Module name
+ * @param minLevel - Minimum log level
+ * @returns A new RippleLogger instance
+ */
+export declare function createLogger(module: string, minLevel?: LogLevel): RippleLogger;

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

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

package/dist/ripple/src/tracking/ConnectionTracker.d.ts

@@ -0,0 +1,116 @@
+import type { RippleLogger } from '../logging/Logger';
+/**
+ * Events tracked by the ConnectionTracker.
+ */
+export type ConnectionEvent = {
+    type: 'connected';
+    clientId: string;
+    timestamp: Date;
+} | {
+    type: 'disconnected';
+    clientId: string;
+    timestamp: Date;
+    code: number;
+    reason: string;
+    duration: number;
+} | {
+    type: 'subscribed';
+    clientId: string;
+    channel: string;
+    timestamp: Date;
+} | {
+    type: 'unsubscribed';
+    clientId: string;
+    channel: string;
+    timestamp: Date;
+} | {
+    type: 'error';
+    clientId: string;
+    error: string;
+    timestamp: Date;
+};
+/**
+ * Interface for tracking WebSocket connection lifecycles and statistics.
+ *
+ * Implementations are responsible for monitoring active connections,
+ * subscription states, and providing metrics for observability.
+ */
+export interface ConnectionTracker {
+    /** Called when a client establishes a connection */
+    onConnect(clientId: string): void;
+    /** Called when a client disconnects */
+    onDisconnect(clientId: string, code: number, reason: string): void;
+    /** Called when a client subscribes to a channel */
+    onSubscribe(clientId: string, channel: string): void;
+    /** Called when a client unsubscribes from a channel */
+    onUnsubscribe(clientId: string, channel: string): void;
+    /** Called when a client-related error occurs */
+    onError(clientId: string, error: string): void;
+    /** Get the duration of an active connection in milliseconds */
+    getConnectionDuration(clientId: string): number | null;
+    /** Get the total number of active connections */
+    getActiveConnections(): number;
+}
+/**
+ * Default implementation of the ConnectionTracker.
+ *
+ * Maintains an in-memory map of active connections and logs lifecycle events.
+ * Provides basic metrics like active connection count and connection duration.
+ */
+export declare class DefaultConnectionTracker implements ConnectionTracker {
+    /** Map of active connection data: clientId -> connection info */
+    private connections;
+    private logger;
+    /**
+     * Create a new DefaultConnectionTracker.
+     *
+     * @param logger - Optional custom logger (defaults to ConsoleLogger)
+     */
+    constructor(logger?: RippleLogger);
+    /**
+     * Track a new connection.
+     *
+     * @param clientId - Unique client identifier
+     */
+    onConnect(clientId: string): void;
+    /**
+     * Clean up and log disconnection metrics.
+     *
+     * @param clientId - Client identifier
+     * @param code - WebSocket close code
+     * @param reason - Close reason
+     */
+    onDisconnect(clientId: string, code: number, reason: string): void;
+    /**
+     * Track channel subscription.
+     *
+     * @param clientId - Client identifier
+     * @param channel - Channel name
+     */
+    onSubscribe(clientId: string, channel: string): void;
+    /**
+     * Track channel unsubscription.
+     *
+     * @param clientId - Client identifier
+     * @param channel - Channel name
+     */
+    onUnsubscribe(clientId: string, channel: string): void;
+    /**
+     * Log client errors.
+     *
+     * @param clientId - Client identifier
+     * @param error - Error message
+     */
+    onError(clientId: string, error: string): void;
+    /**
+     * Calculate connection duration.
+     *
+     * @param clientId - Client identifier
+     * @returns Duration in milliseconds, or null if not found
+     */
+    getConnectionDuration(clientId: string): number | null;
+    /**
+     * Get total active connection count.
+     */
+    getActiveConnections(): number;
+}

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

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