automategraph 1.5.1 → 1.5.3

package/examples/branching-graph.ts

@@ -0,0 +1,333 @@
+/* ============================================================
+ * Branching graph — a → b / c / d / e / f
+ * ------------------------------------------------------------
+ * ONE GraphDefinition. No router, no walk loop, no engine change.
+ * Built with the same tiny builders the fixtures use:
+ *
+ *   node(id, run, extra)      → { id, run, ...extra }
+ *   constNode(id, output, x)  → node(id, () => output, x)
+ *   g(spec)                   → GraphDefinition
+ *
+ * The picture:
+ *
+ *   a ── result === 1 ────────────▶ b ──(forces)──▶ f
+ *   a ── test(result) === true ───▶ c
+ *   a ── else ────────────────────▶ d
+ *   a ── on throw ────────────────▶ e
+ *   a ── on retry ────────────────▶ f
+ *
+ * HOW EACH ARROW IS EXPRESSED (engine-native only)
+ * ---------------------------------------------------------------
+ * fan-out + guards   `next` is an UNCONDITIONAL fan-out, so a lists
+ *                    every candidate and each one starts with a guard
+ *                    that reads a's output: the acting branch does its
+ *                    work, the others return a SKIP marker.
+ * result === 1 → b   guard: a.route === "b"
+ * test(result) → c   guard: a.route === "c"      (test(r) = r === 2)
+ * else → d           guard: a.route === "d"      (a computed "else")
+ * on throw → e       real transition: a.onThrow = "e"
+ * on retry → f       a returns route "f" when context.attempt > 1
+ *                    (the retry loop is internal, so the attempt
+ *                    number is the only per-attempt signal a node has)
+ * b forces f         b returns void, then releases a gate that f is
+ *                    waiting on — f cannot act before b finished.
+ *
+ * WHY THE GATE FOR "b FORCES f"
+ * ---------------------------------------------------------------
+ * A node cannot schedule work. The only in-node state transition the
+ * engine offers is `throw` + `onThrow`, and here it cannot be used:
+ *   • f must stay in a's fan-out, otherwise the retry arrow has no way
+ *     to reach it (a recovered attempt succeeds, it cannot also throw);
+ *   • if b threw to f, f would be activated a SECOND time, and f
+ *     cannot tell that arrival apart from the fan-out one — both see
+ *     the same outputs (b threw, so it has no output to check);
+ *   • and b would be recorded FAILED, which is wrong for a jump.
+ * So b forces f by ORDER, not by scheduling: f is already activated by
+ * the fan-out, but it blocks on a gate that only b releases. The
+ * observable result is exactly "b runs, then f runs — because of b".
+ *
+ * COMPLETION
+ * ---------------------------------------------------------------
+ * b, c, d, e and f are declared terminal and the graph uses
+ * completionPolicy: "DRAIN", because skipping nodes also succeed and
+ * FIRST_TERMINAL could otherwise latch on a SKIP and drop real work.
+ *
+ * Run:  node js/examples/branching-graph.js     (after npm run build)
+ * ============================================================ */
+
+import {
+  ExecutionReport,
+  GraphDefinition,
+  GraphExecutionEngine,
+  NodeContext,
+  NodeDefinition
+} from "../src/automategraph";
+
+/* =========================
+ * 1. Simple builders (same shape as tests/helpers.ts)
+ * ========================= */
+
+type Extra = Omit<Partial<NodeDefinition>, "id" | "run">;
+
+const node = (
+  id: string,
+  run: NodeDefinition["run"],
+  extra: Extra = {}
+): NodeDefinition => ({ id, run, ...extra });
+
+const constNode = (
+  id: string,
+  output: unknown,
+  extra: Extra = {}
+): NodeDefinition => node(id, () => output, extra);
+
+interface GraphSpec {
+  id?: string;
+  version?: string;
+  nodes: NodeDefinition[];
+  entryNodes: string[];
+  terminalNodes: string[];
+  errorPolicy?: GraphDefinition["errorPolicy"];
+  completionPolicy?: GraphDefinition["completionPolicy"];
+}
+
+const g = (spec: GraphSpec): GraphDefinition => ({
+  id: spec.id ?? "branching-graph",
+  version: spec.version ?? "1.0.0",
+  entryNodes: spec.entryNodes,
+  terminalNodes: spec.terminalNodes,
+  errorPolicy: spec.errorPolicy,
+  completionPolicy: spec.completionPolicy,
+  nodes: Object.fromEntries(spec.nodes.map(definition => [definition.id, definition]))
+});
+
+/* =========================
+ * 2. The spec: a returns 1, 2 or 3; test() splits c from d
+ * ========================= */
+
+export type ScenarioSeed = 1 | 2 | 3 | "throw" | "retry";
+
+/** `test(result)` from the picture. */
+export const test = (result: number): boolean => result === 2;
+
+/** Marker returned by every branch that was activated but is not the chosen one. */
+export interface Skipped {
+  readonly skipped: true;
+  readonly nodeId: string;
+}
+
+const SKIPPED = (nodeId: string): Skipped => ({ skipped: true, nodeId });
+
+/** What node `a` publishes for its successors. */
+interface ARoute {
+  readonly route: "b" | "c" | "d" | "f";
+  readonly result: number;
+  readonly attempts: number;
+}
+
+const routeOf = (context: NodeContext): ARoute | undefined =>
+  context.outputs.a as ARoute | undefined;
+
+/** Observation only — nobody acts on this event; it just records the intent. */
+export const FORCE_EVENT = "graph.force";
+
+/* =========================
+ * 3. The graph
+ * ========================= */
+
+/**
+ * Builds the graph for one run. A fresh gate per run is what makes
+ * "b forces f" deterministic without a router.
+ */
+export function buildGraph(seed: ScenarioSeed): GraphDefinition {
+  /* --- the b → f gate (closure state, not engine state) --- */
+  let released = false;
+  let release: () => void = () => {};
+  const gate = new Promise<void>(resolve => { release = () => { released = true; resolve(); }; });
+
+  return g({
+    id: "branching-graph",
+    version: "1.0.0",
+
+    nodes: [
+      /* ---------------- a: produces the value, owns every arrow ---------------- */
+      node("a", (context: NodeContext): ARoute => {
+        // on throw → e (engine transition, declared as a.onThrow below)
+        if (seed === "throw") {
+          throw new Error("a: upstream exploded");
+        }
+
+        // on retry → f: the retry loop is internal, so a sees its own attempt
+        if (seed === "retry" && context.attempt === 1) {
+          throw new Error(`a: transient failure on attempt ${context.attempt}`);
+        }
+
+        const result = seed === "retry" ? 2 : seed;
+
+        if (context.attempt > 1) {
+          // recovered on a later attempt → the "on retry" arrow points at f
+          return { route: "f", result, attempts: context.attempt };
+        }
+
+        if (result === 1) return { route: "b", result, attempts: context.attempt };
+        if (test(result)) return { route: "c", result, attempts: context.attempt };
+        return { route: "d", result, attempts: context.attempt }; // else
+      }, {
+        // unconditional fan-out: every candidate is activated, guards pick one
+        next: ["b", "c", "d", "f"],
+        onThrow: "e",
+        retry: { maxAttempts: 2, delayMs: 5 },
+        errorPolicy: "RETRY"
+      }),
+
+      /* ---------------- b: returns void, then forces f ---------------- */
+      node("b", async (context: NodeContext) => {
+        if (routeOf(context)?.route !== "b") return SKIPPED("b");
+
+        // b's work ... whatever it needs to do, it returns nothing
+        await context.emit(FORCE_EVENT, { from: "b", to: "f", reason: "b short-circuits to f" });
+
+        release();          // ← this is the force: f is unblocked by b, after b
+        return undefined;   // void
+      }),
+
+      /* ---------------- c: test(result) === true ---------------- */
+      node("c", (context: NodeContext) =>
+        routeOf(context)?.route === "c"
+          ? `c: handled result ${routeOf(context)!.result}`
+          : SKIPPED("c")
+      ),
+
+      /* ---------------- d: else ---------------- */
+      node("d", (context: NodeContext) =>
+        routeOf(context)?.route === "d"
+          ? `d: handled result ${routeOf(context)!.result}`
+          : SKIPPED("d")
+      ),
+
+      /* ---------------- e: on throw ---------------- */
+      constNode("e", "e: failure route"),
+
+      /* ---------------- f: on retry, or forced by b ---------------- */
+      node("f", async (context: NodeContext) => {
+        const route = routeOf(context)?.route;
+
+        if (route === "f") return "f: reached after a retry (on retry arrow)";
+        if (route !== "b") return SKIPPED("f");
+
+        // route === "b": f only acts once b has forced it
+        if (!released) await gate;
+        return "f: forced by b (ran after b completed)";
+      })
+    ],
+
+    entryNodes: ["a"],
+    terminalNodes: ["b", "c", "d", "e", "f"],
+    // skipping nodes succeed too, so let the graph drain instead of
+    // latching on the first success (FIRST_TERMINAL would drop work)
+    completionPolicy: "DRAIN"
+  });
+}
+
+/* =========================
+ * 4. Demo — one engine run per seed, no router
+ * ========================= */
+
+const SCENARIOS: ReadonlyArray<{
+  label: string;
+  seed: ScenarioSeed;
+  /** branch nodes that must do real work, in order */
+  expectedActed: string[];
+}> = [
+  { label: "result === 1      → b, then b forces f", seed: 1, expectedActed: ["b", "f"] },
+  { label: "test(result)      → c", seed: 2, expectedActed: ["c"] },
+  { label: "else              → d", seed: 3, expectedActed: ["d"] },
+  { label: "on throw          → e", seed: "throw", expectedActed: ["e"] },
+  { label: "on retry          → f", seed: "retry", expectedActed: ["f"] }
+];
+
+const isSkipped = (output: unknown): boolean =>
+  typeof output === "object" && output !== null && (output as Skipped).skipped === true;
+
+const show = (output: unknown): string =>
+  output === undefined ? "undefined (void)" : JSON.stringify(output);
+
+const BRANCHES = ["b", "c", "d", "e", "f"] as const;
+
+/** `acted` = the branch nodes that did real work (a is the dispatcher, not a branch). */
+export function summarise(report: ExecutionReport): {
+  acted: string[];
+  status: string;
+  attempts: number;
+} {
+  const dispatcher = report.results.find(result => result.nodeId === "a");
+  return {
+    acted: report.results
+      .filter(
+        result =>
+          BRANCHES.includes(result.nodeId as (typeof BRANCHES)[number]) &&
+          result.status === "SUCCEEDED" &&
+          !isSkipped(result.output)
+      )
+      .map(result => result.nodeId),
+    status: report.status,
+    attempts: dispatcher?.attempt ?? 0
+  };
+}
+
+async function main(): Promise<void> {
+  console.log("=".repeat(104));
+  console.log("branching graph — one GraphDefinition, no router, engine untouched");
+  console.log("=".repeat(104));
+
+  let failures = 0;
+
+  for (const scenario of SCENARIOS) {
+    const engine = new GraphExecutionEngine(buildGraph(scenario.seed), { lint: "error" });
+    const forces: unknown[] = [];
+    engine.events.on(FORCE_EVENT, payload => { forces.push(payload); });
+
+    const report = await engine.run();
+    const summary = summarise(report);
+
+    const actedOk = summary.acted.join(",") === scenario.expectedActed.join(",");
+    const statusOk = summary.status === "COMPLETED";
+    if (!actedOk || !statusOk) failures += 1;
+
+    console.log(`\n▶ seed = ${JSON.stringify(scenario.seed)}   ${scenario.label}`);
+    console.log(
+      `   status=${summary.status}  a.attempt=${summary.attempts}  ` +
+        `acted: ${summary.acted.join(" → ")}  ${actedOk && statusOk ? "✓" : "✗"}`
+    );
+
+    for (const result of report.results) {
+      const tag = result.status === "SUCCEEDED" && !isSkipped(result.output)
+        ? "ACTS "
+        : result.status === "SUCCEEDED"
+          ? "skip "
+          : result.status.padEnd(5);
+      console.log(
+        `     ${tag} ${result.nodeId}  attempt=${result.attempt}  output=${show(result.output)}`
+      );
+    }
+
+    if (report.errors.length > 0) {
+      console.log(
+        `   errors: ${report.errors
+          .map(error => `${error.code}@${error.nodeId ?? "-"}(handled=${error.handled})`)
+          .join(", ")}`
+      );
+    }
+    if (forces.length > 0) {
+      console.log(`   ${FORCE_EVENT}: ${JSON.stringify(forces[0])}`);
+    }
+  }
+
+  console.log(`\n${"-".repeat(104)}`);
+  console.log(`scenarios: ${SCENARIOS.length - failures}/${SCENARIOS.length} matched`);
+  if (failures > 0) process.exitCode = 1;
+}
+
+if (require.main === module) {
+  void main();
+}