@mesh-kit/server 2.0.0 → 2.0.1

package/dist/index.d.mts

@@ -0,0 +1,1129 @@
+import { ServerOptions, WebSocket, WebSocketServer } from 'ws';
+export { ServerOptions } from 'ws';
+import { LogLevel, Status, Command } from '@mesh-kit/shared';
+import { EventEmitter } from 'node:events';
+import { IncomingMessage } from 'node:http';
+import Redis, { RedisOptions, Redis as Redis$1 } from 'ioredis';
+import { Operation } from 'fast-json-patch';
+import { EventEmitter as EventEmitter$1 } from 'events';
+
+declare class Latency {
+    start: number;
+    end: number;
+    ms: number;
+    interval?: ReturnType<typeof setTimeout>;
+    onRequest(): void;
+    onResponse(): void;
+}
+
+declare class Ping {
+    interval?: ReturnType<typeof setTimeout>;
+}
+
+declare class MeshContext<T = any> {
+    server: MeshServer;
+    command: string;
+    connection: Connection;
+    payload: T;
+    constructor(server: MeshServer, command: string, connection: Connection, payload: T);
+}
+
+interface PersistenceAdapter {
+    initialize(): Promise<void>;
+    storeMessages(messages: PersistedMessage[]): Promise<void>;
+    getMessages(channel: string, since?: string | number, limit?: number): Promise<PersistedMessage[]>;
+    storeRecords?(records: PersistedRecord[]): Promise<void>;
+    getRecords?(pattern: string): Promise<PersistedRecord[]>;
+    close(): Promise<void>;
+}
+interface PersistedMessage {
+    id: string;
+    channel: string;
+    message: string;
+    instanceId: string;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}
+interface ChannelPersistenceOptions {
+    /**
+     * Maximum number of messages to retain per channel
+     * @default 50
+     */
+    historyLimit?: number;
+    /**
+     * Function to filter messages for persistence
+     * Return false to skip persistence for a specific message
+     */
+    filter?: (message: string, channel: string) => boolean;
+    /**
+     * Optional adapter override for this pattern
+     */
+    adapter?: PersistenceAdapter;
+    /**
+     * How often (in ms) to flush buffered messages to the database
+     * @default 500
+     */
+    flushInterval?: number;
+    /**
+     * Maximum number of messages to hold in memory per channel
+     * If this limit is reached, the buffer is flushed immediately
+     * @default 100
+     */
+    maxBufferSize?: number;
+}
+interface RecordPersistenceOptions {
+    /**
+     * Optional adapter override for this pattern
+     */
+    adapter?: PersistenceAdapter;
+    /**
+     * How often (in ms) to flush buffered records to the database
+     * @default 500
+     */
+    flushInterval?: number;
+    /**
+     * Maximum number of records to hold in memory before flushing
+     * If this limit is reached, the buffer is flushed immediately
+     * @default 100
+     */
+    maxBufferSize?: number;
+}
+interface PersistedRecord {
+    recordId: string;
+    version: number;
+    value: string;
+    timestamp: number;
+}
+interface PersistenceAdapterOptions {
+    /**
+     * Database file path for file-based adapters
+     * @default ":memory:"
+     */
+    filename?: string;
+}
+interface PostgreSQLAdapterOptions extends PersistenceAdapterOptions {
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    user?: string;
+    password?: string;
+    ssl?: boolean;
+    max?: number;
+}
+
+type SocketMiddleware = (context: MeshContext<any>) => any | Promise<any>;
+interface MeshServerOptions extends ServerOptions {
+    /**
+     * The interval at which to send ping messages to the client.
+     *
+     * @default 30000
+     */
+    pingInterval?: number;
+    /**
+     * The interval at which to send both latency requests and updates to the client.
+     *
+     * @default 5000
+     */
+    latencyInterval?: number;
+    redisOptions: RedisOptions;
+    /**
+     * Whether to enable Redis keyspace notifications for presence expiration.
+     * When enabled, connections will be automatically marked as offline when their presence TTL expires.
+     *
+     * @default true
+     */
+    enablePresenceExpirationEvents?: boolean;
+    /**
+     * The maximum number of consecutive ping intervals the server will wait
+     * for a pong response before considering the client disconnected.
+     * A value of 1 means the client must respond within roughly 2 * pingInterval
+     * before being disconnected. Setting it to 0 is not recommended as it will
+     * immediately disconnect the client if it doesn't respond to the first ping in
+     * exactly `pingInterval` milliseconds, which doesn't provide wiggle room for
+     * network latency.
+     *
+     * @see pingInterval
+     * @default 1
+     */
+    maxMissedPongs?: number;
+    /**
+     * The log level for server-side logs.
+     * Controls which messages are displayed in the console.
+     *
+     * @default LogLevel.ERROR
+     */
+    logLevel?: LogLevel;
+    /**
+     * Options for the persistence layer.
+     * By default, persistence uses an in-memory SQLite database.
+     * To persist data across restarts, specify a file path.
+     *
+     * @example
+     * ```
+     * persistenceOptions: {
+     *   filename: "./data/channels.db"
+     * }
+     * ```
+     */
+    persistenceOptions?: PersistenceAdapterOptions | PostgreSQLAdapterOptions;
+    /**
+     * Adapter type for persistence layer.
+     * @default "sqlite"
+     */
+    persistenceAdapter?: "sqlite" | "postgres";
+}
+type ChannelPattern$1 = string | RegExp;
+
+declare class Connection extends EventEmitter {
+    id: string;
+    socket: WebSocket;
+    alive: boolean;
+    missedPongs: number;
+    latency: Latency;
+    ping: Ping;
+    remoteAddress: string;
+    connectionOptions: MeshServerOptions;
+    status: Status;
+    server: MeshServer;
+    constructor(socket: WebSocket, req: IncomingMessage, options: MeshServerOptions, server: MeshServer);
+    get isDead(): boolean;
+    private startIntervals;
+    stopIntervals(): void;
+    private applyListeners;
+    send(cmd: Command): boolean;
+    close(): Promise<boolean>;
+}
+
+declare class RoomManager {
+    private redis;
+    constructor(options: {
+        redis: Redis;
+    });
+    private roomKey;
+    private connectionsRoomKey;
+    private roomMetadataKey;
+    /**
+     * Retrieves all connection IDs associated with the specified room.
+     *
+     * @param {string} roomName - The name of the room for which to fetch connection IDs.
+     * @returns {Promise<string[]>} A promise that resolves to an array of connection IDs in the room.
+     * @throws {Error} If there is an issue communicating with Redis or retrieving the data, the promise will be rejected with an error.
+     */
+    getRoomConnectionIds(roomName: string): Promise<string[]>;
+    /**
+     * Checks whether a given connection (by object or ID) is a member of a specified room.
+     *
+     * @param {string} roomName - The name of the room to check for membership.
+     * @param {Connection | string} connection - The connection object or connection ID to check.
+     * @returns {Promise<boolean>} A promise that resolves to true if the connection is in the room, false otherwise.
+     * @throws {Error} If there is an issue communicating with Redis or processing the request, the promise may be rejected with an error.
+     */
+    connectionIsInRoom(roomName: string, connection: Connection | string): Promise<boolean>;
+    /**
+     * Adds a connection to a specified room, associating the connection ID with the room name
+     * in Redis. Supports both `Connection` objects and connection IDs as strings.
+     *
+     * @param {string} roomName - The name of the room to add the connection to.
+     * @param {Connection | string} connection - The connection object or connection ID to add to the room.
+     * @returns {Promise<void>} A promise that resolves when the operation is complete.
+     * @throws {Error} If an error occurs while updating Redis, the promise will be rejected with the error.
+     */
+    addToRoom(roomName: string, connection: Connection | string): Promise<void>;
+    /**
+     * Retrieves a list of rooms that the specified connection is currently a member of.
+     *
+     * @param {Connection | string} connection - The connection object or connection ID for which to retrieve room memberships.
+     * @returns {Promise<string[]>} A promise that resolves to an array of room names associated with the connection.
+     * @throws {Error} If the underlying Redis operation fails, the promise will be rejected with an error.
+     */
+    getRoomsForConnection(connection: Connection | string): Promise<string[]>;
+    /**
+     * Retrieves all room names from Redis.
+     *
+     * @returns {Promise<string[]>} A promise that resolves to an array of all room names.
+     * @throws {Error} If there is an issue communicating with Redis, the promise will be rejected with an error.
+     */
+    getAllRooms(): Promise<string[]>;
+    /**
+     * Removes a connection from a specified room and updates Redis accordingly.
+     * Accepts either a Connection object or a string representing the connection ID.
+     * Updates both the room's set of connections and the connection's set of rooms in Redis.
+     *
+     * @param {string} roomName - The name of the room from which to remove the connection.
+     * @param {Connection | string} connection - The connection to be removed, specified as either a Connection object or a connection ID string.
+     * @returns {Promise<void>} A promise that resolves when the removal is complete.
+     * @throws {Error} If there is an error executing the Redis pipeline, the promise will be rejected with the error.
+     */
+    removeFromRoom(roomName: string, connection: Connection | string): Promise<void>;
+    /**
+     * Removes the specified connection from all rooms it is a member of and deletes its room membership record.
+     *
+     * @param {Connection | string} connection - The connection object or its unique identifier to be removed from all rooms.
+     * @returns {Promise<void>} A promise that resolves once the removal from all rooms is complete.
+     * @throws {Error} If an error occurs during Redis operations, the promise will be rejected with the error.
+     */
+    removeFromAllRooms(connection: Connection | string): Promise<void>;
+    /**
+     * Removes all connections from the specified room but preserves room metadata.
+     * This clears the room occupants without destroying the room's configuration.
+     *
+     * @param {string} roomName - The name of the room to be cleared of occupants.
+     * @returns {Promise<void>} A promise that resolves when all occupants have been removed from the room.
+     * @throws {Error} If an error occurs while interacting with Redis, the promise will be rejected with the error.
+     */
+    clearRoom(roomName: string): Promise<void>;
+    /**
+     * Completely deletes the specified room, removing all occupants and destroying
+     * all associated room metadata. This permanently removes the room from the system.
+     *
+     * @param {string} roomName - The name of the room to be completely deleted.
+     * @returns {Promise<void>} A promise that resolves when the room has been completely deleted.
+     * @throws {Error} If an error occurs while interacting with Redis, the promise will be rejected with the error.
+     */
+    deleteRoom(roomName: string): Promise<void>;
+    /**
+     * Cleans up all Redis references for a given connection by removing the connection
+     * from all rooms it is associated with and deleting the connection's room key.
+     *
+     * @param {Connection} connection - The connection object whose references should be cleaned up.
+     * @returns {Promise<void>} A promise that resolves when the cleanup is complete.
+     * @throws {Error} If an error occurs while interacting with Redis, the promise will be rejected with the error.
+     */
+    cleanupConnection(connection: Connection): Promise<void>;
+    /**
+     * Sets the metadata for a given room by storing the serialized metadata
+     * object in Redis under the room's metadata key.
+     *
+     * @param {string} roomName - The unique name of the room whose metadata is being set.
+     * @param {any} metadata - The metadata object to associate with the room, or partial metadata when using merge strategy.
+     * @param {{ strategy?: "replace" | "merge" | "deepMerge" }} [options] - Update options: strategy defaults to "replace" which replaces the entire metadata, "merge" merges with existing metadata properties, "deepMerge" recursively merges nested objects.
+     * @returns {Promise<void>} A promise that resolves when the metadata has been successfully set.
+     * @throws {Error} If an error occurs while storing metadata in Redis, the promise will be rejected with the error.
+     */
+    setMetadata(roomName: string, metadata: any, options?: {
+        strategy?: "replace" | "merge" | "deepMerge";
+    }): Promise<void>;
+    /**
+     * Retrieves and parses metadata associated with the specified room from Redis storage.
+     *
+     * @param {string} roomName - The name of the room whose metadata is to be retrieved.
+     * @returns {Promise<any | null>} A promise that resolves to the parsed metadata object if found,
+     * or null if no metadata exists for the given room.
+     * @throws {SyntaxError} If the retrieved data is not valid JSON and cannot be parsed.
+     * @throws {Error} If there is an issue communicating with Redis.
+     */
+    getMetadata(roomName: string): Promise<any | null>;
+    /**
+     * Retrieves and returns all room metadata stored in Redis.
+     * Fetches all keys matching the pattern "mesh:roommeta:*", retrieves their "data" fields,
+     * parses them as JSON, and returns an array of room objects with id and metadata.
+     *
+     * @returns {Promise<Array<{ id: string, metadata: any }>>} A promise that resolves to an array of room objects.
+     * @throws {SyntaxError} If the stored metadata cannot be parsed as JSON, an error is logged and the room is omitted from the result.
+     */
+    getAllMetadata(): Promise<Array<{
+        id: string;
+        metadata: any;
+    }>>;
+}
+
+declare class ConnectionManager {
+    private redis;
+    private instanceId;
+    private localConnections;
+    private roomManager;
+    constructor(options: {
+        redis: Redis;
+        instanceId: string;
+        roomManager: RoomManager;
+    });
+    getLocalConnections(): Connection[];
+    getLocalConnection(id: string): Connection | null;
+    registerConnection(connection: Connection): Promise<void>;
+    private getInstanceConnectionsKey;
+    private deregisterConnection;
+    private getInstanceIdForConnection;
+    getInstanceIdsForConnections(connectionIds: string[]): Promise<{
+        [connectionId: string]: string | null;
+    }>;
+    getAllConnectionIds(): Promise<string[]>;
+    getLocalConnectionIds(): Promise<string[]>;
+    /**
+     * Sets metadata for a given connection in the Redis hash.
+     * Serializes the metadata as a JSON string and stores it under the connection's ID.
+     *
+     * @param {Connection} connection - The connection object whose metadata is being set.
+     * @param {any} metadata - The metadata to associate with the connection, or partial metadata when using merge strategy.
+     * @param {{ strategy?: "replace" | "merge" | "deepMerge" }} [options] - Update options: strategy defaults to "replace" which replaces the entire metadata, "merge" merges with existing metadata properties, "deepMerge" recursively merges nested objects.
+     * @returns {Promise<void>} A promise that resolves when the metadata has been successfully set.
+     * @throws {Error} If an error occurs while executing the Redis pipeline.
+     */
+    setMetadata(connection: Connection, metadata: any, options?: {
+        strategy?: "replace" | "merge" | "deepMerge";
+    }): Promise<void>;
+    /**
+     * Retrieves and parses metadata for the given connection from Redis.
+     *
+     * @param {Connection} connection - The connection object whose metadata is to be retrieved.
+     * @returns {Promise<any|null>} A promise that resolves to the parsed metadata object if found, or null if no metadata exists.
+     * @throws {SyntaxError} If the stored metadata is not valid JSON and fails to parse.
+     * @throws {Error} If a Redis error occurs during retrieval.
+     */
+    getMetadata(connection: Connection): Promise<any | null>;
+    /**
+     * Retrieves metadata for all available connections by fetching all connection IDs,
+     * obtaining their associated metadata, and parsing the metadata as JSON.
+     *
+     * @returns {Promise<Array<{ id: string, metadata: any }>>}
+     *   A promise that resolves to an array of connection objects with id and metadata properties.
+     * @throws {Error} If an error occurs while fetching connection IDs, retrieving metadata, or parsing JSON.
+     */
+    getAllMetadata(): Promise<Array<{
+        id: string;
+        metadata: any;
+    }>>;
+    /**
+     * Retrieves all metadata objects for each connection in the specified room.
+     * Returns an array of connection objects with id and metadata properties.
+     * If no metadata is found for a connection, the metadata value is set to null.
+     *
+     * @param {string} roomName - The name of the room for which to retrieve connection metadata.
+     * @returns {Promise<Array<{ id: string, metadata: any }>>} A promise that resolves to an array of
+     * connection objects with id and metadata properties (metadata is null if not available).
+     * @throws {Error} If there is an error retrieving connection IDs or metadata, the promise will be rejected with the error.
+     */
+    getAllMetadataForRoom(roomName: string): Promise<Array<{
+        id: string;
+        metadata: any;
+    }>>;
+    cleanupConnection(connection: Connection): Promise<void>;
+}
+
+declare class RedisManager {
+    private _redis;
+    private _pubClient;
+    private _subClient;
+    private _isShuttingDown;
+    /**
+     * Initializes Redis connections with the provided options
+     *
+     * @param options - Redis connection options
+     * @param onError - Error handler callback
+     */
+    initialize(options: RedisOptions, onError: (err: Error) => void): void;
+    /**
+     * Gets the main Redis client
+     *
+     * @returns The Redis client
+     * @throws Error if Redis is not initialized
+     */
+    get redis(): Redis$1;
+    /**
+     * Gets the Redis client for publishing
+     *
+     * @returns The publishing Redis client
+     * @throws Error if Redis is not initialized
+     */
+    get pubClient(): Redis$1;
+    /**
+     * Gets the Redis client for subscribing
+     *
+     * @returns The subscribing Redis client
+     * @throws Error if Redis is not initialized
+     */
+    get subClient(): Redis$1;
+    /**
+     * Disconnects all Redis clients
+     */
+    disconnect(): void;
+    /**
+     * Checks if Redis is shutting down
+     *
+     * @returns true if Redis is shutting down, false otherwise
+     */
+    get isShuttingDown(): boolean;
+    /**
+     * Sets the shutting down state
+     *
+     * @param value - The new shutting down state
+     */
+    set isShuttingDown(value: boolean);
+    /**
+     * Enables Redis keyspace notifications for expired events by updating the
+     * "notify-keyspace-events" configuration. Ensures that both keyevent ('E')
+     * and expired event ('x') notifications are enabled. If they are not already
+     * present, the method appends them to the current configuration.
+     *
+     * @returns {Promise<void>} A promise that resolves when the configuration has been updated.
+     * @throws {Error} If the Redis CONFIG commands fail or the connection encounters an error.
+     */
+    enableKeyspaceNotifications(): Promise<void>;
+}
+
+type ChannelPattern = string | RegExp;
+declare class PresenceManager {
+    private redis;
+    private roomManager;
+    private redisManager;
+    private presenceExpirationEventsEnabled;
+    private getExpiredEventsPattern;
+    private readonly PRESENCE_KEY_PATTERN;
+    private readonly PRESENCE_STATE_KEY_PATTERN;
+    private trackedRooms;
+    private roomGuards;
+    private roomTTLs;
+    private defaultTTL;
+    constructor(options: {
+        redis: Redis$1;
+        roomManager: RoomManager;
+        redisManager: RedisManager;
+        enableExpirationEvents?: boolean;
+    });
+    /**
+     * Subscribes to Redis keyspace notifications for expired presence keys
+     */
+    private subscribeToExpirationEvents;
+    /**
+     * Handles an expired key notification
+     */
+    private handleExpiredKey;
+    trackRoom(roomPattern: ChannelPattern, guardOrOptions?: ((connection: Connection, roomName: string) => Promise<boolean> | boolean) | {
+        ttl?: number;
+        guard?: (connection: Connection, roomName: string) => Promise<boolean> | boolean;
+    }): void;
+    isRoomTracked(roomName: string, connection?: Connection): Promise<boolean>;
+    getRoomTTL(roomName: string): number;
+    private presenceRoomKey;
+    private presenceConnectionKey;
+    private presenceStateKey;
+    markOnline(connectionId: string, roomName: string): Promise<void>;
+    markOffline(connectionId: string, roomName: string): Promise<void>;
+    refreshPresence(connectionId: string, roomName: string): Promise<void>;
+    getPresentConnections(roomName: string): Promise<string[]>;
+    private publishPresenceUpdate;
+    /**
+     * Publishes a presence state for a connection in a room
+     *
+     * @param connectionId The ID of the connection
+     * @param roomName The name of the room
+     * @param state The state object to publish
+     * @param expireAfter Optional TTL in milliseconds
+     */
+    publishPresenceState(connectionId: string, roomName: string, state: Record<string, any>, expireAfter?: number, silent?: boolean): Promise<void>;
+    /**
+     * Clears the presence state for a connection in a room
+     *
+     * @param connectionId The ID of the connection
+     * @param roomName The name of the room
+     */
+    clearPresenceState(connectionId: string, roomName: string): Promise<void>;
+    /**
+     * Gets the current presence state for a connection in a room
+     *
+     * @param connectionId The ID of the connection
+     * @param roomName The name of the room
+     * @returns The presence state or null if not found
+     */
+    getPresenceState(connectionId: string, roomName: string): Promise<Record<string, any> | null>;
+    /**
+     * Gets all presence states for a room
+     *
+     * @param roomName The name of the room
+     * @returns A map of connection IDs to their presence states
+     */
+    getAllPresenceStates(roomName: string): Promise<Map<string, Record<string, any>>>;
+    /**
+     * Publishes a presence state update to Redis
+     *
+     * @param roomName The name of the room
+     * @param connectionId The ID of the connection
+     * @param state The state object or null
+     */
+    private publishPresenceStateUpdate;
+    cleanupConnection(connection: Connection): Promise<void>;
+    /**
+     * Cleans up Redis subscriptions when the PresenceManager is being destroyed.
+     */
+    cleanup(): Promise<void>;
+}
+
+declare class RecordManager {
+    private redis;
+    private recordUpdateCallbacks;
+    private recordRemovedCallbacks;
+    private server;
+    constructor(options: {
+        redis: Redis$1;
+        server: MeshServer;
+    });
+    /**
+     * Gets the server instance associated with this record manager
+     */
+    getServer(): MeshServer;
+    /**
+     * Gets the Redis instance used by this record manager
+     * This is used by the persistence manager to restore records
+     */
+    getRedis(): Redis$1;
+    recordKey(recordId: string): string;
+    recordVersionKey(recordId: string): string;
+    /**
+     * Retrieves a record from Redis by its unique identifier. Attempts to parse
+     * the stored data as JSON before returning. If the record does not exist,
+     * returns null.
+     *
+     * @param {string} recordId - The unique identifier of the record to retrieve.
+     * @returns {Promise<any | null>} A promise that resolves to the parsed record object,
+     * or null if the record does not exist.
+     * @throws {SyntaxError} If the stored data is not valid JSON and cannot be parsed.
+     * @throws {Error} If an error occurs during the Redis operation.
+     */
+    getRecord(recordId: string): Promise<any | null>;
+    /**
+     * Retrieves the version number associated with the specified record ID from Redis.
+     * If no version is found, returns 0.
+     *
+     * @param {string} recordId - The unique identifier for the record whose version is to be retrieved.
+     * @returns {Promise<number>} A promise that resolves to the version number of the record. Returns 0 if not found.
+     * @throws {Error} If there is an issue communicating with Redis or parsing the version.
+     */
+    getVersion(recordId: string): Promise<number>;
+    /**
+     * Retrieves a record and its associated version from Redis.
+     * Fetches both the record data and its version by their respective keys.
+     *
+     * @param {string} recordId - The unique identifier for the record to retrieve.
+     * @returns {Promise<{ record: any | null; version: number }>}
+     *          A promise that resolves to an object containing the parsed record (or null if not found)
+     *          and its version number (0 if version data is not found or invalid).
+     * @throws {Error} If there is a Redis error or if JSON parsing fails for the record data.
+     */
+    getRecordAndVersion(recordId: string): Promise<{
+        record: any | null;
+        version: number;
+    }>;
+    /**
+     * Publishes an update to a record by computing and applying a JSON Patch,
+     * incrementing the version, and persisting the updated value and version in Redis.
+     * If there are no changes between the old and new value, returns null.
+     *
+     * @param {string} recordId - The unique identifier of the record to update.
+     * @param {any} newValue - The new value to set for the record, or partial value when using merge strategy.
+     * @param {"replace" | "merge" | "deepMerge"} [strategy="replace"] - Update strategy: "replace" (default) replaces the entire record, "merge" merges with existing object properties, "deepMerge" recursively merges nested objects.
+     * @returns {Promise<{ patch: Operation[]; version: number; finalValue: any } | null>}
+     *          A promise resolving to an object containing the JSON Patch operations, new version number, and final merged value,
+     *          or null if there were no changes to publish.
+     * @throws {Error} If there is a failure reading or writing to Redis, or during patch computation, the promise will be rejected with the error.
+     */
+    publishUpdate(recordId: string, newValue: any, strategy?: "replace" | "merge" | "deepMerge"): Promise<{
+        patch: Operation[];
+        version: number;
+        finalValue: any;
+    } | null>;
+    /**
+     * Deletes a record and its associated version from Redis storage.
+     *
+     * @param {string} recordId - The unique identifier of the record to be deleted.
+     * @returns {Promise<{ version: number }|null>} A promise that resolves to the final version of the deleted record, or null if the record didn't exist.
+     * @throws {Error} If an error occurs during the Redis pipeline execution, the promise will be rejected with the error.
+     */
+    deleteRecord(recordId: string): Promise<{
+        version: number;
+    } | null>;
+    /**
+     * Registers a callback function to be called when a record is updated.
+     *
+     * @param {(data: { recordId: string; value: any }) => Promise<void> | void} callback - The callback function to execute when a record is updated.
+     * @returns {() => void} A function that, when called, will unregister the callback.
+     */
+    onRecordUpdate(callback: (data: {
+        recordId: string;
+        value: any;
+    }) => Promise<void> | void): () => void;
+    /**
+     * Registers a callback function to be called when a record is removed.
+     *
+     * @param {(data: { recordId: string; value: any }) => Promise<void> | void} callback - The callback function to execute when a record is removed.
+     * @returns {() => void} A function that, when called, will unregister the callback.
+     */
+    onRecordRemoved(callback: (data: {
+        recordId: string;
+        value: any;
+    }) => Promise<void> | void): () => void;
+}
+
+declare class MeshServer extends WebSocketServer {
+    readonly instanceId: string;
+    private redisManager;
+    private instanceManager;
+    private commandManager;
+    private channelManager;
+    private pubSubManager;
+    private recordSubscriptionManager;
+    private collectionManager;
+    private broadcastManager;
+    private persistenceManager;
+    roomManager: RoomManager;
+    recordManager: RecordManager;
+    connectionManager: ConnectionManager;
+    presenceManager: PresenceManager;
+    serverOptions: MeshServerOptions;
+    status: Status;
+    private _listening;
+    get listening(): boolean;
+    set listening(value: boolean);
+    get port(): number;
+    constructor(opts: MeshServerOptions);
+    /**
+     * Waits until the service is ready by ensuring it is listening, the instance channel subscription is established,
+     * and the persistence manager is fully initialized.
+     *
+     * @returns {Promise<void>} A promise that resolves when the service is fully ready.
+     * @throws {Error} If the readiness process fails or if any awaited promise rejects.
+     */
+    ready(): Promise<void>;
+    private applyListeners;
+    /**
+     * Registers a command with an associated callback and optional middleware.
+     *
+     * @template T The type for `MeshContext.payload`. Defaults to `any`.
+     * @template U The command's return value type. Defaults to `any`.
+     * @param {string} command - The unique identifier for the command to register.
+     * @param {(context: MeshContext<T>) => Promise<U> | U} callback - The function to execute when the command is invoked. It receives a `MeshContext` of type `T` and may return a value of type `U` or a `Promise` resolving to `U`.
+     * @param {SocketMiddleware[]} [middlewares=[]] - An optional array of middleware functions to apply to the command. Defaults to an empty array.
+     * @throws {Error} May throw an error if the command registration or middleware addition fails.
+     */
+    exposeCommand<T = any, U = any>(command: string, callback: (context: MeshContext<T>) => Promise<U> | U, middlewares?: SocketMiddleware[]): void;
+    /**
+     * Adds one or more middleware functions to the global middleware stack.
+     *
+     * @param {SocketMiddleware[]} middlewares - An array of middleware functions to be added. Each middleware
+     *                                           is expected to conform to the `SocketMiddleware` type.
+     * @returns {void}
+     * @throws {Error} If the provided middlewares are not valid or fail validation (if applicable).
+     */
+    useMiddleware(...middlewares: SocketMiddleware[]): void;
+    /**
+     * Adds an array of middleware functions to a specific command.
+     *
+     * @param {string} command - The name of the command to associate the middleware with.
+     * @param {SocketMiddleware[]} middlewares - An array of middleware functions to be added to the command.
+     * @returns {void}
+     */
+    useMiddlewareWithCommand(command: string, middlewares: SocketMiddleware[]): void;
+    /**
+     * Exposes a channel for external access and optionally associates a guard function
+     * to control access to that channel. The guard function determines whether a given
+     * connection is permitted to access the channel.
+     *
+     * @param {ChannelPattern} channel - The channel or pattern to expose.
+     * @param {(connection: Connection, channel: string) => Promise<boolean> | boolean} [guard] -
+     *   Optional guard function that receives the connection and channel name, returning
+     *   a boolean or a promise that resolves to a boolean indicating whether access is allowed.
+     * @returns {void}
+     */
+    exposeChannel(channel: ChannelPattern$1, guard?: (connection: Connection, channel: string) => Promise<boolean> | boolean): void;
+    /**
+     * Publishes a message to a specified channel and optionally maintains a history of messages.
+     *
+     * @param {string} channel - The name of the channel to which the message will be published.
+     * @param {any} message - The message to be published. Will not be stringified automatically for you. You need to do that yourself.
+     * @param {number} [history=0] - The number of historical messages to retain for the channel. Defaults to 0, meaning no history is retained.
+     *                               If greater than 0, the message will be added to the channel's history and the history will be trimmed to the specified size.
+     * @returns {Promise<void>} A Promise that resolves once the message has been published and, if applicable, the history has been updated.
+     * @throws {Error} This function may throw an error if the underlying `pubClient` operations (e.g., `lpush`, `ltrim`, `publish`) fail.
+     */
+    writeChannel(channel: string, message: any, history?: number): Promise<void>;
+    /**
+     * Enables persistence for channels matching the specified pattern.
+     *
+     * @param {ChannelPattern} pattern - The channel pattern to enable persistence for.
+     * @param {ChannelPersistenceOptions} [options] - Options for persistence.
+     * @throws {Error} If persistence is not enabled for this server instance.
+     */
+    enableChannelPersistence(pattern: ChannelPattern$1, options?: ChannelPersistenceOptions): void;
+    /**
+     * Enables persistence for records matching the specified pattern.
+     *
+     * @param {ChannelPattern} pattern - The record ID pattern to enable persistence for.
+     * @param {RecordPersistenceOptions} [options] - Options for persistence.
+     * @throws {Error} If persistence is not enabled for this server instance.
+     */
+    enableRecordPersistence(pattern: ChannelPattern$1, options?: RecordPersistenceOptions): void;
+    /**
+     * Exposes a record or pattern for client subscriptions, optionally adding a guard function.
+     *
+     * @param {ChannelPattern} recordPattern - The record ID or pattern to expose.
+     * @param {(connection: Connection, recordId: string) => Promise<boolean> | boolean} [guard] - Optional guard function.
+     */
+    exposeRecord(recordPattern: ChannelPattern$1, guard?: (connection: Connection, recordId: string) => Promise<boolean> | boolean): void;
+    /**
+     * Exposes a record or pattern for client writes, optionally adding a guard function.
+     *
+     * @param {ChannelPattern} recordPattern - The record ID or pattern to expose as writable.
+     * @param {(connection: Connection, recordId: string) => Promise<boolean> | boolean} [guard] - Optional guard function.
+     */
+    exposeWritableRecord(recordPattern: ChannelPattern$1, guard?: (connection: Connection, recordId: string) => Promise<boolean> | boolean): void;
+    /**
+     * Updates a record, persists it to Redis, increments its version, computes a patch,
+     * and publishes the update via Redis pub/sub.
+     *
+     * @param {string} recordId - The ID of the record to update.
+     * @param {any} newValue - The new value for the record, or partial value when using merge strategy.
+     * @param {{ strategy?: "replace" | "merge" | "deepMerge" }} [options] - Update options: strategy defaults to "replace" which replaces the entire record, "merge" merges with existing object properties, "deepMerge" recursively merges nested objects.
+     * @returns {Promise<void>}
+     * @throws {Error} If the update fails.
+     *
+     * @example
+     * // Replace strategy (default) - replaces entire record
+     * await server.writeRecord("user:123", { name: "John", age: 30 });
+     *
+     * // Merge strategy - merges with existing record
+     * // If record currently contains: { name: "old name", age: 30, city: "NYC" }
+     * await server.writeRecord("user:123", { name: "new name" }, { strategy: "merge" });
+     * // Result: { name: "new name", age: 30, city: "NYC" }
+     *
+     * // Deep merge strategy - recursively merges nested objects
+     * // If record currently contains: { name: "John", profile: { age: 30, city: "NYC", preferences: { theme: "dark" } } }
+     * await server.writeRecord("user:123", { profile: { age: 31 } }, { strategy: "deepMerge" });
+     * // Result: { name: "John", profile: { age: 31, city: "NYC", preferences: { theme: "dark" } } }
+     */
+    writeRecord(recordId: string, newValue: any, options?: {
+        strategy?: "replace" | "merge" | "deepMerge";
+    }): Promise<void>;
+    /**
+     * Retrieves the value of a record by its ID.
+     *
+     * @param {string} recordId - The ID of the record to retrieve.
+     * @returns {Promise<any>} A promise that resolves to the value of the record, or null if not found.
+     */
+    getRecord(recordId: string): Promise<any>;
+    deleteRecord(recordId: string): Promise<void>;
+    /**
+     * Lists and processes records matching a pattern. Designed for use in collection resolvers.
+     * Returns transformed records that will be sent to subscribed clients.
+     *
+     * @param {string} pattern - Redis glob pattern to match record IDs against (e.g., "user:*", "post:?", "[abc]*").
+     * @param {Object} [options] - Processing options.
+     * @param {Function} [options.map] - Transform each record before sorting/slicing.
+     * @param {Function} [options.sort] - Sort function for the records.
+     * @param {Object} [options.slice] - Pagination slice.
+     * @param {number} [options.slice.start] - Start index.
+     * @param {number} [options.slice.count] - Number of records to return.
+     * @returns {Promise<any[]>} The processed records to send to clients.
+     */
+    listRecordsMatching(pattern: string, options?: {
+        map?: (record: any) => any;
+        sort?: (a: any, b: any) => number;
+        slice?: {
+            start: number;
+            count: number;
+        };
+    }): Promise<any[]>;
+    /**
+     * Exposes a collection pattern for client subscriptions with a resolver function
+     * that determines which records belong to the collection.
+     *
+     * @param {ChannelPattern} pattern - The collection ID or pattern to expose.
+     * @param {(connection: Connection, collectionId: string) => Promise<any[]> | any[]} resolver -
+     *        Function that resolves which records belong to the collection.
+     */
+    exposeCollection(pattern: ChannelPattern$1, resolver: (connection: Connection, collectionId: string) => Promise<any[]> | any[]): void;
+    isInRoom(roomName: string, connection: Connection | string): Promise<boolean>;
+    addToRoom(roomName: string, connection: Connection | string): Promise<void>;
+    removeFromRoom(roomName: string, connection: Connection | string): Promise<void>;
+    removeFromAllRooms(connection: Connection | string): Promise<void>;
+    clearRoom(roomName: string): Promise<void>;
+    deleteRoom(roomName: string): Promise<void>;
+    getRoomMembers(roomName: string): Promise<string[]>;
+    getRoomMembersWithMetadata(roomName: string): Promise<Array<{
+        id: string;
+        metadata: any;
+    }>>;
+    getAllRooms(): Promise<string[]>;
+    /**
+     * Broadcasts a command and payload to a set of connections or all available connections.
+     *
+     * @param {string} command - The command to be broadcasted.
+     * @param {any} payload - The data associated with the command.
+     * @param {Connection[]=} connections - (Optional) A specific list of connections to broadcast to. If not provided, the command will be sent to all connections.
+     *
+     * @throws {Error} Emits an "error" event if broadcasting fails.
+     */
+    broadcast(command: string, payload: any, connections?: Connection[]): Promise<void>;
+    /**
+     * Broadcasts a command and associated payload to all active connections within the specified room.
+     *
+     * @param {string} roomName - The name of the room whose connections will receive the broadcast.
+     * @param {string} command - The command to be broadcasted to the connections.
+     * @param {unknown} payload - The data payload associated with the command.
+     * @returns {Promise<void>} A promise that resolves when the broadcast operation is complete.
+     * @throws {Error} If the broadcast operation fails, an error is thrown and the promise is rejected.
+     */
+    broadcastRoom(roomName: string, command: string, payload: any): Promise<void>;
+    /**
+     * Broadcasts a command and payload to all active connections except for the specified one(s).
+     * Excludes the provided connection(s) from receiving the broadcast.
+     *
+     * @param {string} command - The command to broadcast to connections.
+     * @param {any} payload - The payload to send along with the command.
+     * @param {Connection | Connection[]} exclude - A single connection or an array of connections to exclude from the broadcast.
+     * @returns {Promise<void>} A promise that resolves when the broadcast is complete.
+     * @emits {Error} Emits an "error" event if broadcasting the command fails.
+     */
+    broadcastExclude(command: string, payload: any, exclude: Connection | Connection[]): Promise<void>;
+    /**
+     * Broadcasts a command with a payload to all connections in a specified room,
+     * excluding one or more given connections. If the broadcast fails, emits an error event.
+     *
+     * @param {string} roomName - The name of the room to broadcast to.
+     * @param {string} command - The command to broadcast.
+     * @param {any} payload - The payload to send with the command.
+     * @param {Connection | Connection[]} exclude - A connection or array of connections to exclude from the broadcast.
+     * @returns {Promise<void>} A promise that resolves when the broadcast is complete.
+     * @emits {Error} Emits an error event if broadcasting fails.
+     */
+    broadcastRoomExclude(roomName: string, command: string, payload: any, exclude: Connection | Connection[]): Promise<void>;
+    trackPresence(roomPattern: string | RegExp, guardOrOptions?: ((connection: Connection, roomName: string) => Promise<boolean> | boolean) | {
+        ttl?: number;
+        guard?: (connection: Connection, roomName: string) => Promise<boolean> | boolean;
+    }): void;
+    private registerBuiltinCommands;
+    private registerRecordCommands;
+    cleanupConnection(connection: Connection): Promise<void>;
+    /**
+     * Gracefully closes all active connections, cleans up resources,
+     * and shuts down the service. Optionally accepts a callback function
+     * that will be invoked once shutdown is complete or if an error occurs.
+     *
+     * @param {((err?: Error) => void)=} callback - Optional callback to be invoked when closing is complete or if an error occurs.
+     * @returns {Promise<void>} A promise that resolves when shutdown is complete.
+     * @throws {Error} If an error occurs during shutdown, the promise will be rejected with the error.
+     */
+    close(callback?: (err?: Error) => void): Promise<void>;
+    /**
+     * Registers a callback function to be executed when a new connection is established.
+     *
+     * @param {(connection: Connection) => Promise<void> | void} callback - The function to execute when a new connection is established.
+     * @returns {MeshServer} The server instance for method chaining.
+     */
+    onConnection(callback: (connection: Connection) => Promise<void> | void): MeshServer;
+    /**
+     * Registers a callback function to be executed when a connection is closed.
+     *
+     * @param {(connection: Connection) => Promise<void> | void} callback - The function to execute when a connection is closed.
+     * @returns {MeshServer} The server instance for method chaining.
+     */
+    onDisconnection(callback: (connection: Connection) => Promise<void> | void): MeshServer;
+    /**
+     * Registers a callback function to be executed when a record is updated.
+     *
+     * @param {(data: { recordId: string; value: any }) => Promise<void> | void} callback - The function to execute when a record is updated.
+     * @returns {() => void} A function that, when called, will unregister the callback.
+     */
+    onRecordUpdate(callback: (data: {
+        recordId: string;
+        value: any;
+    }) => Promise<void> | void): () => void;
+    /**
+     * Registers a callback function to be executed when a record is removed.
+     *
+     * @param {(data: { recordId: string; value: any }) => Promise<void> | void} callback - The function to execute when a record is removed.
+     * @returns {() => void} A function that, when called, will unregister the callback.
+     */
+    onRecordRemoved(callback: (data: {
+        recordId: string;
+        value: any;
+    }) => Promise<void> | void): () => void;
+}
+
+declare class SQLitePersistenceAdapter implements PersistenceAdapter {
+    private db;
+    private options;
+    private initialized;
+    constructor(options?: PersistenceAdapterOptions);
+    initialize(): Promise<void>;
+    private createTables;
+    storeMessages(messages: PersistedMessage[]): Promise<void>;
+    getMessages(channel: string, since?: string | number, limit?: number): Promise<PersistedMessage[]>;
+    close(): Promise<void>;
+    /**
+     * Store records in the database
+     * @param records Array of records to store
+     */
+    storeRecords(records: PersistedRecord[]): Promise<void>;
+    /**
+     * Get records matching a pattern
+     * @param pattern Pattern to match record IDs against
+     * @returns Array of matching records
+     */
+    getRecords(pattern: string): Promise<PersistedRecord[]>;
+}
+
+declare class PostgreSQLPersistenceAdapter implements PersistenceAdapter {
+    private pool;
+    private options;
+    private initialized;
+    constructor(options?: PostgreSQLAdapterOptions);
+    initialize(): Promise<void>;
+    private createTables;
+    storeMessages(messages: PersistedMessage[]): Promise<void>;
+    getMessages(channel: string, since?: string | number, limit?: number): Promise<PersistedMessage[]>;
+    storeRecords(records: PersistedRecord[]): Promise<void>;
+    getRecords(pattern: string): Promise<PersistedRecord[]>;
+    close(): Promise<void>;
+}
+
+/**
+ * MessageStream provides a unified internal event stream for channel messages.
+ * It decouples channel message delivery from persistence.
+ */
+declare class MessageStream extends EventEmitter$1 {
+    private static instance;
+    /**
+     * Get the MessageStream singleton
+     */
+    static getInstance(): MessageStream;
+    private constructor();
+    /**
+     * Publish a message to the stream
+     * @param channel The channel the message was published to
+     * @param message The message content
+     * @param instanceId ID of the server instance
+     */
+    publishMessage(channel: string, message: string, instanceId: string): void;
+    /**
+     * Subscribe to all messages in the stream
+     * @param callback Function to call for each message
+     */
+    subscribeToMessages(callback: (message: {
+        channel: string;
+        message: string;
+        instanceId: string;
+        timestamp: number;
+    }) => void): void;
+    /**
+     * Unsubscribe from messages
+     * @param callback The callback function to remove
+     */
+    unsubscribeFromMessages(callback: (message: {
+        channel: string;
+        message: string;
+        instanceId: string;
+        timestamp: number;
+    }) => void): void;
+}
+
+declare class PersistenceManager extends EventEmitter$1 {
+    private defaultAdapter;
+    private channelPatterns;
+    private recordPatterns;
+    private messageBuffer;
+    private recordBuffer;
+    private flushTimers;
+    private recordFlushTimer;
+    private isShuttingDown;
+    private initialized;
+    private recordManager;
+    private pendingRecordUpdates;
+    private messageStream;
+    constructor(options: {
+        defaultAdapterOptions?: any;
+        adapterType?: "sqlite" | "postgres";
+    });
+    /**
+     * Sets the record manager reference for record restoration
+     * @param recordManager The record manager instance
+     */
+    setRecordManager(recordManager: RecordManager): void;
+    /**
+     * Waits until the persistence manager is fully ready and initialized.
+     *
+     * @returns {Promise<void>} A promise that resolves when persistence is ready.
+     */
+    ready(): Promise<void>;
+    /**
+     * Processes any record updates that were buffered during initialization
+     */
+    private processPendingRecordUpdates;
+    initialize(): Promise<void>;
+    /**
+     * Restores persisted records from storage into Redis on startup
+     */
+    private restorePersistedRecords;
+    /**
+     * Handle a message received from the internal message stream.
+     */
+    private handleStreamMessage;
+    /**
+     * Enable persistence for channels matching the given pattern.
+     * @param pattern string or regexp pattern to match channel names
+     * @param options persistence options
+     */
+    enableChannelPersistence(pattern: string | RegExp, options?: ChannelPersistenceOptions): void;
+    /**
+     * Enable persistence for records matching the given pattern.
+     * @param pattern string or regexp pattern to match record IDs
+     * @param options persistence options
+     */
+    enableRecordPersistence(pattern: string | RegExp, options?: RecordPersistenceOptions): void;
+    /**
+     * Check if a channel has persistence enabled and return its options.
+     * @param channel channel name to check
+     * @returns the persistence options if enabled, undefined otherwise
+     */
+    getChannelPersistenceOptions(channel: string): Required<ChannelPersistenceOptions> | undefined;
+    /**
+     * Check if a record has persistence enabled and return its options.
+     * @param recordId record ID to check
+     * @returns the persistence options if enabled, undefined otherwise
+     */
+    getRecordPersistenceOptions(recordId: string): Required<RecordPersistenceOptions> | undefined;
+    /**
+     * Handle an incoming message for potential persistence.
+     * @param channel channel the message was published to
+     * @param message the message content
+     * @param instanceId id of the server instance
+     */
+    handleChannelMessage(channel: string, message: string, instanceId: string, timestamp?: number): void;
+    /**
+     * Flush buffered messages for a specific channel to its adapter.
+     * @param channel channel to flush
+     */
+    private flushChannel;
+    /**
+     * Flush all buffered messages across all channels.
+     */
+    flushAll(): Promise<void>;
+    /**
+     * Get persisted messages for a channel.
+     * @param channel channel to get messages for
+     * @param since optional cursor (timestamp or message id) to retrieve messages after
+     * @param limit maximum number of messages to retrieve
+     */
+    getMessages(channel: string, since?: string | number, limit?: number): Promise<PersistedMessage[]>;
+    /**
+     * Handles a record update for potential persistence
+     * @param recordId ID of the record
+     * @param value record value (will be stringified)
+     * @param version record version
+     */
+    handleRecordUpdate(recordId: string, value: any, version: number): void;
+    /**
+     * Flush all buffered records to storage
+     */
+    flushRecords(): Promise<void>;
+    /**
+     * Retrieve persisted records matching a pattern
+     * @param pattern pattern to match record IDs
+     * @returns array of persisted records
+     */
+    getPersistedRecords(pattern: string): Promise<PersistedRecord[]>;
+    /**
+     * Shutdown the persistence manager, flushing pending messages and closing adapters.
+     */
+    shutdown(): Promise<void>;
+}
+
+export { type ChannelPattern$1 as ChannelPattern, Connection, ConnectionManager, MeshContext, MeshServer, type MeshServerOptions, MessageStream, type PersistenceAdapter, type PersistenceAdapterOptions, PersistenceManager, type PostgreSQLAdapterOptions, PostgreSQLPersistenceAdapter, PresenceManager, RecordManager, RoomManager, SQLitePersistenceAdapter, type SocketMiddleware };