@frontmcp/utils 1.9.1 → 1.9.3

package/storage/adapters/redis.d.ts

@@ -39,6 +39,9 @@ export declare class RedisStorageAdapter extends BaseStorageAdapter {
     private connecting?;
     private readonly keyPrefix;
     private readonly subscriptionHandlers;
+    private readonly connectionUrl?;
+    /** The connection options of a URL this adapter reads itself; undefined for one only ioredis reads. */
+    private readonly urlOptions?;
     constructor(options?: RedisAdapterOptions);
     connect(): Promise<void>;
     private openConnection;
@@ -73,6 +76,10 @@ export declare class RedisStorageAdapter extends BaseStorageAdapter {
      * Build Redis options from config.
      */
     private buildRedisOptions;
+    /**
+     * Create a client this adapter owns. A URL only ioredis reads goes to it as is.
+     */
+    private newClient;
     /**
      * Create subscriber connection.
      */
@@ -104,6 +111,9 @@ export interface CreateRedisClientOptions {
 /**
  * Create a plain ioredis client that reconnects on its own and never emits an unhandled
  * 'error' event. The caller owns the client and must `quit()`/`disconnect()` it.
+ *
+ * With a `url`, the other connection fields fill in only what the URL leaves out (port,
+ * password, db, tls), and one that contradicts it throws a `StorageConfigError`.
  */
 export declare function createRedisClient(options: CreateRedisClientOptions): Redis;
 export {};

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

@@ -6,6 +6,46 @@
  */
 import type { SetOptions, VercelKvAdapterOptions } from '../types';
 import { BaseStorageAdapter } from './base';
+type VercelKvClient = {
+    get: (key: string) => Promise<string | null>;
+    set: (key: string, value: string, options?: {
+        ex?: number;
+        nx?: boolean;
+        xx?: boolean;
+    }) => Promise<string | null>;
+    del: (...keys: string[]) => Promise<number>;
+    exists: (...keys: string[]) => Promise<number>;
+    mget: (...keys: string[]) => Promise<(string | null)[]>;
+    expire: (key: string, seconds: number) => Promise<number>;
+    ttl: (key: string) => Promise<number>;
+    incr: (key: string) => Promise<number>;
+    decr: (key: string) => Promise<number>;
+    incrby: (key: string, increment: number) => Promise<number>;
+    eval: (script: string, keys: string[], args: string[]) => Promise<unknown>;
+    scan: (cursor: number, options?: {
+        match?: string;
+        count?: number;
+    }) => Promise<[string, string[]]>;
+    keys: (pattern: string) => Promise<string[]>;
+};
+/** Where a Vercel KV client connects; both default to the `KV_REST_API_URL` / `KV_REST_API_TOKEN` variables. */
+export interface VercelKvConnection {
+    url?: string;
+    token?: string;
+}
+/**
+ * Build a `@vercel/kv` REST client, the one loader every FrontMCP Vercel KV store shares (#711).
+ *
+ * `@vercel/kv` sets `cache: 'default'` on every request, which Cloudflare Workers reject ("The
+ * 'cache' field on 'RequestInitializerDict' is not implemented" / "Unsupported cache mode:
+ * default"), and the module's `kv` singleton cannot take another value. So each store gets a client
+ * of its own with the fetch cache mode unset (the value `@vercel/kv` itself calls equivalent), and
+ * values are read back exactly as stored instead of being JSON-parsed.
+ *
+ * @param connection - URL and token; each falls back to its environment variable
+ * @returns The client, typed as the subset of it the caller uses
+ */
+export declare function createVercelKvClient<TClient = VercelKvClient>(connection?: VercelKvConnection): Promise<TClient>;
 /**
  * Vercel KV storage adapter.
  *
@@ -68,3 +108,4 @@ export declare class VercelKvStorageAdapter extends BaseStorageAdapter {
      */
     private unprefixKey;
 }
+export {};

package/storage/index.d.ts

@@ -4,17 +4,19 @@
  * 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 type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, RedisHostConnectionConfig, RedisUrlConnectionConfig, RedisUrlFillInConfig, VercelKvAdapterOptions, UpstashAdapterOptions, StorageType, StorageConfig, } from './types';
 export { createStorage, createMemoryStorage, getDetectedStorageType } from './factory';
 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';
+export type { RedisUrlConnection, RedisUrlMerge, RedisUrlSiblingFields } from './redis-url';
 export { NamespacedStorageImpl, createRootStorage, createNamespacedStorage, buildPrefix, NAMESPACE_SEPARATOR, } from './namespace';
 export { StorageError, StorageConnectionError, StorageOperationError, StorageNotSupportedError, StorageConfigError, StorageTTLError, StoragePatternError, StorageNotConnectedError, EncryptedStorageError, } from './errors';
 export { TypedStorage } from './typed-storage';
 export type { TypedStorageOptions, TypedSetOptions, TypedSetEntry } from './typed-storage.types';
 export { EncryptedTypedStorage } from './encrypted-typed-storage';
 export type { EncryptedTypedStorageOptions, EncryptedSetOptions, EncryptedSetEntry, EncryptionKey, StoredEncryptedBlob, ClientKeyBinding, } from './encrypted-typed-storage.types';
-export { BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, createRedisClient, VercelKvStorageAdapter, UpstashStorageAdapter, FileSystemStorageAdapter, LocalStorageAdapter, IndexedDBStorageAdapter, } from './adapters';
-export type { CreateRedisClientOptions, FileSystemAdapterOptions, LocalStorageAdapterOptions, IndexedDBAdapterOptions, } from './adapters';
+export { BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, createRedisClient, VercelKvStorageAdapter, createVercelKvClient, UpstashStorageAdapter, FileSystemStorageAdapter, LocalStorageAdapter, IndexedDBStorageAdapter, } from './adapters';
+export type { CreateRedisClientOptions, VercelKvConnection, FileSystemAdapterOptions, LocalStorageAdapterOptions, IndexedDBAdapterOptions, } 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/redis-url.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Connection fields that may be written beside a Redis `url`.
+ */
+export interface RedisUrlSiblingFields {
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    tls?: boolean;
+}
+/**
+ * What a `redis://` or `rediss://` URL states, read as ioredis reads it: the userinfo, port and path
+ * first, then the same names in its query. An empty username or password counts as left out.
+ */
+export interface RedisUrlConnection {
+    host?: string;
+    port?: number;
+    username?: string;
+    password?: string;
+    db?: number;
+    tls: boolean;
+    /** The query's other options, which ioredis takes as they are (`family` as a number). */
+    queryOptions: Record<string, string | number>;
+}
+/**
+ * Outcome of combining a Redis URL with the fields written beside it.
+ */
+export interface RedisUrlMerge {
+    /** What the URL states. */
+    connection: RedisUrlConnection;
+    /** Fields the URL leaves out that the sibling fields supply. */
+    fillIns: Pick<RedisUrlSiblingFields, 'port' | 'password' | 'db' | 'tls'>;
+    /** Sibling fields whose value contradicts the URL. */
+    conflicts: Array<keyof RedisUrlSiblingFields>;
+}
+/**
+ * Read a `redis://` or `rediss://` URL. Returns `undefined` for an unparseable URL or another
+ * scheme (such as a socket path), which only ioredis reads.
+ */
+export declare function readRedisUrl(rawUrl: string): RedisUrlConnection | undefined;
+/**
+ * The URL is the base: fields beside it fill in only what it leaves out (a
+ * port, a password, a database, TLS), and a field that contradicts what it
+ * states, in its userinfo, path or query, is a conflict the caller must reject
+ * (#768). Returns `undefined` for a URL {@link readRedisUrl} cannot read, which
+ * the caller reports on its own terms.
+ */
+export declare function mergeRedisUrlFields(rawUrl: string, fields: RedisUrlSiblingFields): RedisUrlMerge | undefined;
+/** Human-readable reason for {@link RedisUrlMerge.conflicts}. */
+export declare function describeRedisUrlConflicts(conflicts: RedisUrlMerge['conflicts']): string;

package/storage/types.d.ts

@@ -309,6 +309,31 @@ export interface MemoryAdapterOptions {
      */
     maxEntries?: number;
 }
+/**
+ * Redis connection by host.
+ */
+export interface RedisHostConnectionConfig {
+    host: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    tls?: boolean;
+    /** Unset for a host config (a config built from optional settings may carry `url: undefined`). */
+    url?: undefined;
+}
+/**
+ * Redis connection by URL (`redis://` / `rediss://`).
+ */
+export interface RedisUrlConnectionConfig extends Partial<Omit<RedisHostConnectionConfig, 'url'>> {
+    url: string;
+}
+/**
+ * Fields beside a top-level `url` (`{ url, config: { password } }`) that fill in what the URL
+ * leaves out. Without a `url` the adapter needs a `host` and rejects this shape.
+ */
+export interface RedisUrlFillInConfig extends Partial<Omit<RedisHostConnectionConfig, 'url'>> {
+    url?: undefined;
+}
 /**
  * Options for Redis storage adapter.
  */
@@ -319,19 +344,16 @@ export interface RedisAdapterOptions {
      */
     client?: unknown;
     /**
-     * Redis connection configuration.
+     * Redis connection configuration — `host`, or a `url` like the top-level
+     * `redis` option. Beside a URL, the other fields only fill in what the URL
+     * leaves out; a contradicting field is rejected.
      * Mutually exclusive with `client`.
      */
-    config?: {
-        host: string;
-        port?: number;
-        password?: string;
-        db?: number;
-        tls?: boolean;
-    };
+    config?: RedisHostConnectionConfig | RedisUrlConnectionConfig | RedisUrlFillInConfig;
     /**
      * Redis connection URI.
-     * e.g., "redis://user:pass@host:6379/0"
+     * e.g., "redis://user:pass@host:6379/0". Fields in `config` fill in what it
+     * leaves out (port, password, db, tls).
      * Mutually exclusive with `client`.
      */
     url?: string;