@frontmcp/utils 1.10.16 → 1.11.0-rc.2

package/storage/index.d.ts

@@ -4,8 +4,10 @@
  * Unified storage abstraction with pluggable backends.
  * Supports Memory (dev), Redis (prod), Vercel KV (edge), and Upstash (edge + pub/sub).
  */
-export type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, RedisHostConnectionConfig, RedisUrlConnectionConfig, RedisUrlFillInConfig, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, } from './types';
+export type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, RedisHostConnectionConfig, RedisUrlConnectionConfig, RedisUrlFillInConfig, VercelKvAdapterOptions, UpstashAdapterOptions, SqliteAdapterOptions, StorageType, StorageConfig, } from './types';
 export { createStorage, createMemoryStorage, getDetectedStorageType } from './factory';
+export { createChangeFeed, DEFAULT_CHANGE_FEED_COALESCE_MS, DEFAULT_CHANGE_FEED_POLL_INTERVAL_MS } from './change-feed';
+export type { ChangeFeed, ChangeFeedKind, ChangeFeedOptions } from './change-feed';
 export { attachRedisErrorListener, DEFAULT_REDIS_ERROR_LOG_INTERVAL_MS } from './redis-error-listener';
 export type { RedisErrorListenerOptions, ErrorEmitterClient } from './redis-error-listener';
 export { mergeRedisUrlFields, describeRedisUrlConflicts } from './redis-url';

package/storage/namespace.d.ts

@@ -68,8 +68,10 @@ export declare class NamespacedStorageImpl implements NamespacedStorage {
     incrBy(key: string, amount: number): Promise<number>;
     deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
     expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
+    setIfEquals(key: string, expectedValue: string, value: string): Promise<boolean>;
     publish(channel: string, message: string): Promise<number>;
     subscribe(channel: string, handler: MessageHandler): Promise<Unsubscribe>;
+    onPubSubReconnect(listener: () => void): () => void;
     supportsPubSub(): boolean;
 }
 /**

package/storage/types.d.ts

@@ -224,6 +224,22 @@ export interface StorageAdapter {
      * @throws StorageNotSupportedError if the backend has no atomic compare-and-expire
      */
     expireIfEquals?(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Atomically replace a key's value only while it still holds `expectedValue` (compare-and-set).
+     * Like a plain `set(key, value)`, the key has no TTL afterwards.
+     *
+     * @param key - Storage key
+     * @param expectedValue - The exact value the key must hold
+     * @param value - The value to store
+     * @returns true if this call stored `value`, false if the key was missing or held another value
+     * @throws StorageNotSupportedError if the backend has no atomic compare-and-set
+     */
+    setIfEquals?(key: string, expectedValue: string, value: string): Promise<boolean>;
+    /**
+     * A number that changes whenever another connection commits a write (SQLite's `PRAGMA data_version`),
+     * so a change feed can tell cheaply that another process wrote. Only the SQLite adapter has it.
+     */
+    dataVersion?(): Promise<number>;
     /**
      * Publish a message to a channel.
      * Not all adapters support pub/sub (e.g., Vercel KV doesn't).
@@ -244,6 +260,13 @@ export interface StorageAdapter {
      * @throws StorageNotSupportedError if adapter doesn't support pub/sub
      */
     subscribe(channel: string, handler: MessageHandler): Promise<Unsubscribe>;
+    /**
+     * Call `listener` each time the pub/sub connection is back after it was lost. The messages published while it
+     * was down were missed, so a subscriber that must not miss a change re-reads the state. Only Redis has it.
+     *
+     * @returns The function that stops calling `listener`
+     */
+    onPubSubReconnect?(listener: () => void): () => void;
     /**
      * Check if this adapter supports pub/sub.
      *
@@ -290,6 +313,8 @@ export interface NamespacedStorage extends StorageAdapter {
     deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
     /** {@link StorageAdapter.expireIfEquals}; throws StorageNotSupportedError when the adapter has none. */
     expireIfEquals(key: string, expectedValue: string, ttlSeconds: number): Promise<boolean>;
+    /** {@link StorageAdapter.setIfEquals}; throws StorageNotSupportedError when the adapter has none. */
+    setIfEquals(key: string, expectedValue: string, value: string): Promise<boolean>;
     /**
      * Get the underlying root adapter (for advanced use).
      * Use with caution - operations bypass namespace prefixing.
@@ -457,10 +482,25 @@ export interface CloudflareKvAdapterOptions {
     /** Key prefix applied to all keys. @default '' */
     keyPrefix?: string;
 }
+/** SQLite adapter options (type 'sqlite', from `@frontmcp/storage-sqlite`): processes on one file share its keys. */
+export interface SqliteAdapterOptions {
+    /** Path to the database file; its directory is created if missing. */
+    path: string;
+    /** Write-ahead log: readers don't wait for the writer. Needs a local filesystem. @default true */
+    walMode?: boolean;
+    /** How long an operation waits for another process's lock before failing with `SQLITE_BUSY`. @default 5000 */
+    busyTimeoutMs?: number;
+    /** How often expired keys are purged, in milliseconds; 0 turns the sweep off. @default 60000 */
+    ttlCleanupIntervalMs?: number;
+    /** Encrypt values at rest with AES-256-GCM, from a key derived with HKDF-SHA256. */
+    encryption?: {
+        secret: string;
+    };
+}
 /**
  * Storage backend type.
  */
-export type StorageType = 'memory' | 'redis' | 'vercel-kv' | 'upstash' | 'cloudflare-kv' | 'auto';
+export type StorageType = 'memory' | 'redis' | 'vercel-kv' | 'upstash' | 'cloudflare-kv' | 'sqlite' | 'auto';
 /**
  * Configuration for createStorage factory.
  */
@@ -471,6 +511,7 @@ export interface StorageConfig {
      * - 'redis': Redis (production)
      * - 'vercel-kv': Vercel KV (edge deployment, no pub/sub)
      * - 'upstash': Upstash Redis (edge deployment, with pub/sub)
+     * - 'sqlite': A local SQLite file, shared by the processes on one machine (no pub/sub)
      * - 'auto': Auto-detect based on environment variables
      * @default 'auto'
      */
@@ -495,6 +536,10 @@ export interface StorageConfig {
      * Upstash adapter options (when type='upstash').
      */
     upstash?: UpstashAdapterOptions;
+    /**
+     * SQLite adapter options (when type='sqlite').
+     */
+    sqlite?: SqliteAdapterOptions;
     /**
      * Root namespace prefix for all keys.
      * Applied on top of any adapter-specific prefix.

package/storage/utils/compare-and-delete.d.ts

@@ -2,3 +2,5 @@
 export declare const COMPARE_AND_DELETE_SCRIPT = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0";
 /** Redis Lua script for `expireIfEquals`: sets KEYS[1]'s TTL to ARGV[2] seconds only while it holds ARGV[1]. */
 export declare const COMPARE_AND_EXPIRE_SCRIPT = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('EXPIRE', KEYS[1], ARGV[2]) end return 0";
+/** Redis Lua script for `setIfEquals`: sets KEYS[1] to ARGV[2] only while it holds ARGV[1], returning 1 or 0. */
+export declare const COMPARE_AND_SET_SCRIPT = "if redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('SET', KEYS[1], ARGV[2]) return 1 end return 0";