@jsenv/navi 0.0.1

package/src/utils/get_caller_info.js

@@ -0,0 +1,85 @@
+export const getCallerInfo = (targetFunction = null, additionalOffset = 0) => {
+  const originalPrepareStackTrace = Error.prepareStackTrace;
+  try {
+    Error.prepareStackTrace = (_, stack) => stack;
+
+    const error = new Error();
+    const stack = error.stack;
+
+    if (!stack || stack.length === 0 || !Array.isArray(stack)) {
+      return { raw: "unknown" };
+    }
+
+    let targetIndex = -1;
+
+    if (targetFunction) {
+      // ✅ Chercher la fonction cible par référence directe
+      for (let i = 0; i < stack.length; i++) {
+        const frame = stack[i];
+        const frameFunction = frame.getFunction();
+
+        // ✅ Comparaison directe par référence
+        if (frameFunction === targetFunction) {
+          targetIndex = i;
+          break;
+        }
+      }
+
+      if (targetIndex === -1) {
+        return {
+          raw: `target function not found in stack`,
+          targetFunction: targetFunction.name,
+        };
+      }
+
+      // ✅ Prendre la fonction qui appelle targetFunction + offset
+      const callerIndex = targetIndex + 1 + additionalOffset;
+
+      if (callerIndex >= stack.length) {
+        return {
+          raw: `caller at offset ${additionalOffset} not found`,
+          targetFunction: targetFunction.name,
+          requestedIndex: callerIndex,
+          stackLength: stack.length,
+        };
+      }
+
+      const callerFrame = stack[callerIndex];
+      return {
+        file: callerFrame.getFileName(),
+        line: callerFrame.getLineNumber(),
+        column: callerFrame.getColumnNumber(),
+        function: callerFrame.getFunctionName() || "<anonymous>",
+        raw: callerFrame.toString(),
+        targetFunction: targetFunction.name,
+        offset: additionalOffset,
+      };
+    }
+
+    // ✅ Comportement original si pas de targetFunction
+    if (stack.length > 2) {
+      const callerFrame = stack[2 + additionalOffset];
+
+      if (!callerFrame) {
+        return {
+          raw: `caller at offset ${additionalOffset} not found`,
+          requestedIndex: 2 + additionalOffset,
+          stackLength: stack.length,
+        };
+      }
+
+      return {
+        file: callerFrame.getFileName(),
+        line: callerFrame.getLineNumber(),
+        column: callerFrame.getColumnNumber(),
+        function: callerFrame.getFunctionName() || "<anonymous>",
+        raw: callerFrame.toString(),
+        offset: additionalOffset,
+      };
+    }
+
+    return { raw: "unknown" };
+  } finally {
+    Error.prepareStackTrace = originalPrepareStackTrace;
+  }
+};

package/src/utils/iterable_weak_set.js

@@ -0,0 +1,62 @@
+export const createIterableWeakSet = () => {
+  const objectWeakRefSet = new Set();
+
+  return {
+    add: (object) => {
+      const objectWeakRef = new WeakRef(object);
+      objectWeakRefSet.add(objectWeakRef);
+    },
+
+    delete: (object) => {
+      for (const weakRef of objectWeakRefSet) {
+        if (weakRef.deref() === object) {
+          objectWeakRefSet.delete(weakRef);
+          return true;
+        }
+      }
+      return false;
+    },
+
+    *[Symbol.iterator]() {
+      for (const objectWeakRef of objectWeakRefSet) {
+        const object = objectWeakRef.deref();
+        if (object === undefined) {
+          objectWeakRefSet.delete(objectWeakRef);
+          continue;
+        }
+        yield object;
+      }
+    },
+
+    has: (object) => {
+      for (const weakRef of objectWeakRefSet) {
+        const objectCandidate = weakRef.deref();
+        if (objectCandidate === undefined) {
+          objectWeakRefSet.delete(weakRef);
+          continue;
+        }
+        if (objectCandidate === object) {
+          return true;
+        }
+      }
+      return false;
+    },
+
+    get size() {
+      return objectWeakRefSet.size;
+    },
+
+    getStats: () => {
+      let alive = 0;
+      let dead = 0;
+      for (const weakRef of objectWeakRefSet) {
+        if (weakRef.deref() !== undefined) {
+          alive++;
+        } else {
+          dead++;
+        }
+      }
+      return { total: objectWeakRefSet.size, alive, dead };
+    },
+  };
+};

package/src/utils/js_value_weak_map.js

@@ -0,0 +1,162 @@
+/**
+ * jsenv/navi - createJsValueWeakMap
+ *
+ * Key/value cache with true ephemeron behavior and deep equality support.
+ *
+ * Features:
+ * - Mutual retention: key keeps value alive, value keeps key alive
+ * - Deep equality: different objects with same content are treated as identical keys
+ * - Automatic GC: entries are eligible for collection when unreferenced
+ * - Iteration support: can iterate over live entries for deep equality lookup
+ *
+ * Implementation:
+ * - Dual WeakMap (key->value, value->key) provides ephemeron behavior
+ * - WeakRef registry enables iteration without preventing GC
+ * - Primitives stored in Map (permanent retention - avoid for keys)
+ *
+ * Use case: Action caching where params (key) and action (value) should have
+ * synchronized lifetimes while allowing natural garbage collection.
+ */
+
+import { compareTwoJsValues } from "./compare_two_js_values.js";
+
+export const createJsValueWeakMap = () => {
+  // Core ephemeron maps for mutual retention
+  const keyToValue = new WeakMap(); // key -> value
+  const valueToKey = new WeakMap(); // value -> key
+
+  // Registry for iteration/deep equality (holds WeakRefs)
+  const keyRegistry = new Set(); // Set of WeakRef(key)
+
+  // Primitive cache
+  const primitiveCache = new Map();
+
+  function cleanupKeyRegistry() {
+    for (const keyRef of keyRegistry) {
+      if (keyRef.deref() === undefined) {
+        keyRegistry.delete(keyRef);
+      }
+    }
+  }
+
+  return {
+    *[Symbol.iterator]() {
+      cleanupKeyRegistry();
+      for (const keyRef of keyRegistry) {
+        const key = keyRef.deref();
+        if (key && keyToValue.has(key)) {
+          yield [key, keyToValue.get(key)];
+        }
+      }
+      for (const [k, v] of primitiveCache) {
+        yield [k, v];
+      }
+    },
+
+    get(key) {
+      const isObject =
+        key && (typeof key === "object" || typeof key === "function");
+      if (isObject) {
+        // Fast path: exact key match
+        if (keyToValue.has(key)) {
+          return keyToValue.get(key);
+        }
+
+        // Slow path: deep equality search
+        cleanupKeyRegistry();
+        for (const keyRef of keyRegistry) {
+          const existingKey = keyRef.deref();
+          if (existingKey && compareTwoJsValues(existingKey, key)) {
+            return keyToValue.get(existingKey);
+          }
+        }
+        return undefined;
+      }
+      return primitiveCache.get(key);
+    },
+
+    set(key, value) {
+      const isObject =
+        key && (typeof key === "object" || typeof key === "function");
+      if (isObject) {
+        cleanupKeyRegistry();
+
+        // Remove existing deep-equal key
+        for (const keyRef of keyRegistry) {
+          const existingKey = keyRef.deref();
+          if (existingKey && compareTwoJsValues(existingKey, key)) {
+            const existingValue = keyToValue.get(existingKey);
+            keyToValue.delete(existingKey);
+            valueToKey.delete(existingValue);
+            keyRegistry.delete(keyRef);
+            break;
+          }
+        }
+
+        // Set ephemeron pair
+        keyToValue.set(key, value);
+        valueToKey.set(value, key);
+        keyRegistry.add(new WeakRef(key));
+      } else {
+        primitiveCache.set(key, value);
+      }
+    },
+
+    delete(key) {
+      const isObject =
+        key && (typeof key === "object" || typeof key === "function");
+      if (isObject) {
+        cleanupKeyRegistry();
+
+        // Try exact match first
+        if (keyToValue.has(key)) {
+          const value = keyToValue.get(key);
+          keyToValue.delete(key);
+          valueToKey.delete(value);
+
+          // Remove from registry
+          for (const keyRef of keyRegistry) {
+            if (keyRef.deref() === key) {
+              keyRegistry.delete(keyRef);
+              break;
+            }
+          }
+          return true;
+        }
+
+        // Try deep equality
+        for (const keyRef of keyRegistry) {
+          const existingKey = keyRef.deref();
+          if (existingKey && compareTwoJsValues(existingKey, key)) {
+            const value = keyToValue.get(existingKey);
+            keyToValue.delete(existingKey);
+            valueToKey.delete(value);
+            keyRegistry.delete(keyRef);
+            return true;
+          }
+        }
+        return false;
+      }
+      return primitiveCache.delete(key);
+    },
+
+    getStats: () => {
+      cleanupKeyRegistry();
+      const aliveKeys = Array.from(keyRegistry).filter((ref) =>
+        ref.deref(),
+      ).length;
+
+      return {
+        ephemeronPairs: {
+          total: keyRegistry.size,
+          alive: aliveKeys,
+          note: "True ephemeron: key ↔ value mutual retention via dual WeakMap",
+        },
+        primitive: {
+          total: primitiveCache.size,
+          note: "Primitive keys never GC'd",
+        },
+      };
+    },
+  };
+};