@frontmcp/utils 1.8.6 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/utils",
-  "version": "1.8.6",
+  "version": "1.9.0",
   "description": "Shared utility functions for FrontMCP - string manipulation, URI handling, path utilities, and more",
   "author": "AgentFront <info@agentfront.dev>",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
     "@noble/hashes": "^2.0.1"
   },
   "peerDependencies": {
-    "@frontmcp/lazy-zod": "1.8.6",
+    "@frontmcp/lazy-zod": "1.9.0",
     "@vercel/kv": "^2.0.0 || ^3.0.0",
     "ioredis": "^5.0.0"
   },
@@ -47,32 +47,50 @@
   "imports": {
     "#crypto-provider": {
       "worker": "./crypto/node.js",
-      "browser": "./crypto/browser.js",
+      "browser": {
+        "import": "./esm/crypto/browser.mjs",
+        "default": "./crypto/browser.js"
+      },
       "default": "./crypto/node.js"
     },
     "#async-context": {
       "worker": "./async-context/node-async-context.js",
-      "browser": "./async-context/browser-async-context.js",
+      "browser": {
+        "import": "./esm/async-context/browser-async-context.mjs",
+        "default": "./async-context/browser-async-context.js"
+      },
       "default": "./async-context/node-async-context.js"
     },
     "#event-emitter": {
       "worker": "./event-emitter/node-event-emitter.js",
-      "browser": "./event-emitter/browser-event-emitter.js",
+      "browser": {
+        "import": "./esm/event-emitter/browser-event-emitter.mjs",
+        "default": "./event-emitter/browser-event-emitter.js"
+      },
       "default": "./event-emitter/node-event-emitter.js"
     },
     "#env": {
       "worker": "./env/node-env.js",
-      "browser": "./env/browser-env.js",
+      "browser": {
+        "import": "./esm/env/browser-env.mjs",
+        "default": "./env/browser-env.js"
+      },
       "default": "./env/node-env.js"
     },
     "#runtime-context": {
       "worker": "./env/runtime-context.js",
-      "browser": "./env/browser-runtime-context.js",
+      "browser": {
+        "import": "./esm/env/browser-runtime-context.mjs",
+        "default": "./env/browser-runtime-context.js"
+      },
       "default": "./env/runtime-context.js"
     },
     "#path": {
       "worker": "./path/node-path.js",
-      "browser": "./path/browser-path.js",
+      "browser": {
+        "import": "./esm/path/browser-path.mjs",
+        "default": "./path/browser-path.js"
+      },
       "default": "./path/node-path.js"
     }
   },

package/path/browser-path.js

@@ -0,0 +1,79 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// libs/utils/src/path/browser-path.ts
+var browser_path_exports = {};
+__export(browser_path_exports, {
+  basename: () => basename,
+  dirname: () => dirname,
+  extname: () => extname,
+  isAbsolute: () => isAbsolute,
+  join: () => join,
+  pathToFileURL: () => pathToFileURL,
+  resolve: () => resolve,
+  sep: () => sep
+});
+module.exports = __toCommonJS(browser_path_exports);
+function notAvailable(name) {
+  throw new Error(`path.${name}() is not available in browser environments`);
+}
+function resolve(..._segments) {
+  return notAvailable("resolve");
+}
+function join(..._segments) {
+  return notAvailable("join");
+}
+function basename(p, ext) {
+  const trimmed = p.replace(/[/\\]+$/, "");
+  const lastSep = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
+  let base = lastSep >= 0 ? trimmed.slice(lastSep + 1) : trimmed;
+  if (ext && base.endsWith(ext)) {
+    base = base.slice(0, -ext.length);
+  }
+  return base;
+}
+function dirname(_p) {
+  return notAvailable("dirname");
+}
+function extname(p) {
+  const base = basename(p);
+  const dotIndex = base.lastIndexOf(".");
+  return dotIndex > 0 ? base.slice(dotIndex) : "";
+}
+function isAbsolute(p) {
+  if (!p) return false;
+  if (p.startsWith("/") || p.startsWith("\\")) return true;
+  if (/^[A-Za-z]:[\\/]/.test(p)) return true;
+  return false;
+}
+function pathToFileURL(_p) {
+  return notAvailable("pathToFileURL");
+}
+var sep = "/";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  pathToFileURL,
+  resolve,
+  sep
+});

package/path/node-path.js

@@ -0,0 +1,45 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// libs/utils/src/path/node-path.ts
+var node_path_exports = {};
+__export(node_path_exports, {
+  basename: () => import_path.basename,
+  dirname: () => import_path.dirname,
+  extname: () => import_path.extname,
+  isAbsolute: () => import_path.isAbsolute,
+  join: () => import_path.join,
+  pathToFileURL: () => import_url.pathToFileURL,
+  resolve: () => import_path.resolve,
+  sep: () => import_path.sep
+});
+module.exports = __toCommonJS(node_path_exports);
+var import_path = require("path");
+var import_url = require("url");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  pathToFileURL,
+  resolve,
+  sep
+});

package/storage/adapters/base.d.ts

@@ -4,7 +4,7 @@
  * Abstract base class for storage adapters.
  * Provides common validation and default implementations.
  */
-import type { StorageAdapter, SetOptions, SetEntry, MessageHandler, Unsubscribe } from '../types';
+import type { MessageHandler, SetEntry, SetOptions, StorageAdapter, Unsubscribe } from '../types';
 /**
  * Abstract base class for storage adapters.
  * Subclasses must implement the abstract methods.
@@ -63,6 +63,11 @@ export declare abstract class BaseStorageAdapter implements StorageAdapter {
     abstract incr(key: string): Promise<number>;
     abstract decr(key: string): Promise<number>;
     abstract incrBy(key: string, amount: number): Promise<number>;
+    /**
+     * Default: not supported, since a read followed by a delete is not atomic.
+     * Override in adapters whose backend can compare and delete in one step.
+     */
+    deleteIfEquals(_key: string, _expectedValue: string): Promise<boolean>;
     /**
      * Default: pub/sub not supported.
      * Override in adapters that support it.

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

@@ -18,6 +18,7 @@ export declare class CloudflareKvStorageAdapter extends BaseStorageAdapter {
     incr(key: string): Promise<number>;
     decr(key: string): Promise<number>;
     incrBy(_key: string, _amount: number): Promise<number>;
+    deleteIfEquals(_key: string, _expectedValue: string): Promise<boolean>;
     protected getPubSubSuggestion(): string;
     /** Validate + enforce KV's 60s minimum `expirationTtl`. */
     private toExpirationTtl;

package/storage/adapters/index.d.ts

@@ -5,7 +5,8 @@
  */
 export { BaseStorageAdapter } from './base';
 export { MemoryStorageAdapter } from './memory';
-export { RedisStorageAdapter } from './redis';
+export { RedisStorageAdapter, createRedisClient } from './redis';
+export type { CreateRedisClientOptions } from './redis';
 export { VercelKvStorageAdapter } from './vercel-kv';
 export { UpstashStorageAdapter } from './upstash';
 export { CloudflareKvStorageAdapter } from './cloudflare-kv';

package/storage/adapters/memory.d.ts

@@ -4,8 +4,8 @@
  * In-memory storage implementation for development and testing.
  * Supports TTL, pattern matching, pub/sub via EventEmitter.
  */
+import type { MemoryAdapterOptions, MessageHandler, SetOptions, Unsubscribe } from '../types';
 import { BaseStorageAdapter } from './base';
-import type { MemoryAdapterOptions, SetOptions, MessageHandler, Unsubscribe } from '../types';
 /**
  * In-memory storage adapter.
  *
@@ -42,6 +42,7 @@ export declare class MemoryStorageAdapter extends BaseStorageAdapter {
     get(key: string): Promise<string | null>;
     protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
     delete(key: string): Promise<boolean>;
+    deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     expire(key: string, ttlSeconds: number): Promise<boolean>;
     ttl(key: string): Promise<number | null>;

package/storage/adapters/redis.d.ts

@@ -4,6 +4,7 @@
  * Redis-based storage implementation for production use.
  * Uses ioredis with dynamic import for browser compatibility.
  */
+import { type RedisErrorListenerOptions } from '../redis-error-listener';
 import type { MessageHandler, RedisAdapterOptions, SetOptions, Unsubscribe } from '../types';
 import { BaseStorageAdapter } from './base';
 type Redis = import('ioredis').Redis;
@@ -34,6 +35,7 @@ export declare class RedisStorageAdapter extends BaseStorageAdapter {
     private subscriber?;
     private readonly options;
     private readonly ownsClient;
+    private detachErrorListener?;
     private connecting?;
     private readonly keyPrefix;
     private readonly subscriptionHandlers;
@@ -53,6 +55,7 @@ export declare class RedisStorageAdapter extends BaseStorageAdapter {
     get(key: string): Promise<string | null>;
     protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
     delete(key: string): Promise<boolean>;
+    deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     mget(keys: string[]): Promise<(string | null)[]>;
     mset(entries: import('../types').SetEntry[]): Promise<void>;
@@ -87,4 +90,20 @@ export declare class RedisStorageAdapter extends BaseStorageAdapter {
      */
     getClient(): Redis | undefined;
 }
+export interface CreateRedisClientOptions {
+    url?: string;
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    tls?: boolean;
+    /** Prefix for the rate-limited connection-error log line. */
+    label?: string;
+    logger?: RedisErrorListenerOptions['logger'];
+}
+/**
+ * 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.
+ */
+export declare function createRedisClient(options: CreateRedisClientOptions): Redis;
 export {};

package/storage/adapters/upstash.d.ts

@@ -4,8 +4,8 @@
  * Upstash Redis (REST-based) storage implementation for edge deployment.
  * Supports pub/sub via Upstash's REST API with polling mechanism.
  */
+import type { MessageHandler, SetOptions, Unsubscribe, UpstashAdapterOptions } from '../types';
 import { BaseStorageAdapter } from './base';
-import type { UpstashAdapterOptions, SetOptions, MessageHandler, Unsubscribe } from '../types';
 /**
  * Upstash Redis storage adapter.
  *
@@ -52,6 +52,7 @@ export declare class UpstashStorageAdapter extends BaseStorageAdapter {
     get(key: string): Promise<string | null>;
     protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
     delete(key: string): Promise<boolean>;
+    deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     mget(keys: string[]): Promise<(string | null)[]>;
     mdelete(keys: string[]): Promise<number>;

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

@@ -4,8 +4,8 @@
  * Vercel KV (REST-based) storage implementation for edge deployment.
  * NOTE: Vercel KV does NOT support pub/sub. Use Upstash adapter instead.
  */
+import type { SetOptions, VercelKvAdapterOptions } from '../types';
 import { BaseStorageAdapter } from './base';
-import type { VercelKvAdapterOptions, SetOptions } from '../types';
 /**
  * Vercel KV storage adapter.
  *
@@ -47,6 +47,7 @@ export declare class VercelKvStorageAdapter extends BaseStorageAdapter {
     get(key: string): Promise<string | null>;
     protected doSet(key: string, value: string, options?: SetOptions): Promise<void>;
     delete(key: string): Promise<boolean>;
+    deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
     exists(key: string): Promise<boolean>;
     mget(keys: string[]): Promise<(string | null)[]>;
     mdelete(keys: string[]): Promise<number>;

package/storage/index.d.ts

@@ -6,13 +6,15 @@
  */
 export type { StorageAdapter, NamespacedStorage, RootStorage, SetOptions, SetEntry, MessageHandler, Unsubscribe, MemoryAdapterOptions, RedisAdapterOptions, 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 { 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, VercelKvStorageAdapter, UpstashStorageAdapter, FileSystemStorageAdapter, LocalStorageAdapter, IndexedDBStorageAdapter, } from './adapters';
-export type { FileSystemAdapterOptions, LocalStorageAdapterOptions, IndexedDBAdapterOptions } from './adapters';
+export { BaseStorageAdapter, MemoryStorageAdapter, RedisStorageAdapter, createRedisClient, VercelKvStorageAdapter, UpstashStorageAdapter, FileSystemStorageAdapter, LocalStorageAdapter, IndexedDBStorageAdapter, } from './adapters';
+export type { CreateRedisClientOptions, 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/namespace.d.ts

@@ -4,7 +4,7 @@
  * 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';
+import type { MessageHandler, NamespacedStorage, SetEntry, SetOptions, StorageAdapter, Unsubscribe } from './types';
 /**
  * Separator used between namespace segments.
  */
@@ -66,6 +66,7 @@ export declare class NamespacedStorageImpl implements NamespacedStorage {
     incr(key: string): Promise<number>;
     decr(key: string): Promise<number>;
     incrBy(key: string, amount: number): Promise<number>;
+    deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
     publish(channel: string, message: string): Promise<number>;
     subscribe(channel: string, handler: MessageHandler): Promise<Unsubscribe>;
     supportsPubSub(): boolean;

package/storage/redis-error-listener.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Permanent, rate-limited 'error' listener for ioredis clients.
+ *
+ * ioredis emits 'error' for every failed reconnect attempt. With no listener it
+ * prints "[ioredis] Unhandled error event" once per attempt, which floods logs
+ * while Redis is down. This listener swallows the event and logs at most once
+ * per interval, counting the errors it suppressed.
+ */
+export interface RedisErrorListenerOptions {
+    /** Name used in the log line, e.g. 'HA'. */
+    label?: string;
+    /** Logger to write to. Falls back to `console.warn`. */
+    logger?: {
+        warn: (message: string, ...meta: unknown[]) => void;
+    };
+    /** Minimum time between two log lines. Defaults to 30 seconds. */
+    intervalMs?: number;
+}
+export interface ErrorEmitterClient {
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    removeListener(event: 'error', listener: (error: Error) => void): unknown;
+}
+export declare const DEFAULT_REDIS_ERROR_LOG_INTERVAL_MS = 30000;
+/**
+ * Attach the listener and return a function that removes it.
+ */
+export declare function attachRedisErrorListener(client: ErrorEmitterClient, options?: RedisErrorListenerOptions): () => void;

package/storage/types.d.ts

@@ -205,6 +205,15 @@ export interface StorageAdapter {
      * @throws StorageOperationError if value is not a valid integer
      */
     incrBy(key: string, amount: number): Promise<number>;
+    /**
+     * Atomically delete a key only while it still holds `expectedValue` (compare-and-delete).
+     *
+     * @param key - Storage key
+     * @param expectedValue - The exact value the key must hold
+     * @returns true if this call deleted the key, false if it was missing or held another value
+     * @throws StorageNotSupportedError if the backend has no atomic compare-and-delete
+     */
+    deleteIfEquals?(key: string, expectedValue: string): Promise<boolean>;
     /**
      * Publish a message to a channel.
      * Not all adapters support pub/sub (e.g., Vercel KV doesn't).
@@ -267,6 +276,8 @@ export interface NamespacedStorage extends StorageAdapter {
      * @returns A new NamespacedStorage with extended prefix
      */
     namespace(name: string, id?: string): NamespacedStorage;
+    /** {@link StorageAdapter.deleteIfEquals}; throws StorageNotSupportedError when the adapter has none. */
+    deleteIfEquals(key: string, expectedValue: string): Promise<boolean>;
     /**
      * Get the underlying root adapter (for advanced use).
      * Use with caution - operations bypass namespace prefixing.

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

@@ -0,0 +1,2 @@
+/** Redis Lua script for `deleteIfEquals`: deletes KEYS[1] only while it holds ARGV[1], returning 1 or 0. */
+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";