@graphrefly/graphrefly 0.7.0 → 0.9.0

package/dist/index.cjs

@@ -237,6 +237,7 @@ __export(index_exports, {
   reactiveLog: () => reactiveLog,
   reactiveMap: () => reactiveMap,
   reduce: () => reduce,
+  reduction: () => reduction_exports,
   repeat: () => repeat,
   replay: () => replay,
   replayWAL: () => replayWAL,
@@ -726,6 +727,7 @@ function isV1(info) {
 }
 
 // src/core/node.ts
+var NO_VALUE = /* @__PURE__ */ Symbol.for("graphrefly/NO_VALUE");
 function createIntBitSet() {
   let bits = 0;
   return {
@@ -826,7 +828,6 @@ var NodeImpl = class {
   _producerStarted = false;
   _connecting = false;
   _manualEmitUsed = false;
-  _hasEmittedData = false;
   _sinkCount = 0;
   _singleDepSinkCount = 0;
   // --- Object/collection state ---
@@ -856,10 +857,10 @@ var NodeImpl = class {
     this._hasDeps = deps.length > 0;
     this._autoComplete = opts.completeWhenDepsComplete ?? true;
     this._isSingleDep = deps.length === 1 && fn != null;
-    this._cached = opts.initial;
+    this._cached = "initial" in opts ? opts.initial : NO_VALUE;
     this._status = this._hasDeps ? "disconnected" : "settled";
     this._hashFn = opts.versioningHash ?? defaultHash;
-    this._versioning = opts.versioning != null ? createVersioning(opts.versioning, this._cached, {
+    this._versioning = opts.versioning != null ? createVersioning(opts.versioning, this._cached === NO_VALUE ? void 0 : this._cached, {
       id: opts.versioningId,
       hash: this._hashFn
     }) : void 0;
@@ -943,10 +944,14 @@ var NodeImpl = class {
   _applyVersioning(level, opts) {
     if (this._versioning != null) return;
     this._hashFn = opts?.hash ?? this._hashFn;
-    this._versioning = createVersioning(level, this._cached, {
-      id: opts?.id,
-      hash: this._hashFn
-    });
+    this._versioning = createVersioning(
+      level,
+      this._cached === NO_VALUE ? void 0 : this._cached,
+      {
+        id: opts?.id,
+        hash: this._hashFn
+      }
+    );
   }
   hasGuard() {
     return this._guard != null;
@@ -956,7 +961,7 @@ var NodeImpl = class {
     return this._guard(normalizeActor(actor), "observe");
   }
   get() {
-    return this._cached;
+    return this._cached === NO_VALUE ? void 0 : this._cached;
   }
   down(messages, options) {
     if (messages.length === 0) return;
@@ -1013,6 +1018,7 @@ var NodeImpl = class {
     }
     if (this._terminal && this._opts.resubscribable) {
       this._terminal = false;
+      this._cached = NO_VALUE;
       this._status = this._hasDeps ? "disconnected" : "settled";
       this._opts.onResubscribe?.();
     }
@@ -1112,8 +1118,7 @@ var NodeImpl = class {
         const cleanupFn = this._cleanup;
         this._cleanup = void 0;
         cleanupFn?.();
-        this._cached = void 0;
-        this._hasEmittedData = false;
+        this._cached = NO_VALUE;
         this._lastDepValues = void 0;
       }
       this._status = statusAfterMessage(this._status, m);
@@ -1122,8 +1127,7 @@ var NodeImpl = class {
       }
       if (t === TEARDOWN) {
         if (this._opts.resetOnTeardown) {
-          this._cached = void 0;
-          this._hasEmittedData = false;
+          this._cached = NO_VALUE;
         }
         const teardownCleanup = this._cleanup;
         this._cleanup = void 0;
@@ -1156,14 +1160,13 @@ var NodeImpl = class {
     const wasDirty = this._status === "dirty";
     let unchanged;
     try {
-      unchanged = this._hasEmittedData && this._equals(this._cached, value);
+      unchanged = this._cached !== NO_VALUE && 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;
@@ -1387,7 +1390,7 @@ var DynamicNodeImpl = class {
   _actions;
   _boundEmitToSinks;
   // Mutable state
-  _cached;
+  _cached = NO_VALUE;
   _status = "disconnected";
   _terminal = false;
   _connected = false;
@@ -1481,7 +1484,7 @@ var DynamicNodeImpl = class {
     return this._guard(normalizeActor(actor), "observe");
   }
   get() {
-    return this._cached;
+    return this._cached === NO_VALUE ? void 0 : this._cached;
   }
   down(messages, options) {
     if (messages.length === 0) return;
@@ -1539,6 +1542,7 @@ var DynamicNodeImpl = class {
     }
     if (this._terminal && this._resubscribable) {
       this._terminal = false;
+      this._cached = NO_VALUE;
       this._status = "disconnected";
       this._onResubscribe?.();
     }
@@ -1616,10 +1620,13 @@ var DynamicNodeImpl = class {
       const t = m[0];
       if (t === DATA) this._cached = m[1];
       if (t === INVALIDATE) {
-        this._cached = void 0;
+        this._cached = NO_VALUE;
+        this._status = "dirty";
       }
-      if (t === DATA || t === RESOLVED) {
+      if (t === DATA) {
         this._status = "settled";
+      } else if (t === RESOLVED) {
+        this._status = "resolved";
       } else if (t === DIRTY) {
         this._status = "dirty";
       } else if (t === COMPLETE) {
@@ -1630,7 +1637,7 @@ var DynamicNodeImpl = class {
         this._terminal = true;
       }
       if (t === TEARDOWN) {
-        if (this._resetOnTeardown) this._cached = void 0;
+        if (this._resetOnTeardown) this._cached = NO_VALUE;
         try {
           this._propagateToMeta(t);
         } finally {
@@ -1653,7 +1660,15 @@ var DynamicNodeImpl = class {
   }
   _emitAutoValue(value) {
     const wasDirty = this._status === "dirty";
-    const unchanged = this._equals(this._cached, value);
+    let unchanged;
+    try {
+      unchanged = this._cached !== NO_VALUE && 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;
+    }
     if (unchanged) {
       this._downInternal(wasDirty ? [[RESOLVED]] : [[DIRTY], [RESOLVED]]);
       return;
@@ -5174,20 +5189,28 @@ var Graph = class _Graph {
     return g;
   }
   /**
-   * Plain snapshot with **recursively sorted object keys** for deterministic serialization (§3.8).
+   * Plain snapshot object with **recursively sorted object keys** for deterministic serialization (§3.8).
    *
    * @remarks
-   * ECMAScript `JSON.stringify(graph)` invokes this method; it must return a plain object, not an
-   * already-stringified JSON string (otherwise the graph would be double-encoded).
    * For a single UTF-8 string with a trailing newline (convenient for git), use {@link Graph.toJSONString}.
    *
    * @returns Same object as {@link Graph.snapshot}.
    */
-  toJSON() {
+  toObject() {
     return this.snapshot();
   }
   /**
-   * Deterministic JSON **text**: `JSON.stringify` of {@link Graph.toJSON} plus a trailing newline (§3.8).
+   * ECMAScript `JSON.stringify` hook — delegates to {@link Graph.toObject}.
+   *
+   * @remarks
+   * Must return a plain object (not a string) so `JSON.stringify(graph)` works correctly
+   * without double-encoding.
+   */
+  toJSON() {
+    return this.toObject();
+  }
+  /**
+   * Deterministic JSON **text**: `JSON.stringify` of {@link Graph.toObject} plus a trailing newline (§3.8).
    *
    * @returns Stable string suitable for diffs.
    */
@@ -12842,7 +12865,8 @@ __export(patterns_exports, {
   layout: () => reactive_layout_exports,
   memory: () => memory_exports,
   messaging: () => messaging_exports,
-  orchestration: () => orchestration_exports
+  orchestration: () => orchestration_exports,
+  reduction: () => reduction_exports
 });
 
 // src/patterns/ai.ts
@@ -16662,6 +16686,277 @@ function reactiveBlockLayout(opts) {
   };
 }
 
+// src/patterns/reduction.ts
+var reduction_exports = {};
+__export(reduction_exports, {
+  budgetGate: () => budgetGate,
+  feedback: () => feedback,
+  funnel: () => funnel,
+  scorer: () => scorer,
+  stratify: () => stratify
+});
+function baseMeta2(kind, meta) {
+  return {
+    reduction: true,
+    reduction_type: kind,
+    ...meta ?? {}
+  };
+}
+function stratify(name, source, rules, opts) {
+  const g = new Graph(name, opts);
+  g.add("source", source);
+  const rulesNode = state(rules, {
+    meta: baseMeta2("stratify_rules")
+  });
+  g.add("rules", rulesNode);
+  for (const rule of rules) {
+    _addBranch(g, source, rulesNode, rule);
+  }
+  return g;
+}
+function _addBranch(graph, source, rulesNode, rule) {
+  const branchName = `branch/${rule.name}`;
+  let pendingDirty = false;
+  const filterNode = node([source, rulesNode], () => void 0, {
+    describeKind: "operator",
+    meta: baseMeta2("stratify_branch", { branch: rule.name }),
+    onMessage(msg, depIndex, actions) {
+      if (depIndex !== 0) return false;
+      const t = msg[0];
+      if (t === DATA) {
+        const value = msg[1];
+        const currentRules = rulesNode.get();
+        const currentRule = currentRules.find((r) => r.name === rule.name);
+        if (currentRule && currentRule.classify(value)) {
+          pendingDirty = false;
+          actions.emit(value);
+        } else {
+          if (pendingDirty) {
+            pendingDirty = false;
+            actions.down([[DIRTY], [RESOLVED]]);
+          }
+        }
+        return true;
+      }
+      if (t === DIRTY) {
+        pendingDirty = true;
+        return true;
+      }
+      if (t === RESOLVED) {
+        if (pendingDirty) {
+          pendingDirty = false;
+          actions.down([[DIRTY], [RESOLVED]]);
+        } else {
+          actions.down([[RESOLVED]]);
+        }
+        return true;
+      }
+      if (t === COMPLETE || t === ERROR) {
+        pendingDirty = false;
+        actions.down([msg]);
+        return true;
+      }
+      return false;
+    }
+  });
+  graph.add(branchName, filterNode);
+  graph.connect("source", branchName);
+  if (rule.ops) {
+    const transformed = rule.ops(filterNode);
+    const transformedName = `branch/${rule.name}/out`;
+    graph.add(transformedName, transformed);
+    graph.connect(branchName, transformedName);
+  }
+}
+function funnel(name, sources, stages, opts) {
+  if (sources.length === 0) throw new RangeError("funnel requires at least one source");
+  if (stages.length === 0) throw new RangeError("funnel requires at least one stage");
+  const g = new Graph(name, opts);
+  const merged = sources.length === 1 ? sources[0] : merge(...sources);
+  g.add("merged", merged);
+  let prevOutputPath = "merged";
+  for (let i = 0; i < stages.length; i++) {
+    const stage = stages[i];
+    const sub = new Graph(stage.name);
+    stage.build(sub);
+    try {
+      sub.resolve("input");
+    } catch {
+      throw new Error(`funnel stage "${stage.name}" must define an "input" node`);
+    }
+    try {
+      sub.resolve("output");
+    } catch {
+      throw new Error(`funnel stage "${stage.name}" must define an "output" node`);
+    }
+    g.mount(stage.name, sub);
+    const prevNode = g.resolve(prevOutputPath);
+    const stageInputPath = `${stage.name}::input`;
+    const stageInput = g.resolve(stageInputPath);
+    prevNode.subscribe((msgs) => {
+      for (const msg of msgs) {
+        const t = msg[0];
+        if (t === DATA) {
+          stageInput.down([[DATA, msg[1]]]);
+        } else if (t === DIRTY) {
+          stageInput.down([[DIRTY]]);
+        } else if (t === RESOLVED) {
+          stageInput.down([[RESOLVED]]);
+        } else if (t === COMPLETE || t === ERROR) {
+          stageInput.down([msg]);
+        }
+      }
+    });
+    prevOutputPath = `${stage.name}::output`;
+  }
+  return g;
+}
+function feedback(graph, condition, reentry, opts) {
+  const maxIter = opts?.maxIterations ?? 10;
+  const counterName = `__feedback_${condition}`;
+  const counter = state(0, {
+    meta: baseMeta2("feedback_counter", { maxIterations: maxIter })
+  });
+  graph.add(counterName, counter);
+  const condNode = graph.resolve(condition);
+  const reentryNode = graph.resolve(reentry);
+  condNode.subscribe((msgs) => {
+    for (const msg of msgs) {
+      if (msg[0] === DATA) {
+        const currentCount = counter.get();
+        if (currentCount >= maxIter) continue;
+        const condValue = msg[1];
+        if (condValue == null) continue;
+        counter.down([[DATA, currentCount + 1]]);
+        reentryNode.down([[DATA, condValue]]);
+      }
+    }
+  });
+  return graph;
+}
+function budgetGate(source, constraints, opts) {
+  if (constraints.length === 0) throw new RangeError("budgetGate requires at least one constraint");
+  const constraintNodes = constraints.map((c) => c.node);
+  const allDeps = [source, ...constraintNodes];
+  let buffer2 = [];
+  let paused = false;
+  const lockId = /* @__PURE__ */ Symbol("budget-gate");
+  function checkBudget() {
+    return constraints.every((c) => c.check(c.node.get()));
+  }
+  function flushBuffer(actions) {
+    while (buffer2.length > 0 && checkBudget()) {
+      const item = buffer2.shift();
+      actions.emit(item);
+    }
+  }
+  return node(allDeps, () => void 0, {
+    ...opts,
+    describeKind: "operator",
+    meta: baseMeta2("budget_gate", opts?.meta),
+    onMessage(msg, depIndex, actions) {
+      const t = msg[0];
+      if (depIndex === 0) {
+        if (t === DATA) {
+          if (checkBudget() && buffer2.length === 0) {
+            actions.emit(msg[1]);
+          } else {
+            buffer2.push(msg[1]);
+            if (!paused) {
+              paused = true;
+              actions.up([[PAUSE, lockId]]);
+            }
+          }
+          return true;
+        }
+        if (t === DIRTY) {
+          actions.down([[DIRTY]]);
+          return true;
+        }
+        if (t === RESOLVED) {
+          if (buffer2.length === 0) {
+            actions.down([[RESOLVED]]);
+          }
+          return true;
+        }
+        if (t === COMPLETE || t === ERROR) {
+          for (const item of buffer2) {
+            actions.emit(item);
+          }
+          buffer2 = [];
+          if (paused) {
+            paused = false;
+            actions.up([[RESUME, lockId]]);
+          }
+          actions.down([msg]);
+          return true;
+        }
+        return false;
+      }
+      if (t === DATA || t === RESOLVED) {
+        if (checkBudget() && buffer2.length > 0) {
+          flushBuffer(actions);
+          if (buffer2.length === 0 && paused) {
+            paused = false;
+            actions.up([[RESUME, lockId]]);
+          }
+        } else if (!checkBudget() && !paused && buffer2.length > 0) {
+          paused = true;
+          actions.up([[PAUSE, lockId]]);
+        }
+        return true;
+      }
+      if (t === DIRTY) {
+        return true;
+      }
+      if (t === ERROR) {
+        actions.down([msg]);
+        return true;
+      }
+      if (t === COMPLETE) {
+        return true;
+      }
+      return false;
+    }
+  });
+}
+function scorer(sources, weights, opts) {
+  if (sources.length === 0) throw new RangeError("scorer requires at least one source");
+  if (sources.length !== weights.length) {
+    throw new RangeError("scorer requires the same number of sources and weights");
+  }
+  const allDeps = [...sources, ...weights];
+  const n = sources.length;
+  const scoreFns = opts?.scoreFns;
+  return derived(
+    allDeps,
+    (vals) => {
+      const signals = vals.slice(0, n);
+      const weightValues = vals.slice(n);
+      const breakdown = [];
+      let totalScore = 0;
+      for (let i = 0; i < n; i++) {
+        const sig = signals[i] ?? 0;
+        const wt = weightValues[i] ?? 0;
+        const rawScore = scoreFns?.[i] ? scoreFns[i](sig) : sig;
+        const weighted = rawScore * wt;
+        breakdown.push(weighted);
+        totalScore += weighted;
+      }
+      return {
+        value: signals,
+        score: totalScore,
+        breakdown
+      };
+    },
+    {
+      ...opts,
+      describeKind: "derived",
+      meta: baseMeta2("scorer", opts?.meta)
+    }
+  );
+}
+
 // src/index.ts
 var version = "0.0.0";
 // Annotate the CommonJS export names for ESM import in node:
@@ -16838,6 +17133,7 @@ var version = "0.0.0";
   reactiveLog,
   reactiveMap,
   reduce,
+  reduction,
   repeat,
   replay,
   replayWAL,