@frontmcp/utils 1.10.16 → 1.11.0-rc.1

package/browser/storage/namespace.mjs

@@ -0,0 +1,186 @@
+// libs/utils/src/storage/namespace.ts
+import { StorageNotSupportedError } from "./errors.mjs";
+var NAMESPACE_SEPARATOR = ":";
+function buildPrefix(name, id) {
+  if (id) {
+    return `${name}${NAMESPACE_SEPARATOR}${id}${NAMESPACE_SEPARATOR}`;
+  }
+  return `${name}${NAMESPACE_SEPARATOR}`;
+}
+var NamespacedStorageImpl = class _NamespacedStorageImpl {
+  constructor(adapter, prefix = "", root = adapter) {
+    this.adapter = adapter;
+    this.prefix = prefix;
+    this.root = root;
+  }
+  adapter;
+  prefix;
+  root;
+  // ============================================
+  // Key Prefixing Helpers
+  // ============================================
+  /**
+   * Add prefix to a key.
+   */
+  prefixKey(key) {
+    return this.prefix + key;
+  }
+  /**
+   * Remove prefix from a key.
+   */
+  unprefixKey(key) {
+    if (this.prefix && key.startsWith(this.prefix)) {
+      return key.slice(this.prefix.length);
+    }
+    return key;
+  }
+  /**
+   * Add prefix to a pattern (for keys() operation).
+   */
+  prefixPattern(pattern) {
+    return this.prefix + pattern;
+  }
+  /**
+   * Add prefix to a channel (for pub/sub).
+   */
+  prefixChannel(channel) {
+    return this.prefix + channel;
+  }
+  // ============================================
+  // Namespace API
+  // ============================================
+  namespace(name, id) {
+    const newPrefix = this.prefix + buildPrefix(name, id);
+    return new _NamespacedStorageImpl(this.adapter, newPrefix, this.root);
+  }
+  // ============================================
+  // Connection Lifecycle (delegated to root)
+  // ============================================
+  async connect() {
+    return this.adapter.connect();
+  }
+  async disconnect() {
+    return this.adapter.disconnect();
+  }
+  async ping() {
+    return this.adapter.ping();
+  }
+  // ============================================
+  // Core Operations (with prefixing)
+  // ============================================
+  async get(key) {
+    return this.adapter.get(this.prefixKey(key));
+  }
+  async set(key, value, options) {
+    return this.adapter.set(this.prefixKey(key), value, options);
+  }
+  async delete(key) {
+    return this.adapter.delete(this.prefixKey(key));
+  }
+  async exists(key) {
+    return this.adapter.exists(this.prefixKey(key));
+  }
+  // ============================================
+  // Batch Operations (with prefixing)
+  // ============================================
+  async mget(keys) {
+    const prefixedKeys = keys.map((k) => this.prefixKey(k));
+    return this.adapter.mget(prefixedKeys);
+  }
+  async mset(entries) {
+    const prefixedEntries = entries.map((e) => ({
+      ...e,
+      key: this.prefixKey(e.key)
+    }));
+    return this.adapter.mset(prefixedEntries);
+  }
+  async mdelete(keys) {
+    const prefixedKeys = keys.map((k) => this.prefixKey(k));
+    return this.adapter.mdelete(prefixedKeys);
+  }
+  // ============================================
+  // TTL Operations (with prefixing)
+  // ============================================
+  async expire(key, ttlSeconds) {
+    return this.adapter.expire(this.prefixKey(key), ttlSeconds);
+  }
+  async ttl(key) {
+    return this.adapter.ttl(this.prefixKey(key));
+  }
+  // ============================================
+  // Key Enumeration (with prefixing)
+  // ============================================
+  async keys(pattern = "*") {
+    const prefixedPattern = this.prefixPattern(pattern);
+    const keys = await this.adapter.keys(prefixedPattern);
+    return keys.map((k) => this.unprefixKey(k));
+  }
+  async count(pattern = "*") {
+    const prefixedPattern = this.prefixPattern(pattern);
+    return this.adapter.count(prefixedPattern);
+  }
+  // ============================================
+  // Atomic Operations (with prefixing)
+  // ============================================
+  async incr(key) {
+    return this.adapter.incr(this.prefixKey(key));
+  }
+  async decr(key) {
+    return this.adapter.decr(this.prefixKey(key));
+  }
+  async incrBy(key, amount) {
+    return this.adapter.incrBy(this.prefixKey(key), amount);
+  }
+  async deleteIfEquals(key, expectedValue) {
+    if (!this.adapter.deleteIfEquals) {
+      throw new StorageNotSupportedError("deleteIfEquals", "this storage adapter");
+    }
+    return this.adapter.deleteIfEquals(this.prefixKey(key), expectedValue);
+  }
+  async expireIfEquals(key, expectedValue, ttlSeconds) {
+    if (!this.adapter.expireIfEquals) {
+      throw new StorageNotSupportedError("expireIfEquals", "this storage adapter");
+    }
+    return this.adapter.expireIfEquals(this.prefixKey(key), expectedValue, ttlSeconds);
+  }
+  async setIfEquals(key, expectedValue, value) {
+    if (!this.adapter.setIfEquals) {
+      throw new StorageNotSupportedError("setIfEquals", "this storage adapter");
+    }
+    return this.adapter.setIfEquals(this.prefixKey(key), expectedValue, value);
+  }
+  // ============================================
+  // Pub/Sub (with channel prefixing)
+  // ============================================
+  async publish(channel, message) {
+    return this.adapter.publish(this.prefixChannel(channel), message);
+  }
+  async subscribe(channel, handler) {
+    const prefixedChannel = this.prefixChannel(channel);
+    const wrappedHandler = (message, ch) => {
+      const unprefixedChannel = ch.startsWith(this.prefix) ? ch.slice(this.prefix.length) : ch;
+      handler(message, unprefixedChannel);
+    };
+    return this.adapter.subscribe(prefixedChannel, wrappedHandler);
+  }
+  onPubSubReconnect(listener) {
+    return this.adapter.onPubSubReconnect?.(listener) ?? (() => void 0);
+  }
+  supportsPubSub() {
+    return this.adapter.supportsPubSub();
+  }
+};
+function createRootStorage(adapter) {
+  return new NamespacedStorageImpl(adapter, "", adapter);
+}
+function createNamespacedStorage(adapter, prefix) {
+  const normalizedPrefix = prefix && !prefix.endsWith(NAMESPACE_SEPARATOR) ? prefix + NAMESPACE_SEPARATOR : prefix;
+  return new NamespacedStorageImpl(adapter, normalizedPrefix, adapter);
+}
+export {
+  NAMESPACE_SEPARATOR,
+  NamespacedStorageImpl,
+  buildPrefix,
+  createNamespacedStorage,
+  createRootStorage
+};

package/browser/storage/redis-error-listener.mjs

@@ -0,0 +1,32 @@
+// libs/utils/src/storage/redis-error-listener.ts
+var DEFAULT_REDIS_ERROR_LOG_INTERVAL_MS = 3e4;
+function attachRedisErrorListener(client, options = {}) {
+  const label = options.label ?? "redis";
+  const intervalMs = options.intervalMs ?? DEFAULT_REDIS_ERROR_LOG_INTERVAL_MS;
+  let lastLoggedAt = 0;
+  let suppressed = 0;
+  const listener = (error) => {
+    const now = Date.now();
+    if (lastLoggedAt !== 0 && now - lastLoggedAt < intervalMs) {
+      suppressed++;
+      return;
+    }
+    const extra = suppressed > 0 ? ` (${suppressed} similar error(s) suppressed)` : "";
+    suppressed = 0;
+    lastLoggedAt = now;
+    const message = `[${label}] Redis connection error: ${error?.message ?? String(error)}${extra}`;
+    if (options.logger) {
+      options.logger.warn(message);
+    } else {
+      console.warn(message);
+    }
+  };
+  client.on("error", listener);
+  return () => {
+    client.removeListener("error", listener);
+  };
+}
+export {
+  DEFAULT_REDIS_ERROR_LOG_INTERVAL_MS,
+  attachRedisErrorListener
+};

package/browser/storage/redis-url.mjs

@@ -0,0 +1,66 @@
+// libs/utils/src/storage/redis-url.ts
+function decodeOrRaw(encoded) {
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return encoded;
+  }
+}
+function integerOrUndefined(text) {
+  const value = Number.parseInt(text ?? "", 10);
+  return Number.isNaN(value) ? void 0 : value;
+}
+function readRedisUrl(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "redis:" && url.protocol !== "rediss:") return void 0;
+  const query = Object.fromEntries(url.searchParams);
+  const { host, port, username, password, db, ...otherOptions } = query;
+  const queryOptions = {};
+  for (const [name, value = ""] of Object.entries(otherOptions)) {
+    queryOptions[name] = name === "family" ? integerOrUndefined(value) ?? value : value;
+  }
+  return {
+    host: url.hostname.replace(/^\[(.*)\]$/, "$1") || host,
+    port: integerOrUndefined(url.port || port),
+    username: decodeOrRaw(url.username) || username || void 0,
+    password: decodeOrRaw(url.password) || password || void 0,
+    db: integerOrUndefined(url.pathname.replace(/^\/+/, "") || db),
+    tls: url.protocol === "rediss:",
+    queryOptions
+  };
+}
+function mergeRedisUrlFields(rawUrl, fields) {
+  const connection = readRedisUrl(rawUrl);
+  if (!connection) return void 0;
+  const fillIns = {};
+  const conflicts = [];
+  if (fields.host !== void 0 && fields.host !== connection.host) conflicts.push("host");
+  if (fields.port !== void 0) {
+    if (connection.port === void 0) fillIns.port = fields.port;
+    else if (fields.port !== connection.port) conflicts.push("port");
+  }
+  if (fields.password !== void 0) {
+    if (connection.password === void 0) fillIns.password = fields.password;
+    else if (fields.password !== connection.password) conflicts.push("password");
+  }
+  if (fields.db !== void 0) {
+    if (connection.db === void 0) fillIns.db = fields.db;
+    else if (fields.db !== connection.db) conflicts.push("db");
+  }
+  if (fields.tls === true && !connection.tls) fillIns.tls = true;
+  if (fields.tls === false && connection.tls) conflicts.push("tls");
+  return { connection, fillIns, conflicts };
+}
+function describeRedisUrlConflicts(conflicts) {
+  return `redis ${conflicts.join(", ")} contradict${conflicts.length === 1 ? "s" : ""} redis.url. Fields beside a url only fill in what the URL leaves out (port, password, db, tls); put the value in the URL or drop the field.`;
+}
+export {
+  describeRedisUrlConflicts,
+  mergeRedisUrlFields,
+  readRedisUrl
+};

package/browser/storage/typed-storage.mjs

@@ -0,0 +1,171 @@
+// libs/utils/src/storage/typed-storage.ts
+var TypedStorage = class {
+  storage;
+  serialize;
+  deserialize;
+  schema;
+  throwOnInvalid;
+  constructor(storage, options = {}) {
+    this.storage = storage;
+    this.serialize = options.serialize ?? JSON.stringify;
+    this.deserialize = options.deserialize ?? JSON.parse;
+    this.schema = options.schema;
+    this.throwOnInvalid = options.throwOnInvalid ?? false;
+  }
+  /**
+   * Get a typed value by key.
+   *
+   * @param key - Storage key
+   * @returns The typed value, or null if not found or invalid
+   */
+  async get(key) {
+    const raw = await this.storage.get(key);
+    if (raw === null) {
+      return null;
+    }
+    return this.parseValue(raw, key);
+  }
+  /**
+   * Set a typed value with optional TTL.
+   *
+   * @param key - Storage key
+   * @param value - Typed value to store
+   * @param options - Optional TTL and conditional flags
+   */
+  async set(key, value, options) {
+    const serialized = this.serialize(value);
+    await this.storage.set(key, serialized, options);
+  }
+  /**
+   * Delete a key.
+   *
+   * @param key - Storage key
+   * @returns true if key existed and was deleted
+   */
+  async delete(key) {
+    return this.storage.delete(key);
+  }
+  /**
+   * Check if a key exists.
+   *
+   * @param key - Storage key
+   * @returns true if key exists
+   */
+  async exists(key) {
+    return this.storage.exists(key);
+  }
+  /**
+   * Get multiple typed values.
+   *
+   * @param keys - Array of storage keys
+   * @returns Array of typed values (null for missing/invalid keys)
+   */
+  async mget(keys) {
+    if (keys.length === 0) {
+      return [];
+    }
+    const rawValues = await this.storage.mget(keys);
+    return rawValues.map((raw, index) => {
+      if (raw === null) {
+        return null;
+      }
+      return this.parseValue(raw, keys[index]);
+    });
+  }
+  /**
+   * Set multiple typed values.
+   *
+   * @param entries - Array of key-value-options entries
+   */
+  async mset(entries) {
+    if (entries.length === 0) {
+      return;
+    }
+    const rawEntries = entries.map((entry) => ({
+      key: entry.key,
+      value: this.serialize(entry.value),
+      options: entry.options
+    }));
+    await this.storage.mset(rawEntries);
+  }
+  /**
+   * Delete multiple keys.
+   *
+   * @param keys - Array of storage keys
+   * @returns Number of keys actually deleted
+   */
+  async mdelete(keys) {
+    return this.storage.mdelete(keys);
+  }
+  /**
+   * Update TTL on an existing key.
+   *
+   * @param key - Storage key
+   * @param ttlSeconds - New TTL in seconds
+   * @returns true if key exists and TTL was set
+   */
+  async expire(key, ttlSeconds) {
+    return this.storage.expire(key, ttlSeconds);
+  }
+  /**
+   * 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
+   */
+  async ttl(key) {
+    return this.storage.ttl(key);
+  }
+  /**
+   * List keys matching a pattern.
+   *
+   * @param pattern - Glob pattern (default: '*' for all keys)
+   * @returns Array of matching keys
+   */
+  async keys(pattern) {
+    return this.storage.keys(pattern);
+  }
+  /**
+   * Count keys matching a pattern.
+   *
+   * @param pattern - Glob pattern (default: '*' for all keys)
+   * @returns Number of matching keys
+   */
+  async count(pattern) {
+    return this.storage.count(pattern);
+  }
+  /**
+   * Get the underlying storage adapter.
+   * Use with caution - operations bypass type safety.
+   */
+  get raw() {
+    return this.storage;
+  }
+  /**
+   * Parse and validate a raw value.
+   */
+  parseValue(raw, key) {
+    try {
+      const parsed = this.deserialize(raw);
+      if (this.schema) {
+        const result = this.schema.safeParse(parsed);
+        if (!result.success) {
+          if (this.throwOnInvalid) {
+            throw new Error(`TypedStorage validation failed for key "${key}": ${result.error.message}`);
+          }
+          return null;
+        }
+        return result.data;
+      }
+      return parsed;
+    } catch (error) {
+      if (this.throwOnInvalid) {
+        throw error;
+      }
+      return null;
+    }
+  }
+};
+export {
+  TypedStorage
+};

package/browser/storage/utils/compare-and-delete.mjs

@@ -0,0 +1,9 @@
+// libs/utils/src/storage/utils/compare-and-delete.ts
+var COMPARE_AND_DELETE_SCRIPT = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0`;
+var COMPARE_AND_EXPIRE_SCRIPT = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('EXPIRE', KEYS[1], ARGV[2]) end return 0`;
+var COMPARE_AND_SET_SCRIPT = `if redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('SET', KEYS[1], ARGV[2]) return 1 end return 0`;
+export {
+  COMPARE_AND_DELETE_SCRIPT,
+  COMPARE_AND_EXPIRE_SCRIPT,
+  COMPARE_AND_SET_SCRIPT
+};

package/browser/storage/utils/index.mjs

@@ -0,0 +1,24 @@
+// libs/utils/src/storage/utils/index.ts
+import { globToRegex, matchesPattern, validatePattern, escapeGlob } from "./pattern.mjs";
+import {
+  MAX_TTL_SECONDS,
+  validateTTL,
+  validateOptionalTTL,
+  ttlToExpiresAt,
+  expiresAtToTTL,
+  isExpired,
+  normalizeTTL
+} from "./ttl.mjs";
+export {
+  MAX_TTL_SECONDS,
+  escapeGlob,
+  expiresAtToTTL,
+  globToRegex,
+  isExpired,
+  matchesPattern,
+  normalizeTTL,
+  ttlToExpiresAt,
+  validateOptionalTTL,
+  validatePattern,
+  validateTTL
+};

package/browser/storage/utils/pattern.mjs

@@ -0,0 +1,68 @@
+// libs/utils/src/storage/utils/pattern.ts
+import { StoragePatternError } from "../errors.mjs";
+var MAX_PATTERN_LENGTH = 500;
+var MAX_WILDCARDS = 20;
+var REGEX_SPECIAL_CHARS = /[.+^${}()|[\]\\]/g;
+function globToRegex(pattern) {
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    throw new StoragePatternError(
+      pattern.substring(0, 50) + "...",
+      `Pattern exceeds maximum length of ${MAX_PATTERN_LENGTH} characters`
+    );
+  }
+  const wildcardCount = (pattern.match(/[*?]/g) || []).length;
+  if (wildcardCount > MAX_WILDCARDS) {
+    throw new StoragePatternError(pattern, `Pattern has too many wildcards (max: ${MAX_WILDCARDS})`);
+  }
+  if (pattern === "" || pattern === "*") {
+    return /^.*$/;
+  }
+  let regexStr = "^";
+  let prevChar = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    switch (char) {
+      case "*":
+        if (prevChar !== "*") {
+          regexStr += ".*";
+        }
+        break;
+      case "?":
+        regexStr += ".";
+        break;
+      default:
+        regexStr += char.replace(REGEX_SPECIAL_CHARS, "\\$&");
+    }
+    prevChar = char;
+  }
+  regexStr += "$";
+  try {
+    return new RegExp(regexStr);
+  } catch {
+    throw new StoragePatternError(pattern, "Failed to compile pattern to regex");
+  }
+}
+function matchesPattern(key, pattern) {
+  const regex = globToRegex(pattern);
+  return regex.test(key);
+}
+function validatePattern(pattern) {
+  try {
+    globToRegex(pattern);
+    return { valid: true };
+  } catch (e) {
+    return {
+      valid: false,
+      error: e instanceof Error ? e.message : "Invalid pattern"
+    };
+  }
+}
+function escapeGlob(literal) {
+  return literal.replace(/[*?\\]/g, "\\$&");
+}
+export {
+  escapeGlob,
+  globToRegex,
+  matchesPattern,
+  validatePattern
+};

package/browser/storage/utils/ttl.mjs

@@ -0,0 +1,48 @@
+// libs/utils/src/storage/utils/ttl.ts
+import { StorageTTLError } from "../errors.mjs";
+var MAX_TTL_SECONDS = 31536e5;
+function validateTTL(ttlSeconds) {
+  if (typeof ttlSeconds !== "number") {
+    throw new StorageTTLError(ttlSeconds, `TTL must be a number, got ${typeof ttlSeconds}`);
+  }
+  if (!Number.isFinite(ttlSeconds)) {
+    throw new StorageTTLError(ttlSeconds, "TTL must be a finite number");
+  }
+  if (!Number.isInteger(ttlSeconds)) {
+    throw new StorageTTLError(ttlSeconds, `TTL must be an integer, got ${ttlSeconds}`);
+  }
+  if (ttlSeconds <= 0) {
+    throw new StorageTTLError(ttlSeconds, `TTL must be positive, got ${ttlSeconds}`);
+  }
+  if (ttlSeconds > MAX_TTL_SECONDS) {
+    throw new StorageTTLError(ttlSeconds, `TTL exceeds maximum of ${MAX_TTL_SECONDS} seconds`);
+  }
+}
+function validateOptionalTTL(ttlSeconds) {
+  if (ttlSeconds !== void 0) {
+    validateTTL(ttlSeconds);
+  }
+}
+function ttlToExpiresAt(ttlSeconds) {
+  return Date.now() + ttlSeconds * 1e3;
+}
+function expiresAtToTTL(expiresAt) {
+  const remaining = Math.ceil((expiresAt - Date.now()) / 1e3);
+  return Math.max(0, remaining);
+}
+function isExpired(expiresAt) {
+  if (expiresAt === void 0) return false;
+  return Date.now() >= expiresAt;
+}
+function normalizeTTL(ttl, unit) {
+  return unit === "milliseconds" ? Math.ceil(ttl / 1e3) : ttl;
+}
+export {
+  MAX_TTL_SECONDS,
+  expiresAtToTTL,
+  isExpired,
+  normalizeTTL,
+  ttlToExpiresAt,
+  validateOptionalTTL,
+  validateTTL
+};

package/browser/uri/index.mjs

@@ -0,0 +1,19 @@
+// libs/utils/src/uri/index.ts
+import { isValidMcpUri, extractUriScheme, isValidMcpUriTemplate } from "./uri-validation.mjs";
+import {
+  parseUriTemplate,
+  matchUriTemplate,
+  expandUriTemplate,
+  extractTemplateParams,
+  isUriTemplate
+} from "./uri-template.mjs";
+export {
+  expandUriTemplate,
+  extractTemplateParams,
+  extractUriScheme,
+  isUriTemplate,
+  isValidMcpUri,
+  isValidMcpUriTemplate,
+  matchUriTemplate,
+  parseUriTemplate
+};