@graphrefly/graphrefly 0.24.0 → 0.26.0

package/dist/extra/index.cjs

@@ -100,6 +100,7 @@ __export(extra_exports, {
   fromPromise: () => fromPromise,
   fromPulsar: () => fromPulsar,
   fromRabbitMQ: () => fromRabbitMQ,
+  fromRaf: () => fromRaf,
   fromRedisStream: () => fromRedisStream,
   fromSSE: () => fromSSE,
   fromSqlite: () => fromSqlite,
@@ -971,6 +972,12 @@ var NodeImpl = class _NodeImpl {
   _autoError;
   _pausable;
   _guard;
+  /**
+   * @internal Additional guards stacked at runtime via {@link NodeImpl._pushGuard}
+   * (e.g. by `policyEnforcer({ mode: "enforce" })`, roadmap §9.2). Effective
+   * write/signal/observe checks AND the original `_guard` with every entry here.
+   */
+  _extraGuards;
   _hashFn;
   _versioning;
   /**
@@ -1144,18 +1151,61 @@ var NodeImpl = class _NodeImpl {
       if (this._inspectorHooks?.size === 0) this._inspectorHooks = void 0;
     };
   }
+  /**
+   * @internal Push an additional guard onto this node. Effective enforcement
+   * is the AND of `_guard` and every guard pushed via this hook — any one
+   * rejecting throws {@link GuardDenied}. Returns a disposer that removes
+   * the pushed guard. Multiple guards may be stacked simultaneously.
+   *
+   * Used by `policyEnforcer({ mode: "enforce" })` (roadmap §9.2) to overlay
+   * runtime constraint enforcement onto an existing graph without rebuilding
+   * its nodes. Pre-1.0 internal API; not part of the public surface.
+   *
+   * **Identity semantics:** guards are tracked in a `Set`, so pushing the
+   * same `NodeGuard` reference twice is a single registration. Wrap each
+   * push in a unique closure if independent stacking is needed.
+   *
+   * **Iteration order:** insertion-ordered (`Set` semantics). Determinism
+   * follows from single-threaded JS execution; nested re-entry from inside
+   * a guard body (push/pop while iterating) is undefined-but-survivable.
+   */
+  _pushGuard(guard) {
+    if (this._extraGuards == null) this._extraGuards = /* @__PURE__ */ new Set();
+    this._extraGuards.add(guard);
+    return () => {
+      this._extraGuards?.delete(guard);
+      if (this._extraGuards?.size === 0) this._extraGuards = void 0;
+    };
+  }
   allowsObserve(actor) {
-    if (this._guard == null) return true;
-    return this._guard(normalizeActor(actor), "observe");
+    if (this._guard == null && this._extraGuards == null) return true;
+    const a = normalizeActor(actor);
+    if (this._guard != null && !this._guard(a, "observe")) return false;
+    if (this._extraGuards != null) {
+      for (const eg of this._extraGuards) {
+        if (!eg(a, "observe")) return false;
+      }
+    }
+    return true;
   }
   // --- Guard helper ---
   _checkGuard(options) {
-    if (options?.internal || this._guard == null) return;
+    if (options?.internal) return;
+    const hasGuard = this._guard != null || this._extraGuards != null;
+    const hasActor = options?.actor != null;
+    if (!hasGuard && !hasActor) return;
     const actor = normalizeActor(options?.actor);
     const action = options?.delivery === "signal" ? "signal" : "write";
-    if (!this._guard(actor, action)) {
+    if (this._guard != null && !this._guard(actor, action)) {
       throw new GuardDenied({ actor, action, nodeName: this.name });
     }
+    if (this._extraGuards != null) {
+      for (const eg of this._extraGuards) {
+        if (!eg(actor, action)) {
+          throw new GuardDenied({ actor, action, nodeName: this.name });
+        }
+      }
+    }
     this._lastMutation = { actor, timestamp_ns: wallClockNs() };
   }
   // --- Public transport ---
@@ -2330,10 +2380,6 @@ function externalBundle(register, channels, opts) {
   return Object.assign(nodes, { dispose });
 }
 
-// src/extra/sources.ts
-var import_node_fs = require("fs");
-var import_node_path = require("path");
-
 // src/extra/cron.ts
 function parseField(field, min, max) {
   const result = /* @__PURE__ */ new Set();
@@ -2471,6 +2517,72 @@ function fromTimer(ms, opts) {
     return cleanup;
   }, sourceOpts2(rest));
 }
+function fromRaf(opts) {
+  const { signal, ...rest } = opts ?? {};
+  return producer((a) => {
+    let done = false;
+    let rafId;
+    let fallbackTimer;
+    let abortListenerAdded = false;
+    let visibilityListenerAdded = false;
+    const raf = typeof requestAnimationFrame === "function" ? requestAnimationFrame : void 0;
+    const caf = typeof cancelAnimationFrame === "function" ? cancelAnimationFrame : void 0;
+    const doc = typeof document !== "undefined" ? document : void 0;
+    const clearPending = () => {
+      if (rafId !== void 0 && caf) caf(rafId);
+      if (fallbackTimer !== void 0) clearTimeout(fallbackTimer);
+      rafId = void 0;
+      fallbackTimer = void 0;
+    };
+    const cleanup = () => {
+      done = true;
+      clearPending();
+      if (abortListenerAdded) {
+        signal?.removeEventListener("abort", onAbort);
+        abortListenerAdded = false;
+      }
+      if (visibilityListenerAdded && doc) {
+        doc.removeEventListener("visibilitychange", onVisibilityChange);
+        visibilityListenerAdded = false;
+      }
+    };
+    const onAbort = () => {
+      if (done) return;
+      cleanup();
+      a.down([[ERROR, signal.reason]]);
+    };
+    const tick = (now) => {
+      if (done) return;
+      a.emit(now);
+      scheduleNext();
+    };
+    const scheduleNext = () => {
+      if (done) return;
+      if (raf && (!doc || doc.visibilityState !== "hidden")) {
+        rafId = raf(tick);
+      } else {
+        fallbackTimer = setTimeout(() => tick(performance.now()), 16);
+      }
+    };
+    const onVisibilityChange = () => {
+      if (done) return;
+      clearPending();
+      scheduleNext();
+    };
+    if (signal?.aborted) {
+      onAbort();
+      return cleanup;
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+    abortListenerAdded = signal !== void 0;
+    if (doc && raf) {
+      doc.addEventListener("visibilitychange", onVisibilityChange);
+      visibilityListenerAdded = true;
+    }
+    scheduleNext();
+    return cleanup;
+  }, sourceOpts2(rest));
+}
 function fromCron(expr, opts) {
   const schedule = parseCron(expr);
   const { tickMs: tickOpt, output, ...rest } = opts ?? {};
@@ -2505,99 +2617,6 @@ function fromEvent(target, type, opts) {
     return () => target.removeEventListener(type, handler, options);
   }, sourceOpts2(rest));
 }
-function fromFSWatch(paths, opts) {
-  const list = Array.isArray(paths) ? paths : [paths];
-  if (list.length === 0) {
-    throw new RangeError("fromFSWatch expects at least one path");
-  }
-  const { recursive = true, debounce: debounce2 = 100, include, exclude, ...rest } = opts ?? {};
-  const includePatterns = include?.map(globToRegExp) ?? [];
-  const excludePatterns = (exclude ?? ["**/node_modules/**", "**/.git/**", "**/dist/**"]).map(
-    globToRegExp
-  );
-  return producer((a) => {
-    const pending = /* @__PURE__ */ new Map();
-    const watchers = [];
-    let stopped = false;
-    let terminalEmitted = false;
-    let generation = 0;
-    const closeWatchers = () => {
-      for (const watcher of watchers.splice(0)) watcher.close();
-    };
-    const emitError = (err) => {
-      if (terminalEmitted) return;
-      terminalEmitted = true;
-      stopped = true;
-      if (timer !== void 0) clearTimeout(timer);
-      timer = void 0;
-      pending.clear();
-      closeWatchers();
-      a.down([[ERROR, err]]);
-    };
-    let timer;
-    const flush = (token) => {
-      timer = void 0;
-      if (stopped || terminalEmitted) return;
-      if (pending.size === 0) return;
-      const batchMessages = [];
-      for (const evt of pending.values()) batchMessages.push([DATA, evt]);
-      pending.clear();
-      if (stopped || terminalEmitted || token !== generation) return;
-      a.down(batchMessages);
-    };
-    try {
-      for (const basePath of list) {
-        const watcher = (0, import_node_fs.watch)(
-          basePath,
-          { recursive },
-          (eventType, fileName) => {
-            if (stopped || terminalEmitted) return;
-            if (fileName == null) return;
-            const rel = String(fileName).replaceAll("\\", "/");
-            const abs = (0, import_node_path.resolve)(basePath, String(fileName));
-            const normalized = abs.replaceAll("\\", "/");
-            const root = (0, import_node_path.resolve)(basePath).replaceAll("\\", "/");
-            const relForMatch = rel.startsWith("./") ? rel.slice(2) : rel;
-            const included = includePatterns.length === 0 || matchesAnyPattern(normalized, includePatterns) || matchesAnyPattern(relForMatch, includePatterns);
-            if (!included) return;
-            const excluded = matchesAnyPattern(normalized, excludePatterns) || matchesAnyPattern(relForMatch, excludePatterns);
-            if (excluded) return;
-            let kind = "change";
-            if (eventType === "rename") {
-              try {
-                kind = (0, import_node_fs.existsSync)(normalized) ? "create" : "delete";
-              } catch {
-                kind = "rename";
-              }
-            }
-            pending.set(normalized, {
-              type: kind,
-              path: normalized,
-              root,
-              relative_path: relForMatch,
-              timestamp_ns: wallClockNs()
-            });
-            if (timer !== void 0) clearTimeout(timer);
-            const token = generation;
-            timer = setTimeout(() => flush(token), debounce2);
-          }
-        );
-        watcher.on("error", (err) => emitError(err));
-        watchers.push(watcher);
-      }
-    } catch (err) {
-      emitError(err);
-    }
-    return () => {
-      stopped = true;
-      generation += 1;
-      if (timer !== void 0) clearTimeout(timer);
-      timer = void 0;
-      closeWatchers();
-      pending.clear();
-    };
-  }, sourceOpts2(rest));
-}
 function fromIter(iterable, opts) {
   return producer((a) => {
     let cancelled = false;
@@ -8849,11 +8868,111 @@ function reactiveLog(initial, options = {}) {
   };
 }
 
+// src/extra/sources-fs.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+function sourceOpts4(opts) {
+  return { describeKind: "producer", ...opts };
+}
+function fromFSWatch(paths, opts) {
+  const list = Array.isArray(paths) ? paths : [paths];
+  if (list.length === 0) {
+    throw new RangeError("fromFSWatch expects at least one path");
+  }
+  const { recursive = true, debounce: debounce2 = 100, include, exclude, ...rest } = opts ?? {};
+  const includePatterns = include?.map(globToRegExp) ?? [];
+  const excludePatterns = (exclude ?? ["**/node_modules/**", "**/.git/**", "**/dist/**"]).map(
+    globToRegExp
+  );
+  return producer((a) => {
+    const pending = /* @__PURE__ */ new Map();
+    const watchers = [];
+    let stopped = false;
+    let terminalEmitted = false;
+    let generation = 0;
+    const closeWatchers = () => {
+      for (const watcher of watchers.splice(0)) watcher.close();
+    };
+    const emitError = (err) => {
+      if (terminalEmitted) return;
+      terminalEmitted = true;
+      stopped = true;
+      if (timer !== void 0) clearTimeout(timer);
+      timer = void 0;
+      pending.clear();
+      closeWatchers();
+      a.down([[ERROR, err]]);
+    };
+    let timer;
+    const flush = (token) => {
+      timer = void 0;
+      if (stopped || terminalEmitted) return;
+      if (pending.size === 0) return;
+      const batchMessages = [];
+      for (const evt of pending.values()) batchMessages.push([DATA, evt]);
+      pending.clear();
+      if (stopped || terminalEmitted || token !== generation) return;
+      a.down(batchMessages);
+    };
+    try {
+      for (const basePath of list) {
+        const watcher = (0, import_node_fs.watch)(
+          basePath,
+          { recursive },
+          (eventType, fileName) => {
+            if (stopped || terminalEmitted) return;
+            if (fileName == null) return;
+            const rel = String(fileName).replaceAll("\\", "/");
+            const abs = (0, import_node_path.resolve)(basePath, String(fileName));
+            const normalized = abs.replaceAll("\\", "/");
+            const root = (0, import_node_path.resolve)(basePath).replaceAll("\\", "/");
+            const relForMatch = rel.startsWith("./") ? rel.slice(2) : rel;
+            const included = includePatterns.length === 0 || matchesAnyPattern(normalized, includePatterns) || matchesAnyPattern(relForMatch, includePatterns);
+            if (!included) return;
+            const excluded = matchesAnyPattern(normalized, excludePatterns) || matchesAnyPattern(relForMatch, excludePatterns);
+            if (excluded) return;
+            let kind = "change";
+            if (eventType === "rename") {
+              try {
+                kind = (0, import_node_fs.existsSync)(normalized) ? "create" : "delete";
+              } catch {
+                kind = "rename";
+              }
+            }
+            pending.set(normalized, {
+              type: kind,
+              path: normalized,
+              root,
+              relative_path: relForMatch,
+              timestamp_ns: wallClockNs()
+            });
+            if (timer !== void 0) clearTimeout(timer);
+            const token = generation;
+            timer = setTimeout(() => flush(token), debounce2);
+          }
+        );
+        watcher.on("error", (err) => emitError(err));
+        watchers.push(watcher);
+      }
+    } catch (err) {
+      emitError(err);
+    }
+    return () => {
+      stopped = true;
+      generation += 1;
+      if (timer !== void 0) clearTimeout(timer);
+      timer = void 0;
+      closeWatchers();
+      pending.clear();
+    };
+  }, sourceOpts4(rest));
+}
+
 // src/extra/storage.ts
-var import_node_crypto = require("crypto");
-var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
-var import_node_sqlite = require("sqlite");
+var import_node_crypto = require("node:crypto");
+var import_node_fs2 = require("node:fs");
+var import_node_path2 = require("node:path");
+var import_node_sqlite = require("node:sqlite");
 function sortJsonValue(value) {
   if (value === null || typeof value !== "object") return value;
   if (Array.isArray(value)) return value.map(sortJsonValue);
@@ -8878,6 +8997,9 @@ function memoryStorage() {
     },
     clear(key) {
       data.delete(key);
+    },
+    list() {
+      return [...data.keys()].sort();
     }
   };
 }
@@ -8892,16 +9014,54 @@ function dictStorage(storage) {
     },
     clear(key) {
       delete storage[key];
+    },
+    list() {
+      return Object.keys(storage).sort();
     }
   };
 }
 function fileStorage(dir) {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
   const pathFor = (key) => {
-    const safe = key.replace(
-      /[^a-zA-Z0-9_-]/g,
-      (c) => `%${c.charCodeAt(0).toString(16).padStart(2, "0")}`
-    );
-    return (0, import_node_path2.join)(dir, `${safe}.json`);
+    let out = "";
+    for (const ch of key) {
+      if (ch.length === 1 && /[a-zA-Z0-9_-]/.test(ch)) {
+        out += ch;
+        continue;
+      }
+      for (const byte of encoder.encode(ch)) {
+        out += `%${byte.toString(16).padStart(2, "0")}`;
+      }
+    }
+    return (0, import_node_path2.join)(dir, `${out}.json`);
+  };
+  const keyFromFilename = (filename) => {
+    if (!filename.endsWith(".json")) return null;
+    const stem = filename.slice(0, -".json".length);
+    const bytes = [];
+    const encodeAscii = (s) => {
+      for (let i2 = 0; i2 < s.length; i2++) bytes.push(s.charCodeAt(i2));
+    };
+    let i = 0;
+    while (i < stem.length) {
+      const ch = stem[i];
+      if (ch === "%" && i + 2 < stem.length) {
+        const hex = stem.slice(i + 1, i + 3);
+        if (/^[0-9a-f]{2}$/i.test(hex)) {
+          bytes.push(Number.parseInt(hex, 16));
+          i += 3;
+          continue;
+        }
+      }
+      encodeAscii(ch);
+      i += 1;
+    }
+    try {
+      return decoder.decode(new Uint8Array(bytes));
+    } catch {
+      return null;
+    }
   };
   return {
     save(key, record) {
@@ -8938,6 +9098,21 @@ function fileStorage(dir) {
       } catch (e) {
         if (e.code !== "ENOENT") throw e;
       }
+    },
+    list() {
+      try {
+        const entries = (0, import_node_fs2.readdirSync)(dir);
+        const keys = [];
+        for (const entry of entries) {
+          if (entry.startsWith(".")) continue;
+          const k = keyFromFilename(entry);
+          if (k !== null) keys.push(k);
+        }
+        return keys.sort();
+      } catch (e) {
+        if (e.code === "ENOENT") return [];
+        throw e;
+      }
     }
   };
 }
@@ -8960,6 +9135,10 @@ function sqliteStorage(path) {
     clear(key) {
       db.prepare(`DELETE FROM graphrefly_checkpoint WHERE k = ?`).run(key);
     },
+    list() {
+      const rows = db.prepare(`SELECT k FROM graphrefly_checkpoint ORDER BY k`).all();
+      return rows.map((r) => r.k);
+    },
     close() {
       try {
         db.close();
@@ -9687,6 +9866,7 @@ function workerSelf(target, opts) {
   fromPromise,
   fromPulsar,
   fromRabbitMQ,
+  fromRaf,
   fromRedisStream,
   fromSSE,
   fromSqlite,