@graphrefly/graphrefly 0.6.0 → 0.7.0

package/dist/graph/index.cjs

@@ -159,10 +159,14 @@ function partitionForBatch(messages) {
   }
   return { immediate, deferred, terminal };
 }
-function emitWithBatch(emit, messages, phase = 2) {
+function emitWithBatch(emit, messages, phase = 2, options) {
   if (messages.length === 0) {
     return;
   }
+  if (options?.strategy === "sequential") {
+    _emitSequential(emit, messages, phase);
+    return;
+  }
   const queue = phase === 3 ? pendingPhase3 : pendingPhase2;
   if (messages.length === 1) {
     const t = messages[0][0];
@@ -203,6 +207,29 @@ function emitWithBatch(emit, messages, phase = 2) {
     }
   }
 }
+function _emitSequential(emit, messages, phase = 2) {
+  const dataQueue = phase === 3 ? pendingPhase3 : pendingPhase2;
+  for (const msg of messages) {
+    const tier = messageTier(msg[0]);
+    if (tier === 2) {
+      if (isBatching()) {
+        const m = msg;
+        dataQueue.push(() => emit([m]));
+      } else {
+        emit([msg]);
+      }
+    } else if (tier >= 3) {
+      if (isBatching()) {
+        const m = msg;
+        pendingPhase3.push(() => emit([m]));
+      } else {
+        emit([msg]);
+      }
+    } else {
+      emit([msg]);
+    }
+  }
+}
 
 // src/core/clock.ts
 function monotonicNs() {
@@ -411,6 +438,7 @@ var NodeImpl = class {
   _producerStarted = false;
   _connecting = false;
   _manualEmitUsed = false;
+  _hasEmittedData = false;
   _sinkCount = 0;
   _singleDepSinkCount = 0;
   // --- Object/collection state ---
@@ -697,6 +725,7 @@ var NodeImpl = class {
         this._cleanup = void 0;
         cleanupFn?.();
         this._cached = void 0;
+        this._hasEmittedData = false;
         this._lastDepValues = void 0;
       }
       this._status = statusAfterMessage(this._status, m);
@@ -706,6 +735,7 @@ var NodeImpl = class {
       if (t === TEARDOWN) {
         if (this._opts.resetOnTeardown) {
           this._cached = void 0;
+          this._hasEmittedData = false;
         }
         const teardownCleanup = this._cleanup;
         this._cleanup = void 0;
@@ -736,7 +766,16 @@ var NodeImpl = class {
   }
   _emitAutoValue(value) {
     const wasDirty = this._status === "dirty";
-    const unchanged = this._equals(this._cached, value);
+    let unchanged;
+    try {
+      unchanged = this._hasEmittedData && this._equals(this._cached, value);
+    } catch (eqErr) {
+      const eqMsg = eqErr instanceof Error ? eqErr.message : String(eqErr);
+      const wrapped = new Error(`Node "${this.name}": equals threw: ${eqMsg}`, { cause: eqErr });
+      this._downInternal([[ERROR, wrapped]]);
+      return;
+    }
+    this._hasEmittedData = true;
     if (unchanged) {
       this._downInternal(wasDirty ? [[RESOLVED]] : [[DIRTY], [RESOLVED]]);
       return;
@@ -783,7 +822,9 @@ var NodeImpl = class {
       if (out === void 0) return;
       this._emitAutoValue(out);
     } catch (err) {
-      this._downInternal([[ERROR, err]]);
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const wrapped = new Error(`Node "${this.name}": fn threw: ${errMsg}`, { cause: err });
+      this._downInternal([[ERROR, wrapped]]);
     }
   }
   _onDepDirty(index) {
@@ -818,7 +859,11 @@ var NodeImpl = class {
         try {
           if (this._onMessage(msg, index, this._actions)) continue;
         } catch (err) {
-          this._downInternal([[ERROR, err]]);
+          const errMsg = err instanceof Error ? err.message : String(err);
+          const wrapped = new Error(`Node "${this.name}": onMessage threw: ${errMsg}`, {
+            cause: err
+          });
+          this._downInternal([[ERROR, wrapped]]);
           return;
         }
       }
@@ -1383,6 +1428,19 @@ var DynamicNodeImpl = class {
 };
 
 // src/core/meta.ts
+function resolveDescribeFields(detail, fields) {
+  if (fields != null && fields.length > 0) return new Set(fields);
+  switch (detail) {
+    case "standard":
+      return /* @__PURE__ */ new Set(["type", "status", "value", "deps", "meta", "v"]);
+    case "full":
+      return null;
+    // null = include everything
+    case "minimal":
+    default:
+      return /* @__PURE__ */ new Set(["type", "deps"]);
+  }
+}
 function inferDescribeType(n) {
   if (n._describeKind != null) return n._describeKind;
   if (!n._hasDeps) return n._fn != null ? "producer" : "state";
@@ -1400,12 +1458,10 @@ function metaSnapshot(node2) {
   }
   return out;
 }
-function describeNode(node2) {
-  const meta = { ...metaSnapshot(node2) };
-  const guard = node2 instanceof NodeImpl && node2._guard || node2 instanceof DynamicNodeImpl && node2._guard || void 0;
-  if (guard != null && meta.access === void 0) {
-    meta.access = accessHintForGuard(guard);
-  }
+function describeNode(node2, includeFields) {
+  const all = includeFields == null;
+  const metaKeys = !all && includeFields != null ? [...includeFields].filter((f) => f.startsWith("meta.")).map((f) => f.slice(5)) : null;
+  const wantsMeta = all || includeFields.has("meta") || metaKeys != null && metaKeys.length > 0;
   let type = "state";
   let deps = [];
   if (node2 instanceof NodeImpl) {
@@ -1415,20 +1471,36 @@ function describeNode(node2) {
     type = node2._describeKind ?? "derived";
     deps = [];
   }
-  const out = {
-    type,
-    status: node2.status,
-    deps,
-    meta
-  };
+  const out = { type, deps };
+  if (all || includeFields.has("status")) {
+    out.status = node2.status;
+  }
+  const guard = node2 instanceof NodeImpl && node2._guard || node2 instanceof DynamicNodeImpl && node2._guard || void 0;
+  if (wantsMeta) {
+    const rawMeta = { ...metaSnapshot(node2) };
+    if (guard != null && rawMeta.access === void 0) {
+      rawMeta.access = accessHintForGuard(guard);
+    }
+    if (metaKeys != null && metaKeys.length > 0 && !includeFields.has("meta")) {
+      const filtered = {};
+      for (const k of metaKeys) {
+        if (k in rawMeta) filtered[k] = rawMeta[k];
+      }
+      out.meta = filtered;
+    } else {
+      out.meta = rawMeta;
+    }
+  }
   if (node2.name != null) {
     out.name = node2.name;
   }
-  try {
-    out.value = node2.get();
-  } catch {
+  if (all || includeFields.has("value")) {
+    try {
+      out.value = node2.get();
+    } catch {
+    }
   }
-  if (node2.v != null) {
+  if ((all || includeFields.has("v")) && node2.v != null) {
     const vInfo = { id: node2.v.id, version: node2.v.version };
     if ("cid" in node2.v) {
       vInfo.cid = node2.v.cid;
@@ -1436,6 +1508,16 @@ function describeNode(node2) {
     }
     out.v = vInfo;
   }
+  if (all || includeFields.has("guard")) {
+    if (guard != null) {
+      out.guard = accessHintForGuard(guard);
+    }
+  }
+  if (all || includeFields.has("lastMutation")) {
+    if (node2.lastMutation != null) {
+      out.lastMutation = node2.lastMutation;
+    }
+  }
   return out;
 }
 
@@ -1630,6 +1712,23 @@ function resolveSpyTheme(theme) {
     reset: theme.reset ?? ""
   };
 }
+function resolveObserveDetail(opts) {
+  if (opts == null) return {};
+  const detail = opts.detail;
+  if (detail === "full") {
+    return {
+      ...opts,
+      structured: opts.structured ?? true,
+      timeline: opts.timeline ?? true,
+      causal: opts.causal ?? true,
+      derived: opts.derived ?? true
+    };
+  }
+  if (detail === "minimal") {
+    return { ...opts, structured: opts.structured ?? true };
+  }
+  return opts;
+}
 function assertLocalName(name, graphName, label) {
   if (name === "") {
     throw new Error(`Graph "${graphName}": ${label} name must be non-empty`);
@@ -1827,6 +1926,22 @@ var Graph = class _Graph {
       if (this._defaultVersioningLevel != null) {
         node2._applyVersioning(this._defaultVersioningLevel);
       }
+      if (node2._deps.length > 0) {
+        for (const dep of node2._deps) {
+          for (const [depName, depNode] of this._nodes) {
+            if (depNode === dep) {
+              this._edges.add(edgeKey(depName, name));
+              break;
+            }
+          }
+        }
+      }
+      for (const [otherName, otherNode] of this._nodes) {
+        if (otherName === name) continue;
+        if (otherNode instanceof NodeImpl && otherNode._deps.includes(node2)) {
+          this._edges.add(edgeKey(name, otherName));
+        }
+      }
     }
   }
   /**
@@ -2213,6 +2328,9 @@ var Graph = class _Graph {
   describe(options) {
     const actor = options?.actor;
     const filter = options?.filter;
+    const includeFields = resolveDescribeFields(options?.detail, options?.fields);
+    const isSpec = options?.format === "spec";
+    const effectiveFields = isSpec ? resolveDescribeFields("minimal") : includeFields;
     const targets = [];
     this._collectObserveTargets("", targets);
     const nodeToPath = /* @__PURE__ */ new Map();
@@ -2222,7 +2340,7 @@ var Graph = class _Graph {
     const nodes = {};
     for (const [p, n] of targets) {
       if (actor != null && !n.allowsObserve(actor)) continue;
-      const raw = describeNode(n);
+      const raw = describeNode(n, effectiveFields);
       const deps = n instanceof NodeImpl ? n._deps.map((d) => nodeToPath.get(d) ?? d.name ?? "") : [];
       const { name: _name, ...rest } = raw;
       const entry = { ...rest, deps };
@@ -2243,7 +2361,7 @@ var Graph = class _Graph {
               continue;
             }
             if (normalizedKey === "metaHas") {
-              if (!Object.hasOwn(entry.meta, String(fv))) {
+              if (!Object.hasOwn(entry.meta ?? {}, String(fv))) {
                 match = false;
                 break;
               }
@@ -2276,11 +2394,24 @@ var Graph = class _Graph {
       const prefix = `${sg}${PATH_SEP}`;
       return [...nodeKeys].some((k) => k === sg || k.startsWith(prefix));
     }) : allSubgraphs;
+    const graph = this;
+    const baseOpts = options;
     return {
       name: this.name,
       nodes,
       edges,
-      subgraphs
+      subgraphs,
+      expand(detailOrFields) {
+        const merged = { ...baseOpts, format: void 0 };
+        if (Array.isArray(detailOrFields)) {
+          merged.fields = detailOrFields;
+          merged.detail = void 0;
+        } else {
+          merged.detail = detailOrFields;
+          merged.fields = void 0;
+        }
+        return graph.describe(merged);
+      }
     };
   }
   _collectSubgraphs(prefix) {
@@ -2333,14 +2464,15 @@ var Graph = class _Graph {
   observe(pathOrOpts, options) {
     if (typeof pathOrOpts === "string") {
       const path = pathOrOpts;
-      const actor2 = options?.actor;
+      const resolved = resolveObserveDetail(options);
+      const actor2 = resolved.actor;
       const target = this.resolve(path);
       if (actor2 != null && !target.allowsObserve(actor2)) {
         throw new GuardDenied({ actor: actor2, action: "observe", nodeName: path });
       }
-      const wantsStructured2 = options?.structured === true || options?.timeline === true || options?.causal === true || options?.derived === true;
+      const wantsStructured2 = resolved.structured === true || resolved.timeline === true || resolved.causal === true || resolved.derived === true || resolved.detail === "minimal" || resolved.detail === "full";
       if (wantsStructured2 && _Graph.inspectorEnabled) {
-        return this._createObserveResult(path, target, options);
+        return this._createObserveResult(path, target, resolved);
       }
       return {
         subscribe(sink) {
@@ -2356,11 +2488,11 @@ var Graph = class _Graph {
         }
       };
     }
-    const opts = pathOrOpts;
-    const actor = opts?.actor;
-    const wantsStructured = opts?.structured === true || opts?.timeline === true || opts?.causal === true || opts?.derived === true;
+    const opts = resolveObserveDetail(pathOrOpts);
+    const actor = opts.actor;
+    const wantsStructured = opts.structured === true || opts.timeline === true || opts.causal === true || opts.derived === true || opts.detail === "minimal" || opts.detail === "full";
     if (wantsStructured && _Graph.inspectorEnabled) {
-      return this._createObserveResultForAll(opts ?? {});
+      return this._createObserveResultForAll(opts);
     }
     return {
       subscribe: (sink) => {
@@ -2392,6 +2524,7 @@ var Graph = class _Graph {
     const timeline = options.timeline === true;
     const causal = options.causal === true;
     const derived = options.derived === true;
+    const minimal = options.detail === "minimal";
     const result = {
       values: {},
       dirtyCount: 0,
@@ -2437,6 +2570,11 @@ var Graph = class _Graph {
         if (t === DATA) {
           result.values[path] = m[1];
           result.events.push({ type: "data", path, data: m[1], ...base, ...withCausal });
+        } else if (minimal) {
+          if (t === DIRTY) result.dirtyCount++;
+          else if (t === RESOLVED) result.resolvedCount++;
+          else if (t === COMPLETE && !result.errored) result.completedCleanly = true;
+          else if (t === ERROR) result.errored = true;
         } else if (t === DIRTY) {
           result.dirtyCount++;
           result.events.push({ type: "dirty", path, ...base });
@@ -2452,6 +2590,8 @@ var Graph = class _Graph {
         }
       }
     });
+    const graph = this;
+    const basePath = path;
     return {
       get values() {
         return result.values;
@@ -2474,11 +2614,28 @@ var Graph = class _Graph {
       dispose() {
         unsub();
         detachInspectorHook?.();
+      },
+      expand(extra) {
+        unsub();
+        detachInspectorHook?.();
+        const merged = { ...options };
+        if (typeof extra === "string") {
+          merged.detail = extra;
+        } else {
+          Object.assign(merged, extra);
+        }
+        const resolvedTarget = graph.resolve(basePath);
+        return graph._createObserveResult(
+          basePath,
+          resolvedTarget,
+          resolveObserveDetail(merged)
+        );
       }
     };
   }
   _createObserveResultForAll(options) {
     const timeline = options.timeline === true;
+    const minimal = options.detail === "minimal";
     const result = {
       values: {},
       dirtyCount: 0,
@@ -2500,6 +2657,11 @@ var Graph = class _Graph {
           if (t === DATA) {
             result.values[path] = m[1];
             result.events.push({ type: "data", path, data: m[1], ...base });
+          } else if (minimal) {
+            if (t === DIRTY) result.dirtyCount++;
+            else if (t === RESOLVED) result.resolvedCount++;
+            else if (t === COMPLETE && !result.errored) result.completedCleanly = true;
+            else if (t === ERROR) result.errored = true;
           } else if (t === DIRTY) {
             result.dirtyCount++;
             result.events.push({ type: "dirty", path, ...base });
@@ -2516,6 +2678,7 @@ var Graph = class _Graph {
         }
       })
     );
+    const graph = this;
     return {
       get values() {
         return result.values;
@@ -2537,6 +2700,16 @@ var Graph = class _Graph {
       },
       dispose() {
         for (const u of unsubs) u();
+      },
+      expand(extra) {
+        for (const u of unsubs) u();
+        const merged = { ...options };
+        if (typeof extra === "string") {
+          merged.detail = extra;
+        } else {
+          Object.assign(merged, extra);
+        }
+        return graph._createObserveResultForAll(resolveObserveDetail(merged));
       }
     };
   }
@@ -2612,6 +2785,9 @@ var Graph = class _Graph {
         },
         dispose() {
           stop2();
+        },
+        expand() {
+          throw new Error("expand() requires inspector mode (Graph.inspectorEnabled = true)");
         }
       };
       const pushEvent = (path, message) => {
@@ -2712,16 +2888,16 @@ var Graph = class _Graph {
    * @returns Rendered graph text.
    */
   dumpGraph(options = {}) {
-    const described = this.describe({
+    const { expand: _, ...described } = this.describe({
       actor: options.actor,
-      filter: options.filter
+      filter: options.filter,
+      detail: "standard"
     });
     const includeEdges = options.includeEdges ?? true;
     const includeSubgraphs = options.includeSubgraphs ?? true;
     if (options.format === "json") {
       const payload = {
-        name: described.name,
-        nodes: described.nodes,
+        ...described,
         edges: includeEdges ? described.edges : [],
         subgraphs: includeSubgraphs ? described.subgraphs : []
       };
@@ -2791,10 +2967,11 @@ var Graph = class _Graph {
    * @returns Persistable snapshot with sorted keys.
    */
   snapshot() {
-    const d = this.describe();
+    const { expand: _, ...d } = this.describe({ detail: "full" });
     const sortedNodes = {};
     for (const key of Object.keys(d.nodes).sort()) {
-      sortedNodes[key] = d.nodes[key];
+      const { lastMutation: _lm, guard: _g, ...node2 } = d.nodes[key];
+      sortedNodes[key] = node2;
     }
     const sortedSubgraphs = [...d.subgraphs].sort();
     return { ...d, version: 1, nodes: sortedNodes, subgraphs: sortedSubgraphs };
@@ -2948,16 +3125,22 @@ var Graph = class _Graph {
       if (!pending) return;
       pending = false;
       try {
-        const described = this.describe();
+        const { expand: _expand, ...raw } = this.describe({ detail: "full" });
+        const cleanNodes = {};
+        for (const [p, n] of Object.entries(raw.nodes)) {
+          const { lastMutation: _lm, guard: _g, ...node2 } = n;
+          cleanNodes[p] = node2;
+        }
+        const described = { ...raw, nodes: cleanNodes };
         const snapshot = { ...described, version: SNAPSHOT_VERSION };
         seq += 1;
         const shouldCompact = lastDescribe == null || seq % compactEvery === 0;
         if (shouldCompact) {
-          adapter.save({ mode: "full", snapshot, seq });
+          adapter.save(this.name, { mode: "full", snapshot, seq });
         } else {
           const previous = lastDescribe;
           if (previous == null) return;
-          adapter.save({
+          adapter.save(this.name, {
             mode: "diff",
             diff: _Graph.diff(previous, described),
             snapshot,
@@ -2978,8 +3161,10 @@ var Graph = class _Graph {
       const triggeredByTier = messages.some((m) => messageTier(m[0]) >= 2);
       if (!triggeredByTier) return;
       if (options.filter) {
-        const described = this.describe().nodes[path];
-        if (described == null || !options.filter(path, described)) return;
+        const nd = this.resolve(path);
+        if (nd == null) return;
+        const described = describeNode(nd, resolveDescribeFields("standard"));
+        if (!options.filter(path, described)) return;
       }
       schedule();
     });