@mesh-kit/server 2.0.6 → 2.0.8

package/dist/index.d.mts

@@ -71,21 +71,19 @@ interface ChannelPersistenceOptions {
      */
     maxBufferSize?: number;
 }
-interface RecordPersistenceOptions {
-    /**
-     * Optional adapter override for this pattern
-     */
+interface RecordPersistenceAdapterConfig {
     adapter?: PersistenceAdapter;
-    /**
-     * How often (in ms) to flush buffered records to the database
-     * @default 500
-     */
+    restorePattern: string;
+}
+interface RecordPersistenceHooksConfig {
+    persist: (records: CustomPersistedRecord[]) => Promise<void>;
+    restore: () => Promise<CustomPersistedRecord[]>;
+}
+interface RecordPersistenceConfig {
+    pattern: string | RegExp;
+    adapter?: RecordPersistenceAdapterConfig;
+    hooks?: RecordPersistenceHooksConfig;
     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 {
@@ -94,6 +92,11 @@ interface PersistedRecord {
     value: string;
     timestamp: number;
 }
+interface CustomPersistedRecord {
+    recordId: string;
+    value: unknown;
+    version: number;
+}
 interface PersistenceAdapterOptions {
     /**
      * Database file path for file-based adapters
@@ -683,121 +686,6 @@ declare class RecordManager {
     }) => Promise<void> | void): () => void;
 }
 
-type RecordPersistencePattern = {
-    writePattern: string | RegExp;
-    restorePattern: string;
-};
-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
-     */
-    restorePersistedRecords(): Promise<void>;
-    /**
-     * 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 object with writePattern (for runtime matching) and restorePattern (for database queries)
-     * @param options persistence options
-     */
-    enableRecordPersistence(pattern: RecordPersistencePattern, 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>;
-}
-
 declare class MeshServer extends WebSocketServer {
     readonly instanceId: string;
     private redisManager;
@@ -891,12 +779,9 @@ declare class MeshServer extends WebSocketServer {
     enableChannelPersistence(pattern: ChannelPattern$1, options?: ChannelPersistenceOptions): void;
     /**
      * Enables persistence for records matching the specified pattern.
-     *
-     * @param {RecordPersistencePattern} 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.
+     * Use either adapter (for mesh's internal JSON blob storage) or hooks (for custom DB persistence).
      */
-    enableRecordPersistence(pattern: RecordPersistencePattern, options?: RecordPersistenceOptions): void;
+    enableRecordPersistence(config: RecordPersistenceConfig): void;
     /**
      * Exposes a record or pattern for client subscriptions, optionally adding a guard function.
      *
@@ -1161,4 +1046,127 @@ declare class MessageStream extends EventEmitter$1 {
     }) => void): void;
 }
 
-export { type AuthenticateConnectionFn, type AuthenticationError, type ChannelPattern$1 as ChannelPattern, Connection, ConnectionManager, MeshContext, MeshServer, type MeshServerOptions, MessageStream, type PersistenceAdapter, type PersistenceAdapterOptions, PersistenceManager, type PostgreSQLAdapterOptions, PostgreSQLPersistenceAdapter, PresenceManager, RecordManager, type RecordPersistencePattern, RoomManager, SQLitePersistenceAdapter, type SocketMiddleware };
+interface RecordPatternConfig {
+    pattern: string | RegExp;
+    adapter?: {
+        adapter: PersistenceAdapter;
+        restorePattern: string;
+    };
+    hooks?: {
+        persist: (records: CustomPersistedRecord[]) => Promise<void>;
+        restore: () => Promise<CustomPersistedRecord[]>;
+    };
+    flushInterval: number;
+    maxBufferSize: number;
+}
+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
+     */
+    restorePersistedRecords(): Promise<void>;
+    /**
+     * 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.
+     * Use either adapter (for mesh's internal JSON blob storage) or hooks (for custom DB persistence).
+     */
+    enableRecordPersistence(config: RecordPersistenceConfig): 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 config.
+     * @param recordId record ID to check
+     * @returns the persistence config if enabled, undefined otherwise
+     */
+    getRecordPersistenceConfig(recordId: string): RecordPatternConfig | 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 AuthenticateConnectionFn, type AuthenticationError, type ChannelPattern$1 as ChannelPattern, Connection, ConnectionManager, type CustomPersistedRecord, MeshContext, MeshServer, type MeshServerOptions, MessageStream, type PersistenceAdapter, type PersistenceAdapterOptions, PersistenceManager, type PostgreSQLAdapterOptions, PostgreSQLPersistenceAdapter, PresenceManager, RecordManager, type RecordPersistenceConfig, RoomManager, SQLitePersistenceAdapter, type SocketMiddleware };

package/dist/index.d.ts

@@ -71,21 +71,19 @@ interface ChannelPersistenceOptions {
      */
     maxBufferSize?: number;
 }
-interface RecordPersistenceOptions {
-    /**
-     * Optional adapter override for this pattern
-     */
+interface RecordPersistenceAdapterConfig {
     adapter?: PersistenceAdapter;
-    /**
-     * How often (in ms) to flush buffered records to the database
-     * @default 500
-     */
+    restorePattern: string;
+}
+interface RecordPersistenceHooksConfig {
+    persist: (records: CustomPersistedRecord[]) => Promise<void>;
+    restore: () => Promise<CustomPersistedRecord[]>;
+}
+interface RecordPersistenceConfig {
+    pattern: string | RegExp;
+    adapter?: RecordPersistenceAdapterConfig;
+    hooks?: RecordPersistenceHooksConfig;
     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 {
@@ -94,6 +92,11 @@ interface PersistedRecord {
     value: string;
     timestamp: number;
 }
+interface CustomPersistedRecord {
+    recordId: string;
+    value: unknown;
+    version: number;
+}
 interface PersistenceAdapterOptions {
     /**
      * Database file path for file-based adapters
@@ -683,121 +686,6 @@ declare class RecordManager {
     }) => Promise<void> | void): () => void;
 }
 
-type RecordPersistencePattern = {
-    writePattern: string | RegExp;
-    restorePattern: string;
-};
-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
-     */
-    restorePersistedRecords(): Promise<void>;
-    /**
-     * 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 object with writePattern (for runtime matching) and restorePattern (for database queries)
-     * @param options persistence options
-     */
-    enableRecordPersistence(pattern: RecordPersistencePattern, 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>;
-}
-
 declare class MeshServer extends WebSocketServer {
     readonly instanceId: string;
     private redisManager;
@@ -891,12 +779,9 @@ declare class MeshServer extends WebSocketServer {
     enableChannelPersistence(pattern: ChannelPattern$1, options?: ChannelPersistenceOptions): void;
     /**
      * Enables persistence for records matching the specified pattern.
-     *
-     * @param {RecordPersistencePattern} 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.
+     * Use either adapter (for mesh's internal JSON blob storage) or hooks (for custom DB persistence).
      */
-    enableRecordPersistence(pattern: RecordPersistencePattern, options?: RecordPersistenceOptions): void;
+    enableRecordPersistence(config: RecordPersistenceConfig): void;
     /**
      * Exposes a record or pattern for client subscriptions, optionally adding a guard function.
      *
@@ -1161,4 +1046,127 @@ declare class MessageStream extends EventEmitter$1 {
     }) => void): void;
 }
 
-export { type AuthenticateConnectionFn, type AuthenticationError, type ChannelPattern$1 as ChannelPattern, Connection, ConnectionManager, MeshContext, MeshServer, type MeshServerOptions, MessageStream, type PersistenceAdapter, type PersistenceAdapterOptions, PersistenceManager, type PostgreSQLAdapterOptions, PostgreSQLPersistenceAdapter, PresenceManager, RecordManager, type RecordPersistencePattern, RoomManager, SQLitePersistenceAdapter, type SocketMiddleware };
+interface RecordPatternConfig {
+    pattern: string | RegExp;
+    adapter?: {
+        adapter: PersistenceAdapter;
+        restorePattern: string;
+    };
+    hooks?: {
+        persist: (records: CustomPersistedRecord[]) => Promise<void>;
+        restore: () => Promise<CustomPersistedRecord[]>;
+    };
+    flushInterval: number;
+    maxBufferSize: number;
+}
+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
+     */
+    restorePersistedRecords(): Promise<void>;
+    /**
+     * 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.
+     * Use either adapter (for mesh's internal JSON blob storage) or hooks (for custom DB persistence).
+     */
+    enableRecordPersistence(config: RecordPersistenceConfig): 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 config.
+     * @param recordId record ID to check
+     * @returns the persistence config if enabled, undefined otherwise
+     */
+    getRecordPersistenceConfig(recordId: string): RecordPatternConfig | 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 AuthenticateConnectionFn, type AuthenticationError, type ChannelPattern$1 as ChannelPattern, Connection, ConnectionManager, type CustomPersistedRecord, MeshContext, MeshServer, type MeshServerOptions, MessageStream, type PersistenceAdapter, type PersistenceAdapterOptions, PersistenceManager, type PostgreSQLAdapterOptions, PostgreSQLPersistenceAdapter, PresenceManager, RecordManager, type RecordPersistenceConfig, RoomManager, SQLitePersistenceAdapter, type SocketMiddleware };