@frontmcp/utils 0.0.1 → 0.7.1

package/storage/types.d.ts

@@ -0,0 +1,428 @@
+/**
+ * Unified Storage Abstraction Types
+ *
+ * Provides a common interface for key-value storage backends.
+ * Supports Memory (dev), Redis (prod), Vercel KV (edge), and Upstash (edge + pub/sub).
+ */
+/**
+ * Options for set operations.
+ */
+export interface SetOptions {
+    /**
+     * Time-to-live in seconds.
+     * Must be a positive integer if provided.
+     */
+    ttlSeconds?: number;
+    /**
+     * Only set if key doesn't exist (NX in Redis).
+     * Mutually exclusive with `ifExists`.
+     */
+    ifNotExists?: boolean;
+    /**
+     * Only set if key already exists (XX in Redis).
+     * Mutually exclusive with `ifNotExists`.
+     */
+    ifExists?: boolean;
+}
+/**
+ * Entry for batch set operations.
+ */
+export interface SetEntry {
+    key: string;
+    value: string;
+    options?: SetOptions;
+}
+/**
+ * Message handler for pub/sub subscriptions.
+ */
+export type MessageHandler = (message: string, channel: string) => void;
+/**
+ * Unsubscribe function returned by subscribe().
+ */
+export type Unsubscribe = () => Promise<void>;
+/**
+ * Unified storage adapter interface.
+ *
+ * All values are stored as strings - callers handle serialization.
+ * This matches Redis behavior and provides consistent semantics across backends.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new MemoryStorageAdapter();
+ * await adapter.connect();
+ *
+ * // Store JSON data
+ * await adapter.set('user:123', JSON.stringify({ name: 'John' }), { ttlSeconds: 3600 });
+ *
+ * // Retrieve and parse
+ * const raw = await adapter.get('user:123');
+ * const user = raw ? JSON.parse(raw) : null;
+ *
+ * await adapter.disconnect();
+ * ```
+ */
+export interface StorageAdapter {
+    /**
+     * Initialize the storage connection.
+     * For memory adapter, this is a no-op.
+     * For Redis/Upstash, this establishes the connection.
+     *
+     * @throws StorageConnectionError if connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Gracefully close the storage connection.
+     * For memory adapter, clears data and stops timers.
+     * For Redis, closes the connection (if owned by this adapter).
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if storage is connected and healthy.
+     *
+     * @returns true if connected and responsive
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Get a value by key.
+     *
+     * @param key - Storage key
+     * @returns The value as string, or null if not found or expired
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set a value with optional TTL.
+     *
+     * @param key - Storage key
+     * @param value - String value to store
+     * @param options - Optional TTL and conditional flags
+     * @throws StorageOperationError if operation fails
+     */
+    set(key: string, value: string, options?: SetOptions): Promise<void>;
+    /**
+     * Delete a key.
+     *
+     * @param key - Storage key
+     * @returns true if key existed and was deleted, false otherwise
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Check if a key exists (and is not expired).
+     *
+     * @param key - Storage key
+     * @returns true if key exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get multiple values.
+     * Maintains order - returns null for missing keys.
+     *
+     * @param keys - Array of storage keys
+     * @returns Array of values (null for missing keys)
+     */
+    mget(keys: string[]): Promise<(string | null)[]>;
+    /**
+     * Set multiple values atomically (where supported).
+     * For memory adapter, operations are sequential.
+     * For Redis, uses MSET/pipeline for atomicity.
+     *
+     * @param entries - Array of key-value-options entries
+     */
+    mset(entries: SetEntry[]): Promise<void>;
+    /**
+     * Delete multiple keys.
+     *
+     * @param keys - Array of storage keys
+     * @returns Number of keys actually deleted
+     */
+    mdelete(keys: string[]): Promise<number>;
+    /**
+     * Update TTL on an existing key.
+     *
+     * @param key - Storage key
+     * @param ttlSeconds - New TTL in seconds (must be positive integer)
+     * @returns true if key exists and TTL was set, false if key doesn't exist
+     */
+    expire(key: string, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Get remaining TTL for a key.
+     *
+     * @param key - Storage key
+     * @returns TTL in seconds, -1 if no TTL, or null if key doesn't exist
+     */
+    ttl(key: string): Promise<number | null>;
+    /**
+     * List keys matching a pattern.
+     * Pattern supports glob-style wildcards:
+     * - `*` matches any sequence of characters
+     * - `?` matches a single character
+     *
+     * @param pattern - Glob pattern (default: '*' for all keys)
+     * @returns Array of matching keys
+     *
+     * @example
+     * ```typescript
+     * // Find all session keys
+     * const sessionKeys = await adapter.keys('session:*');
+     *
+     * // Find keys with specific format
+     * const userKeys = await adapter.keys('user:???:profile');
+     * ```
+     */
+    keys(pattern?: string): Promise<string[]>;
+    /**
+     * Count keys matching a pattern.
+     * More efficient than keys().length for large datasets.
+     *
+     * @param pattern - Glob pattern (default: '*' for all keys)
+     * @returns Number of matching keys
+     */
+    count(pattern?: string): Promise<number>;
+    /**
+     * Atomically increment a numeric value.
+     * Creates key with value 1 if it doesn't exist.
+     *
+     * @param key - Storage key
+     * @returns New value after increment
+     * @throws StorageOperationError if value is not a valid integer
+     */
+    incr(key: string): Promise<number>;
+    /**
+     * Atomically decrement a numeric value.
+     * Creates key with value -1 if it doesn't exist.
+     *
+     * @param key - Storage key
+     * @returns New value after decrement
+     * @throws StorageOperationError if value is not a valid integer
+     */
+    decr(key: string): Promise<number>;
+    /**
+     * Atomically increment by a specific amount.
+     * Creates key with value `amount` if it doesn't exist.
+     *
+     * @param key - Storage key
+     * @param amount - Amount to increment (can be negative)
+     * @returns New value after increment
+     * @throws StorageOperationError if value is not a valid integer
+     */
+    incrBy(key: string, amount: number): Promise<number>;
+    /**
+     * Publish a message to a channel.
+     * Not all adapters support pub/sub (e.g., Vercel KV doesn't).
+     *
+     * @param channel - Channel name
+     * @param message - Message string
+     * @returns Number of subscribers that received the message
+     * @throws StorageNotSupportedError if adapter doesn't support pub/sub
+     */
+    publish(channel: string, message: string): Promise<number>;
+    /**
+     * Subscribe to a channel.
+     * Not all adapters support pub/sub (e.g., Vercel KV doesn't).
+     *
+     * @param channel - Channel name
+     * @param handler - Function called when message is received
+     * @returns Unsubscribe function
+     * @throws StorageNotSupportedError if adapter doesn't support pub/sub
+     */
+    subscribe(channel: string, handler: MessageHandler): Promise<Unsubscribe>;
+    /**
+     * Check if this adapter supports pub/sub.
+     *
+     * @returns true if publish/subscribe are supported
+     */
+    supportsPubSub(): boolean;
+}
+/**
+ * A namespaced view of a storage adapter.
+ * Automatically prefixes all keys with the namespace path.
+ *
+ * @example
+ * ```typescript
+ * const store = createStorage({ type: 'memory' });
+ * await store.connect();
+ *
+ * // Create nested namespaces
+ * const session = store.namespace('session', 'abc123');
+ * // prefix: "session:abc123:"
+ *
+ * const user = session.namespace('user', '456');
+ * // prefix: "session:abc123:user:456:"
+ *
+ * await user.set('theme', 'dark');
+ * // Actual key: "session:abc123:user:456:theme"
+ * ```
+ */
+export interface NamespacedStorage extends StorageAdapter {
+    /**
+     * The full namespace prefix (e.g., "session:abc123:user:456:").
+     * Empty string for root storage.
+     */
+    readonly prefix: string;
+    /**
+     * Create a child namespace.
+     * Keys become: {parentPrefix}{name}:{id}:{key}
+     *
+     * @param name - Namespace name (e.g., 'session', 'user')
+     * @param id - Optional identifier (e.g., session ID, user ID)
+     * @returns A new NamespacedStorage with extended prefix
+     */
+    namespace(name: string, id?: string): NamespacedStorage;
+    /**
+     * Get the underlying root adapter (for advanced use).
+     * Use with caution - operations bypass namespace prefixing.
+     */
+    readonly root: StorageAdapter;
+}
+/**
+ * Root storage with namespace capability.
+ * The root itself has an empty prefix.
+ */
+export type RootStorage = NamespacedStorage;
+/**
+ * Options for memory storage adapter.
+ */
+export interface MemoryAdapterOptions {
+    /**
+     * Enable periodic sweeping of expired entries.
+     * @default true
+     */
+    enableSweeper?: boolean;
+    /**
+     * Sweep interval in seconds.
+     * @default 60
+     */
+    sweepIntervalSeconds?: number;
+    /**
+     * Maximum number of entries (LRU eviction when exceeded).
+     * @default unlimited (0)
+     */
+    maxEntries?: number;
+}
+/**
+ * Options for Redis storage adapter.
+ */
+export interface RedisAdapterOptions {
+    /**
+     * Use an existing Redis client (we won't close it).
+     * Mutually exclusive with `config` and `url`.
+     */
+    client?: unknown;
+    /**
+     * Redis connection configuration.
+     * Mutually exclusive with `client`.
+     */
+    config?: {
+        host: string;
+        port?: number;
+        password?: string;
+        db?: number;
+        tls?: boolean;
+    };
+    /**
+     * Redis connection URI.
+     * e.g., "redis://user:pass@host:6379/0"
+     * Mutually exclusive with `client`.
+     */
+    url?: string;
+    /**
+     * Key prefix applied to all keys.
+     * @default ''
+     */
+    keyPrefix?: string;
+}
+/**
+ * Options for Vercel KV storage adapter.
+ * Note: Vercel KV does NOT support pub/sub.
+ */
+export interface VercelKvAdapterOptions {
+    /**
+     * KV REST API URL.
+     * @default process.env.KV_REST_API_URL
+     */
+    url?: string;
+    /**
+     * KV REST API Token.
+     * @default process.env.KV_REST_API_TOKEN
+     */
+    token?: string;
+    /**
+     * Key prefix applied to all keys.
+     * @default ''
+     */
+    keyPrefix?: string;
+}
+/**
+ * Options for Upstash Redis storage adapter.
+ * Upstash supports pub/sub via REST API.
+ */
+export interface UpstashAdapterOptions {
+    /**
+     * Upstash Redis REST URL.
+     * @default process.env.UPSTASH_REDIS_REST_URL
+     */
+    url?: string;
+    /**
+     * Upstash Redis REST Token.
+     * @default process.env.UPSTASH_REDIS_REST_TOKEN
+     */
+    token?: string;
+    /**
+     * Key prefix applied to all keys.
+     * @default ''
+     */
+    keyPrefix?: string;
+    /**
+     * Enable pub/sub support.
+     * When enabled, creates additional connections for subscriptions.
+     * @default false
+     */
+    enablePubSub?: boolean;
+}
+/**
+ * Storage backend type.
+ */
+export type StorageType = 'memory' | 'redis' | 'vercel-kv' | 'upstash' | 'auto';
+/**
+ * Configuration for createStorage factory.
+ */
+export interface StorageConfig {
+    /**
+     * Storage backend type.
+     * - 'memory': In-memory (development/testing)
+     * - 'redis': Redis (production)
+     * - 'vercel-kv': Vercel KV (edge deployment, no pub/sub)
+     * - 'upstash': Upstash Redis (edge deployment, with pub/sub)
+     * - 'auto': Auto-detect based on environment variables
+     * @default 'auto'
+     */
+    type?: StorageType;
+    /**
+     * Memory adapter options (when type='memory').
+     */
+    memory?: MemoryAdapterOptions;
+    /**
+     * Redis adapter options (when type='redis').
+     */
+    redis?: RedisAdapterOptions;
+    /**
+     * Vercel KV adapter options (when type='vercel-kv').
+     */
+    vercelKv?: VercelKvAdapterOptions;
+    /**
+     * Upstash adapter options (when type='upstash').
+     */
+    upstash?: UpstashAdapterOptions;
+    /**
+     * Root namespace prefix for all keys.
+     * Applied on top of any adapter-specific prefix.
+     * @default ''
+     */
+    prefix?: string;
+    /**
+     * Fallback behavior when preferred backend is unavailable.
+     * - 'error': Throw error (default for production)
+     * - 'memory': Fall back to memory with warning
+     * @default 'error' in production (NODE_ENV=production), 'memory' otherwise
+     */
+    fallback?: 'error' | 'memory';
+}

package/storage/utils/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Storage Utilities
+ */
+export { globToRegex, matchesPattern, validatePattern, escapeGlob } from './pattern';
+export { MAX_TTL_SECONDS, validateTTL, validateOptionalTTL, ttlToExpiresAt, expiresAtToTTL, isExpired, normalizeTTL, } from './ttl';

package/storage/utils/pattern.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Pattern Matching Utilities
+ *
+ * Convert glob patterns to regex for key matching.
+ * Includes ReDoS protection to prevent denial-of-service attacks.
+ */
+/**
+ * Convert a glob pattern to a RegExp.
+ *
+ * Supports:
+ * - `*` matches any sequence of characters (including empty)
+ * - `?` matches exactly one character
+ *
+ * @param pattern - Glob pattern (e.g., "user:*:profile")
+ * @returns RegExp for matching keys
+ * @throws StoragePatternError if pattern is invalid or too complex
+ *
+ * @example
+ * ```typescript
+ * const regex = globToRegex('user:*:profile');
+ * regex.test('user:123:profile');  // true
+ * regex.test('user:abc:profile');  // true
+ * regex.test('user:profile');      // false (missing segment)
+ *
+ * const regex2 = globToRegex('session:???');
+ * regex2.test('session:abc');      // true
+ * regex2.test('session:ab');       // false (too short)
+ * regex2.test('session:abcd');     // false (too long)
+ * ```
+ */
+export declare function globToRegex(pattern: string): RegExp;
+/**
+ * Test if a key matches a glob pattern.
+ *
+ * @param key - Key to test
+ * @param pattern - Glob pattern
+ * @returns true if key matches pattern
+ *
+ * @example
+ * ```typescript
+ * matchesPattern('user:123:profile', 'user:*:profile');  // true
+ * matchesPattern('session:abc', 'session:???');         // true
+ * matchesPattern('other:key', 'user:*');                // false
+ * ```
+ */
+export declare function matchesPattern(key: string, pattern: string): boolean;
+/**
+ * Check if a pattern is valid without throwing.
+ *
+ * @param pattern - Glob pattern to validate
+ * @returns Object with valid flag and optional error message
+ */
+export declare function validatePattern(pattern: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Escape a string for use as a literal in a glob pattern.
+ * Escapes * and ? characters.
+ *
+ * @param literal - String to escape
+ * @returns Escaped string safe for use in patterns
+ *
+ * @example
+ * ```typescript
+ * const id = 'user*123?';
+ * const pattern = `key:${escapeGlob(id)}:*`;
+ * // pattern = 'key:user\\*123\\?:*'
+ * ```
+ */
+export declare function escapeGlob(literal: string): string;

package/storage/utils/ttl.d.ts

@@ -0,0 +1,54 @@
+/**
+ * TTL Validation Utilities
+ *
+ * Helper functions for validating and normalizing TTL values.
+ */
+/**
+ * Maximum TTL in seconds (roughly 100 years).
+ * Prevents integer overflow issues.
+ */
+export declare const MAX_TTL_SECONDS = 3153600000;
+/**
+ * Validate a TTL value.
+ *
+ * @param ttlSeconds - TTL in seconds
+ * @throws StorageTTLError if TTL is invalid
+ */
+export declare function validateTTL(ttlSeconds: number): void;
+/**
+ * Validate TTL if provided (optional TTL).
+ *
+ * @param ttlSeconds - Optional TTL in seconds
+ * @throws StorageTTLError if TTL is provided but invalid
+ */
+export declare function validateOptionalTTL(ttlSeconds: number | undefined): void;
+/**
+ * Calculate expiration timestamp from TTL.
+ *
+ * @param ttlSeconds - TTL in seconds
+ * @returns Expiration timestamp (Date.now() + ttlSeconds * 1000)
+ */
+export declare function ttlToExpiresAt(ttlSeconds: number): number;
+/**
+ * Calculate remaining TTL from expiration timestamp.
+ *
+ * @param expiresAt - Expiration timestamp
+ * @returns Remaining seconds, or 0 if expired
+ */
+export declare function expiresAtToTTL(expiresAt: number): number;
+/**
+ * Check if an expiration timestamp has passed.
+ *
+ * @param expiresAt - Expiration timestamp
+ * @returns true if expired (current time >= expiresAt)
+ */
+export declare function isExpired(expiresAt: number | undefined): boolean;
+/**
+ * Normalize TTL to seconds if provided in milliseconds.
+ * Useful for adapting from APIs that use milliseconds.
+ *
+ * @param ttl - TTL value
+ * @param unit - 'seconds' or 'milliseconds'
+ * @returns TTL in seconds
+ */
+export declare function normalizeTTL(ttl: number, unit: 'seconds' | 'milliseconds'): number;

package/uri/index.d.ts

@@ -0,0 +1,2 @@
+export { isValidMcpUri, extractUriScheme, isValidMcpUriTemplate } from './uri-validation';
+export { ParsedUriTemplate, parseUriTemplate, matchUriTemplate, expandUriTemplate, extractTemplateParams, isUriTemplate, } from './uri-template';

package/uri/uri-template.d.ts

@@ -0,0 +1,92 @@
+/**
+ * RFC 6570 Level 1 URI Template utilities.
+ *
+ * Provides parsing, matching, and expansion of URI templates using simple
+ * string substitution ({param} syntax). This implements RFC 6570 Level 1 only;
+ * advanced operators like {+path}, {#fragment}, or {?query} are not supported.
+ */
+/**
+ * Parsed URI template information.
+ */
+export interface ParsedUriTemplate {
+    /** Compiled regex pattern for matching URIs */
+    pattern: RegExp;
+    /** Ordered list of parameter names extracted from template */
+    paramNames: string[];
+}
+/**
+ * Parse a URI template (RFC 6570 Level 1) into a regex pattern and parameter names.
+ * Supports simple string substitution: {param}
+ *
+ * @param template - The URI template to parse
+ * @returns Parsed template with pattern and parameter names
+ * @throws Error if template is too long (>1000 chars) or has too many parameters (>50)
+ *
+ * @example
+ * parseUriTemplate("file:///{path}")
+ * // { pattern: /^file:\/\/\/([^/]+)$/, paramNames: ["path"] }
+ *
+ * parseUriTemplate("users/{userId}/posts/{postId}")
+ * // { pattern: /^users\/([^/]+)\/posts\/([^/]+)$/, paramNames: ["userId", "postId"] }
+ */
+export declare function parseUriTemplate(template: string): ParsedUriTemplate;
+/**
+ * Match a URI against a URI template and extract parameters.
+ * Returns null if no match, or an object with extracted parameters.
+ *
+ * @param template - The URI template
+ * @param uri - The URI to match against the template
+ * @returns Object with extracted parameters, or null if no match
+ *
+ * @example
+ * matchUriTemplate("file:///{path}", "file:///documents")
+ * // { path: "documents" }
+ *
+ * matchUriTemplate("users/{userId}/posts/{postId}", "users/123/posts/456")
+ * // { userId: "123", postId: "456" }
+ *
+ * matchUriTemplate("users/{id}", "products/123")
+ * // null (no match)
+ */
+export declare function matchUriTemplate(template: string, uri: string): Record<string, string> | null;
+/**
+ * Expand a URI template with the given parameters.
+ *
+ * @param template - The URI template
+ * @param params - Object with parameter values
+ * @returns Expanded URI with parameters substituted
+ * @throws Error if a required parameter is missing
+ *
+ * @example
+ * expandUriTemplate("file:///{path}", { path: "documents" })
+ * // "file:///documents"
+ *
+ * expandUriTemplate("users/{userId}/posts/{postId}", { userId: "123", postId: "456" })
+ * // "users/123/posts/456"
+ */
+export declare function expandUriTemplate(template: string, params: Record<string, string>): string;
+/**
+ * Extract parameter names from a URI template.
+ *
+ * @param template - The URI template
+ * @returns Array of parameter names in order of appearance
+ *
+ * @example
+ * extractTemplateParams("users/{userId}/posts/{postId}")
+ * // ["userId", "postId"]
+ *
+ * extractTemplateParams("file:///static/path")
+ * // []
+ */
+export declare function extractTemplateParams(template: string): string[];
+/**
+ * Check if a string is a URI template (contains {param} placeholders).
+ *
+ * @param uri - The string to check
+ * @returns true if the string contains template placeholders
+ *
+ * @example
+ * isUriTemplate("users/{userId}") // true
+ * isUriTemplate("users/123") // false
+ */
+export declare function isUriTemplate(uri: string): boolean;

package/uri/uri-validation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * URI validation utilities.
+ *
+ * Provides RFC 3986 compliant URI validation including scheme validation
+ * and extraction. These utilities are commonly used for validating resource URIs.
+ */
+/**
+ * Validate that a URI has a valid scheme per RFC 3986.
+ *
+ * @param uri - The URI to validate
+ * @returns true if the URI has a valid scheme, false otherwise
+ *
+ * @example
+ * isValidMcpUri('file:///path/to/file') // true
+ * isValidMcpUri('https://example.com/resource') // true
+ * isValidMcpUri('custom://my-resource') // true
+ * isValidMcpUri('/path/to/file') // false (no scheme)
+ * isValidMcpUri('123://invalid') // false (scheme must start with letter)
+ */
+export declare function isValidMcpUri(uri: string): boolean;
+/**
+ * Extract the scheme from a URI.
+ *
+ * @param uri - The URI to extract the scheme from
+ * @returns The scheme in lowercase, or null if no valid scheme found
+ *
+ * @example
+ * extractUriScheme('file:///path') // 'file'
+ * extractUriScheme('HTTPS://example.com') // 'https'
+ * extractUriScheme('/no/scheme') // null
+ */
+export declare function extractUriScheme(uri: string): string | null;
+/**
+ * Validate that a URI template has a valid scheme per RFC 3986.
+ * URI templates follow RFC 6570 and can contain template expressions like {var}.
+ * The scheme portion should still be a valid static scheme.
+ *
+ * @param uriTemplate - The URI template to validate
+ * @returns true if the URI template has a valid scheme, false otherwise
+ *
+ * @example
+ * isValidMcpUriTemplate('users://{userId}/profile') // true
+ * isValidMcpUriTemplate('file:///{path}') // true
+ * isValidMcpUriTemplate('{scheme}://dynamic') // false (scheme must be static)
+ */
+export declare function isValidMcpUriTemplate(uriTemplate: string): boolean;