@frontmcp/utils 1.12.0-rc.1 → 1.12.1

package/optional-module/index.d.ts

@@ -0,0 +1 @@
+export { registerOptionalModule, requireOptionalModule } from './optional-module';

package/optional-module/optional-module.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hand FrontMCP an optional package (`@frontmcp/observability`, `@frontmcp/storage-sqlite`) that the
+ * bundle already contains. On Cloudflare Workers `require()` cannot reach bundled
+ * modules, so the worker entry registers them here (#768). Kept on
+ * `globalThis` so a second copy of a FrontMCP package in the same bundle sees it too.
+ */
+export declare function registerOptionalModule(moduleName: string, moduleExports: unknown): void;
+/**
+ * Return a module registered with {@link registerOptionalModule}, or run
+ * `load` — pass a literal `() => require('pkg')` so bundlers still see it.
+ */
+export declare function requireOptionalModule<T>(moduleName: string, load: () => T): T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.12.0-rc.1",
+  "version": "1.12.1",
   "description": "Shared helpers for FrontMCP: URI templates, naming, cross-platform crypto and PKCE, key-value storage, file system and environment detection",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -28,12 +28,12 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@enclave-vm/ast": "^2.18.0",
+    "@enclave-vm/ast": "^2.19.2",
     "@noble/ciphers": "^2.1.1",
     "@noble/hashes": "^2.0.1"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.12.0-rc.1",
+    "@frontmcp/lazy-zod": "1.12.1",
     "@upstash/redis": "^1.34.0",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
     "ioredis": "^5.0.0"

package/redaction/redaction.d.ts

@@ -12,7 +12,7 @@ export type RedactedFields = readonly string[] | ((key: string) => boolean);
  *
  * @param obj - Object to redact fields from
  * @param fields - Field names to redact (case-insensitive), or a test on each key
- * @param maxDepth - Maximum recursion depth (default: 5)
+ * @param maxDepth - Maximum recursion depth (default: 5); an object or list below it becomes '[TRUNCATED]'
  * @returns New object with sensitive fields replaced by '[REDACTED]'
  */
 export declare function redactFields(obj: Record<string, unknown>, fields: RedactedFields, maxDepth?: number): Record<string, unknown>;

package/storage/adapters/filesystem.d.ts

@@ -88,6 +88,8 @@ export declare class FileSystemStorageAdapter extends BaseStorageAdapter {
     private readonly extension;
     private readonly dirMode;
     private readonly fileMode;
+    /** The last update queued for each key, so a counter's read and write never interleave with another update. */
+    private readonly keyUpdates;
     constructor(options: FileSystemAdapterOptions);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
@@ -97,11 +99,20 @@ export declare class FileSystemStorageAdapter extends BaseStorageAdapter {
     delete(key: string): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     expire(key: string, ttlSeconds: number): Promise<boolean>;
+    /** Set the expiry of `key` from its current entry; run only through {@link updateInTurn}. */
+    private expireNow;
     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>;
+    /** Add `amount` to the counter at `key`; run only through {@link updateInTurn}. */
+    private incrByNow;
+    /**
+     * Run `update` once the updates of `key` queued before it in this process have finished, so two updates of
+     * one key never read the same entry. Processes that share a directory are not coordinated.
+     */
+    private updateInTurn;
     /**
      * Convert a storage key to a file path.
      * Sanitizes the key to be filesystem-safe.

package/storage/adapters/memory.d.ts

@@ -34,7 +34,7 @@ export declare class MemoryStorageAdapter extends BaseStorageAdapter {
     private readonly emitter;
     private sweepInterval?;
     private readonly options;
-    private accessOrder;
+    private readonly accessOrder;
     constructor(options?: MemoryAdapterOptions);
     connect(): Promise<void>;
     disconnect(): Promise<void>;
@@ -76,7 +76,11 @@ export declare class MemoryStorageAdapter extends BaseStorageAdapter {
      */
     private removeLRU;
     /**
-     * Evict oldest entry (LRU).
+     * Evict least recently used entries until a new key fits within maxEntries.
+     */
+    private makeRoomFor;
+    /**
+     * Evict the least recently used entry. Returns false when no entry is left to evict.
      */
     private evictOldest;
     /**

package/storage/index.d.ts

@@ -20,5 +20,5 @@ 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, 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 { createGlobMatcher, globToRegex, matchesPattern, validatePattern, escapeGlob } from './utils/pattern';
 export { MAX_TTL_SECONDS, validateTTL, validateOptionalTTL, ttlToExpiresAt, expiresAtToTTL, isExpired, normalizeTTL, } from './utils/ttl';

package/storage/utils/index.d.ts

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

package/storage/utils/pattern.d.ts

@@ -1,15 +1,41 @@
 /**
  * Pattern Matching Utilities
  *
- * Convert glob patterns to regex for key matching.
- * Includes ReDoS protection to prevent denial-of-service attacks.
+ * Glob patterns for key matching: `*` matches any sequence, `?` matches one character, and a backslash makes the
+ * next character literal, as in Redis `SCAN MATCH`, so `escapeGlob()` output means the same thing on every backend.
+ * Matching runs without regular expressions, in time bounded by the key length times the pattern length.
  */
 /**
- * Convert a glob pattern to a RegExp.
+ * Compile a glob pattern into a function that tests whole keys.
  *
  * Supports:
  * - `*` matches any sequence of characters (including empty)
  * - `?` matches exactly one character
+ * - a backslash makes the next character literal, so `escapeGlob(value)` matches exactly `value`
+ *
+ * Unlike {@link globToRegex}, the matcher never backtracks: a pattern with many wildcards cannot stall the process.
+ *
+ * @param pattern - Glob pattern (e.g., "user:*:profile")
+ * @returns A function that reports whether a key matches the whole pattern
+ * @throws StoragePatternError if the pattern is too long or has too many wildcards
+ *
+ * @example
+ * ```typescript
+ * const isProfile = createGlobMatcher('user:*:profile');
+ * isProfile('user:123:profile'); // true
+ * isProfile('user:profile');     // false
+ *
+ * const exact = createGlobMatcher(`id:${escapeGlob('a*b')}`);
+ * exact('id:a*b');  // true
+ * exact('id:axxb'); // false
+ * ```
+ */
+export declare function createGlobMatcher(pattern: string): (key: string) => boolean;
+/**
+ * Convert a glob pattern to a RegExp.
+ *
+ * Supports `*`, `?` and backslash escapes, as {@link createGlobMatcher} does. The result is a backtracking regular
+ * expression; to test keys, use {@link createGlobMatcher} or {@link matchesPattern}, which do not backtrack.
  *
  * @param pattern - Glob pattern (e.g., "user:*:profile")
  * @returns RegExp for matching keys
@@ -56,7 +82,8 @@ export declare function validatePattern(pattern: string): {
 };
 /**
  * Escape a string for use as a literal in a glob pattern.
- * Escapes * and ? characters.
+ * Escapes `*`, `?`, `[`, `]` and backslash (Redis `SCAN MATCH` reads `[` as the start of a character class). Every
+ * matcher in this module, and Redis `SCAN MATCH`, reads the result as the literal string.
  *
  * @param literal - String to escape
  * @returns Escaped string safe for use in patterns