@frontmcp/utils 1.10.16 → 1.11.0-rc.2

package/browser/storage/adapters/localstorage.mjs

@@ -0,0 +1,222 @@
+// libs/utils/src/storage/adapters/localstorage.ts
+import { BaseStorageAdapter } from "./base.mjs";
+import { encryptAesGcm, decryptAesGcm, randomBytes, base64urlEncode, base64urlDecode } from "../../crypto/index.mjs";
+import { matchesPattern } from "../utils/pattern.mjs";
+var LocalStorageAdapter = class extends BaseStorageAdapter {
+  backendName = "localstorage";
+  prefix;
+  encryptionKey;
+  allowPlaintext;
+  encoder = new TextEncoder();
+  decoder = new TextDecoder();
+  constructor(options) {
+    super();
+    this.prefix = options?.prefix ?? "frontmcp:";
+    this.allowPlaintext = options?.allowPlaintext ?? true;
+    if (options?.encryptionKey) {
+      if (options.encryptionKey.length !== 32) {
+        throw new Error(`encryptionKey must be exactly 32 bytes, got ${options.encryptionKey.length}`);
+      }
+      this.encryptionKey = options.encryptionKey;
+    }
+  }
+  assertAvailable() {
+    if (typeof localStorage === "undefined") {
+      throw new Error("localStorage is not available in this environment");
+    }
+  }
+  key(k) {
+    return `${this.prefix}${k}`;
+  }
+  stripPrefix(fullKey) {
+    return fullKey.slice(this.prefix.length);
+  }
+  async connect() {
+    this.assertAvailable();
+    const probeKey = this.key("__probe__");
+    try {
+      localStorage.setItem(probeKey, "1");
+      const read = localStorage.getItem(probeKey);
+      if (read !== "1") {
+        throw new Error("localStorage probe: read-back mismatch");
+      }
+    } catch (err) {
+      throw new Error(`localStorage is not writable: ${err instanceof Error ? err.message : String(err)}`);
+    } finally {
+      try {
+        localStorage.removeItem(probeKey);
+      } catch {
+      }
+    }
+    this.connected = true;
+  }
+  async disconnect() {
+    this.connected = false;
+  }
+  async ping() {
+    const probeKey = this.key("__probe__");
+    try {
+      this.assertAvailable();
+      localStorage.setItem(probeKey, "1");
+      return localStorage.getItem(probeKey) === "1";
+    } catch {
+      return false;
+    } finally {
+      try {
+        localStorage.removeItem(probeKey);
+      } catch {
+      }
+    }
+  }
+  async get(key) {
+    const raw = localStorage.getItem(this.key(key));
+    if (raw === null) return null;
+    try {
+      const entry = JSON.parse(raw);
+      if (entry.e && entry.e < Date.now()) {
+        localStorage.removeItem(this.key(key));
+        return null;
+      }
+      if (entry._enc) {
+        if (!this.encryptionKey) return null;
+        const iv = base64urlDecode(entry._enc.iv);
+        const tag = base64urlDecode(entry._enc.tag);
+        const ciphertext = base64urlDecode(entry._enc.data);
+        const plainBytes = decryptAesGcm(this.encryptionKey, ciphertext, iv, tag);
+        return this.decoder.decode(plainBytes);
+      }
+      return entry.v;
+    } catch {
+      return null;
+    }
+  }
+  async set(key, value, options) {
+    if (options?.ifNotExists) {
+      const existing = await this.get(key);
+      if (existing !== null) return;
+    }
+    if (options?.ifExists) {
+      const existing = await this.get(key);
+      if (existing === null) return;
+    }
+    await this.doSet(key, value, options);
+  }
+  async doSet(key, value, options) {
+    const entry = { v: "" };
+    if (options?.ttlSeconds) {
+      entry.e = Date.now() + options.ttlSeconds * 1e3;
+    }
+    if (this.encryptionKey) {
+      const iv = randomBytes(12);
+      const plainBytes = this.encoder.encode(value);
+      const { ciphertext, tag } = encryptAesGcm(this.encryptionKey, plainBytes, iv);
+      entry._enc = {
+        alg: "A256GCM",
+        iv: base64urlEncode(iv),
+        tag: base64urlEncode(tag),
+        data: base64urlEncode(ciphertext)
+      };
+    } else {
+      if (!this.allowPlaintext) {
+        throw new Error("Plaintext storage is disabled. Provide an encryptionKey or set allowPlaintext: true.");
+      }
+      entry.v = value;
+    }
+    localStorage.setItem(this.key(key), JSON.stringify(entry));
+  }
+  async delete(key) {
+    const existed = await this.get(key) !== null;
+    localStorage.removeItem(this.key(key));
+    return existed;
+  }
+  async exists(key) {
+    return await this.get(key) !== null;
+  }
+  async mget(keys) {
+    return Promise.all(keys.map((k) => this.get(k)));
+  }
+  async mset(entries) {
+    for (const entry of entries) {
+      await this.set(entry.key, entry.value, entry.options);
+    }
+  }
+  async mdelete(keys) {
+    let count = 0;
+    for (const key of keys) {
+      if (await this.delete(key)) count++;
+    }
+    return count;
+  }
+  async expire(key, ttlSeconds) {
+    const value = await this.get(key);
+    if (value === null) return false;
+    await this.set(key, value, { ttlSeconds });
+    return true;
+  }
+  async ttl(key) {
+    const raw = localStorage.getItem(this.key(key));
+    if (raw === null) return null;
+    try {
+      const entry = JSON.parse(raw);
+      if (!entry.e) return -1;
+      const remaining = Math.ceil((entry.e - Date.now()) / 1e3);
+      return remaining > 0 ? remaining : null;
+    } catch {
+      return null;
+    }
+  }
+  async keys(pattern) {
+    const result = [];
+    const candidates = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const fullKey = localStorage.key(i);
+      if (fullKey && fullKey.startsWith(this.prefix)) {
+        candidates.push(this.stripPrefix(fullKey));
+      }
+    }
+    for (const key of candidates) {
+      if (!pattern || pattern === "*" || this.matchPattern(key, pattern)) {
+        if (await this.get(key) !== null) {
+          result.push(key);
+        }
+      }
+    }
+    return result;
+  }
+  async count(pattern) {
+    return (await this.keys(pattern)).length;
+  }
+  async incr(key) {
+    return this.incrBy(key, 1);
+  }
+  async decr(key) {
+    return this.incrBy(key, -1);
+  }
+  async incrBy(key, amount) {
+    if (!Number.isInteger(amount)) {
+      throw new Error(`amount must be an integer, got ${amount}`);
+    }
+    const current = await this.get(key);
+    if (current !== null && !/^-?\d+$/.test(current)) {
+      throw new Error(`Value at "${key}" is not an integer`);
+    }
+    const value = current !== null ? parseInt(current, 10) + amount : amount;
+    await this.set(key, String(value));
+    return value;
+  }
+  async publish() {
+    throw new Error("LocalStorage adapter does not support pub/sub");
+  }
+  async subscribe(_channel, _handler) {
+    throw new Error("LocalStorage adapter does not support pub/sub");
+  }
+  supportsPubSub() {
+    return false;
+  }
+  matchPattern(key, pattern) {
+    return matchesPattern(key, pattern);
+  }
+};
+export {
+  LocalStorageAdapter
+};

package/browser/storage/adapters/memory.mjs

@@ -0,0 +1,350 @@
+// libs/utils/src/storage/adapters/memory.ts
+import { EventEmitter } from "../../event-emitter/browser-event-emitter.mjs";
+import { StorageOperationError } from "../errors.mjs";
+import { globToRegex } from "../utils/pattern.mjs";
+import { expiresAtToTTL, isExpired, ttlToExpiresAt, validateTTL } from "../utils/ttl.mjs";
+import { BaseStorageAdapter } from "./base.mjs";
+var DEFAULT_SWEEP_INTERVAL_SECONDS = 60;
+var MAX_TIMEOUT_MS = 2147483647;
+var MemoryStorageAdapter = class extends BaseStorageAdapter {
+  backendName = "memory";
+  store = /* @__PURE__ */ new Map();
+  emitter = new EventEmitter();
+  sweepInterval;
+  options;
+  // LRU tracking (simple linked list via insertion order in Map)
+  accessOrder = [];
+  constructor(options = {}) {
+    super();
+    this.options = {
+      enableSweeper: options.enableSweeper ?? true,
+      sweepIntervalSeconds: options.sweepIntervalSeconds ?? DEFAULT_SWEEP_INTERVAL_SECONDS,
+      maxEntries: options.maxEntries ?? 0
+      // 0 = unlimited
+    };
+    this.emitter.setMaxListeners(1e3);
+  }
+  // ============================================
+  // Connection Lifecycle
+  // ============================================
+  async connect() {
+    if (this.connected) return;
+    this.connected = true;
+    if (this.options.enableSweeper && this.options.sweepIntervalSeconds > 0) {
+      this.startSweeper();
+    }
+  }
+  async disconnect() {
+    if (!this.connected) return;
+    this.stopSweeper();
+    this.clearAllTimeouts();
+    this.store.clear();
+    this.accessOrder = [];
+    this.emitter.removeAllListeners();
+    this.connected = false;
+  }
+  async ping() {
+    return this.connected;
+  }
+  // ============================================
+  // Core Operations
+  // ============================================
+  async get(key) {
+    this.ensureConnected();
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (isExpired(entry.expiresAt)) {
+      this.deleteEntry(key);
+      return null;
+    }
+    this.touchLRU(key);
+    return entry.value;
+  }
+  async doSet(key, value, options) {
+    const existingEntry = this.store.get(key);
+    const exists = existingEntry !== void 0 && !isExpired(existingEntry.expiresAt);
+    if (options?.ifNotExists && exists) {
+      return;
+    }
+    if (options?.ifExists && !exists) {
+      return;
+    }
+    this.clearEntryTimeout(key);
+    const entry = { value };
+    if (options?.ttlSeconds) {
+      entry.expiresAt = ttlToExpiresAt(options.ttlSeconds);
+      const ttlMs = options.ttlSeconds * 1e3;
+      if (ttlMs < MAX_TIMEOUT_MS) {
+        entry.timeout = setTimeout(() => {
+          this.deleteEntry(key);
+        }, ttlMs);
+        if (entry.timeout.unref) {
+          entry.timeout.unref();
+        }
+      }
+    }
+    if (this.options.maxEntries > 0 && !this.store.has(key)) {
+      while (this.store.size >= this.options.maxEntries) {
+        this.evictOldest();
+      }
+    }
+    this.store.set(key, entry);
+    this.touchLRU(key);
+  }
+  async delete(key) {
+    this.ensureConnected();
+    return this.deleteEntry(key);
+  }
+  async deleteIfEquals(key, expectedValue) {
+    this.ensureConnected();
+    const entry = this.store.get(key);
+    if (!entry || isExpired(entry.expiresAt) || entry.value !== expectedValue) return false;
+    return this.deleteEntry(key);
+  }
+  async expireIfEquals(key, expectedValue, ttlSeconds) {
+    this.ensureConnected();
+    const entry = this.store.get(key);
+    if (!entry || isExpired(entry.expiresAt) || entry.value !== expectedValue) return false;
+    return this.expire(key, ttlSeconds);
+  }
+  async setIfEquals(key, expectedValue, value) {
+    this.ensureConnected();
+    const entry = this.store.get(key);
+    if (!entry || isExpired(entry.expiresAt) || entry.value !== expectedValue) return false;
+    await this.doSet(key, value);
+    return true;
+  }
+  async exists(key) {
+    this.ensureConnected();
+    const entry = this.store.get(key);
+    if (!entry) return false;
+    if (isExpired(entry.expiresAt)) {
+      this.deleteEntry(key);
+      return false;
+    }
+    return true;
+  }
+  // ============================================
+  // TTL Operations
+  // ============================================
+  async expire(key, ttlSeconds) {
+    this.ensureConnected();
+    validateTTL(ttlSeconds);
+    const entry = this.store.get(key);
+    if (!entry || isExpired(entry.expiresAt)) {
+      return false;
+    }
+    this.clearEntryTimeout(key);
+    entry.expiresAt = ttlToExpiresAt(ttlSeconds);
+    const ttlMs = ttlSeconds * 1e3;
+    if (ttlMs < MAX_TIMEOUT_MS) {
+      entry.timeout = setTimeout(() => {
+        this.deleteEntry(key);
+      }, ttlMs);
+      if (entry.timeout.unref) {
+        entry.timeout.unref();
+      }
+    }
+    return true;
+  }
+  async ttl(key) {
+    this.ensureConnected();
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (isExpired(entry.expiresAt)) {
+      this.deleteEntry(key);
+      return null;
+    }
+    if (entry.expiresAt === void 0) {
+      return -1;
+    }
+    return expiresAtToTTL(entry.expiresAt);
+  }
+  // ============================================
+  // Key Enumeration
+  // ============================================
+  async keys(pattern = "*") {
+    this.ensureConnected();
+    const regex = globToRegex(pattern);
+    const result = [];
+    for (const [key, entry] of this.store) {
+      if (isExpired(entry.expiresAt)) {
+        this.deleteEntry(key);
+        continue;
+      }
+      if (regex.test(key)) {
+        result.push(key);
+      }
+    }
+    return result;
+  }
+  // ============================================
+  // Atomic Operations
+  // ============================================
+  async incr(key) {
+    return this.incrBy(key, 1);
+  }
+  async decr(key) {
+    return this.incrBy(key, -1);
+  }
+  async incrBy(key, amount) {
+    this.ensureConnected();
+    const entry = this.store.get(key);
+    let currentValue = 0;
+    if (entry && !isExpired(entry.expiresAt)) {
+      const parsed = parseInt(entry.value, 10);
+      if (isNaN(parsed)) {
+        throw new StorageOperationError("incrBy", key, "Value is not an integer");
+      }
+      currentValue = parsed;
+    }
+    const newValue = currentValue + amount;
+    const newEntry = { value: String(newValue) };
+    if (entry?.expiresAt && !isExpired(entry.expiresAt)) {
+      newEntry.expiresAt = entry.expiresAt;
+      const remainingMs = entry.expiresAt - Date.now();
+      if (remainingMs > 0 && remainingMs < MAX_TIMEOUT_MS) {
+        this.clearEntryTimeout(key);
+        newEntry.timeout = setTimeout(() => {
+          this.deleteEntry(key);
+        }, remainingMs);
+        if (newEntry.timeout.unref) {
+          newEntry.timeout.unref();
+        }
+      }
+    }
+    this.store.set(key, newEntry);
+    this.touchLRU(key);
+    return newValue;
+  }
+  // ============================================
+  // Pub/Sub
+  // ============================================
+  supportsPubSub() {
+    return true;
+  }
+  async publish(channel, message) {
+    this.ensureConnected();
+    return this.emitter.listenerCount(channel) > 0 ? (this.emitter.emit(channel, message, channel), this.emitter.listenerCount(channel)) : 0;
+  }
+  async subscribe(channel, handler) {
+    this.ensureConnected();
+    const wrappedHandler = (message, ch) => {
+      handler(message, ch);
+    };
+    this.emitter.on(channel, wrappedHandler);
+    return async () => {
+      this.emitter.off(channel, wrappedHandler);
+    };
+  }
+  // ============================================
+  // Internal Helpers
+  // ============================================
+  /**
+   * Delete an entry and clear its timeout.
+   */
+  deleteEntry(key) {
+    const entry = this.store.get(key);
+    if (!entry) return false;
+    this.clearEntryTimeout(key);
+    this.store.delete(key);
+    this.removeLRU(key);
+    return true;
+  }
+  /**
+   * Clear timeout for an entry.
+   */
+  clearEntryTimeout(key) {
+    const entry = this.store.get(key);
+    if (entry?.timeout) {
+      clearTimeout(entry.timeout);
+      entry.timeout = void 0;
+    }
+  }
+  /**
+   * Clear all timeouts.
+   */
+  clearAllTimeouts() {
+    for (const [key] of this.store) {
+      this.clearEntryTimeout(key);
+    }
+  }
+  /**
+   * Update LRU access order.
+   */
+  touchLRU(key) {
+    if (this.options.maxEntries <= 0) return;
+    const idx = this.accessOrder.indexOf(key);
+    if (idx !== -1) {
+      this.accessOrder.splice(idx, 1);
+    }
+    this.accessOrder.push(key);
+  }
+  /**
+   * Remove key from LRU tracking.
+   */
+  removeLRU(key) {
+    if (this.options.maxEntries <= 0) return;
+    const idx = this.accessOrder.indexOf(key);
+    if (idx !== -1) {
+      this.accessOrder.splice(idx, 1);
+    }
+  }
+  /**
+   * Evict oldest entry (LRU).
+   */
+  evictOldest() {
+    if (this.accessOrder.length === 0) return;
+    const oldestKey = this.accessOrder.shift();
+    if (oldestKey) {
+      this.deleteEntry(oldestKey);
+    }
+  }
+  /**
+   * Start background sweeper.
+   */
+  startSweeper() {
+    this.sweepInterval = setInterval(() => {
+      this.sweep();
+    }, this.options.sweepIntervalSeconds * 1e3);
+    if (this.sweepInterval.unref) {
+      this.sweepInterval.unref();
+    }
+  }
+  /**
+   * Stop background sweeper.
+   */
+  stopSweeper() {
+    if (this.sweepInterval) {
+      clearInterval(this.sweepInterval);
+      this.sweepInterval = void 0;
+    }
+  }
+  /**
+   * Sweep expired entries.
+   */
+  sweep() {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (entry.expiresAt && now >= entry.expiresAt) {
+        this.deleteEntry(key);
+      }
+    }
+  }
+  // ============================================
+  // Stats (for debugging)
+  // ============================================
+  /**
+   * Get storage statistics.
+   */
+  getStats() {
+    return {
+      size: this.store.size,
+      maxEntries: this.options.maxEntries,
+      sweeperActive: this.sweepInterval !== void 0
+    };
+  }
+};
+export {
+  MemoryStorageAdapter
+};