@funkai/agents 0.1.0

package/src/core/agents/flow/steps/each.test.ts

@@ -0,0 +1,257 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createStepBuilder } from "@/core/agents/flow/steps/factory.js";
+import { createMockCtx } from "@/testing/index.js";
+
+describe("each()", () => {
+  it("iterates items sequentially", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const order: number[] = [];
+
+    const result = await $.each({
+      id: "each-seq",
+      input: [1, 2, 3],
+      execute: async ({ item }) => {
+        order.push(item);
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(order).toEqual([1, 2, 3]);
+    expect(result.step.type).toBe("each");
+  });
+
+  it("returns ok: true with void value on success", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.each({
+      id: "each-void",
+      input: [1],
+      execute: async () => {},
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value).toBeUndefined();
+  });
+
+  it("propagates errors from execute", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    const result = await $.each({
+      id: "each-err",
+      input: [1, 2, 3],
+      execute: async ({ item }) => {
+        if (item === 2) {
+          throw new Error("stop at 2");
+        }
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.message).toBe("stop at 2");
+    expect(result.error.stepId).toBe("each-err");
+  });
+
+  it("stops iteration on error (does not process remaining items)", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const processed: number[] = [];
+
+    await $.each({
+      id: "each-stop",
+      input: [1, 2, 3],
+      execute: async ({ item }) => {
+        if (item === 2) {
+          throw new Error("stop");
+        }
+        processed.push(item);
+      },
+    });
+
+    expect(processed).toEqual([1]);
+  });
+
+  it("handles empty input array", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const executeSpy = vi.fn();
+
+    const result = await $.each({
+      id: "each-empty",
+      input: [],
+      execute: executeSpy,
+    });
+
+    expect(result.ok).toBe(true);
+    expect(executeSpy).not.toHaveBeenCalled();
+  });
+
+  it("handles single-item input", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const processed: string[] = [];
+
+    const result = await $.each({
+      id: "each-single",
+      input: ["only"],
+      execute: async ({ item }) => {
+        processed.push(item);
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(processed).toEqual(["only"]);
+  });
+
+  it("passes index to execute callback", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const indices: number[] = [];
+
+    await $.each({
+      id: "each-index",
+      input: ["a", "b", "c"],
+      execute: async ({ index }) => {
+        indices.push(index);
+      },
+    });
+
+    expect(indices).toEqual([0, 1, 2]);
+  });
+
+  it("respects abort signal", async () => {
+    const controller = new AbortController();
+    const ctx = createMockCtx({ signal: controller.signal });
+    const $ = createStepBuilder({ ctx });
+    const processed: number[] = [];
+
+    controller.abort();
+
+    const result = await $.each({
+      id: "each-aborted",
+      input: [1, 2, 3],
+      execute: async ({ item }) => {
+        processed.push(item);
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.message).toBe("Aborted");
+  });
+
+  it("fires onStart and onFinish hooks", async () => {
+    const order: string[] = [];
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.each({
+      id: "each-hooks",
+      input: [1, 2],
+      onStart: () => {
+        order.push("onStart");
+      },
+      execute: async ({ item }) => {
+        order.push(`execute:${item}`);
+      },
+      onFinish: () => {
+        order.push("onFinish");
+      },
+    });
+
+    expect(order).toEqual(["onStart", "execute:1", "execute:2", "onFinish"]);
+  });
+
+  it("fires onError hook on failure", async () => {
+    const onError = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.each({
+      id: "each-onerror",
+      input: [1],
+      execute: async () => {
+        throw new Error("each failure");
+      },
+      onError,
+    });
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "each-onerror",
+        error: expect.any(Error),
+      }),
+    );
+  });
+
+  it("onFinish receives duration but no result", async () => {
+    const onFinish = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.each({
+      id: "each-finish",
+      input: [1],
+      execute: async () => {},
+      onFinish,
+    });
+
+    expect(onFinish).toHaveBeenCalledTimes(1);
+    expect(onFinish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "each-finish",
+        duration: expect.any(Number),
+      }),
+    );
+  });
+
+  it("records trace entry", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+
+    await $.each({
+      id: "each-trace",
+      input: [10, 20],
+      execute: async () => {},
+    });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.id).toBe("each-trace");
+    expect(traceEntry.type).toBe("each");
+    expect(traceEntry.input).toEqual([10, 20]);
+  });
+
+  it("provides child $ for nested operations", async () => {
+    const ctx = createMockCtx();
+    const $$ = createStepBuilder({ ctx });
+
+    await $$.each({
+      id: "each-nested",
+      input: [1],
+      execute: async ({ $ }) => {
+        await $.step({ id: "inner-step", execute: async () => "nested" });
+      },
+    });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.children).toHaveLength(1);
+  });
+});

package/src/core/agents/flow/steps/each.ts

@@ -0,0 +1,61 @@
+import type { StepBuilder } from "@/core/agents/flow/steps/builder.js";
+
+/**
+ * Configuration for `$.each()` — sequential side effects.
+ *
+ * Runs items one at a time in order. Returns `void`. If you need
+ * accumulated results from sequential iteration, use `$.reduce()`.
+ *
+ * @typeParam T - Input item type.
+ */
+export interface EachConfig<T> {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace.
+   */
+  id: string;
+
+  /**
+   * Array of items to process sequentially.
+   *
+   * Each item is passed to the `execute` callback in order.
+   */
+  input: readonly T[];
+
+  /**
+   * Process a single item (side effect).
+   *
+   * @param params - Execution parameters.
+   * @param params.item - The current item from the input array.
+   * @param params.index - The item's zero-based index in the input array.
+   * @param params.$ - The step builder for nesting further operations.
+   */
+  execute: (params: { item: T; index: number; $: StepBuilder }) => Promise<void>;
+
+  /**
+   * Hook: fires when the each operation starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: { id: string }) => void | Promise<void>;
+
+  /**
+   * Hook: fires when all items are processed.
+   *
+   * @param event - Event containing the step id and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: { id: string; duration: number }) => void | Promise<void>;
+
+  /**
+   * Hook: fires if the each operation encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: { id: string; error: Error }) => void | Promise<void>;
+}

package/src/core/agents/flow/steps/factory.test-d.ts

@@ -0,0 +1,50 @@
+import { describe, expectTypeOf, it } from "vitest";
+
+import type { StepBuilder } from "@/core/agents/flow/steps/builder.js";
+import { createStepBuilder } from "@/core/agents/flow/steps/factory.js";
+import type { StepResult, StepError } from "@/core/agents/flow/steps/result.js";
+import type { ResultError } from "@/utils/result.js";
+
+describe("StepError extends ResultError", () => {
+  it("is assignable to ResultError", () => {
+    expectTypeOf<StepError>().toExtend<ResultError>();
+  });
+
+  it("has stepId field", () => {
+    expectTypeOf<StepError["stepId"]>().toBeString();
+  });
+});
+
+describe("StepResult<T>", () => {
+  it("success branch has ok: true", () => {
+    type Success = Extract<StepResult<{ value: number }>, { ok: true }>;
+    expectTypeOf<Success["ok"]>().toEqualTypeOf<true>();
+  });
+
+  it("success branch has value: T field", () => {
+    type Success = Extract<StepResult<{ value: number }>, { ok: true }>;
+    expectTypeOf<Success["value"]>().toEqualTypeOf<{ value: number }>();
+  });
+
+  it("success branch has step and duration", () => {
+    type Success = Extract<StepResult<{ value: number }>, { ok: true }>;
+    expectTypeOf<Success["step"]>().toHaveProperty("id");
+    expectTypeOf<Success["duration"]>().toBeNumber();
+  });
+
+  it("failure branch has ok: false", () => {
+    type Failure = Extract<StepResult<{ value: number }>, { ok: false }>;
+    expectTypeOf<Failure["ok"]>().toEqualTypeOf<false>();
+  });
+
+  it("failure branch has StepError", () => {
+    type Failure = Extract<StepResult<{ value: number }>, { ok: false }>;
+    expectTypeOf<Failure["error"]>().toExtend<StepError>();
+  });
+});
+
+describe("createStepBuilder", () => {
+  it("returns StepBuilder", () => {
+    expectTypeOf(createStepBuilder).returns.toExtend<StepBuilder>();
+  });
+});