honeydrop 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,748 @@
+import { Socket, ManagerOptions, SocketOptions } from 'socket.io-client';
+
+/**
+ * Honeydrop Logger
+ * Debug and logging utilities for development
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+interface LoggerOptions {
+    level?: LogLevel;
+    prefix?: string;
+    enabled?: boolean;
+}
+declare class Logger {
+    private level;
+    private prefix;
+    private enabled;
+    private isBrowser;
+    constructor(options?: LoggerOptions);
+    /**
+     * Set the logging level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Enable or disable logging
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if logging is enabled for a specific level
+     */
+    private shouldLog;
+    /**
+     * Format the log message
+     */
+    private formatMessage;
+    /**
+     * Log a debug message
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Log a connection event
+     */
+    connection(event: 'connected' | 'disconnected' | 'reconnecting' | 'reconnected', details?: unknown): void;
+    /**
+     * Log an event emission
+     */
+    emit(event: string, data?: unknown): void;
+    /**
+     * Log an event reception
+     */
+    receive(event: string, data?: unknown): void;
+}
+
+/**
+ * Honeydrop Reconnection Handler
+ * Manages automatic reconnection with customizable retry strategies
+ */
+
+type ReconnectionStrategy = 'linear' | 'exponential';
+interface ReconnectionOptions {
+    enabled?: boolean;
+    maxAttempts?: number;
+    delay?: number;
+    maxDelay?: number;
+    strategy?: ReconnectionStrategy;
+    onReconnecting?: (attempt: number) => void;
+    onReconnected?: () => void;
+    onFailed?: () => void;
+}
+declare class ReconnectionHandler {
+    private options;
+    private callbacks;
+    private socket;
+    private logger;
+    private attempts;
+    private timer;
+    private isReconnecting;
+    constructor(options: ReconnectionOptions, logger: Logger);
+    /**
+     * Set the socket instance to manage
+     */
+    setSocket(socket: Socket): void;
+    /**
+     * Calculate the delay for the next reconnection attempt
+     */
+    private calculateDelay;
+    /**
+     * Setup socket event listeners for reconnection
+     */
+    private setupListeners;
+    /**
+     * Start the reconnection process
+     */
+    private startReconnection;
+    /**
+     * Attempt a single reconnection
+     */
+    private attemptReconnection;
+    /**
+     * Manually trigger a reconnection
+     */
+    reconnect(): void;
+    /**
+     * Reset reconnection state
+     */
+    private reset;
+    /**
+     * Stop reconnection attempts
+     */
+    stop(): void;
+    /**
+     * Get current reconnection status
+     */
+    getStatus(): {
+        isReconnecting: boolean;
+        attempts: number;
+    };
+    /**
+     * Update reconnection options
+     */
+    updateOptions(options: Partial<ReconnectionOptions>): void;
+}
+
+/**
+ * Honeydrop Namespaced Events
+ * Provides namespaced event prefixing for cleaner event organization
+ */
+interface NamespacedEmitter {
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    once(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler?: (...args: unknown[]) => void): void;
+    emit(event: string, ...args: unknown[]): void;
+}
+type NamespaceDelimiter = ':' | '/' | '.' | '_';
+interface NamespaceOptions {
+    delimiter?: NamespaceDelimiter;
+}
+declare class NamespacedEvents {
+    private name;
+    private delimiter;
+    private emitter;
+    constructor(name: string, emitter: NamespacedEmitter, options?: NamespaceOptions);
+    /**
+     * Get the full namespaced event name
+     */
+    private getEventName;
+    /**
+     * Register an event listener with namespace prefix
+     */
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * Register a one-time event listener with namespace prefix
+     */
+    once(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * Remove an event listener from namespaced event
+     */
+    off(event: string, handler?: (...args: unknown[]) => void): void;
+    /**
+     * Emit an event with namespace prefix
+     */
+    emit(event: string, ...args: unknown[]): void;
+    /**
+     * Get the namespace name
+     */
+    getName(): string;
+    /**
+     * Get the delimiter used for this namespace
+     */
+    getDelimiter(): NamespaceDelimiter;
+    /**
+     * Create a sub-namespace
+     */
+    sub(name: string): NamespacedEvents;
+}
+
+/**
+ * Honeydrop Offline Queue
+ * Stores events when disconnected and flushes them on reconnect
+ */
+
+interface QueuedEvent {
+    event: string;
+    args: unknown[];
+    timestamp: number;
+}
+interface OfflineQueueOptions {
+    /** Enable offline queueing (default: true) */
+    enabled?: boolean;
+    /** Maximum number of events to queue (default: 100, 0 = unlimited) */
+    maxSize?: number;
+    /** Maximum age of events in ms before they're discarded (default: 0 = no expiry) */
+    maxAge?: number;
+    /** Called when an event is queued */
+    onQueued?: (event: QueuedEvent) => void;
+    /** Called when events are flushed */
+    onFlushed?: (count: number) => void;
+    /** Called when queue is full and event is dropped */
+    onDropped?: (event: QueuedEvent) => void;
+}
+declare class OfflineQueue {
+    private queue;
+    private options;
+    private logger;
+    private socket;
+    constructor(options: OfflineQueueOptions | undefined, logger: Logger);
+    /**
+     * Set the socket instance
+     */
+    setSocket(socket: Socket): void;
+    /**
+     * Add an event to the queue
+     * Returns true if queued, false if dropped
+     */
+    enqueue(event: string, ...args: unknown[]): boolean;
+    /**
+     * Flush all queued events to the socket
+     */
+    flush(): void;
+    /**
+     * Get current queue length
+     */
+    get length(): number;
+    /**
+     * Get all queued events (read-only copy)
+     */
+    getQueue(): readonly QueuedEvent[];
+    /**
+     * Clear all queued events
+     */
+    clear(): void;
+    /**
+     * Check if queueing is enabled
+     */
+    get enabled(): boolean;
+    /**
+     * Enable or disable queueing
+     */
+    setEnabled(enabled: boolean): void;
+}
+
+/**
+ * Honeydrop Connection Monitor
+ * Tracks connection health, latency, and quality
+ */
+
+type ConnectionQuality = 'excellent' | 'good' | 'fair' | 'poor' | 'disconnected';
+interface ConnectionMonitorOptions {
+    /** Enable automatic ping monitoring (default: true) */
+    enabled?: boolean;
+    /** Ping interval in ms (default: 5000) */
+    pingInterval?: number;
+    /** Ping timeout in ms (default: 3000) */
+    pingTimeout?: number;
+    /** Number of pings to average for latency (default: 5) */
+    sampleSize?: number;
+    /** Quality thresholds in ms */
+    thresholds?: {
+        excellent?: number;
+        good?: number;
+        fair?: number;
+    };
+    /** Called when connection quality changes */
+    onQualityChange?: (quality: ConnectionQuality, latency: number) => void;
+}
+declare class ConnectionMonitor {
+    private socket;
+    private options;
+    private logger;
+    private intervalId;
+    private latencySamples;
+    private currentQuality;
+    private lastPingTime;
+    constructor(options: ConnectionMonitorOptions | undefined, logger: Logger);
+    /**
+     * Set the socket instance and start monitoring
+     */
+    setSocket(socket: Socket): void;
+    /**
+     * Start automatic ping monitoring
+     */
+    start(): void;
+    /**
+     * Stop automatic ping monitoring
+     */
+    stop(): void;
+    /**
+     * Perform a single ping and return the latency
+     */
+    ping(): Promise<number>;
+    /**
+     * Record a latency sample and update quality
+     */
+    private recordLatency;
+    /**
+     * Update the current quality and notify listeners
+     */
+    private updateQuality;
+    /**
+     * Calculate quality based on latency thresholds
+     */
+    private calculateQuality;
+    /**
+     * Get average latency from samples
+     */
+    getAverageLatency(): number;
+    /**
+     * Get the last recorded latency
+     */
+    getLatency(): number;
+    /**
+     * Get current connection quality
+     */
+    getQuality(): ConnectionQuality;
+    /**
+     * Get all latency samples
+     */
+    getLatencySamples(): readonly number[];
+    /**
+     * Check if monitoring is active
+     */
+    get isMonitoring(): boolean;
+    /**
+     * Enable or disable monitoring
+     */
+    setEnabled(enabled: boolean): void;
+}
+
+/**
+ * Honeydrop Room Manager
+ * Client-side helpers for room-based event patterns
+ */
+
+interface RoomEmitter {
+    /** Emit an event to the room */
+    emit(event: string, ...args: unknown[]): void;
+}
+interface RoomManagerOptions {
+    /** Event name used to join rooms (default: 'join') */
+    joinEvent?: string;
+    /** Event name used to leave rooms (default: 'leave') */
+    leaveEvent?: string;
+}
+declare class RoomManager {
+    private socket;
+    private options;
+    private logger;
+    private joinedRooms;
+    constructor(options: RoomManagerOptions | undefined, logger: Logger);
+    /**
+     * Set the socket instance
+     */
+    setSocket(socket: Socket): void;
+    /**
+     * Join a room
+     * @param room - Room name to join
+     * @param data - Optional data to send with join request
+     */
+    join(room: string, data?: unknown): void;
+    /**
+     * Leave a room
+     * @param room - Room name to leave
+     * @param data - Optional data to send with leave request
+     */
+    leave(room: string, data?: unknown): void;
+    /**
+     * Create an emitter scoped to a room
+     * Events are emitted with room as first argument
+     * @param room - Target room
+     */
+    toRoom(room: string): RoomEmitter;
+    /**
+     * Get list of currently joined rooms
+     */
+    getRooms(): string[];
+    /**
+     * Check if currently in a room
+     */
+    isInRoom(room: string): boolean;
+    /**
+     * Leave all rooms
+     */
+    leaveAll(): void;
+}
+
+/**
+ * Honeydrop Utility Functions
+ * Helper functions for common Socket.IO operations
+ */
+
+interface EmitItem {
+    event: string;
+    data?: unknown;
+}
+interface EmitWithAckItem extends EmitItem {
+    timeout?: number;
+}
+/**
+ * Emit multiple events at once
+ */
+declare function emitMultiple(socket: Socket, events: EmitItem[]): void;
+/**
+ * Emit multiple events with acknowledgment support
+ */
+declare function emitMultipleWithAck(socket: Socket, events: EmitWithAckItem[]): Promise<unknown[]>;
+/**
+ * Wait for a specific event with optional timeout
+ */
+declare function waitForEvent(socket: Socket, event: string, timeout?: number): Promise<unknown>;
+/**
+ * Wait for any of the specified events
+ */
+declare function waitForAnyEvent(socket: Socket, events: string[], timeout?: number): Promise<{
+    event: string;
+    data: unknown;
+}>;
+/**
+ * Create a promise-based emit with acknowledgment
+ */
+declare function emitWithAck(socket: Socket, event: string, data?: unknown, timeout?: number): Promise<unknown>;
+/**
+ * Check if socket is connected
+ */
+declare function isConnected(socket: Socket | null): boolean;
+/**
+ * Get socket connection info
+ */
+declare function getConnectionInfo(socket: Socket | null): {
+    connected: boolean;
+    id: string | null;
+    transport: string | null;
+};
+/**
+ * Create a throttled emit function
+ */
+declare function createThrottledEmit(socket: Socket, event: string, intervalMs: number): (data?: unknown) => void;
+/**
+ * Create a debounced emit function
+ */
+declare function createDebouncedEmit(socket: Socket, event: string, delayMs: number): (data?: unknown) => void;
+
+/**
+ * Honeydrop - Main Class
+ * The core Socket.IO helper providing easy connection management and event handling
+ */
+
+interface HoneydropOptions {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Log level */
+    logLevel?: LogLevel;
+    /** Reconnection configuration */
+    reconnection?: ReconnectionOptions;
+    /** Offline queue configuration */
+    offlineQueue?: OfflineQueueOptions;
+    /** Connection monitor configuration */
+    connectionMonitor?: ConnectionMonitorOptions;
+    /** Room manager configuration */
+    roomManager?: RoomManagerOptions;
+    /** Default namespace delimiter */
+    namespaceDelimiter?: NamespaceDelimiter;
+    /** Socket.IO client options */
+    socketOptions?: Partial<ManagerOptions & SocketOptions>;
+    /** Auto-connect on instantiation */
+    autoConnect?: boolean;
+}
+declare class Honeydrop {
+    private socket;
+    private url;
+    private options;
+    private logger;
+    private eventManager;
+    private reconnectionHandler;
+    private offlineQueue;
+    private connectionMonitor;
+    private roomManager;
+    private namespaces;
+    constructor(url: string, options?: HoneydropOptions);
+    /**
+     * Connect to the Socket.IO server
+     */
+    connect(): Socket;
+    /**
+     * Disconnect from the server and cleanup all listeners
+     */
+    disconnect(): void;
+    /**
+     * Register an event listener
+     */
+    on(event: string, handler: (...args: unknown[]) => void): this;
+    /**
+     * Register a one-time event listener
+     */
+    once(event: string, handler: (...args: unknown[]) => void): this;
+    /**
+     * Remove event listener(s)
+     */
+    off(event: string, handler?: (...args: unknown[]) => void): this;
+    /**
+     * Emit an event
+     * If disconnected and offline queue is enabled, the event will be queued
+     */
+    emit(event: string, ...args: unknown[]): this;
+    /**
+     * Emit multiple events at once
+     */
+    emitMultiple(events: EmitItem[]): this;
+    /**
+     * Emit with acknowledgment
+     */
+    emitWithAck(event: string, data?: unknown, timeout?: number): Promise<unknown>;
+    /**
+     * Request/Response pattern (RPC-style)
+     * Emits an event and waits for a response event
+     * @param event - Event to emit
+     * @param data - Data to send
+     * @param options - Request options
+     */
+    request<T = unknown>(event: string, data?: unknown, options?: {
+        timeout?: number;
+        responseEvent?: string;
+    }): Promise<T>;
+    /**
+     * Emit with automatic retry on failure
+     * @param event - Event to emit
+     * @param data - Data to send
+     * @param options - Retry options
+     */
+    emitWithRetry(event: string, data?: unknown, options?: {
+        maxRetries?: number;
+        retryDelay?: number;
+        timeout?: number;
+        onRetry?: (attempt: number, error: Error) => void;
+    }): Promise<unknown>;
+    /**
+     * Emit multiple events with acknowledgment
+     */
+    emitMultipleWithAck(events: EmitWithAckItem[]): Promise<unknown[]>;
+    /**
+     * Register handlers for multiple events at once
+     */
+    onMultiple(events: string[], handler: (event: string, ...args: unknown[]) => void): this;
+    /**
+     * Register a handler that fires once when any of the specified events occur
+     */
+    onceAny(events: string[], handler: (event: string, ...args: unknown[]) => void): this;
+    /**
+     * Wait for a specific event
+     */
+    waitFor(event: string, timeout?: number): Promise<unknown>;
+    /**
+     * Wait for any of the specified events
+     */
+    waitForAny(events: string[], timeout?: number): Promise<{
+        event: string;
+        data: unknown;
+    }>;
+    /**
+     * Create a namespaced event emitter
+     */
+    namespace(name: string, options?: NamespaceOptions): NamespacedEvents;
+    /**
+     * Create a throttled emit function for an event
+     */
+    throttle(event: string, intervalMs: number): (data?: unknown) => void;
+    /**
+     * Create a debounced emit function for an event
+     */
+    debounce(event: string, delayMs: number): (data?: unknown) => void;
+    /**
+     * Get the underlying Socket.IO socket instance
+     */
+    getSocket(): Socket | null;
+    /**
+     * Check if connected
+     */
+    get connected(): boolean;
+    /**
+     * Get socket ID
+     */
+    get id(): string | undefined;
+    /**
+     * Get connection info
+     */
+    getConnectionInfo(): {
+        connected: boolean;
+        id: string | null;
+        transport: string | null;
+    };
+    /**
+     * Manually trigger reconnection
+     */
+    reconnect(): void;
+    /**
+     * Get reconnection status
+     */
+    getReconnectionStatus(): {
+        isReconnecting: boolean;
+        attempts: number;
+    } | null;
+    /**
+     * Get event listener count
+     */
+    listenerCount(event: string): number;
+    /**
+     * Get all registered event names
+     */
+    eventNames(): string[];
+    /**
+     * Enable or disable debug logging
+     */
+    setDebug(enabled: boolean): this;
+    /**
+     * Set log level
+     */
+    setLogLevel(level: LogLevel): this;
+    /**
+     * Get the number of queued events (when offline)
+     */
+    getQueueLength(): number;
+    /**
+     * Get all queued events (read-only)
+     */
+    getQueuedEvents(): readonly {
+        event: string;
+        args: unknown[];
+        timestamp: number;
+    }[];
+    /**
+     * Clear the offline queue
+     */
+    clearQueue(): this;
+    /**
+     * Enable or disable offline queueing
+     */
+    setOfflineQueue(enabled: boolean): this;
+    /**
+     * Ping the server and get latency
+     */
+    ping(): Promise<number>;
+    /**
+     * Get average latency to server
+     */
+    getLatency(): number;
+    /**
+     * Get current connection quality
+     */
+    getConnectionQuality(): ConnectionQuality;
+    /**
+     * Enable or disable connection monitoring
+     */
+    setConnectionMonitoring(enabled: boolean): this;
+    /**
+     * Join a room
+     */
+    join(room: string, data?: unknown): this;
+    /**
+     * Leave a room
+     */
+    leave(room: string, data?: unknown): this;
+    /**
+     * Create a room-scoped emitter
+     */
+    toRoom(room: string): RoomEmitter;
+    /**
+     * Get list of joined rooms
+     */
+    getRooms(): string[];
+    /**
+     * Check if in a specific room
+     */
+    isInRoom(room: string): boolean;
+}
+
+/**
+ * Honeydrop Event Manager
+ * Tracks and manages event listeners with auto-cleanup capabilities
+ */
+
+declare class EventManager {
+    private listeners;
+    private socket;
+    private logger;
+    constructor(logger: Logger);
+    /**
+     * Set the socket instance to manage
+     */
+    setSocket(socket: Socket): void;
+    /**
+     * Register an event listener
+     */
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * Register a one-time event listener
+     */
+    once(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * Remove a specific event listener or all listeners for an event
+     */
+    off(event: string, handler?: (...args: unknown[]) => void): void;
+    /**
+     * Register handlers for multiple events at once
+     */
+    onMultiple(events: string[], handler: (event: string, ...args: unknown[]) => void): void;
+    /**
+     * Register a handler that fires once when any of the specified events occur
+     */
+    onceAny(events: string[], handler: (event: string, ...args: unknown[]) => void): void;
+    /**
+     * Get the count of listeners for an event
+     */
+    listenerCount(event: string): number;
+    /**
+     * Get all registered event names
+     */
+    eventNames(): string[];
+    /**
+     * Remove all event listeners (auto-cleanup)
+     */
+    removeAllListeners(): void;
+    /**
+     * Track a listener internally
+     */
+    private addListener;
+    /**
+     * Remove a listener from internal tracking
+     */
+    private removeListener;
+}
+
+/**
+ * Honeydrop - Socket.IO Helper Library
+ * A lightweight, developer-friendly helper for Socket.IO applications
+ */
+
+export { ConnectionMonitor, EventManager, Honeydrop, Logger, NamespacedEvents, OfflineQueue, ReconnectionHandler, RoomManager, createDebouncedEmit, createThrottledEmit, Honeydrop as default, emitMultiple, emitMultipleWithAck, emitWithAck, getConnectionInfo, isConnected, waitForAnyEvent, waitForEvent };
+export type { ConnectionMonitorOptions, ConnectionQuality, EmitItem, EmitWithAckItem, HoneydropOptions, LogLevel, NamespaceDelimiter, NamespaceOptions, NamespacedEmitter, OfflineQueueOptions, QueuedEvent, ReconnectionOptions, ReconnectionStrategy, RoomEmitter, RoomManagerOptions };