@q1k-oss/btree-workflows 0.0.1

package/src/composites/selector.test.ts

@@ -0,0 +1,387 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { ActionNode } from "../base-node.js";
+import { ScopedBlackboard } from "../blackboard.js";
+import { ConfigurationError } from "../errors.js";
+import { MockAction } from "../test-nodes.js";
+import { type TemporalContext, NodeStatus } from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+import { Fallback, Selector } from "./selector.js";
+
+describe("Selector", () => {
+  let context: TemporalContext;
+  let selector: Selector;
+
+  beforeEach(() => {
+    context = {
+      blackboard: new ScopedBlackboard(),
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+    selector = new Selector({ id: "test-selector" });
+  });
+
+  it("should return FAILURE when empty", async () => {
+    const status = await selector.tick(context);
+    expect(status).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should return SUCCESS on first successful child", async () => {
+    const executionOrder: string[] = [];
+
+    const child1 = new MockAction({
+      id: "child1",
+      returnStatus: NodeStatus.FAILURE,
+    });
+    const child2 = new MockAction({
+      id: "child2",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+    const child3 = new MockAction({
+      id: "child3",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    // Track execution order
+    const originalTick1 = child1.tick.bind(child1);
+    const originalTick2 = child2.tick.bind(child2);
+    const originalTick3 = child3.tick.bind(child3);
+
+    child1.tick = (ctx) => {
+      executionOrder.push("child1");
+      return originalTick1(ctx);
+    };
+    child2.tick = (ctx) => {
+      executionOrder.push("child2");
+      return originalTick2(ctx);
+    };
+    child3.tick = (ctx) => {
+      executionOrder.push("child3");
+      return originalTick3(ctx);
+    };
+
+    selector.addChildren([child1, child2, child3]);
+
+    const status = await selector.tick(context);
+
+    expect(status).toBe(NodeStatus.SUCCESS);
+    expect(executionOrder).toEqual(["child1", "child2"]); // child3 should not execute
+    expect(selector.status()).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should return FAILURE when all children fail", async () => {
+    const child1 = new MockAction({
+      id: "child1",
+      returnStatus: NodeStatus.FAILURE,
+    });
+    const child2 = new MockAction({
+      id: "child2",
+      returnStatus: NodeStatus.FAILURE,
+    });
+    const child3 = new MockAction({
+      id: "child3",
+      returnStatus: NodeStatus.FAILURE,
+    });
+
+    selector.addChildren([child1, child2, child3]);
+
+    const status = await selector.tick(context);
+
+    expect(status).toBe(NodeStatus.FAILURE);
+    expect(selector.status()).toBe(NodeStatus.FAILURE);
+  });
+
+  it("should handle RUNNING status correctly", async () => {
+    const child1 = new MockAction({
+      id: "child1",
+      returnStatus: NodeStatus.FAILURE,
+    });
+    let child2 = new MockAction({
+      id: "child2",
+      returnStatus: NodeStatus.RUNNING,
+      ticksBeforeComplete: 2,
+    });
+    const child3 = new MockAction({
+      id: "child3",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    selector.addChildren([child1, child2, child3]);
+
+    // First tick - child2 returns RUNNING
+    let status = await selector.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+    expect(child1.status()).toBe(NodeStatus.FAILURE);
+    expect(child2.status()).toBe(NodeStatus.RUNNING);
+
+    // Second tick - child2 still RUNNING
+    status = await selector.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+
+    // Replace child2 to simulate completion
+    child2 = new MockAction({
+      id: "child2",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+    selector._children[1] = child2;
+
+    status = await selector.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+    expect(child3.status()).toBe(NodeStatus.IDLE); // Should not have been executed
+  });
+
+  it("should continue after RUNNING child fails", async () => {
+    let tickCount = 0;
+    const child1 = new MockAction({
+      id: "child1",
+      returnStatus: NodeStatus.FAILURE,
+    });
+
+    // Custom child that returns RUNNING first, then FAILURE
+    const child2 = new MockAction({ id: "child2" });
+    child2.tick = async (_ctx) => {
+      tickCount++;
+      if (tickCount === 1) {
+        (child2 as unknown)._status = NodeStatus.RUNNING;
+        return NodeStatus.RUNNING;
+      }
+      (child2 as unknown)._status = NodeStatus.FAILURE;
+      return NodeStatus.FAILURE;
+    };
+
+    const child3 = new MockAction({
+      id: "child3",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    selector.addChildren([child1, child2, child3]);
+
+    // First tick - child2 returns RUNNING
+    let status = await selector.tick(context);
+    expect(status).toBe(NodeStatus.RUNNING);
+
+    // Second tick - child2 fails, moves to child3
+    status = await selector.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+    expect(child3.status()).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should reset child index on completion", async () => {
+    const child1 = new MockAction({
+      id: "child1",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+    const child2 = new MockAction({
+      id: "child2",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    selector.addChildren([child1, child2]);
+
+    // First execution
+    await selector.tick(context);
+    expect((selector as unknown).currentChildIndex).toBe(0);
+
+    // Reset children status for second execution
+    child1.reset();
+
+    // Second execution should start from beginning
+    await selector.tick(context);
+    expect(child1.status()).toBe(NodeStatus.SUCCESS);
+  });
+
+  it("should halt running children when halted", async () => {
+    const child1 = new MockAction({
+      id: "child1",
+      returnStatus: NodeStatus.FAILURE,
+    });
+    const child2 = new MockAction({
+      id: "child2",
+      returnStatus: NodeStatus.RUNNING,
+    });
+
+    selector.addChildren([child1, child2]);
+
+    // Start execution
+    await selector.tick(context);
+    expect(selector.status()).toBe(NodeStatus.RUNNING);
+
+    // Halt the selector
+    selector.halt();
+
+    expect(selector.status()).toBe(NodeStatus.IDLE);
+    expect((selector as unknown).currentChildIndex).toBe(0);
+  });
+
+  it("should throw error if child is undefined", () => {
+    expect(() => selector.addChild(undefined as unknown)).toThrow(
+      "Cannot add undefined child to composite node",
+    );
+  });
+
+  describe("Signal-based cancellation", () => {
+    it("should stop executing children when signal is aborted", async () => {
+      const executionOrder: string[] = [];
+      const controller = new AbortController();
+
+      context.signal = controller.signal;
+
+      const child1 = new MockAction({
+        id: "child1",
+        returnStatus: NodeStatus.FAILURE,
+      });
+      const child2 = new MockAction({
+        id: "child2",
+        returnStatus: NodeStatus.SUCCESS,
+      });
+      const child3 = new MockAction({
+        id: "child3",
+        returnStatus: NodeStatus.SUCCESS,
+      });
+
+      const originalTick1 = child1.tick.bind(child1);
+      const originalTick2 = child2.tick.bind(child2);
+      const originalTick3 = child3.tick.bind(child3);
+
+      child1.tick = (ctx: TemporalContext) => {
+        executionOrder.push("child1");
+        return originalTick1(ctx);
+      };
+      child2.tick = (ctx: TemporalContext) => {
+        executionOrder.push("child2");
+        return originalTick2(ctx);
+      };
+      child3.tick = (ctx: TemporalContext) => {
+        executionOrder.push("child3");
+        return originalTick3(ctx);
+      };
+
+      selector.addChildren([child1, child2, child3]);
+
+      // Abort signal before ticking
+      controller.abort();
+
+      try {
+        await selector.tick(context);
+        expect.fail("Should have thrown an error");
+      } catch (error) {
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).name).toBe("OperationCancelledError");
+      }
+
+      expect(executionOrder.length).toBe(0);
+    });
+
+    it("should respect abort signal in child iteration loop", async () => {
+      const controller = new AbortController();
+      const childrenExecuted: string[] = [];
+
+      context.signal = controller.signal;
+
+      const children = Array.from({ length: 5 }, (_, i) => {
+        const child = new MockAction({
+          id: `child${i}`,
+          returnStatus: NodeStatus.FAILURE,
+        });
+        child.tick = async (ctx: TemporalContext) => {
+          await checkSignal(ctx.signal);
+          childrenExecuted.push(`child${i}`);
+          return NodeStatus.FAILURE;
+        };
+        return child;
+      });
+
+      selector.addChildren(children);
+
+      // Abort after 2 children
+      let execCount = 0;
+      children.forEach((child) => {
+        const orig = child.tick;
+        child.tick = async (ctx: TemporalContext) => {
+          execCount++;
+          if (execCount === 2) {
+            controller.abort();
+          }
+          return await orig(ctx);
+        };
+      });
+
+      try {
+        await selector.tick(context);
+        expect.fail("Should have thrown an error");
+      } catch (error) {
+        expect(error).toBeInstanceOf(Error);
+        expect((error as Error).name).toBe("OperationCancelledError");
+      }
+
+      expect(childrenExecuted.length).toBeLessThanOrEqual(2);
+    });
+  });
+
+  describe("ConfigurationError handling", () => {
+    it(
+      "should NOT catch ConfigurationError from child - it propagates up",
+      async () => {
+        class MisconfiguredNode extends ActionNode {
+          executeTick(_context: TemporalContext) {
+            throw new ConfigurationError("Element not found in blackboard");
+          }
+        }
+
+        const misconfiguredChild = new MisconfiguredNode({ id: "broken" });
+        const validChild = new MockAction({
+          id: "valid",
+          returnStatus: NodeStatus.SUCCESS,
+        });
+
+        selector.addChildren([misconfiguredChild, validChild]);
+
+        // ConfigurationError should propagate as error
+        // Selector should NOT try the next child
+        try {
+          await selector.tick(context);
+          expect.fail("Should have thrown ConfigurationError");
+        } catch (error) {
+          expect(error).toBeInstanceOf(ConfigurationError);
+          expect((error as ConfigurationError).message).toContain(
+            "Element not found in blackboard",
+          );
+        }
+
+        // Verify second child was NOT executed
+        expect(validChild.status()).toBe(NodeStatus.IDLE);
+      },
+    );
+  });
+});
+
+describe("Fallback", () => {
+  it("should be an alias for Selector", () => {
+    const fallback = new Fallback({ id: "test-fallback" });
+    expect(fallback).toBeInstanceOf(Selector);
+    expect(fallback.type).toBe("Fallback");
+  });
+
+  it("should behave like Selector", async () => {
+    const context: TemporalContext = {
+      blackboard: new ScopedBlackboard(),
+      timestamp: Date.now(),
+      deltaTime: 0,
+    };
+
+    const fallback = new Fallback({ id: "test-fallback" });
+
+    const child1 = new MockAction({
+      id: "child1",
+      returnStatus: NodeStatus.FAILURE,
+    });
+    const child2 = new MockAction({
+      id: "child2",
+      returnStatus: NodeStatus.SUCCESS,
+    });
+
+    fallback.addChildren([child1, child2]);
+
+    const status = await fallback.tick(context);
+    expect(status).toBe(NodeStatus.SUCCESS);
+  });
+});

package/src/composites/selector.ts

@@ -0,0 +1,85 @@
+/**
+ * Selector (Fallback) composite node
+ * Executes children in order until one succeeds or all fail
+ */
+
+import { CompositeNode } from "../base-node.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  NodeStatus,
+} from "../types.js";
+import { checkSignal } from "../utils/signal-check.js";
+
+export class Selector extends CompositeNode {
+  private currentChildIndex: number = 0;
+
+  async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    this.log("Ticking with", this._children.length, "children");
+
+    if (this._children.length === 0) {
+      return NodeStatus.FAILURE;
+    }
+
+    // Continue from where we left off if RUNNING
+    while (this.currentChildIndex < this._children.length) {
+      // Check for cancellation before ticking each child
+      checkSignal(context.signal);
+
+      const child = this._children[this.currentChildIndex];
+      if (!child) {
+        throw new Error(
+          `Child at index ${this.currentChildIndex} is undefined`,
+        );
+      }
+
+      this.log(`Ticking child ${this.currentChildIndex}: ${child.name}`);
+      const childStatus = await child.tick(context);
+
+      switch (childStatus) {
+        case NodeStatus.SUCCESS:
+          this.log(`Child ${child.name} succeeded - selector succeeds`);
+          this._status = NodeStatus.SUCCESS;
+          this.currentChildIndex = 0;
+          return NodeStatus.SUCCESS;
+
+        case NodeStatus.FAILURE:
+          this.log(`Child ${child.name} failed`);
+          this.currentChildIndex++;
+          break;
+
+        case NodeStatus.RUNNING:
+          this.log(`Child ${child.name} is running`);
+          this._status = NodeStatus.RUNNING;
+          return NodeStatus.RUNNING;
+
+        default:
+          throw new Error(`Unexpected status from child: ${childStatus}`);
+      }
+    }
+
+    // All children failed
+    this.log("All children failed");
+    this._status = NodeStatus.FAILURE;
+    this.currentChildIndex = 0;
+    return NodeStatus.FAILURE;
+  }
+
+  protected onHalt(): void {
+    this.haltChildren(this.currentChildIndex);
+    this.currentChildIndex = 0;
+  }
+
+  protected onReset(): void {
+    this.currentChildIndex = 0;
+  }
+}
+
+/**
+ * Fallback is an alias for Selector (BehaviorTree.CPP compatibility)
+ */
+export class Fallback extends Selector {
+  constructor(config: NodeConfiguration) {
+    super({ ...config, type: "Fallback" });
+  }
+}

package/src/composites/sequence.schema.ts

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