@q1k-oss/btree-workflows 0.0.1 → 0.0.2

package/src/decorators/delay.test.ts

@@ -1,261 +0,0 @@
-import { beforeEach, describe, expect, it } from "vitest";
-import { ScopedBlackboard } from "../blackboard.js";
-import { MockAction } from "../test-nodes.js";
-import { type TemporalContext, NodeStatus } from "../types.js";
-import { Delay } from "./delay.js";
-
-describe("Delay", () => {
-  let context: TemporalContext;
-
-  beforeEach(() => {
-    context = {
-      blackboard: new ScopedBlackboard(),
-      timestamp: Date.now(),
-      deltaTime: 0,
-    };
-  });
-
-  it("should throw error if delayMs is negative", () => {
-    expect(() => new Delay({ id: "test", delayMs: -100 })).toThrow(
-      "test: Delay must be non-negative (got -100)",
-    );
-  });
-
-  it("should throw ConfigurationError if no child is set", async () => {
-    const delay = new Delay({ id: "test-delay", delayMs: 100 });
-    await expect(delay.tick(context)).rejects.toThrow("test-delay: Decorator must have a child");
-  });
-
-  it("should execute child immediately when delayMs is 0", async () => {
-    const delay = new Delay({ id: "test-delay", delayMs: 0 });
-    const child = new MockAction({
-      id: "child",
-      returnStatus: NodeStatus.SUCCESS,
-    });
-
-    delay.setChild(child);
-
-    const status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.SUCCESS);
-    expect(child.status()).toBe(NodeStatus.SUCCESS);
-  });
-
-  it("should delay child execution", async () => {
-    const delayMs = 50;
-    const delay = new Delay({ id: "test-delay", delayMs });
-    const child = new MockAction({
-      id: "child",
-      returnStatus: NodeStatus.SUCCESS,
-    });
-
-    delay.setChild(child);
-
-    const startTime = Date.now();
-
-    // First tick - should be delaying
-    let status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.RUNNING);
-    expect(child.status()).toBe(NodeStatus.IDLE); // Child not executed yet
-
-    // Tick while still delaying
-    status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.RUNNING);
-    expect(Date.now() - startTime).toBeLessThan(delayMs);
-
-    // Wait for delay to complete
-    await new Promise((resolve) => setTimeout(resolve, delayMs + 10));
-
-    // Next tick should execute child
-    status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.SUCCESS);
-    expect(child.status()).toBe(NodeStatus.SUCCESS);
-    expect(Date.now() - startTime).toBeGreaterThanOrEqual(delayMs);
-  });
-
-  it("should pass through child status after delay", async () => {
-    const delay = new Delay({ id: "test-delay", delayMs: 30 });
-    const child = new MockAction({
-      id: "child",
-      returnStatus: NodeStatus.FAILURE,
-    });
-
-    delay.setChild(child);
-
-    // Wait through delay
-    await delay.tick(context);
-    await new Promise((resolve) => setTimeout(resolve, 40));
-
-    const status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.FAILURE);
-    expect(delay.status()).toBe(NodeStatus.FAILURE);
-  });
-
-  it("should handle RUNNING child after delay", async () => {
-    const delay = new Delay({ id: "test-delay", delayMs: 30 });
-    let tickCount = 0;
-    const child = new MockAction({ id: "child" });
-    child.tick = async (_ctx) => {
-      tickCount++;
-      if (tickCount < 3) {
-        (child as any)._status = NodeStatus.RUNNING;
-        return NodeStatus.RUNNING;
-      }
-      (child as any)._status = NodeStatus.SUCCESS;
-      return NodeStatus.SUCCESS;
-    };
-
-    delay.setChild(child);
-
-    // Wait through delay
-    await delay.tick(context);
-    await new Promise((resolve) => setTimeout(resolve, 40));
-
-    // Child starts executing
-    let status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.RUNNING);
-    // Child has been ticked (verified by child status check)
-
-    // Child still running
-    status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.RUNNING);
-
-    // Child completes
-    status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.SUCCESS);
-  });
-
-  it("should reset delay state on halt", async () => {
-    const delay = new Delay({ id: "test-delay", delayMs: 100 });
-    const child = new MockAction({
-      id: "child",
-      returnStatus: NodeStatus.SUCCESS,
-    });
-
-    delay.setChild(child);
-
-    // Start delay
-    await delay.tick(context);
-    expect((delay as any).delayStartTime).not.toBeNull();
-
-    // Halt
-    delay.halt();
-
-    expect(delay.status()).toBe(NodeStatus.IDLE);
-    expect((delay as any).delayStartTime).toBeNull();
-  });
-
-  it("should reset delay state on reset", async () => {
-    const delay = new Delay({ id: "test-delay", delayMs: 30 });
-    const child = new MockAction({
-      id: "child",
-      returnStatus: NodeStatus.SUCCESS,
-    });
-
-    delay.setChild(child);
-
-    // Complete execution
-    await delay.tick(context);
-    await new Promise((resolve) => setTimeout(resolve, 40));
-    await delay.tick(context);
-
-    // Child has been ticked (verified by child status check)
-
-    // Reset
-    delay.reset();
-
-    expect(delay.status()).toBe(NodeStatus.IDLE);
-    expect((delay as any).delayStartTime).toBeNull();
-  });
-
-  it("should track remaining delay time correctly", async () => {
-    const delayMs = 100;
-    const delay = new Delay({ id: "test-delay", delayMs });
-    const child = new MockAction({
-      id: "child",
-      returnStatus: NodeStatus.SUCCESS,
-    });
-
-    delay.setChild(child);
-
-    // Start delay
-    await delay.tick(context);
-
-    // Check multiple times during delay
-    for (let i = 0; i < 3; i++) {
-      await new Promise((resolve) => setTimeout(resolve, 20));
-      const status = await delay.tick(context);
-      expect(status).toBe(NodeStatus.RUNNING);
-
-      // Verify delay is being tracked (can check logs)
-      const delayStartTime = (delay as any).delayStartTime;
-      if (!delayStartTime) {
-        throw new Error("delayStartTime not found");
-      }
-      const elapsed = Date.now() - delayStartTime;
-      expect(elapsed).toBeLessThan(delayMs);
-    }
-
-    // Wait for completion
-    await new Promise((resolve) => setTimeout(resolve, 50));
-    const finalStatus = await delay.tick(context);
-    expect(finalStatus).toBe(NodeStatus.SUCCESS);
-  });
-
-  it("should only start child execution once", async () => {
-    const delay = new Delay({ id: "test-delay", delayMs: 30 });
-    let tickCount = 0;
-
-    const child = new MockAction({ id: "child" });
-    const originalTick = child.tick.bind(child);
-    child.tick = (ctx) => {
-      tickCount++;
-      return originalTick(ctx);
-    };
-
-    delay.setChild(child);
-
-    // Wait through delay
-    await delay.tick(context);
-    await new Promise((resolve) => setTimeout(resolve, 40));
-
-    // First tick after delay
-    await delay.tick(context);
-    expect(tickCount).toBe(1);
-    // Child has been ticked (verified by child status check)
-
-    // Subsequent ticks start new delay cycles (return RUNNING without ticking child)
-    await delay.tick(context);
-    await delay.tick(context);
-    expect(tickCount).toBe(1); // Child only ticked once (subsequent ticks are delaying)
-  });
-
-  it("should handle multiple executions correctly", async () => {
-    const delay = new Delay({ id: "test-delay", delayMs: 30 });
-    const child = new MockAction({
-      id: "child",
-      returnStatus: NodeStatus.SUCCESS,
-    });
-
-    delay.setChild(child);
-
-    // First execution
-    await delay.tick(context);
-    await new Promise((resolve) => setTimeout(resolve, 40));
-    let status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.SUCCESS);
-
-    // Reset for second execution
-    delay.reset();
-    child.reset();
-
-    // Second execution should also delay
-    const startTime = Date.now();
-    status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.RUNNING);
-
-    await new Promise((resolve) => setTimeout(resolve, 40));
-    status = await delay.tick(context);
-    expect(status).toBe(NodeStatus.SUCCESS);
-    expect(Date.now() - startTime).toBeGreaterThanOrEqual(30);
-  });
-});

package/src/decorators/delay.ts

@@ -1,140 +0,0 @@
-/**
- * Delay decorator node
- * Waits for a specified duration before executing the child
- *
- * In Temporal workflows: Uses sleep() for deterministic delays
- * In standalone mode: Uses Date.now() polling for multi-tick behavior
- */
-
-import { sleep } from "@temporalio/workflow";
-import { DecoratorNode } 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 DelayConfiguration extends NodeConfiguration {
-  /**
-   * Delay duration in milliseconds
-   */
-  delayMs: number;
-}
-
-export class Delay extends DecoratorNode {
-  private delayMs: number;
-  private delayStartTime: number | null = null;
-  private useTemporalAPI: boolean | null = null;  // Cached detection result
-
-  constructor(config: DelayConfiguration) {
-    super(config);
-    this.delayMs = config.delayMs;
-
-    if (this.delayMs < 0) {
-      throw new ConfigurationError(
-        `${this.name}: Delay must be non-negative (got ${this.delayMs})`,
-      );
-    }
-  }
-
-  async executeTick(context: TemporalContext): Promise<NodeStatus> {
-    checkSignal(context.signal);
-
-    if (!this.child) {
-      throw new ConfigurationError(`${this.name}: Decorator must have a child`);
-    }
-
-    // If delay is 0, just execute the child immediately
-    if (this.delayMs === 0) {
-      return await this.child.tick(context);
-    }
-
-    // Try Temporal API on first execution only
-    if (this.useTemporalAPI === null) {
-      try {
-        this.log(`Starting delay of ${this.delayMs}ms`);
-        await sleep(this.delayMs);
-
-        // Success - we're in a Temporal workflow
-        this.useTemporalAPI = true;
-        this.log("Delay completed, executing child");
-
-        checkSignal(context.signal);
-        const childStatus = await this.child.tick(context);
-        this._status = childStatus;
-        return childStatus;
-
-      } catch (err) {
-        // Not in Temporal workflow - use standalone polling
-        this.useTemporalAPI = false;
-        // Fall through to polling implementation below
-      }
-    }
-
-    // Use Temporal API (we know we're in a workflow)
-    if (this.useTemporalAPI === true) {
-      this.log(`Starting delay of ${this.delayMs}ms`);
-      await sleep(this.delayMs);
-      this.log("Delay completed, executing child");
-
-      checkSignal(context.signal);
-      const childStatus = await this.child.tick(context);
-      this._status = childStatus;
-      return childStatus;
-    }
-
-    // Standalone polling implementation (multi-tick)
-    // If child is already running from a previous tick, execute it immediately
-    if (this.child.status() === NodeStatus.RUNNING) {
-      checkSignal(context.signal);
-      const childStatus = await this.child.tick(context);
-
-      if (childStatus !== NodeStatus.RUNNING) {
-        // Child completed - reset delay timer for next cycle
-        this.delayStartTime = null;
-      }
-
-      this._status = childStatus;
-      return childStatus;
-    }
-
-    // Start delay if not started
-    if (this.delayStartTime === null) {
-      this.delayStartTime = Date.now();
-      this.log(`Starting delay of ${this.delayMs}ms`);
-    }
-
-    const elapsed = Date.now() - this.delayStartTime;
-
-    if (elapsed < this.delayMs) {
-      // Still delaying
-      this._status = NodeStatus.RUNNING;
-      return NodeStatus.RUNNING;
-    }
-
-    // Delay completed - execute child
-    this.log("Delay completed, executing child");
-
-    checkSignal(context.signal);
-    const childStatus = await this.child.tick(context);
-
-    if (childStatus !== NodeStatus.RUNNING) {
-      // Child completed - reset delay timer for next cycle
-      this.delayStartTime = null;
-    }
-
-    this._status = childStatus;
-    return childStatus;
-  }
-
-  protected onHalt(): void {
-    this.delayStartTime = null;
-  }
-
-  protected onReset(): void {
-    this.delayStartTime = null;
-    this.useTemporalAPI = null;  // Re-detect on next execution
-  }
-}

package/src/decorators/force-result.schema.ts

@@ -1,32 +0,0 @@
-/**
- * ForceSuccess and ForceFailure decorator configuration schemas
- */
-
-import { z } from "zod";
-import { nodeConfigurationSchema } from "../schemas/base.schema.js";
-
-/**
- * Schema for ForceSuccess decorator configuration
- * Uses base schema only (no additional properties)
- */
-export const forceSuccessConfigurationSchema = nodeConfigurationSchema;
-
-/**
- * Schema for ForceFailure decorator configuration
- * Uses base schema only (no additional properties)
- */
-export const forceFailureConfigurationSchema = nodeConfigurationSchema;
-
-/**
- * Validated ForceSuccess configuration type
- */
-export type ValidatedForceSuccessConfiguration = z.infer<
-  typeof forceSuccessConfigurationSchema
->;
-
-/**
- * Validated ForceFailure configuration type
- */
-export type ValidatedForceFailureConfiguration = z.infer<
-  typeof forceFailureConfigurationSchema
->;

package/src/decorators/force-result.test.ts

@@ -1,133 +0,0 @@
-/**
- * Tests for ForceSuccess and ForceFailure decorators
- */
-
-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 { ForceFailure, ForceSuccess } from "./force-result.js";
-
-describe("ForceSuccess", () => {
-  let blackboard: ScopedBlackboard;
-  let context: TemporalContext;
-
-  beforeEach(() => {
-    blackboard = new ScopedBlackboard("root");
-    context = {
-      blackboard,
-      timestamp: Date.now(),
-      deltaTime: 0,
-    };
-  });
-
-  it("should return SUCCESS when child succeeds", async () => {
-    const force = new ForceSuccess({ id: "force1" });
-    force.setChild(new SuccessNode({ id: "child" }));
-
-    const result = await force.tick(context);
-    expect(result).toBe(NodeStatus.SUCCESS);
-  });
-
-  it("should return SUCCESS when child fails", async () => {
-    const force = new ForceSuccess({ id: "force1" });
-    force.setChild(new FailureNode({ id: "child" }));
-
-    const result = await force.tick(context);
-    expect(result).toBe(NodeStatus.SUCCESS);
-  });
-
-  it("should return RUNNING when child is running", async () => {
-    const force = new ForceSuccess({ id: "force1" });
-    force.setChild(new RunningNode({ id: "child" }));
-
-    const result = await force.tick(context);
-    expect(result).toBe(NodeStatus.RUNNING);
-    expect(force.status()).toBe(NodeStatus.RUNNING);
-  });
-
-  it("should still tick child for side effects", async () => {
-    const force = new ForceSuccess({ id: "force1" });
-
-    let childTicked = false;
-    class SideEffectNode extends FailureNode {
-      tick(context: TemporalContext) {
-        childTicked = true;
-        return super.tick(context);
-      }
-    }
-
-    force.setChild(new SideEffectNode({ id: "child" }));
-
-    await force.tick(context);
-    expect(childTicked).toBe(true);
-  });
-
-  it("should throw ConfigurationError if no child", async () => {
-    const force = new ForceSuccess({ id: "force1" });
-
-    await expect(force.tick(context)).rejects.toThrow("ForceSuccess requires a child");
-  });
-});
-
-describe("ForceFailure", () => {
-  let blackboard: ScopedBlackboard;
-  let context: TemporalContext;
-
-  beforeEach(() => {
-    blackboard = new ScopedBlackboard("root");
-    context = {
-      blackboard,
-      timestamp: Date.now(),
-      deltaTime: 0,
-    };
-  });
-
-  it("should return FAILURE when child succeeds", async () => {
-    const force = new ForceFailure({ id: "force1" });
-    force.setChild(new SuccessNode({ id: "child" }));
-
-    const result = await force.tick(context);
-    expect(result).toBe(NodeStatus.FAILURE);
-  });
-
-  it("should return FAILURE when child fails", async () => {
-    const force = new ForceFailure({ id: "force1" });
-    force.setChild(new FailureNode({ id: "child" }));
-
-    const result = await force.tick(context);
-    expect(result).toBe(NodeStatus.FAILURE);
-  });
-
-  it("should return RUNNING when child is running", async () => {
-    const force = new ForceFailure({ id: "force1" });
-    force.setChild(new RunningNode({ id: "child" }));
-
-    const result = await force.tick(context);
-    expect(result).toBe(NodeStatus.RUNNING);
-    expect(force.status()).toBe(NodeStatus.RUNNING);
-  });
-
-  it("should still tick child for side effects", async () => {
-    const force = new ForceFailure({ id: "force1" });
-
-    let childTicked = false;
-    class SideEffectNode extends SuccessNode {
-      tick(context: TemporalContext) {
-        childTicked = true;
-        return super.tick(context);
-      }
-    }
-
-    force.setChild(new SideEffectNode({ id: "child" }));
-
-    await force.tick(context);
-    expect(childTicked).toBe(true);
-  });
-
-  it("should throw ConfigurationError if no child", async () => {
-    const force = new ForceFailure({ id: "force1" });
-
-    await expect(force.tick(context)).rejects.toThrow("ForceFailure requires a child");
-  });
-});

package/src/decorators/force-result.ts

@@ -1,63 +0,0 @@
-/**
- * ForceSuccess and ForceFailure decorators
- * Always return specific result regardless of child
- */
-
-import { DecoratorNode } from "../base-node.js";
-import { ConfigurationError } from "../errors.js";
-import { type TemporalContext, NodeStatus } from "../types.js";
-import { checkSignal } from "../utils/signal-check.js";
-
-/**
- * ForceSuccess always returns SUCCESS regardless of child result.
- * Useful for ensuring a branch always succeeds.
- */
-export class ForceSuccess extends DecoratorNode {
-  async executeTick(context: TemporalContext): Promise<NodeStatus> {
-    checkSignal(context.signal);
-
-    if (!this.child) {
-      throw new ConfigurationError("ForceSuccess requires a child");
-    }
-
-    // Tick child and check status
-    const childStatus = await this.child.tick(context);
-
-    // Propagate RUNNING status - only force result when child completes
-    if (childStatus === NodeStatus.RUNNING) {
-      this._status = NodeStatus.RUNNING;
-      return NodeStatus.RUNNING;
-    }
-
-    // Force SUCCESS regardless of child result (SUCCESS or FAILURE)
-    this._status = NodeStatus.SUCCESS;
-    return NodeStatus.SUCCESS;
-  }
-}
-
-/**
- * ForceFailure always returns FAILURE regardless of child result.
- * Useful for negation or testing.
- */
-export class ForceFailure extends DecoratorNode {
-  async executeTick(context: TemporalContext): Promise<NodeStatus> {
-    checkSignal(context.signal);
-
-    if (!this.child) {
-      throw new ConfigurationError("ForceFailure requires a child");
-    }
-
-    // Tick child and check status
-    const childStatus = await this.child.tick(context);
-
-    // Propagate RUNNING status - only force result when child completes
-    if (childStatus === NodeStatus.RUNNING) {
-      this._status = NodeStatus.RUNNING;
-      return NodeStatus.RUNNING;
-    }
-
-    // Force FAILURE regardless of child result (SUCCESS or FAILURE)
-    this._status = NodeStatus.FAILURE;
-    return NodeStatus.FAILURE;
-  }
-}

package/src/decorators/index.ts

@@ -1,13 +0,0 @@
-/**
- * Export all decorator nodes
- */
-
-export { Delay } from "./delay.js";
-export { ForceFailure, ForceSuccess } from "./force-result.js";
-export { Invert } from "./invert.js";
-export { KeepRunningUntilFailure } from "./keep-running.js";
-export { Precondition } from "./precondition.js";
-export { Repeat } from "./repeat.js";
-export { RunOnce } from "./run-once.js";
-export { SoftAssert } from "./soft-assert.js";
-export { Timeout } from "./timeout.js";

package/src/decorators/invert.schema.ts

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