@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/logger/symbols-builder.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file Free-function helpers for per-instance log-symbol construction + symbol
+ *   stripping. Extracted from `logger/logger.ts` (the `Logger` class) so the
+ *   class stays under the 1000-line hard cap and so other callers (alt loggers,
+ *   format helpers) can reuse the same logic without instantiating a `Logger`.
+ *
+ *   - `buildLoggerSymbols` — theme + unicode-detection → `LogSymbols` map
+ *   - `stripLoggerSymbols` — strip leading status emoji from a string
+ */
+import type { LogSymbols } from './types';
+import type { Theme } from '../themes/types';
+/**
+ * Build a `LogSymbols` map for the given theme.
+ *
+ * On unicode-supporting terminals returns the canonical icons (`✔`, `✖`, `⚠`,
+ * `ℹ`, `→`, `∴`, `↻`); otherwise returns ASCII fallbacks (`√`, `×`, `‼`, `i`,
+ * `>`, `:.`, `@`). Colors are pulled from the supplied theme via `applyColor`.
+ */
+export declare function buildLoggerSymbols(theme: Theme): LogSymbols;
+/**
+ * Strip leading log-status symbols (and variation selectors) from a string.
+ * Matches both unicode forms (`✖`, `⚠`, `✔`, `ℹ`, `→`, `∴`, `↻`) and the
+ * unambiguous ASCII fallback `:.`. Does not strip lone ASCII letters (`i`, `>`,
+ * `@`) since those would mangle real words.
+ *
+ * Handles the trailing variation-selector U+FE0F + whitespace so a `'✔ Done'`
+ * input becomes `'Done'`.
+ */
+export declare function stripLoggerSymbols(text: string): string;

package/dist/logger/symbols-builder.js

@@ -0,0 +1,61 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var symbols_builder_exports = {};
+__export(symbols_builder_exports, {
+  buildLoggerSymbols: () => buildLoggerSymbols,
+  stripLoggerSymbols: () => stripLoggerSymbols
+});
+module.exports = __toCommonJS(symbols_builder_exports);
+var import_is_unicode_supported = __toESM(require("../external/@socketregistry/is-unicode-supported"));
+var import_string = require("../primordials/string");
+var import_colors = require("./colors");
+function buildLoggerSymbols(theme) {
+  const supported = (0, import_is_unicode_supported.default)();
+  const colors = (0, import_colors.getYoctocolors)();
+  return {
+    __proto__: null,
+    fail: (0, import_colors.applyColor)(supported ? "\u2716" : "\xD7", theme.colors.error, colors),
+    info: (0, import_colors.applyColor)(supported ? "\u2139" : "i", theme.colors.info, colors),
+    progress: (0, import_colors.applyColor)(supported ? "\u2234" : ":.", theme.colors.step, colors),
+    skip: (0, import_colors.applyColor)(supported ? "\u21BB" : "@", theme.colors.step, colors),
+    step: (0, import_colors.applyColor)(supported ? "\u2192" : ">", theme.colors.step, colors),
+    success: (0, import_colors.applyColor)(supported ? "\u2714" : "\u221A", theme.colors.success, colors),
+    warn: (0, import_colors.applyColor)(supported ? "\u26A0" : "\u203C", theme.colors.warning, colors)
+  };
+}
+function stripLoggerSymbols(text) {
+  return (0, import_string.StringPrototypeReplace)(text, /^(?:[✖✗×⚠‼✔✓√ℹ→∴↻]|:.)[️\s]*/u, "");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildLoggerSymbols,
+  stripLoggerSymbols
+});

package/dist/logger/symbols.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file Symbol exports + the `LOG_SYMBOLS` proxy. The two `Symbol.for(...)`
+ *   constants are how the spinner (and tests) reach into a `Logger` instance to
+ *   bump the call counter and toggle blank-line tracking without exposing
+ *   private fields. The `LOG_SYMBOLS` proxy is the public colored-symbol
+ *   palette that lazily initializes on first access (so importing the logger
+ *   during early Node.js bootstrap doesn't pre-resolve the theme before themes
+ *   are configured) and re-renders whenever `setTheme()` fires
+ *   `onThemeChange`.
+ */
+/**
+ * Lazily get console symbols on first access.
+ *
+ * Deferred to avoid accessing global console during early Node.js bootstrap
+ * before stdout is ready.
+ */
+export declare function getConsoleSymbols(): symbol[];
+/**
+ * Lazily get kGroupIndentationWidth symbol on first access.
+ */
+export declare function getKGroupIndentationWidthSymbol(): symbol;
+/**
+ * Symbol for incrementing the internal log call counter.
+ *
+ * This is an internal symbol used to track the number of times logging methods
+ * have been called on a logger instance.
+ */
+export declare const incLogCallCountSymbol: unique symbol;
+/**
+ * Symbol for tracking whether the last logged line was blank.
+ *
+ * This is used internally to prevent multiple consecutive blank lines and to
+ * determine whether to add spacing before certain messages.
+ */
+export declare const lastWasBlankSymbol: unique symbol;
+/**
+ * Log symbols for terminal output with colored indicators.
+ *
+ * Provides colored Unicode symbols (✖, ℹ, ∴, →, ✔, ⚠) with ASCII fallbacks (×,
+ * i, :., >, √, ‼) for terminals that don't support Unicode. Symbols are colored
+ * according to the active theme's color palette (error, info, reason, step,
+ * success, warning).
+ *
+ * The symbols are lazily initialized on first access and automatically update
+ * when the fallback theme changes (via setTheme()). Note that LOG_SYMBOLS
+ * reflect the global fallback theme, not async-local theme contexts from
+ * withTheme().
+ *
+ * @example
+ *   ```typescript
+ *   import { LOG_SYMBOLS } from '@socketsecurity/lib/logger/symbols'
+ *
+ *   console.log(`${LOG_SYMBOLS.fail} Build failed`) // Theme error color ✖
+ *   console.log(`${LOG_SYMBOLS.info} Starting process`) // Theme info color ℹ
+ *   console.log(`${LOG_SYMBOLS.progress} Working on task`) // Theme step color ∴
+ *   console.log(`${LOG_SYMBOLS.step} Processing files`) // Theme step color →
+ *   console.log(`${LOG_SYMBOLS.success} Build completed`) // Theme success color ✔
+ *   console.log(`${LOG_SYMBOLS.warn} Deprecated API used`) // Theme warning color ⚠
+ *   ```
+ */
+export declare const LOG_SYMBOLS: Record<string, string>;

package/dist/logger/symbols.js

@@ -0,0 +1,129 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var symbols_exports = {};
+__export(symbols_exports, {
+  LOG_SYMBOLS: () => LOG_SYMBOLS,
+  getConsoleSymbols: () => getConsoleSymbols,
+  getKGroupIndentationWidthSymbol: () => getKGroupIndentationWidthSymbol,
+  incLogCallCountSymbol: () => incLogCallCountSymbol,
+  lastWasBlankSymbol: () => lastWasBlankSymbol
+});
+module.exports = __toCommonJS(symbols_exports);
+var import_is_unicode_supported = __toESM(require("../external/@socketregistry/is-unicode-supported"));
+var import_globals = require("../primordials/globals");
+var import_object = require("../primordials/object");
+var import_reflect = require("../primordials/reflect");
+var import_context = require("../themes/context");
+var import_colors = require("./colors");
+var import_internal = require("./_internal");
+let _consoleSymbols;
+let _kGroupIndentationWidthSymbol;
+function getConsoleSymbols() {
+  if (_consoleSymbols === void 0) {
+    _consoleSymbols = (0, import_object.ObjectGetOwnPropertySymbols)(import_internal.globalConsole);
+  }
+  return _consoleSymbols;
+}
+function getKGroupIndentationWidthSymbol() {
+  if (_kGroupIndentationWidthSymbol === void 0) {
+    _kGroupIndentationWidthSymbol = getConsoleSymbols().find((s) => s.label === "kGroupIndentWidth") ?? Symbol("kGroupIndentWidth");
+  }
+  return _kGroupIndentationWidthSymbol;
+}
+const incLogCallCountSymbol = Symbol.for("logger.logCallCount++");
+const lastWasBlankSymbol = Symbol.for("logger.lastWasBlank");
+const LOG_SYMBOLS = /* @__PURE__ */ (() => {
+  const target = {
+    __proto__: null
+  };
+  let initialized = false;
+  const handler = {
+    __proto__: null
+  };
+  const updateSymbols = () => {
+    const supported = (0, import_is_unicode_supported.default)();
+    const colors = (0, import_colors.getYoctocolors)();
+    const theme = (0, import_context.getTheme)();
+    const successColor = theme.colors.success;
+    const errorColor = theme.colors.error;
+    const warningColor = theme.colors.warning;
+    const infoColor = theme.colors.info;
+    const stepColor = theme.colors.step;
+    target["fail"] = (0, import_colors.applyColor)(supported ? "\u2716" : "\xD7", errorColor, colors);
+    target["info"] = (0, import_colors.applyColor)(supported ? "\u2139" : "i", infoColor, colors);
+    target["progress"] = (0, import_colors.applyColor)(supported ? "\u2234" : ":.", stepColor, colors);
+    target["reason"] = colors.dim(
+      (0, import_colors.applyColor)(supported ? "\u2234" : ":.", warningColor, colors)
+    );
+    target["skip"] = (0, import_colors.applyColor)(supported ? "\u21BB" : "@", stepColor, colors);
+    target["step"] = (0, import_colors.applyColor)(supported ? "\u2192" : ">", stepColor, colors);
+    target["success"] = (0, import_colors.applyColor)(supported ? "\u2714" : "\u221A", successColor, colors);
+    target["warn"] = (0, import_colors.applyColor)(supported ? "\u26A0" : "\u203C", warningColor, colors);
+  };
+  const init = () => {
+    if (initialized) {
+      return;
+    }
+    updateSymbols();
+    initialized = true;
+    for (const trapName in handler) {
+      delete handler[trapName];
+    }
+  };
+  const reset = () => {
+    if (!initialized) {
+      return;
+    }
+    updateSymbols();
+  };
+  for (const trapName of (0, import_reflect.ReflectOwnKeys)(Reflect)) {
+    const fn = Reflect[trapName];
+    if (typeof fn === "function") {
+      ;
+      handler[trapName] = (...args) => {
+        init();
+        return fn(...args);
+      };
+    }
+  }
+  (0, import_context.onThemeChange)(() => {
+    reset();
+  });
+  return new import_globals.ProxyCtor(target, handler);
+})();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LOG_SYMBOLS,
+  getConsoleSymbols,
+  getKGroupIndentationWidthSymbol,
+  incLogCallCountSymbol,
+  lastWasBlankSymbol
+});

package/dist/logger/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @file Public type surface for `logger/*` modules — the `LogSymbols` shape,
+ *   the `LoggerMethods` mapped type that mirrors `console`, and the `Task`
+ *   interface returned by `Logger.createTask`. Pure types; no runtime side
+ *   effects so this module stays cheap to import everywhere.
+ */
+import type { Logger } from './logger';
+/**
+ * Log symbols for terminal output with colored indicators.
+ *
+ * Each symbol provides visual feedback for different message types, with
+ * Unicode and ASCII fallback support.
+ *
+ * @example
+ *   ```typescript
+ *   import { LOG_SYMBOLS } from '@socketsecurity/lib/logger/symbols'
+ *
+ *   console.log(`${LOG_SYMBOLS.success} Operation completed`)
+ *   console.log(`${LOG_SYMBOLS.fail} Operation failed`)
+ *   console.log(`${LOG_SYMBOLS.warn} Warning message`)
+ *   console.log(`${LOG_SYMBOLS.info} Information message`)
+ *   console.log(`${LOG_SYMBOLS.step} Processing step`)
+ *   console.log(`${LOG_SYMBOLS.progress} Working on task`)
+ *   ```
+ */
+export type LogSymbols = {
+    /**
+     * Red colored failure symbol (✖ or × in ASCII)
+     */
+    fail: string;
+    /**
+     * Blue colored information symbol (ℹ or i in ASCII)
+     */
+    info: string;
+    /**
+     * Cyan colored progress indicator symbol (∴ or :. in ASCII)
+     */
+    progress: string;
+    /**
+     * Cyan colored skip symbol (↻ or @ in ASCII)
+     */
+    skip: string;
+    /**
+     * Cyan colored step symbol (→ or > in ASCII)
+     */
+    step: string;
+    /**
+     * Green colored success symbol (✔ or √ in ASCII)
+     */
+    success: string;
+    /**
+     * Yellow colored warning symbol (⚠ or ‼ in ASCII)
+     */
+    warn: string;
+};
+/**
+ * Type definition for logger methods that mirror console methods.
+ *
+ * All methods return the logger instance for method chaining.
+ */
+export type LoggerMethods = {
+    [K in keyof typeof console]: (typeof console)[K] extends (...args: infer A) => any ? (...args: A) => Logger : (typeof console)[K];
+};
+/**
+ * A task that can be executed with automatic start/complete logging.
+ *
+ * @example
+ *   ;```typescript
+ *   const task = logger.createTask('Database migration')
+ *   task.run(() => {
+ *     // Migration logic here
+ *   })
+ *   // Logs: "Starting task: Database migration"
+ *   // Logs: "Completed task: Database migration"
+ *   ```
+ */
+export interface Task {
+    /**
+     * Executes the task function with automatic logging.
+     *
+     * @template T - The return type of the task function.
+     *
+     * @param f - The function to execute.
+     *
+     * @returns The result of the task function
+     */
+    run<T>(f: () => T): T;
+}

package/dist/logger/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/memo/_internal.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Private internals for `memo/*` modules — the shared `cacheRegistry`
+ *   (each memoize variant registers its per-instance clear function here so
+ *   `clearAllMemoizationCaches` can fan out). `defaultKeyGen` is co-located
+ *   because both `memoize` and `memoizeAsync` use it as the default cache-key
+ *   encoder.
+ */
+/**
+ * Global registry of memoization cache clear functions.
+ */
+export declare const cacheRegistry: Array<() => void>;
+/**
+ * Default cache key generator that disambiguates `undefined`, `BigInt`, and
+ * `Map`/`Set` arguments (which `JSON.stringify` drops or collapses).
+ */
+export declare function defaultKeyGen(args: readonly unknown[]): string;

package/dist/memo/_internal.js

@@ -0,0 +1,53 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"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);
+var internal_exports = {};
+__export(internal_exports, {
+  cacheRegistry: () => cacheRegistry,
+  defaultKeyGen: () => defaultKeyGen
+});
+module.exports = __toCommonJS(internal_exports);
+var import_json = require("../primordials/json");
+const cacheRegistry = [];
+function defaultKeyGen(args) {
+  return (0, import_json.JSONStringify)(args, (_key, value) => {
+    if (value === void 0) {
+      return "\0undefined";
+    }
+    if (typeof value === "bigint") {
+      return `\0bigint:${value.toString()}`;
+    }
+    if (typeof value === "function") {
+      return `\0fn:${value.name || "anonymous"}`;
+    }
+    if (value instanceof Map) {
+      return { __tag: "Map", entries: Array.from(value.entries()) };
+    }
+    if (value instanceof Set) {
+      return { __tag: "Set", values: Array.from(value.values()) };
+    }
+    return value;
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cacheRegistry,
+  defaultKeyGen
+});

package/dist/memo/async.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file `memoizeAsync` — async-aware memoizer with the same LRU+TTL contract as
+ *   `memoize`, plus thundering-herd dedup. Concurrent callers join an in-flight
+ *   promise instead of starting fresh fetches, and the cache timestamp is
+ *   refreshed on resolution so a slow fn can't land a value that's already
+ *   "expired".
+ */
+import type { MemoizeOptions } from './types';
+/**
+ * Memoize an async function. Similar to memoize() but handles promises
+ * properly.
+ *
+ * @example
+ *   import { memoizeAsync } from '@socketsecurity/lib/memo/async'
+ *
+ *   const fetchUser = memoizeAsync(
+ *     async (id: string) => {
+ *       const response = await fetch(`/api/users/${id}`)
+ *       return response.json()
+ *     },
+ *     { ttl: 300000, name: 'fetchUser' },
+ *   )
+ *
+ *   await fetchUser('123') // Fetches from API
+ *   await fetchUser('123') // Returns cached result
+ *
+ * @param fn - Async function to memoize.
+ * @param options - Memoization options.
+ *
+ * @returns Memoized version of the async function
+ */
+export declare function memoizeAsync<Args extends unknown[], Result>(fn: (...args: Args) => Promise<Result>, options?: MemoizeOptions<Args>): (...args: Args) => Promise<Result>;

package/dist/memo/async.js

@@ -0,0 +1,120 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"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);
+var async_exports = {};
+__export(async_exports, {
+  memoizeAsync: () => memoizeAsync
+});
+module.exports = __toCommonJS(async_exports);
+var import_output = require("../debug/output");
+var import_date = require("../primordials/date");
+var import_map_set = require("../primordials/map-set");
+var import_promise = require("../primordials/promise");
+var import_internal = require("./_internal");
+function memoizeAsync(fn, options = {}) {
+  const {
+    keyGen = (...args) => (0, import_internal.defaultKeyGen)(args),
+    maxSize = Number.POSITIVE_INFINITY,
+    name = fn.name || "anonymous",
+    ttl = Number.POSITIVE_INFINITY
+  } = options;
+  const cache = new import_map_set.MapCtor();
+  import_internal.cacheRegistry.push(() => {
+    cache.clear();
+  });
+  function evictLRU() {
+    if (cache.size >= maxSize) {
+      const oldest = cache.keys().next().value;
+      if (oldest !== void 0) {
+        cache.delete(oldest);
+        (0, import_output.debugLog)(`[memoizeAsync:${name}] clear`, {
+          key: oldest,
+          reason: "LRU"
+        });
+      }
+    }
+  }
+  function isExpired(entry) {
+    if (ttl === Number.POSITIVE_INFINITY) {
+      return false;
+    }
+    return (0, import_date.DateNow)() - entry.timestamp > ttl;
+  }
+  function bumpRecency(key, entry) {
+    cache.delete(key);
+    cache.set(key, entry);
+  }
+  const refreshing = new import_map_set.MapCtor();
+  return async function memoized(...args) {
+    const key = keyGen(...args);
+    const cached = cache.get(key);
+    if (cached) {
+      if (!isExpired(cached)) {
+        cached.hits++;
+        bumpRecency(key, cached);
+        (0, import_output.debugLog)(`[memoizeAsync:${name}] hit`, { key, hits: cached.hits });
+        return await cached.value;
+      }
+      const inflight = refreshing.get(key);
+      if (inflight) {
+        (0, import_output.debugLog)(`[memoizeAsync:${name}] stale-dedup`, { key });
+        bumpRecency(key, cached);
+        return await inflight;
+      }
+      cache.delete(key);
+    }
+    const inflightCold = refreshing.get(key);
+    if (inflightCold) {
+      (0, import_output.debugLog)(`[memoizeAsync:${name}] cold-dedup`, { key });
+      return await inflightCold;
+    }
+    (0, import_output.debugLog)(`[memoizeAsync:${name}] miss`, { key });
+    const promise = (async () => {
+      try {
+        const result = await fn(...args);
+        refreshing.delete(key);
+        const entry = cache.get(key);
+        if (entry) {
+          entry.value = (0, import_promise.PromiseResolve)(result);
+          entry.timestamp = (0, import_date.DateNow)();
+        }
+        return result;
+      } catch (error) {
+        refreshing.delete(key);
+        cache.delete(key);
+        (0, import_output.debugLog)(`[memoizeAsync:${name}] error`, { key, error });
+        throw error;
+      }
+    })();
+    refreshing.set(key, promise);
+    evictLRU();
+    cache.set(key, {
+      value: promise,
+      timestamp: Date.now(),
+      hits: 0
+    });
+    (0, import_output.debugLog)(`[memoizeAsync:${name}] set`, { key, cacheSize: cache.size });
+    return await promise;
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  memoizeAsync
+});

package/dist/memo/clear.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file `clearAllMemoizationCaches` — fan out to every per-cache clear function
+ *   registered in `_internal.cacheRegistry`. Useful for tests and for callers
+ *   that need to force recomputation across every memoize instance.
+ */
+/**
+ * Clear all memoization caches. Useful for testing or when you need to force
+ * recomputation.
+ *
+ * @example
+ *   ;```typescript
+ *   clearAllMemoizationCaches()
+ *   ```
+ */
+export declare function clearAllMemoizationCaches(): void;

package/dist/memo/clear.js

@@ -0,0 +1,37 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"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);
+var clear_exports = {};
+__export(clear_exports, {
+  clearAllMemoizationCaches: () => clearAllMemoizationCaches
+});
+module.exports = __toCommonJS(clear_exports);
+var import_output = require("../debug/output");
+var import_internal = require("./_internal");
+function clearAllMemoizationCaches() {
+  (0, import_output.debugLog)("[memoize:all] clear", { action: "clear-all-caches" });
+  for (const clear of import_internal.cacheRegistry) {
+    clear();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearAllMemoizationCaches
+});