flowcraft 2.2.0 → 2.3.0

package/dist/testing/run-with-trace.d.ts

@@ -0,0 +1,38 @@
+import { c as FlowRuntime, g as WorkflowBlueprint, J as WorkflowResult } from '../types-ezHUBdpL.js';
+import '../errors.js';
+import '../container.js';
+
+/**
+ * A test helper that executes a workflow and automatically prints a detailed
+ * execution trace to the console if the workflow fails.
+ *
+ * @example
+ * // In your test file (e.g., my-workflow.test.ts)
+ * it('should process data correctly', async () => {
+ *   const flow = createFlow('my-flow')
+ *     .node('a', async () => ({ output: 1 }))
+ *     .node('b', async ({ input }) => ({ output: input + 1 })) // Bug: returns { output: 3 }
+ *     .edge('a', 'b')
+ *
+ *   const runtime = new FlowRuntime({})
+ *
+ *   // If this test fails, a full, human-readable trace of the execution
+ *   // (inputs, outputs, context changes) is printed to the console.
+ *   const result = await runWithTrace(runtime, flow.toBlueprint())
+ *
+ *   expect(result.context.b).toBe(2)
+ * })
+ *
+ * @param runtime The original FlowRuntime instance (its options will be used).
+ * @param blueprint The WorkflowBlueprint to execute.
+ * @param initialState The initial state for the workflow run.
+ * @param options Additional options for the run.
+ * @returns The WorkflowResult if successful.
+ */
+declare function runWithTrace<TContext extends Record<string, any>>(runtime: FlowRuntime<TContext, any>, blueprint: WorkflowBlueprint, initialState?: Partial<TContext> | string, options?: {
+    functionRegistry?: Map<string, any>;
+    strict?: boolean;
+    signal?: AbortSignal;
+}): Promise<WorkflowResult<Record<string, any>>>;
+
+export { runWithTrace };

package/dist/testing/run-with-trace.js

@@ -0,0 +1,29 @@
+export { runWithTrace } from '../chunk-CY755I7I.js';
+import '../chunk-MUYLRTSR.js';
+import '../chunk-NVJ3ZO3P.js';
+import '../chunk-NVLZFLYM.js';
+import '../chunk-6INWPSZT.js';
+import '../chunk-IB2BISIC.js';
+import '../chunk-MCGK3FXQ.js';
+import '../chunk-DL7KVYZF.js';
+import '../chunk-ONH7PIJZ.js';
+import '../chunk-5KKSQWSC.js';
+import '../chunk-CD3Q4N6V.js';
+import '../chunk-G5BGBPFP.js';
+import '../chunk-DSYAC4WB.js';
+import '../chunk-BC4G7OM6.js';
+import '../chunk-RM677CNU.js';
+import '../chunk-233SESC2.js';
+import '../chunk-33NO4PUJ.js';
+import '../chunk-HAZ26F3P.js';
+import '../chunk-FRKO3WX4.js';
+import '../chunk-CD4FUZOJ.js';
+import '../chunk-4PELJWF7.js';
+import '../chunk-CYHZ2YVH.js';
+import '../chunk-WWGFIYKW.js';
+import '../chunk-R3HQXIEL.js';
+import '../chunk-BCRWXTWX.js';
+import '../chunk-PH2IYZHV.js';
+import '../chunk-LNK7LZER.js';
+//# sourceMappingURL=run-with-trace.js.map
+//# sourceMappingURL=run-with-trace.js.map

package/dist/testing/run-with-trace.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"run-with-trace.js"}

package/dist/testing/stepper.d.ts

@@ -0,0 +1,79 @@
+import { W as WorkflowState, G as GraphTraverser, J as WorkflowResult, c as FlowRuntime, g as WorkflowBlueprint, n as NodeFunction, o as NodeClass } from '../types-ezHUBdpL.js';
+import '../errors.js';
+import '../container.js';
+
+/**
+ * Represents the controlled, step-by-step execution of a workflow.
+ * Returned by the `createStepper` utility.
+ */
+interface IWorkflowStepper<TContext extends Record<string, any>> {
+    /** The current state of the workflow. Can be inspected after each step. */
+    readonly state: WorkflowState<TContext>;
+    /** The graph traverser instance. Can be used to inspect the frontier or completed nodes. */
+    readonly traverser: GraphTraverser;
+    /**
+     * Executes the next "turn" or batch of ready nodes in the workflow.
+     * @param options Optional configuration for this specific step, like a cancellation signal.
+     * @returns A `WorkflowResult` representing the state after the step, or `null` if the workflow has already completed.
+     */
+    next(options?: {
+        signal?: AbortSignal;
+        concurrency?: number;
+    }): Promise<WorkflowResult<TContext> | null>;
+    /**
+     * Reverts the workflow to its previous state.
+     * @returns The `WorkflowResult` of the previous state, or `null` if there is no history to revert to.
+     */
+    prev(): Promise<WorkflowResult<TContext> | null>;
+    /**
+     * Resets the stepper to its initial state, clearing all progress and history.
+     */
+    reset(): void;
+    /**
+     * A convenience method to check if the workflow has any more steps to run.
+     * @returns `true` if the workflow is complete or stalled, `false` otherwise.
+     */
+    isDone(): boolean;
+}
+/**
+ * A test utility that creates a stepper to execute a workflow one "turn" at a time.
+ * This is invaluable for debugging and writing fine-grained tests where you need to
+ * assert the state of the workflow after each logical step.
+ *
+ * @example
+ * // In your test file
+ * it('should correctly execute step-by-step', async () => {
+ *   const runtime = new FlowRuntime({ ... });
+ *   const flow = createFlow('test')
+ *     .node('a', async () => ({ output: 10 }))
+ *     .node('b', async ({ input }) => ({ output: input * 2 }))
+ *     .edge('a', 'b');
+ *
+ *   const stepper = await createStepper(runtime, flow.toBlueprint(), flow.getFunctionRegistry());
+ *
+ *   // First step (executes node 'a')
+ *   const result1 = await stepper.next();
+ *   expect(stepper.isDone()).toBe(false);
+ *   expect(result1.status).toBe('stalled');
+ *   expect(result1.context._outputs.a).toBe(10);
+ *
+ *   // Second step (executes node 'b')
+ *   const result2 = await stepper.next();
+ *   expect(stepper.isDone()).toBe(true);
+ *   expect(result2.status).toBe('completed');
+ *   expect(result2.context._outputs.b).toBe(20);
+ *
+ *   // Final step (no more work)
+ *   const result3 = await stepper.next();
+ *   expect(result3).toBeNull();
+ * });
+ *
+ * @param runtime The `FlowRuntime` instance, used for its configuration.
+ * @param blueprint The `WorkflowBlueprint` to execute.
+ * @param functionRegistry The function registry from createFlow, containing the node implementations.
+ * @param initialState The initial state for the workflow run.
+ * @returns A Promise that resolves to an `IWorkflowStepper` instance.
+ */
+declare function createStepper<TContext extends Record<string, any>, TDependencies extends Record<string, any>>(runtime: FlowRuntime<TContext, TDependencies>, blueprint: WorkflowBlueprint, functionRegistry: Map<string, NodeFunction | NodeClass>, initialState?: Partial<TContext>): Promise<IWorkflowStepper<TContext>>;
+
+export { type IWorkflowStepper, createStepper };

package/dist/testing/stepper.js

@@ -0,0 +1,11 @@
+export { createStepper } from '../chunk-XNRIM27H.js';
+import '../chunk-G53CSLBF.js';
+import '../chunk-G5BGBPFP.js';
+import '../chunk-233SESC2.js';
+import '../chunk-HAZ26F3P.js';
+import '../chunk-FRKO3WX4.js';
+import '../chunk-CD4FUZOJ.js';
+import '../chunk-R3HQXIEL.js';
+import '../chunk-BCRWXTWX.js';
+//# sourceMappingURL=stepper.js.map
+//# sourceMappingURL=stepper.js.map

package/dist/testing/stepper.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stepper.js"}