dialogue-ts 0.0.1

package/dist/src/index.d.ts

@@ -0,0 +1,664 @@
+import { Hono } from 'hono';
+import { Result } from 'slang-ts';
+import { Socket, Server } from 'socket.io';
+import { z } from 'zod';
+
+/**
+ * Structured log entry for Dialogue logging.
+ */
+interface LogEntry {
+    /** The message describing what happened */
+    message: string;
+    /** The function or location where the log originated */
+    atFunction: string;
+    /** Additional data for context */
+    data: unknown;
+}
+/**
+ * Logger interface for Dialogue.
+ * Implement this interface to provide custom logging behavior.
+ * By default, Dialogue uses a console-based logger.
+ */
+interface Logger {
+    /** Log debug information (verbose, development only) */
+    debug: (entry: LogEntry) => void;
+    /** Log informational messages */
+    info: (entry: LogEntry) => void;
+    /** Log warning messages (non-critical issues) */
+    warn: (entry: LogEntry) => void;
+    /** Log error messages (critical issues) */
+    error: (entry: LogEntry) => void;
+}
+/**
+ * Event definition - defines a named event with optional schema validation.
+ * Events are first-class citizens in Dialogue, not just message payloads.
+ *
+ * @template T - The data type this event carries
+ */
+interface EventDefinition<T = unknown> {
+    readonly name: string;
+    readonly description?: string;
+    readonly schema?: z.ZodType<T>;
+    readonly history?: EventHistoryConfig;
+}
+/**
+ * Configuration for event history storage.
+ * When enabled, events of this type are stored in memory per room.
+ */
+interface EventHistoryConfig {
+    /** Whether to store this event type in history */
+    enabled: boolean;
+    /** Maximum number of events to keep in memory per room */
+    limit: number;
+}
+/**
+ * Room configuration - defines a room's properties and allowed events.
+ * Used when creating rooms in DialogueConfig.
+ */
+interface RoomConfig {
+    name: string;
+    description?: string;
+    /** Max concurrent connections. Undefined means unlimited. */
+    maxSize?: number;
+    /** Events allowed in this room. Empty array means any event allowed. */
+    events: EventDefinition<unknown>[];
+    /** Event names to auto-subscribe clients to on join */
+    defaultSubscriptions?: string[];
+    /** User ID of room creator for ownership tracking */
+    createdById?: string;
+    /** Auto-send history on join. true = all history, number = limit per event type */
+    syncHistoryOnJoin?: boolean | number;
+}
+/**
+ * CORS configuration for Socket.IO server.
+ * Set to true to allow all origins, or specify allowed origins.
+ */
+interface CorsConfig {
+    /** Allowed origins. Use "*" or true for all origins. */
+    origin: string | string[] | boolean;
+    /** Allowed HTTP methods */
+    methods?: string[];
+    /** Whether to allow credentials (cookies, auth headers) */
+    credentials?: boolean;
+}
+/**
+ * JWT claims structure for client authentication.
+ * Standard JWT payload format with extensibility.
+ */
+interface JwtClaims {
+    /** Subject - typically the user ID */
+    sub: string;
+    /** Expiration timestamp (Unix time in seconds) */
+    exp?: number;
+    /** Issued at timestamp (Unix time in seconds) */
+    iat?: number;
+    /** Additional custom claims */
+    [key: string]: unknown;
+}
+/**
+ * Authentication data stored on each client after successful authentication.
+ * Supports JWT-based auth with room for future authentication methods.
+ */
+interface AuthData {
+    /** JWT claims/payload */
+    jwt: JwtClaims;
+    /** Future authentication-related fields can be added here */
+    [key: string]: unknown;
+}
+/**
+ * Result of a successful authentication.
+ * Provides the resolved user identity and metadata.
+ */
+interface AuthenticateResult {
+    /** Resolved application user ID */
+    userId: string;
+    /** Additional metadata (role, permissions, etc.) */
+    meta: Record<string, unknown>;
+}
+/**
+ * Global runtime context representing the current state of the Dialogue server.
+ * Provides awareness of all connected clients, active rooms, and the Socket.IO server.
+ * This context is passed to all hooks alongside case-specific data.
+ */
+interface DialogueContext {
+    /** The Socket.IO server instance */
+    io: Server;
+    /** Map of all connected clients, keyed by client ID */
+    clients: Record<string, ConnectedClient>;
+    /** Map of all active rooms, keyed by room ID */
+    rooms: Record<string, Room>;
+}
+/**
+ * Hooks configuration for lifecycle events.
+ * Use hooks to respond to room, client, and event lifecycle events.
+ *
+ * Hooks prefixed with "before" run before the action and can block it (return Err to deny).
+ * Hooks prefixed with "after" run after the action for side-effects (fire-and-forget).
+ * Hooks prefixed with "on" are legacy notification hooks (fire-and-forget).
+ *
+ * All hooks receive a DialogueContext containing global runtime state (io, clients, rooms)
+ * along with case-specific data relevant to that particular hook.
+ */
+interface HooksConfig {
+    socket?: {
+        /**
+         * Called during Socket.IO handshake before connection is accepted.
+         * Return Ok(authData) with JWT claims to accept, Err("reason") to reject.
+         * The authData will be stored in the client's auth field.
+         */
+        authenticate?: (params: {
+            context: DialogueContext;
+            clientSocket: Socket;
+            authData: unknown;
+        }) => Result<AuthData, string> | Promise<Result<AuthData, string>>;
+        /**
+         * Called when a client socket connects.
+         * Receives the global context and the newly connected client socket.
+         */
+        onConnect?: (params: {
+            context: DialogueContext;
+            clientSocket: Socket;
+        }) => void | Promise<void>;
+        /**
+         * Called when a client socket disconnects.
+         * Receives the global context and the disconnecting client socket.
+         */
+        onDisconnect?: (params: {
+            context: DialogueContext;
+            clientSocket: Socket;
+        }) => void | Promise<void>;
+    };
+    rooms?: {
+        /** Called when a room is created */
+        onCreated?: (room: Room) => void | Promise<void>;
+        /** Called when a room is updated */
+        onUpdated?: (room: Room) => void | Promise<void>;
+        /** Called when a room is deleted */
+        onDeleted?: (roomId: string) => void | Promise<void>;
+    };
+    clients?: {
+        /**
+         * Called synchronously before a client joins a room. Can deny room access.
+         * Return Ok(undefined) to allow, Err("reason") to deny.
+         * When denied, the client receives a dialogue:error with code JOIN_DENIED.
+         * Must be synchronous to preserve real-time performance.
+         */
+        beforeJoin?: (params: {
+            context: DialogueContext;
+            client: ConnectedClient;
+            roomId: string;
+            room: Room;
+        }) => Result<void, string>;
+        /** Called when a client connects */
+        onConnected?: (client: ConnectedClient) => void | Promise<void>;
+        /** Called when a client disconnects */
+        onDisconnected?: (client: ConnectedClient) => void | Promise<void>;
+        /** Called when a client joins a room */
+        onJoined?: (client: ConnectedClient, roomId: string) => void | Promise<void>;
+        /** Called when a client leaves a room */
+        onLeft?: (client: ConnectedClient, roomId: string) => void | Promise<void>;
+    };
+    events?: {
+        /**
+         * Called synchronously before each event is broadcast. Can block or transform events.
+         * Return Ok(message) with the (possibly modified) message to proceed.
+         * Return Err("reason") to block the event from being broadcast.
+         * Must be synchronous to preserve real-time performance.
+         */
+        beforeEach?: (params: {
+            context: DialogueContext;
+            roomId: string;
+            message: EventMessage;
+            from: string;
+        }) => Result<EventMessage, string>;
+        /**
+         * Called synchronously after each event is broadcast. Fire-and-forget for side-effects.
+         * Useful for logging, analytics, metrics, etc.
+         * Must be synchronous to preserve real-time performance.
+         */
+        afterEach?: (params: {
+            context: DialogueContext;
+            roomId: string;
+            message: EventMessage;
+            recipientCount: number;
+        }) => void;
+        /** Called when an event is triggered */
+        onTriggered?: (roomId: string, event: EventMessage) => void | Promise<void>;
+        /** Called when events are evicted from in-memory history (oldest first) */
+        onCleanup?: (roomId: string, eventName: string, events: EventMessage[]) => void | Promise<void>;
+        /** Called to load historical events beyond in-memory (for pagination) */
+        onLoad?: (roomId: string, eventName: string, start: number, end: number) => Promise<EventMessage[]>;
+    };
+}
+/**
+ * Main dialogue configuration - passed to createDialogue.
+ * Defines all rooms and their events upfront for config-first approach.
+ */
+interface DialogueConfig {
+    /** Port to run server on. Optional if using existing app. */
+    port?: number;
+    /** Existing Hono app to attach to. Creates new one if not provided. */
+    app?: Hono;
+    /** Room configurations keyed by room ID */
+    rooms: Record<string, RoomConfig>;
+    /** Lifecycle hooks for rooms, clients, and events */
+    hooks?: HooksConfig;
+    /** Custom logger implementation. Uses default console logger if not provided. */
+    logger?: Logger;
+    /** CORS configuration. Defaults to allowing all origins in development. */
+    cors?: CorsConfig | boolean;
+}
+/**
+ * Message envelope - the shape of all messages sent between clients and server.
+ * Same structure for both directions (incoming and outgoing).
+ *
+ * @template T - The data payload type
+ */
+interface EventMessage<T = unknown> {
+    event: string;
+    roomId: string;
+    data: T;
+    /** User ID of sender */
+    from: string;
+    timestamp: number;
+    /** Optional metadata for flexible additional context */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Room instance - runtime representation of a room with methods.
+ * Manages connections, subscriptions, and event broadcasting.
+ */
+interface Room {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly maxSize?: number;
+    readonly events: EventDefinition<unknown>[];
+    readonly defaultSubscriptions: string[];
+    readonly createdById?: string;
+    /**
+     * Trigger event to all subscribers in this room.
+     * Validates data against schema if event has one.
+     * @returns Result<void, string> - Ok if successful, Err with validation message if failed
+     */
+    trigger<T>(event: EventDefinition<T>, data: T, from?: string, meta?: Record<string, unknown>): Result<void, string>;
+    /**
+     * Subscribe to events in this room with a callback.
+     * For backend side-effects like logging, persistence, notifications.
+     * @returns Unsubscribe function
+     */
+    on<T>(event: EventDefinition<T>, handler: (msg: EventMessage<T>) => void | Promise<void>): () => void;
+    /** Current connection count */
+    size(): number;
+    /** Check if room is at maxSize capacity */
+    isFull(): boolean;
+    /** Get all participants in this room */
+    participants(): ConnectedClient[];
+    /**
+     * Get historical events for this room (paginated, newest first).
+     * @param eventName - Event type to get history for
+     * @param start - Starting index (0 = most recent)
+     * @param end - Ending index (exclusive)
+     * @returns Events from start to end, empty array if event has no history
+     */
+    history(eventName: string, start: number, end: number): Promise<EventMessage[]>;
+}
+/**
+ * Connected client - represents a connected socket with user context.
+ * Provides methods for room management and event subscriptions.
+ */
+interface ConnectedClient {
+    /** Unique client/session ID */
+    readonly id: string;
+    /** Application user ID from auth */
+    readonly userId: string;
+    /** Underlying Socket.IO socket */
+    readonly socket: Socket;
+    /** Additional user metadata (role, permissions, etc.) */
+    readonly meta: Record<string, unknown>;
+    /** Authentication data (JWT claims and related info) */
+    readonly auth?: AuthData;
+    /** Join a room by ID */
+    join(roomId: string): void;
+    /** Leave a room by ID */
+    leave(roomId: string): void;
+    /** Subscribe to specific event in a room */
+    subscribe(roomId: string, eventName: string): void;
+    /** Subscribe to all events in a room (wildcard) */
+    subscribeAll(roomId: string): void;
+    /** Unsubscribe from event in a room */
+    unsubscribe(roomId: string, eventName: string): void;
+    /** Get list of room IDs this client is in */
+    rooms(): string[];
+    /** Get subscribed event names for a room */
+    subscriptions(roomId: string): string[];
+    /** Send data directly to this client only */
+    send<T>(event: string, data: T): void;
+    /** Disconnect this client */
+    disconnect(): void;
+}
+/**
+ * Represents a user's rooms with helper methods.
+ * Returned by dialogue.getClientRooms() for managing user room membership.
+ */
+interface ClientRooms {
+    /** Array of room IDs the user is currently in */
+    readonly ids: string[];
+    /**
+     * Execute a callback for each room the user is in.
+     * Does not modify room membership - use for broadcasting, logging, etc.
+     * @param callback - Function called for each room
+     */
+    forAll(callback: (roomId: string) => void): void;
+    /**
+     * Remove the user from all rooms.
+     * Optionally execute a callback for each room before leaving.
+     * @param callback - Optional function called for each room before leaving
+     */
+    leaveAll(callback?: (roomId: string) => void): void;
+}
+/**
+ * Main Dialogue instance - the core API returned by createDialogue.
+ * Use this to trigger events, subscribe to events, and manage rooms.
+ */
+interface Dialogue {
+    /** The Hono app instance (provided or created) */
+    readonly app: Hono;
+    /** The Socket.IO server instance */
+    readonly io: Server;
+    /**
+     * Trigger event to all subscribers in a room.
+     * Call this from anywhere in your backend (API routes, jobs, webhooks).
+     * @returns Result<void, string> - Ok if successful, Err with validation message if failed
+     */
+    trigger<T>(roomId: string, event: EventDefinition<T>, data: T, from?: string, meta?: Record<string, unknown>): Result<void, string>;
+    /**
+     * Subscribe with callback for backend side-effects.
+     * Useful for logging, persistence, triggering other events.
+     * @returns Unsubscribe function
+     */
+    on<T>(roomId: string, event: EventDefinition<T>, handler: (msg: EventMessage<T>) => void | Promise<void>): () => void;
+    /** Get room by ID */
+    room(id: string): Room | null;
+    /** Get all rooms */
+    rooms(): Room[];
+    /**
+     * Create a new room at runtime
+     * @param id - Unique room identifier
+     * @param config - Room configuration
+     * @returns The created Room instance, or null if room already exists
+     */
+    createRoom(id: string, config: RoomConfig): Room | null;
+    /**
+     * Delete a room at runtime
+     * @param id - Room ID to delete
+     * @returns true if room was deleted, false if it didn't exist
+     */
+    deleteRoom(id: string): boolean;
+    /**
+     * Get a connected client by user ID.
+     * Returns array since a user may have multiple connections (tabs/devices).
+     * @param userId - The user ID to look up
+     * @returns Array of connected clients for this user
+     */
+    getClients(userId: string): ConnectedClient[];
+    /**
+     * Get all connected clients
+     * @returns Array of all connected clients
+     */
+    getAllClients(): ConnectedClient[];
+    /**
+     * Get rooms that a user is currently in with helper methods.
+     * Aggregates rooms across all connections for this user.
+     * @param userId - The user ID to look up
+     * @returns ClientRooms object with room IDs and utility methods
+     */
+    getClientRooms(userId: string): ClientRooms;
+    /**
+     * Check if a user is in a specific room
+     * @param userId - The user ID to check
+     * @param roomId - The room ID to check
+     * @returns true if the user is in the room
+     */
+    isInRoom(userId: string, roomId: string): boolean;
+    /** Start the server */
+    start(): Promise<void>;
+    /** Stop the server */
+    stop(): Promise<void>;
+}
+/**
+ * Internal room manager interface - used internally to coordinate rooms.
+ */
+interface RoomManager {
+    get(id: string): Room | null;
+    all(): Room[];
+    addParticipant(roomId: string, client: ConnectedClient): boolean;
+    removeParticipant(roomId: string, clientId: string): void;
+}
+
+/**
+ * Creates a Dialogue instance from configuration.
+ * This is the main entry point for the library.
+ *
+ * @param config - Dialogue configuration with rooms, events, and handlers
+ * @returns Dialogue instance for triggering events, subscribing, and server control
+ *
+ * @example
+ * // Basic setup with rooms defined upfront
+ * const dialogue = createDialogue({
+ *   port: 3000,
+ *   rooms: {
+ *     chat: {
+ *       name: 'Chat Room',
+ *       events: [Message, Typing],
+ *       defaultSubscriptions: ['message'],
+ *       syncHistoryOnJoin: true,
+ *     }
+ *   },
+ *   hooks: {
+ *     clients: {
+ *       onConnected: (client) => {
+ *         client.join('chat')
+ *       },
+ *       onDisconnected: (client) => {
+ *         console.log('Client disconnected:', client.userId)
+ *       }
+ *     },
+ *     events: {
+ *       onCleanup: async (roomId, eventName, events) => {
+ *         await db.events.insertMany(events)
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * // Use elsewhere in your app
+ * dialogue.trigger('chat', Message, { text: 'Hello!' })
+ *
+ * // Start the server
+ * await dialogue.start()
+ */
+declare function createDialogue(config: DialogueConfig): Dialogue;
+
+/**
+ * Options for defining an event
+ */
+interface DefineEventOptions<T> {
+    /** Zod schema for validating event data */
+    schema?: z.ZodType<T>;
+    /** Human-readable description of the event */
+    description?: string;
+    /** History configuration - when enabled, events are stored in memory */
+    history?: EventHistoryConfig;
+}
+/**
+ * Creates a typed event definition for use in rooms.
+ * Events are immutable once created.
+ *
+ * @param name - Unique event name (e.g., 'message', 'order:updated')
+ * @param options - Optional schema and description
+ * @returns Frozen event definition object
+ *
+ * @example
+ * // Simple event without validation
+ * const Typing = defineEvent('typing')
+ *
+ * @example
+ * // Event with Zod schema validation
+ * const Message = defineEvent('message', {
+ *   schema: z.object({
+ *     text: z.string().min(1).max(1000),
+ *     senderId: z.string()
+ *   }),
+ *   description: 'Chat message sent by a user',
+ *   history: { enabled: true, limit: 50 }
+ * })
+ *
+ * @example
+ * // Event with inferred type from schema
+ * const OrderUpdated = defineEvent('order:updated', {
+ *   schema: z.object({
+ *     orderId: z.string(),
+ *     status: z.enum(['pending', 'shipped', 'delivered'])
+ *   })
+ * })
+ * // Type of data is inferred as { orderId: string, status: 'pending' | 'shipped' | 'delivered' }
+ */
+declare function defineEvent<T = unknown>(name: string, options?: DefineEventOptions<T>): EventDefinition<T>;
+/**
+ * Validates event data against its schema if one exists.
+ * Returns a Result with either parsed data or error message.
+ *
+ * @param event - The event definition with optional schema
+ * @param data - Data to validate
+ * @returns Result<T, string> - Ok with data or Err with validation message
+ */
+declare function validateEventData<T>(event: EventDefinition<T>, data: unknown): Result<T, string>;
+/**
+ * Checks if an event is allowed in a room based on its event definitions.
+ * - Empty array: No events allowed (reject all)
+ * - Wildcard "*": All events allowed (accept all)
+ * - Specific events: Only listed events allowed
+ *
+ * @param eventName - Name of the event to check
+ * @param allowedEvents - List of allowed events for the room
+ * @returns True if event is allowed (explicit match or wildcard)
+ */
+declare function isEventAllowed(eventName: string, allowedEvents: EventDefinition<unknown>[]): boolean;
+/**
+ * Gets an event definition by name from a list of events.
+ *
+ * @param eventName - Name of the event to find
+ * @param events - List of event definitions to search
+ * @returns The event definition or undefined if not found
+ */
+declare function getEventByName(eventName: string, events: EventDefinition<unknown>[]): EventDefinition<unknown> | undefined;
+
+/**
+ * Configuration for the history manager
+ */
+interface HistoryManagerConfig {
+    /** Called when events are evicted from in-memory history (oldest first) */
+    onCleanup?: (roomId: string, eventName: string, events: EventMessage[]) => void | Promise<void>;
+    /** Called to load historical events beyond in-memory (for pagination) */
+    onLoad?: (roomId: string, eventName: string, start: number, end: number) => Promise<EventMessage[]>;
+}
+/**
+ * History manager instance returned by createHistoryManager
+ */
+interface HistoryManager {
+    /** Add an event to history, evict oldest if exceeds limit */
+    push(roomId: string, eventName: string, event: EventMessage, limit: number): void;
+    /** Get events (0 = newest, reads backward) */
+    get(roomId: string, eventName: string, start: number, end: number): EventMessage[];
+    /** Get all events for a room across all event types, sorted newest first */
+    getAll(roomId: string, limit?: number): EventMessage[];
+    /** Get total count of events for a specific event type in a room */
+    count(roomId: string, eventName: string): number;
+    /** Clear all history for a room */
+    clearRoom(roomId: string): void;
+    /** Get event names that have history for a room */
+    getEventNames(roomId: string): string[];
+}
+/**
+ * Creates a history manager for storing events in memory.
+ * Stores per-room, per-event-type with FIFO eviction (oldest first).
+ *
+ * @param config - Configuration with optional cleanup and load callbacks
+ * @returns HistoryManager instance
+ *
+ * @example
+ * const history = createHistoryManager({
+ *   onCleanup: async (roomId, eventName, events) => {
+ *     await db.events.insertMany(events);
+ *   }
+ * });
+ *
+ * // Push an event
+ * history.push("room-1", "message", eventMessage, 50);
+ *
+ * // Get last 10 messages (newest first)
+ * const recent = history.get("room-1", "message", 0, 10);
+ */
+declare function createHistoryManager(config?: HistoryManagerConfig): HistoryManager;
+
+/**
+ * Creates the default console-based logger for Dialogue.
+ * Outputs structured log entries as JSON-like objects.
+ *
+ * @returns Logger implementation using console methods
+ */
+declare function createDefaultLogger(): Logger;
+/**
+ * Creates a silent logger that does not output anything.
+ * Useful for testing or when logging is not desired.
+ *
+ * @returns Logger implementation that does nothing
+ */
+declare function createSilentLogger(): Logger;
+
+/**
+ * Rate limiter configuration
+ */
+interface RateLimiterConfig {
+    /** Maximum number of requests allowed in the window */
+    maxRequests: number;
+    /** Time window in milliseconds */
+    windowMs: number;
+}
+/**
+ * Rate limiter instance returned by createRateLimiter
+ */
+interface RateLimiter {
+    /**
+     * Check if a request is allowed for the given key.
+     * Returns true if allowed, false if rate limited.
+     */
+    isAllowed(key: string): boolean;
+    /**
+     * Get remaining requests for the given key
+     */
+    remaining(key: string): number;
+    /**
+     * Clear all rate limit data (useful for testing)
+     */
+    clear(): void;
+}
+/**
+ * Creates a simple in-memory rate limiter using sliding window algorithm.
+ * Tracks requests per key (typically socket ID or user ID) and enforces limits.
+ *
+ * @param config - Rate limiter configuration
+ * @returns RateLimiter instance
+ *
+ * @example
+ * const limiter = createRateLimiter({ maxRequests: 10, windowMs: 60000 });
+ *
+ * if (!limiter.isAllowed(socketId)) {
+ *   socket.emit("dialogue:error", { code: "RATE_LIMITED" });
+ *   return;
+ * }
+ */
+declare function createRateLimiter(config: RateLimiterConfig): RateLimiter;
+
+export { type AuthData, type AuthenticateResult, type ConnectedClient, type CorsConfig, type Dialogue, type DialogueConfig, type DialogueContext, type EventDefinition, type EventHistoryConfig, type EventMessage, type HistoryManager, type HistoryManagerConfig, type HooksConfig, type JwtClaims, type LogEntry, type Logger, type RateLimiter, type RateLimiterConfig, type Room, type RoomConfig, type RoomManager, createDefaultLogger, createDialogue, createHistoryManager, createRateLimiter, createSilentLogger, defineEvent, getEventByName, isEventAllowed, validateEventData };