@particle-academy/fancy-flow 0.28.0 → 0.29.0

package/dist/run-cohort-CV7EcwGG.d.ts

@@ -0,0 +1,111 @@
+import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-CMSrWVYM.js';
+
+type RunOptions = {
+    /** Stop the run after this many ms. Default: no timeout. */
+    timeoutMs?: number;
+    /** Abort signal — host can cancel the run. */
+    signal?: AbortSignal;
+    /** Initial inputs supplied to entry-point nodes (no incoming edges). */
+    initialInputs?: Record<string, Record<string, unknown>>;
+    /** Nesting depth — set by `subflow` when it runs a child graph. */
+    depth?: number;
+};
+type RunResult = {
+    ok: boolean;
+    /** Outputs collected per node, keyed by node id. */
+    outputs: Record<string, unknown>;
+    /** Error captured if any node threw. */
+    error?: string;
+};
+/**
+ * runFlow — topological execution of a FlowGraph against an ExecutorRegistry.
+ *
+ * Each node runs once, when all upstream nodes have produced outputs on the
+ * connected ports. Decision nodes (or any executor that returns `{ branch:
+ * 'true' }`) can short-circuit specific output ports — only edges leaving
+ * an "active" port propagate to downstream nodes.
+ *
+ * Cycles are detected and abort the run with an error.
+ *
+ * The `onEvent` callback receives a stream of `RunEvent`s — wire it to a
+ * status feed, log panel, or store.
+ */
+declare function runFlow(graph: FlowGraph, executors: ExecutorRegistry, onEvent?: (event: RunEvent) => void, options?: RunOptions): Promise<RunResult>;
+
+/**
+ * How the flows one trigger fired should treat each other.
+ *
+ * - `serial-guarded` (default) — run in the declared order, one at a time,
+ *   re-checking `guard` immediately before each. This is the safe default
+ *   because it is the only one that notices when an earlier flow invalidated
+ *   the state a later one was fired for.
+ * - `serial` — ordered, one at a time, unguarded.
+ * - `parallel` — all at once. Ordering is incidental and collisions are yours to
+ *   handle; correct for fan-outs that share no state, and only those.
+ */
+type CohortPolicy = "serial-guarded" | "serial" | "parallel";
+/**
+ * The precondition re-checked just before each flow starts.
+ *
+ * Return `false` (or throw) to skip that flow. The engine cannot know what
+ * "still valid" means for your data, so it asks you — right before the run,
+ * not at dispatch, because the whole hazard is what changed in between.
+ */
+type CohortGuard = (flow: FlowGraph, index: number) => boolean | Promise<boolean>;
+type CohortOptions = RunOptions & {
+    policy?: CohortPolicy;
+    guard?: CohortGuard;
+    /** Why the guard said no — recorded on the skipped result. */
+    reason?: (flow: FlowGraph, index: number) => string;
+};
+type CohortResult = RunResult & {
+    index: number;
+    /** True when the flow never ran because its guard did not pass. */
+    skipped?: boolean;
+    skippedReason?: string;
+};
+/**
+ * runCohort — run every flow that one trigger event fired, as a group.
+ *
+ * ## Why this exists
+ *
+ * `runFlow` runs one graph. A host that fans a single webhook, schedule, or
+ * record change out to several flows usually loops it — and a loop, or worse a
+ * `Promise.all`, has no answer for the case that actually bites: one of those
+ * flows deletes or mutates the record they were ALL fired for. The others then
+ * run against state that is no longer there and resolve `ok: true`, having done
+ * nothing. Nothing throws. Nothing is logged. That silent success is the failure
+ * mode this function exists to remove.
+ *
+ * ## What it does
+ *
+ * Runs the flows in the order you declared, one at a time, and calls `guard`
+ * immediately before each. A flow whose guard does not pass is returned with
+ * `skipped: true` and a reason instead of being run — and the cohort carries on
+ * to the next one.
+ *
+ * ```ts
+ * const results = await runCohort([enrich, archive, notify], executors, undefined, {
+ *   initialInputs: { t: { deal } },          // snapshotted once, shared by all
+ *   guard: async () => Boolean(await findDeal(deal.id)),
+ *   reason: () => `deal ${deal.id} no longer exists`,
+ * });
+ * ```
+ *
+ * If `archive` deletes the deal, `notify` comes back skipped with that reason
+ * rather than notifying about nothing.
+ *
+ * ## Failure does not cancel the cohort
+ *
+ * A flow that fails is reported and the next one still runs. "The flow before me
+ * threw" is not an answer to "is my input still there" — the guard is, and it
+ * gets asked either way.
+ *
+ * The Laravel twin (`FancyFlow::dispatchCohort()` in `fancy-flow-php`) is the
+ * same contract across a queue, where each run is durable and hands on to its
+ * successor when it settles. Same policies, same guard semantics, same
+ * fail-closed rule.
+ */
+declare function runCohort(flows: FlowGraph[], executors: ExecutorRegistry, onEvent?: (event: RunEvent, index: number) => void, options?: CohortOptions): Promise<CohortResult[]>;
+
+export { type CohortGuard as C, type RunOptions as R, type CohortOptions as a, type CohortPolicy as b, type CohortResult as c, type RunResult as d, runFlow as e, runCohort as r };

package/dist/run-cohort-DitsaYgS.d.cts

@@ -0,0 +1,111 @@
+import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-CMSrWVYM.cjs';
+
+type RunOptions = {
+    /** Stop the run after this many ms. Default: no timeout. */
+    timeoutMs?: number;
+    /** Abort signal — host can cancel the run. */
+    signal?: AbortSignal;
+    /** Initial inputs supplied to entry-point nodes (no incoming edges). */
+    initialInputs?: Record<string, Record<string, unknown>>;
+    /** Nesting depth — set by `subflow` when it runs a child graph. */
+    depth?: number;
+};
+type RunResult = {
+    ok: boolean;
+    /** Outputs collected per node, keyed by node id. */
+    outputs: Record<string, unknown>;
+    /** Error captured if any node threw. */
+    error?: string;
+};
+/**
+ * runFlow — topological execution of a FlowGraph against an ExecutorRegistry.
+ *
+ * Each node runs once, when all upstream nodes have produced outputs on the
+ * connected ports. Decision nodes (or any executor that returns `{ branch:
+ * 'true' }`) can short-circuit specific output ports — only edges leaving
+ * an "active" port propagate to downstream nodes.
+ *
+ * Cycles are detected and abort the run with an error.
+ *
+ * The `onEvent` callback receives a stream of `RunEvent`s — wire it to a
+ * status feed, log panel, or store.
+ */
+declare function runFlow(graph: FlowGraph, executors: ExecutorRegistry, onEvent?: (event: RunEvent) => void, options?: RunOptions): Promise<RunResult>;
+
+/**
+ * How the flows one trigger fired should treat each other.
+ *
+ * - `serial-guarded` (default) — run in the declared order, one at a time,
+ *   re-checking `guard` immediately before each. This is the safe default
+ *   because it is the only one that notices when an earlier flow invalidated
+ *   the state a later one was fired for.
+ * - `serial` — ordered, one at a time, unguarded.
+ * - `parallel` — all at once. Ordering is incidental and collisions are yours to
+ *   handle; correct for fan-outs that share no state, and only those.
+ */
+type CohortPolicy = "serial-guarded" | "serial" | "parallel";
+/**
+ * The precondition re-checked just before each flow starts.
+ *
+ * Return `false` (or throw) to skip that flow. The engine cannot know what
+ * "still valid" means for your data, so it asks you — right before the run,
+ * not at dispatch, because the whole hazard is what changed in between.
+ */
+type CohortGuard = (flow: FlowGraph, index: number) => boolean | Promise<boolean>;
+type CohortOptions = RunOptions & {
+    policy?: CohortPolicy;
+    guard?: CohortGuard;
+    /** Why the guard said no — recorded on the skipped result. */
+    reason?: (flow: FlowGraph, index: number) => string;
+};
+type CohortResult = RunResult & {
+    index: number;
+    /** True when the flow never ran because its guard did not pass. */
+    skipped?: boolean;
+    skippedReason?: string;
+};
+/**
+ * runCohort — run every flow that one trigger event fired, as a group.
+ *
+ * ## Why this exists
+ *
+ * `runFlow` runs one graph. A host that fans a single webhook, schedule, or
+ * record change out to several flows usually loops it — and a loop, or worse a
+ * `Promise.all`, has no answer for the case that actually bites: one of those
+ * flows deletes or mutates the record they were ALL fired for. The others then
+ * run against state that is no longer there and resolve `ok: true`, having done
+ * nothing. Nothing throws. Nothing is logged. That silent success is the failure
+ * mode this function exists to remove.
+ *
+ * ## What it does
+ *
+ * Runs the flows in the order you declared, one at a time, and calls `guard`
+ * immediately before each. A flow whose guard does not pass is returned with
+ * `skipped: true` and a reason instead of being run — and the cohort carries on
+ * to the next one.
+ *
+ * ```ts
+ * const results = await runCohort([enrich, archive, notify], executors, undefined, {
+ *   initialInputs: { t: { deal } },          // snapshotted once, shared by all
+ *   guard: async () => Boolean(await findDeal(deal.id)),
+ *   reason: () => `deal ${deal.id} no longer exists`,
+ * });
+ * ```
+ *
+ * If `archive` deletes the deal, `notify` comes back skipped with that reason
+ * rather than notifying about nothing.
+ *
+ * ## Failure does not cancel the cohort
+ *
+ * A flow that fails is reported and the next one still runs. "The flow before me
+ * threw" is not an answer to "is my input still there" — the guard is, and it
+ * gets asked either way.
+ *
+ * The Laravel twin (`FancyFlow::dispatchCohort()` in `fancy-flow-php`) is the
+ * same contract across a queue, where each run is durable and hands on to its
+ * successor when it settles. Same policies, same guard semantics, same
+ * fail-closed rule.
+ */
+declare function runCohort(flows: FlowGraph[], executors: ExecutorRegistry, onEvent?: (event: RunEvent, index: number) => void, options?: CohortOptions): Promise<CohortResult[]>;
+
+export { type CohortGuard as C, type RunOptions as R, type CohortOptions as a, type CohortPolicy as b, type CohortResult as c, type RunResult as d, runFlow as e, runCohort as r };

package/dist/runtime/index.d.cts

@@ -1,5 +1,5 @@
-import { a as RunResult, R as RunOptions } from '../run-flow-AXzOR-Wq.cjs';
-export { r as runFlow } from '../run-flow-AXzOR-Wq.cjs';
+import { d as RunResult, R as RunOptions } from '../run-cohort-DitsaYgS.cjs';
+export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, r as runCohort, e as runFlow } from '../run-cohort-DitsaYgS.cjs';
 import { e as NodeRunStatus, F as FlowGraph, E as ExecutorRegistry, a as FlowNode, b as FlowEdge } from '../types-CMSrWVYM.cjs';
 import { NodeChange, EdgeChange, Connection } from '@xyflow/react';
 

package/dist/runtime/index.d.ts

@@ -1,5 +1,5 @@
-import { a as RunResult, R as RunOptions } from '../run-flow-9U-gaYVF.js';
-export { r as runFlow } from '../run-flow-9U-gaYVF.js';
+import { d as RunResult, R as RunOptions } from '../run-cohort-CV7EcwGG.js';
+export { C as CohortGuard, a as CohortOptions, b as CohortPolicy, c as CohortResult, r as runCohort, e as runFlow } from '../run-cohort-CV7EcwGG.js';
 import { e as NodeRunStatus, F as FlowGraph, E as ExecutorRegistry, a as FlowNode, b as FlowEdge } from '../types-CMSrWVYM.js';
 import { NodeChange, EdgeChange, Connection } from '@xyflow/react';
 

package/dist/runtime.cjs

@@ -198,6 +198,51 @@ function activatedPorts(node, result) {
   const declared = resolveNodePorts(node, kind).outputs?.map((p) => p.id);
   return { ports: declared?.length ? declared : ["out"], value: result };
 }
+
+// src/runtime/run-cohort.ts
+async function runCohort(flows, executors, onEvent = () => {
+}, options = {}) {
+  const { policy = "serial-guarded", guard, reason, ...runOptions } = options;
+  if (policy === "parallel") {
+    return Promise.all(
+      flows.map(async (flow, index2) => ({
+        ...await runFlow(flow, executors, (e) => onEvent(e, index2), runOptions),
+        index: index2
+      }))
+    );
+  }
+  const results = [];
+  for (const [index2, flow] of flows.entries()) {
+    if (policy === "serial-guarded" && guard) {
+      const why = () => reason?.(flow, index2) ?? "trigger precondition no longer holds";
+      let passes;
+      try {
+        passes = await guard(flow, index2);
+      } catch (error) {
+        results.push({
+          ok: false,
+          outputs: {},
+          index: index2,
+          skipped: true,
+          skippedReason: `guard could not be evaluated: ${errorText(error)}`
+        });
+        continue;
+      }
+      if (!passes) {
+        results.push({ ok: false, outputs: {}, index: index2, skipped: true, skippedReason: why() });
+        continue;
+      }
+    }
+    results.push({
+      ...await runFlow(flow, executors, (e) => onEvent(e, index2), runOptions),
+      index: index2
+    });
+  }
+  return results;
+}
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 function useFlowRun({ maxFeed = 200 } = {}) {
   const [statuses, setStatuses] = ReactExports.useState({});
   const [statusText, setStatusText] = ReactExports.useState({});
@@ -9330,6 +9375,7 @@ function useFlowHistory(flow) {
 exports.applyOutputsToNodes = applyOutputsToNodes;
 exports.applyStatusesToNodes = applyStatusesToNodes;
 exports.createHistory = createHistory;
+exports.runCohort = runCohort;
 exports.runFlow = runFlow;
 exports.useFlowHistory = useFlowHistory;
 exports.useFlowRun = useFlowRun;