@frontmcp/utils 0.0.1 → 0.7.1

package/storage/adapters/memory.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Memory Storage Adapter
+ *
+ * In-memory storage implementation for development and testing.
+ * Supports TTL, pattern matching, pub/sub via EventEmitter.
+ */
+import { BaseStorageAdapter } from './base';
+import type { MemoryAdapterOptions, SetOptions, MessageHandler, Unsubscribe } from '../types';
+/**
+ * In-memory storage adapter.
+ *
+ * Features:
+ * - TTL support with lazy expiration + optional background sweeper
+ * - Pattern matching for keys() with ReDoS protection
+ * - Pub/sub via EventEmitter
+ * - Optional LRU eviction
+ *
+ * @example
+ * ```typescript
+ * const adapter = new MemoryStorageAdapter({
+ *   enableSweeper: true,
+ *   sweepIntervalSeconds: 60,
+ * });
+ *
+ * await adapter.connect();
+ * await adapter.set('key', 'value', { ttlSeconds: 300 });
+ * const value = await adapter.get('key');
+ * await adapter.disconnect();
+ * ```
+ */
+export declare class MemoryStorageAdapter extends BaseStorageAdapter {
+    protected readonly backendName = "memory";
+    private readonly store;
+    private readonly emitter;
+    private sweepInterval?;
+    private readonly options;
+    private accessOrder;
+    constructor(options?: MemoryAdapterOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    get(key: string): Promise<string | null>;
+    protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number | null>;
+    keys(pattern?: string): Promise<string[]>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    incrBy(key: string, amount: number): Promise<number>;
+    supportsPubSub(): boolean;
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string, handler: MessageHandler): Promise<Unsubscribe>;
+    /**
+     * Delete an entry and clear its timeout.
+     */
+    private deleteEntry;
+    /**
+     * Clear timeout for an entry.
+     */
+    private clearEntryTimeout;
+    /**
+     * Clear all timeouts.
+     */
+    private clearAllTimeouts;
+    /**
+     * Update LRU access order.
+     */
+    private touchLRU;
+    /**
+     * Remove key from LRU tracking.
+     */
+    private removeLRU;
+    /**
+     * Evict oldest entry (LRU).
+     */
+    private evictOldest;
+    /**
+     * Start background sweeper.
+     */
+    private startSweeper;
+    /**
+     * Stop background sweeper.
+     */
+    private stopSweeper;
+    /**
+     * Sweep expired entries.
+     */
+    private sweep;
+    /**
+     * Get storage statistics.
+     */
+    getStats(): {
+        size: number;
+        maxEntries: number;
+        sweeperActive: boolean;
+    };
+}

package/storage/adapters/redis.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Redis Storage Adapter
+ *
+ * Redis-based storage implementation for production use.
+ * Uses ioredis with dynamic import for browser compatibility.
+ */
+import { BaseStorageAdapter } from './base';
+import type { RedisAdapterOptions, SetOptions, MessageHandler, Unsubscribe } from '../types';
+type Redis = import('ioredis').Redis;
+/**
+ * Redis storage adapter.
+ *
+ * Features:
+ * - Native Redis TTL support
+ * - SCAN for pattern matching (non-blocking)
+ * - Pipeline for batch operations
+ * - Pub/sub with separate subscriber connection
+ *
+ * @example
+ * ```typescript
+ * const adapter = new RedisStorageAdapter({
+ *   url: 'redis://localhost:6379',
+ * });
+ *
+ * await adapter.connect();
+ * await adapter.set('key', 'value', { ttlSeconds: 300 });
+ * const value = await adapter.get('key');
+ * await adapter.disconnect();
+ * ```
+ */
+export declare class RedisStorageAdapter extends BaseStorageAdapter {
+    protected readonly backendName = "redis";
+    private client?;
+    private subscriber?;
+    private readonly options;
+    private readonly ownsClient;
+    private readonly keyPrefix;
+    private readonly subscriptionHandlers;
+    constructor(options?: RedisAdapterOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    /**
+     * Get the connected Redis client, throwing if not connected.
+     */
+    private getConnectedClient;
+    /**
+     * Get the connected Redis subscriber, throwing if not created.
+     */
+    private getConnectedSubscriber;
+    get(key: string): Promise<string | null>;
+    protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    mget(keys: string[]): Promise<(string | null)[]>;
+    mset(entries: import('../types').SetEntry[]): Promise<void>;
+    mdelete(keys: string[]): Promise<number>;
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number | null>;
+    keys(pattern?: string): Promise<string[]>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    incrBy(key: string, amount: number): Promise<number>;
+    supportsPubSub(): boolean;
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string, handler: MessageHandler): Promise<Unsubscribe>;
+    /**
+     * Build Redis options from config.
+     */
+    private buildRedisOptions;
+    /**
+     * Create subscriber connection.
+     */
+    private createSubscriber;
+    /**
+     * Add prefix to a key.
+     */
+    private prefixKey;
+    /**
+     * Remove prefix from a key.
+     */
+    private unprefixKey;
+    /**
+     * Get the underlying Redis client (for advanced use).
+     */
+    getClient(): Redis | undefined;
+}
+export {};

package/storage/adapters/upstash.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Upstash Redis Storage Adapter
+ *
+ * Upstash Redis (REST-based) storage implementation for edge deployment.
+ * Supports pub/sub via Upstash's REST API with polling mechanism.
+ */
+import { BaseStorageAdapter } from './base';
+import type { UpstashAdapterOptions, SetOptions, MessageHandler, Unsubscribe } from '../types';
+/**
+ * Upstash Redis storage adapter.
+ *
+ * Features:
+ * - REST-based storage for edge deployment
+ * - Native TTL support
+ * - Pub/sub support via list-based polling
+ *
+ * @example
+ * ```typescript
+ * const adapter = new UpstashStorageAdapter({
+ *   url: process.env.UPSTASH_REDIS_REST_URL,
+ *   token: process.env.UPSTASH_REDIS_REST_TOKEN,
+ *   enablePubSub: true,
+ * });
+ *
+ * await adapter.connect();
+ * await adapter.set('key', 'value', { ttlSeconds: 300 });
+ * const value = await adapter.get('key');
+ *
+ * // Pub/sub
+ * const unsubscribe = await adapter.subscribe('channel', (msg) => console.log(msg));
+ * await adapter.publish('channel', 'hello');
+ *
+ * await adapter.disconnect();
+ * ```
+ */
+export declare class UpstashStorageAdapter extends BaseStorageAdapter {
+    protected readonly backendName = "upstash";
+    private client?;
+    private readonly options;
+    private readonly keyPrefix;
+    private readonly pubSubEnabled;
+    private readonly subscriptionHandlers;
+    private readonly pollingIntervals;
+    constructor(options?: UpstashAdapterOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    /**
+     * Get the connected Upstash client, throwing if not connected.
+     */
+    private getConnectedClient;
+    get(key: string): Promise<string | null>;
+    protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    mget(keys: string[]): Promise<(string | null)[]>;
+    mdelete(keys: string[]): Promise<number>;
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number | null>;
+    keys(pattern?: string): Promise<string[]>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    incrBy(key: string, amount: number): Promise<number>;
+    supportsPubSub(): boolean;
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string, handler: MessageHandler): Promise<Unsubscribe>;
+    /**
+     * Publish using list-based approach (for polling subscribers).
+     * This is an alternative to native PUBLISH when subscribers are polling.
+     */
+    publishToQueue(channel: string, message: string): Promise<void>;
+    protected getPubSubSuggestion(): string;
+    /**
+     * Add prefix to a key.
+     */
+    private prefixKey;
+    /**
+     * Remove prefix from a key.
+     */
+    private unprefixKey;
+}

package/storage/adapters/vercel-kv.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Vercel KV Storage Adapter
+ *
+ * Vercel KV (REST-based) storage implementation for edge deployment.
+ * NOTE: Vercel KV does NOT support pub/sub. Use Upstash adapter instead.
+ */
+import { BaseStorageAdapter } from './base';
+import type { VercelKvAdapterOptions, SetOptions } from '../types';
+/**
+ * Vercel KV storage adapter.
+ *
+ * Features:
+ * - REST-based storage for edge deployment
+ * - Native TTL support
+ * - Pattern matching via keys() command
+ *
+ * Limitations:
+ * - NO pub/sub support (use Upstash instead)
+ * - keys() may be slow for large datasets
+ *
+ * @example
+ * ```typescript
+ * const adapter = new VercelKvStorageAdapter({
+ *   url: process.env.KV_REST_API_URL,
+ *   token: process.env.KV_REST_API_TOKEN,
+ * });
+ *
+ * await adapter.connect();
+ * await adapter.set('key', 'value', { ttlSeconds: 300 });
+ * const value = await adapter.get('key');
+ * await adapter.disconnect();
+ * ```
+ */
+export declare class VercelKvStorageAdapter extends BaseStorageAdapter {
+    protected readonly backendName = "vercel-kv";
+    private client?;
+    private readonly options;
+    private readonly keyPrefix;
+    constructor(options?: VercelKvAdapterOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    /**
+     * Get the connected Vercel KV client, throwing if not connected.
+     */
+    private getConnectedClient;
+    get(key: string): Promise<string | null>;
+    protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    mget(keys: string[]): Promise<(string | null)[]>;
+    mdelete(keys: string[]): Promise<number>;
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number | null>;
+    keys(pattern?: string): Promise<string[]>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    incrBy(key: string, amount: number): Promise<number>;
+    supportsPubSub(): boolean;
+    protected getPubSubSuggestion(): string;
+    /**
+     * Add prefix to a key.
+     */
+    private prefixKey;
+    /**
+     * Remove prefix from a key.
+     */
+    private unprefixKey;
+}

package/storage/errors.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Storage Error Classes
+ *
+ * Custom error types for storage operations.
+ * All errors extend StorageError for easy catching.
+ */
+/**
+ * Base error class for all storage-related errors.
+ */
+export declare class StorageError extends Error {
+    readonly cause?: Error;
+    constructor(message: string, cause?: Error);
+}
+/**
+ * Error thrown when storage connection fails.
+ *
+ * @example
+ * ```typescript
+ * throw new StorageConnectionError(
+ *   'Failed to connect to Redis',
+ *   originalError
+ * );
+ * ```
+ */
+export declare class StorageConnectionError extends StorageError {
+    readonly backend?: string | undefined;
+    constructor(message: string, cause?: Error, backend?: string | undefined);
+}
+/**
+ * Error thrown when a storage operation fails.
+ *
+ * @example
+ * ```typescript
+ * throw new StorageOperationError(
+ *   'set',
+ *   'user:123',
+ *   'Value too large',
+ *   originalError
+ * );
+ * ```
+ */
+export declare class StorageOperationError extends StorageError {
+    readonly operation: string;
+    readonly key: string;
+    constructor(operation: string, key: string, message: string, cause?: Error);
+}
+/**
+ * Error thrown when a feature is not supported by the adapter.
+ *
+ * @example
+ * ```typescript
+ * throw new StorageNotSupportedError(
+ *   'publish',
+ *   'vercel-kv',
+ *   'Vercel KV does not support pub/sub. Use Upstash instead.'
+ * );
+ * ```
+ */
+export declare class StorageNotSupportedError extends StorageError {
+    readonly operation: string;
+    readonly backend: string;
+    constructor(operation: string, backend: string, suggestion?: string);
+}
+/**
+ * Error thrown when storage configuration is invalid.
+ *
+ * @example
+ * ```typescript
+ * throw new StorageConfigError(
+ *   'redis',
+ *   'Either "client" or "config"/"url" must be provided'
+ * );
+ * ```
+ */
+export declare class StorageConfigError extends StorageError {
+    readonly backend: string;
+    constructor(backend: string, message: string);
+}
+/**
+ * Error thrown when TTL value is invalid.
+ *
+ * @example
+ * ```typescript
+ * throw new StorageTTLError(-1, 'TTL must be a positive integer');
+ * ```
+ */
+export declare class StorageTTLError extends StorageError {
+    readonly ttl: unknown;
+    constructor(ttl: unknown, message?: string);
+}
+/**
+ * Error thrown when a key pattern is invalid or potentially dangerous.
+ *
+ * @example
+ * ```typescript
+ * throw new StoragePatternError(
+ *   pattern,
+ *   'Pattern is too complex and may cause ReDoS'
+ * );
+ * ```
+ */
+export declare class StoragePatternError extends StorageError {
+    readonly pattern: string;
+    constructor(pattern: string, message: string);
+}
+/**
+ * Error thrown when storage is not connected.
+ *
+ * @example
+ * ```typescript
+ * throw new StorageNotConnectedError('redis');
+ * ```
+ */
+export declare class StorageNotConnectedError extends StorageError {
+    readonly backend: string;
+    constructor(backend: string);
+}

package/storage/factory.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Storage Factory
+ *
+ * Factory function to create storage adapters with auto-detection.
+ */
+import type { StorageConfig, StorageType, RootStorage } from './types';
+/**
+ * Create a storage instance.
+ *
+ * @param config - Storage configuration
+ * @returns Promise<RootStorage> - Namespaced storage instance
+ *
+ * @example Basic usage with auto-detection
+ * ```typescript
+ * const store = await createStorage();
+ * await store.set('key', 'value');
+ * ```
+ *
+ * @example Explicit type
+ * ```typescript
+ * const store = await createStorage({ type: 'redis', redis: { url: 'redis://localhost:6379' } });
+ * await store.connect();
+ * ```
+ *
+ * @example With namespaces
+ * ```typescript
+ * const store = await createStorage({ type: 'memory' });
+ * const session = store.namespace('session', sessionId);
+ * await session.set('user', JSON.stringify(user));
+ * // Key: session:{sessionId}:user
+ * ```
+ *
+ * @example With root prefix
+ * ```typescript
+ * const store = await createStorage({
+ *   type: 'redis',
+ *   prefix: 'myapp:',
+ *   redis: { host: 'localhost' }
+ * });
+ * // All keys will be prefixed with 'myapp:'
+ * ```
+ */
+export declare function createStorage(config?: StorageConfig): Promise<RootStorage>;
+/**
+ * Create a storage instance synchronously (memory only).
+ *
+ * Use this when you need synchronous creation and are okay with memory storage.
+ * For distributed storage, use the async `createStorage` function instead.
+ *
+ * @param config - Memory adapter options
+ * @returns RootStorage - Namespaced storage instance
+ *
+ * @example
+ * ```typescript
+ * const store = createMemoryStorage({ maxEntries: 1000 });
+ * store.connect().then(() => {
+ *   store.set('key', 'value');
+ * });
+ * ```
+ */
+export declare function createMemoryStorage(config?: import('./types').MemoryAdapterOptions & {
+    prefix?: string;
+}): RootStorage;
+/**
+ * Get the detected storage type without creating an adapter.
+ * Useful for logging or conditional logic.
+ *
+ * @returns The detected storage type
+ */
+export declare function getDetectedStorageType(): StorageType;

package/storage/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @frontmcp/utils - Storage Module
+ *
+ * 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, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, } from './types';
+export { createStorage, createMemoryStorage, getDetectedStorageType } from './factory';
+export { NamespacedStorageImpl, createRootStorage, createNamespacedStorage, buildPrefix, NAMESPACE_SEPARATOR, } from './namespace';
+export { StorageError, StorageConnectionError, StorageOperationError, StorageNotSupportedError, StorageConfigError, StorageTTLError, StoragePatternError, StorageNotConnectedError, } from './errors';
+export { BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, VercelKvStorageAdapter, UpstashStorageAdapter, } from './adapters';
+export { globToRegex, matchesPattern, validatePattern, escapeGlob } from './utils/pattern';
+export { MAX_TTL_SECONDS, validateTTL, validateOptionalTTL, ttlToExpiresAt, expiresAtToTTL, isExpired, normalizeTTL, } from './utils/ttl';

package/storage/namespace.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Namespaced Storage Implementation
+ *
+ * Wraps a StorageAdapter to provide namespace prefixing.
+ * All operations automatically prefix keys with the namespace path.
+ */
+import type { StorageAdapter, NamespacedStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe } from './types';
+/**
+ * Separator used between namespace segments.
+ */
+export declare const NAMESPACE_SEPARATOR = ":";
+/**
+ * Build a namespace prefix from name and optional id.
+ *
+ * @param name - Namespace name (e.g., 'session', 'user')
+ * @param id - Optional identifier (e.g., session ID, user ID)
+ * @returns Prefix string with trailing separator
+ *
+ * @example
+ * ```typescript
+ * buildPrefix('session', 'abc123');  // 'session:abc123:'
+ * buildPrefix('global');             // 'global:'
+ * ```
+ */
+export declare function buildPrefix(name: string, id?: string): string;
+/**
+ * Implementation of NamespacedStorage.
+ * Wraps a StorageAdapter and prefixes all keys.
+ */
+export declare class NamespacedStorageImpl implements NamespacedStorage {
+    private readonly adapter;
+    readonly prefix: string;
+    readonly root: StorageAdapter;
+    constructor(adapter: StorageAdapter, prefix?: string, root?: StorageAdapter);
+    /**
+     * Add prefix to a key.
+     */
+    private prefixKey;
+    /**
+     * Remove prefix from a key.
+     */
+    private unprefixKey;
+    /**
+     * Add prefix to a pattern (for keys() operation).
+     */
+    private prefixPattern;
+    /**
+     * Add prefix to a channel (for pub/sub).
+     */
+    private prefixChannel;
+    namespace(name: string, id?: string): NamespacedStorage;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    ping(): Promise<boolean>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: SetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    mget(keys: string[]): Promise<(string | null)[]>;
+    mset(entries: SetEntry[]): Promise<void>;
+    mdelete(keys: string[]): Promise<number>;
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    ttl(key: string): Promise<number | null>;
+    keys(pattern?: string): Promise<string[]>;
+    count(pattern?: string): Promise<number>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    incrBy(key: string, amount: number): Promise<number>;
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string, handler: MessageHandler): Promise<Unsubscribe>;
+    supportsPubSub(): boolean;
+}
+/**
+ * Create a root namespaced storage from an adapter.
+ * The root has an empty prefix.
+ *
+ * @param adapter - Storage adapter to wrap
+ * @returns RootStorage (NamespacedStorage with empty prefix)
+ */
+export declare function createRootStorage(adapter: StorageAdapter): NamespacedStorage;
+/**
+ * Create a namespaced storage with an initial prefix.
+ *
+ * @param adapter - Storage adapter to wrap
+ * @param prefix - Initial prefix (without trailing separator)
+ * @returns NamespacedStorage with the given prefix
+ */
+export declare function createNamespacedStorage(adapter: StorageAdapter, prefix: string): NamespacedStorage;