@q1k-oss/btree-workflows 0.0.1

package/src/composites/for-each.test.ts

@@ -0,0 +1,254 @@
+/**
+ * Tests for ForEach node
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { ConfigurationError } from "../errors.js";
+import { SuccessNode } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { ForEach } from "./for-each.js";
+
+describe("ForEach", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  describe("Basic Functionality", () => {
+    it("should iterate over collection", async () => {
+      const forEach = new ForEach({
+        id: "forEach1",
+        collectionKey: "items",
+        itemKey: "currentItem",
+      });
+
+      const items = ["a", "b", "c"];
+      blackboard.set("items", items);
+
+      const processedItems: string[] = [];
+      class RecordingNode extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          const item = context.blackboard.get("currentItem");
+          processedItems.push(item);
+          return await superTick(context);
+        }
+      }
+
+      forEach.addChild(new RecordingNode({ id: "body" }));
+
+      const result = await forEach.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+      expect(processedItems).toEqual(["a", "b", "c"]);
+    });
+
+    it("should set item and index in blackboard", async () => {
+      const forEach = new ForEach({
+        id: "forEach1",
+        collectionKey: "numbers",
+        itemKey: "num",
+        indexKey: "i",
+      });
+
+      blackboard.set("numbers", [10, 20, 30]);
+
+      const recorded: Array<{ item: number; index: number }> = [];
+      class RecordingNode extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          recorded.push({
+            item: context.blackboard.get("num"),
+            index: context.blackboard.get("i"),
+          });
+          return await superTick(context);
+        }
+      }
+
+      forEach.addChild(new RecordingNode({ id: "body" }));
+
+      await forEach.tick(context);
+
+      expect(recorded).toEqual([
+        { item: 10, index: 0 },
+        { item: 20, index: 1 },
+        { item: 30, index: 2 },
+      ]);
+    });
+  });
+
+  describe("Failure Handling", () => {
+    it("should fail on first failure", async () => {
+      const forEach = new ForEach({
+        id: "forEach1",
+        collectionKey: "items",
+        itemKey: "item",
+      });
+
+      blackboard.set("items", ["a", "b", "c"]);
+
+      let tickCount = 0;
+      class FailOnSecond extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          tickCount++;
+          if (tickCount === 2) {
+            this._status = NodeStatus.FAILURE;
+            return NodeStatus.FAILURE;
+          }
+          return await superTick(context);
+        }
+      }
+
+      forEach.addChild(new FailOnSecond({ id: "body" }));
+
+      const result = await forEach.tick(context);
+      expect(result).toBe(NodeStatus.FAILURE);
+      expect(tickCount).toBe(2); // Only processed 2 items
+    });
+
+    it("should fail if collection not found", async () => {
+      const forEach = new ForEach({
+        id: "forEach1",
+        collectionKey: "missing",
+        itemKey: "item",
+      });
+
+      forEach.addChild(new SuccessNode({ id: "body" }));
+
+      const result = await forEach.tick(context);
+      expect(result).toBe(NodeStatus.FAILURE);
+    });
+
+    it("should return FAILURE if collection is not an array", async () => {
+      const forEach = new ForEach({
+        id: "forEach1",
+        collectionKey: "notArray",
+        itemKey: "item",
+      });
+
+      blackboard.set("notArray", "not an array");
+      forEach.addChild(new SuccessNode({ id: "body" }));
+
+      const status = await forEach.tick(context);
+      expect(status).toBe(NodeStatus.FAILURE);
+    });
+  });
+
+  describe("RUNNING State", () => {
+    it("should resume from saved index on RUNNING", async () => {
+      const forEach = new ForEach({
+        id: "forEach1",
+        collectionKey: "items",
+        itemKey: "item",
+      });
+
+      blackboard.set("items", ["a", "b", "c"]);
+
+      let tickCount = 0;
+      class RunningOnSecond extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          tickCount++;
+          if (tickCount === 2) {
+            this._status = NodeStatus.RUNNING;
+            return NodeStatus.RUNNING;
+          }
+          return await superTick(context);
+        }
+      }
+
+      const body = new RunningOnSecond({ id: "body" });
+      forEach.addChild(body);
+
+      // First tick: processes item 0, returns RUNNING on item 1
+      let result = await forEach.tick(context);
+      expect(result).toBe(NodeStatus.RUNNING);
+      expect(tickCount).toBe(2);
+
+      // Second tick: should resume from item 1
+      result = await forEach.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+      expect(tickCount).toBe(4); // item 1 (again), item 2
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should return SUCCESS for empty collection", async () => {
+      const forEach = new ForEach({
+        id: "forEach1",
+        collectionKey: "empty",
+        itemKey: "item",
+      });
+
+      blackboard.set("empty", []);
+      forEach.addChild(new SuccessNode({ id: "body" }));
+
+      const result = await forEach.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+    });
+
+    it("should reset index on success", async () => {
+      const forEach = new ForEach({
+        id: "forEach1",
+        collectionKey: "items",
+        itemKey: "item",
+      });
+
+      blackboard.set("items", ["a", "b"]);
+
+      let firstRunCount = 0;
+      let secondRunCount = 0;
+
+      class CountingNode extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          if (secondRunCount > 0) {
+            secondRunCount++;
+          } else {
+            firstRunCount++;
+          }
+          return await superTick(context);
+        }
+      }
+
+      forEach.addChild(new CountingNode({ id: "body" }));
+
+      // First execution
+      await forEach.tick(context);
+      expect(firstRunCount).toBe(2);
+
+      // Second execution should start from beginning
+      secondRunCount = 1;
+      await forEach.tick(context);
+      expect(secondRunCount).toBe(3); // Initial 1 + 2 items
+    });
+
+    it("should propagate ConfigurationError with no child", async () => {
+      const forEach = new ForEach({
+        id: "forEach1",
+        collectionKey: "items",
+        itemKey: "item",
+      });
+
+      blackboard.set("items", ["a"]);
+
+      try {
+        await forEach.tick(context);
+        expect.fail("Should have thrown ConfigurationError");
+      } catch (error) {
+        expect(error).toBeInstanceOf(ConfigurationError);
+        expect((error as ConfigurationError).message).toContain(
+          "ForEach requires at least one child",
+        );
+      }
+    });
+  });
+});

package/src/composites/for-each.ts

@@ -0,0 +1,132 @@
+/**
+ * ForEach node - Iterate over collection
+ */
+
+import { CompositeNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  NodeStatus,
+} from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+
+export interface ForEachConfiguration extends NodeConfiguration {
+  collectionKey: string; // Blackboard key for array
+  itemKey: string; // Blackboard key for current item
+  indexKey?: string; // Blackboard key for current index
+}
+
+/**
+ * ForEach iterates over a collection from the blackboard.
+ * For each item, it sets the item (and optionally index) in the blackboard
+ * and executes the body (first child).
+ */
+export class ForEach extends CompositeNode {
+  private collectionKey: string;
+  private itemKey: string;
+  private indexKey?: string;
+  private currentIndex: number = 0;
+
+  constructor(config: ForEachConfiguration) {
+    super(config);
+    this.collectionKey = config.collectionKey;
+    this.itemKey = config.itemKey;
+    this.indexKey = config.indexKey;
+  }
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    if (this._children.length === 0) {
+      throw new ConfigurationError(
+        "ForEach requires at least one child (body)",
+      );
+    }
+
+    const body = this._children[0];
+    if (!body) {
+      throw new ConfigurationError(
+        "ForEach requires at least one child (body)",
+      );
+    }
+
+    const collection = context.blackboard.get(this.collectionKey);
+
+    if (!collection) {
+      this.log(`Collection '${this.collectionKey}' not found in blackboard`);
+      this._status = NodeStatus.FAILURE;
+      return NodeStatus.FAILURE;
+    }
+
+    if (!Array.isArray(collection)) {
+      throw new Error(`Collection '${this.collectionKey}' is not an array`);
+    }
+
+    // Empty collection is success
+    if (collection.length === 0) {
+      this.log("Collection is empty - returning SUCCESS");
+      this._status = NodeStatus.SUCCESS;
+      return NodeStatus.SUCCESS;
+    }
+
+    this.log(
+      `Iterating over collection (${collection.length} items), starting at index ${this.currentIndex}`,
+    );
+
+    // Continue from where we left off
+    while (this.currentIndex < collection.length) {
+      // Check for cancellation before processing each item
+      checkSignal(context.signal);
+
+      const item = collection[this.currentIndex];
+
+      // Set current item and index in blackboard
+      context.blackboard.set(this.itemKey, item);
+      if (this.indexKey) {
+        context.blackboard.set(this.indexKey, this.currentIndex);
+      }
+
+      this.log(
+        `Processing item ${this.currentIndex}: ${JSON.stringify(item)}`,
+      );
+      const bodyStatus = await body.tick(context);
+
+      switch (bodyStatus) {
+        case NodeStatus.SUCCESS:
+          this.log(`Item ${this.currentIndex} succeeded`);
+          this.currentIndex++;
+          body.reset(); // Reset for next iteration
+          break;
+
+        case NodeStatus.FAILURE:
+          this.log(`Item ${this.currentIndex} failed - ForEach fails`);
+          this._status = NodeStatus.FAILURE;
+          this.currentIndex = 0; // Reset for next tick
+          return NodeStatus.FAILURE;
+
+        case NodeStatus.RUNNING:
+          this.log(`Item ${this.currentIndex} is running`);
+          this._status = NodeStatus.RUNNING;
+          return NodeStatus.RUNNING; // Will resume from this index next tick
+
+        default:
+          throw new Error(`Unexpected status from body: ${bodyStatus}`);
+      }
+    }
+
+    // All items processed successfully
+    this.log("All items processed successfully");
+    this._status = NodeStatus.SUCCESS;
+    this.currentIndex = 0; // Reset for next tick
+    return NodeStatus.SUCCESS;
+  }
+
+  protected onReset(): void {
+    super.onReset();
+    this.currentIndex = 0;
+  }
+
+  protected onHalt(): void {
+    super.onHalt();
+    this.currentIndex = 0;
+  }
+}

package/src/composites/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Export all composite nodes
+ */
+
+export { Conditional } from "./conditional.js";
+export { ForEach } from "./for-each.js";
+export { MemorySequence, SequenceWithMemory } from "./memory-sequence.js";
+export { Parallel } from "./parallel.js";
+export type { ParallelStrategy } from "./parallel.js";
+export { ReactiveSequence } from "./reactive-sequence.js";
+export { Recovery } from "./recovery.js";
+export { Selector, Fallback } from "./selector.js";
+export { Sequence } from "./sequence.js";
+export { SubTree } from "./sub-tree.js";
+export { While } from "./while.js";

package/src/composites/memory-sequence.schema.ts

@@ -0,0 +1,19 @@
+/**
+ * MemorySequence composite configuration schema
+ */
+
+import { z } from "zod";
+import { nodeConfigurationSchema } from "../schemas/base.schema.js";
+
+/**
+ * Schema for MemorySequence composite configuration
+ * Uses base schema only (no additional properties)
+ */
+export const memorySequenceConfigurationSchema = nodeConfigurationSchema;
+
+/**
+ * Validated MemorySequence configuration type
+ */
+export type ValidatedMemorySequenceConfiguration = z.infer<
+  typeof memorySequenceConfigurationSchema
+>;

package/src/composites/memory-sequence.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Tests for MemorySequence node
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { FailureNode, RunningNode, SuccessNode } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { MemorySequence, SequenceWithMemory } from "./memory-sequence.js";
+
+describe("MemorySequence", () => {
+  let blackboard: ScopedBlackboard;
+  let context: TemporalContext;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard("root");
+    context = {
+      blackboard,
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+  });
+
+  describe("Basic Functionality", () => {
+    it("should execute children in order", async () => {
+      const seq = new MemorySequence({ id: "seq1" });
+      const child1 = new SuccessNode({ id: "child1" });
+      const child2 = new SuccessNode({ id: "child2" });
+      const child3 = new SuccessNode({ id: "child3" });
+
+      seq.addChildren([child1, child2, child3]);
+
+      const result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+    });
+
+    it("should fail fast on first failure", async () => {
+      const seq = new MemorySequence({ id: "seq1" });
+      const child1 = new SuccessNode({ id: "child1" });
+      const child2 = new FailureNode({ id: "child2" });
+      const child3 = new SuccessNode({ id: "child3" });
+
+      seq.addChildren([child1, child2, child3]);
+
+      const result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.FAILURE);
+      expect(child3.status()).toBe(NodeStatus.IDLE); // Never executed
+    });
+  });
+
+  describe("Memory Behavior", () => {
+    it("should skip completed children on retry after failure", async () => {
+      const seq = new MemorySequence({ id: "seq1" });
+
+      // Track execution count for each child
+      let child1Ticks = 0;
+      let child2Ticks = 0;
+      let child3Ticks = 0;
+
+      class CountingSuccess extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          if (this.id === "child1") child1Ticks++;
+          if (this.id === "child2") child2Ticks++;
+          if (this.id === "child3") child3Ticks++;
+          return await superTick(context);
+        }
+      }
+
+      const child1 = new CountingSuccess({ id: "child1" });
+      const child2 = new CountingSuccess({ id: "child2" });
+
+      // Child3 fails first time, succeeds second
+      let child3TickCount = 0;
+      class FlipFlopNode extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          child3TickCount++;
+          child3Ticks++;
+          // Fail first time, succeed second
+          if (child3TickCount === 1) {
+            this._status = NodeStatus.FAILURE;
+            return NodeStatus.FAILURE;
+          }
+          return await superTick(context);
+        }
+      }
+
+      const child3 = new FlipFlopNode({ id: "child3" });
+
+      seq.addChildren([child1, child2, child3]);
+
+      // First tick: child1 and child2 succeed, child3 fails
+      let result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.FAILURE);
+      expect(child1Ticks).toBe(1);
+      expect(child2Ticks).toBe(1);
+      expect(child3Ticks).toBe(1);
+
+      // Second tick: should skip child1 and child2, go straight to child3
+      result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+      expect(child1Ticks).toBe(1); // Not re-executed
+      expect(child2Ticks).toBe(1); // Not re-executed
+      expect(child3Ticks).toBe(2); // Re-executed (not completed before)
+    });
+
+    it("should remember successful children across ticks", async () => {
+      const seq = new MemorySequence({ id: "seq1" });
+
+      const child1 = new SuccessNode({ id: "child1" });
+
+      // Child2 returns RUNNING first time, SUCCESS second time
+      let child2TickCount = 0;
+      class TwoTickNode extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          child2TickCount++;
+          if (child2TickCount === 1) {
+            this._status = NodeStatus.RUNNING;
+            return NodeStatus.RUNNING;
+          }
+          return await superTick(context);
+        }
+      }
+
+      const child2 = new TwoTickNode({ id: "child2" });
+      const child3 = new SuccessNode({ id: "child3" });
+
+      seq.addChildren([child1, child2, child3]);
+
+      // First tick: child1 succeeds, child2 returns RUNNING
+      let result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.RUNNING);
+      expect(child1.status()).toBe(NodeStatus.SUCCESS);
+      expect(child2.status()).toBe(NodeStatus.RUNNING);
+      expect(child3.status()).toBe(NodeStatus.IDLE);
+
+      // Second tick: should skip child1, continue from child2 which now succeeds
+      result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+      expect(child2TickCount).toBe(2);
+      expect(child3.status()).toBe(NodeStatus.SUCCESS);
+    });
+
+    it("should not skip RUNNING children", async () => {
+      const seq = new MemorySequence({ id: "seq1" });
+
+      const child1 = new SuccessNode({ id: "child1" });
+      const child2 = new RunningNode({ id: "child2" });
+
+      seq.addChildren([child1, child2]);
+
+      // First tick: child1 succeeds, child2 running
+      let result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.RUNNING);
+
+      // Second tick: child2 still running, should be ticked again
+      result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.RUNNING);
+      expect(child2.status()).toBe(NodeStatus.RUNNING);
+    });
+
+    it("should clear memory on reset", async () => {
+      const seq = new MemorySequence({ id: "seq1" });
+
+      let child1Ticks = 0;
+      class CountingSuccess extends SuccessNode {
+        async tick(context: TemporalContext): Promise<NodeStatus> {
+          const superTick = super.tick.bind(this);
+          child1Ticks++;
+          return await superTick(context);
+        }
+      }
+
+      const child1 = new CountingSuccess({ id: "child1" });
+      const child2 = new FailureNode({ id: "child2" });
+
+      seq.addChildren([child1, child2]);
+
+      // First execution: child1 succeeds, child2 fails
+      await seq.tick(context);
+      expect(child1Ticks).toBe(1);
+
+      // Reset should clear memory
+      seq.reset();
+
+      // Second execution: child1 should be re-executed
+      await seq.tick(context);
+      expect(child1Ticks).toBe(2);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle empty children array", async () => {
+      const seq = new MemorySequence({ id: "seq1" });
+      const result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+    });
+
+    it("should handle single child", async () => {
+      const seq = new MemorySequence({ id: "seq1" });
+      const child = new SuccessNode({ id: "child1" });
+      seq.addChild(child);
+
+      const result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+    });
+  });
+
+  describe("Alias", () => {
+    it("should work with SequenceWithMemory alias", async () => {
+      const seq = new SequenceWithMemory({ id: "seq1" });
+      const child1 = new SuccessNode({ id: "child1" });
+      const child2 = new SuccessNode({ id: "child2" });
+
+      seq.addChildren([child1, child2]);
+
+      const result = await seq.tick(context);
+      expect(result).toBe(NodeStatus.SUCCESS);
+    });
+  });
+});