@ai.ntellect/core 0.6.20 → 0.7.0

package/test/graph/index.test.ts

@@ -2,41 +2,63 @@ import { expect } from "chai";
 import EventEmitter from "events";
 import sinon from "sinon";
 import { z } from "zod";
+import { GraphFlowController } from "../../graph/controller";
 import { GraphFlow } from "../../graph/index";
-import { GraphDefinition, Node } from "../../types";
+import { GraphContext, GraphDefinition, Node } from "../../types";
+
 /**
- * ✅ Define a valid schema using Zod.
+ * Test schema definition using Zod for graph context validation
+ * Defines a schema with:
+ * - value: numeric value for tracking state changes
+ * - eventPayload: optional object containing transaction metadata
  */
 const TestSchema = z.object({
   value: z.number().default(0),
+  eventPayload: z
+    .object({
+      transactionId: z.string().optional(),
+      status: z.string().optional(),
+    })
+    .optional(),
 });
 
-/**
- * ✅ Define the schema type for TypeScript inference.
- */
 type TestSchema = typeof TestSchema;
 
+/**
+ * Test suite for the Graph Flow implementation
+ * This suite validates the core functionality of the graph-based workflow system:
+ * - Node execution and state management through context
+ * - Event handling (emission, correlation, waiting)
+ * - Error handling and retry mechanisms
+ * - Input/Output validation using Zod schemas
+ * - Complex workflows with multiple branches and conditions
+ * - Parallel and sequential execution patterns
+ *
+ * The tests use a simple numeric value-based context to demonstrate state changes
+ * and a transaction-based event payload for testing event correlation.
+ */
 describe("Graph", function () {
   let graph: GraphFlow<TestSchema>;
   let eventEmitter: EventEmitter;
 
   beforeEach(() => {
     eventEmitter = new EventEmitter();
-    graph = new GraphFlow(
-      "TestGraph",
-      {
-        name: "TestGraph",
-        nodes: [],
-        context: { value: 0 },
-        schema: TestSchema,
-        eventEmitter: eventEmitter,
-      },
-      { verbose: true }
-    );
+    graph = new GraphFlow("TestGraph", {
+      name: "TestGraph",
+      nodes: [],
+      context: { value: 0 },
+      schema: TestSchema,
+      eventEmitter: eventEmitter,
+    });
   });
 
   /**
-   * ✅ Ensure a simple node executes and updates the context correctly.
+   * Tests basic node execution and context update functionality
+   * Validates that:
+   * - A node can be added to the graph
+   * - The node's execute function is called
+   * - The context is properly updated
+   * - The updated context is accessible after execution
    */
   it("should execute a simple node and update the context", async function () {
     const simpleNode: Node<TestSchema> = {
@@ -55,7 +77,11 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Verify that `nodeStarted` and `nodeCompleted` events are triggered.
+   * Tests event emission for node lifecycle events
+   * Validates that the graph properly emits events for:
+   * - Node execution start (nodeStarted)
+   * - Node execution completion (nodeCompleted)
+   * This is crucial for monitoring and debugging workflow execution
    */
   it("should trigger `nodeStarted` and `nodeCompleted` events", async function () {
     const nodeStartedSpy = sinon.spy();
@@ -80,7 +106,12 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Ensure an error is thrown when a node fails and `nodeError` event is triggered.
+   * Tests error handling and error event emission
+   * Validates that:
+   * - Errors in node execution are properly caught
+   * - The nodeError event is emitted
+   * - The error message is preserved
+   * This ensures robust error handling in the workflow
    */
   it("should handle errors and trigger `nodeError` event", async function () {
     const errorNode: Node<TestSchema> = {
@@ -105,7 +136,12 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Ensure that context validation using Zod works correctly.
+   * Tests context validation using Zod schema
+   * Validates that:
+   * - Invalid context values are rejected
+   * - Proper error messages are generated
+   * - Type safety is maintained during execution
+   * This ensures data integrity throughout the workflow
    */
   it("should validate context with Zod", async function () {
     const invalidContext = { value: "invalid_string" };
@@ -129,7 +165,12 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Ensure a node with validated inputs and outputs executes correctly.
+   * Tests node execution with input/output validation
+   * Demonstrates:
+   * - Input parameter validation
+   * - Output state validation
+   * - Integration between node execution and validation
+   * Ensures type safety and data consistency in node interactions
    */
   it("should execute a node with validated inputs and outputs", async function () {
     const paramNode: Node<TestSchema, { increment: number }> = {
@@ -154,7 +195,12 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Ensure a node does not execute if a condition is not met.
+   * Tests conditional node execution
+   * Validates that:
+   * - Nodes can have conditional execution logic
+   * - Conditions are evaluated against current context
+   * - Nodes are skipped when conditions are not met
+   * This enables dynamic workflow paths based on state
    */
   it("should not execute a node when condition is false", async function () {
     const conditionalNode: Node<TestSchema> = {
@@ -174,7 +220,13 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Ensure that a node retries execution when it fails.
+   * Tests node retry functionality
+   * Validates the retry mechanism:
+   * - Maximum attempt limits
+   * - Retry delays
+   * - Success after retry
+   * - Context preservation between attempts
+   * Essential for handling transient failures in workflows
    */
   it("should retry a node execution when it fails", async function () {
     let attemptCount = 0;
@@ -200,45 +252,7 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Ensure dynamic event-based execution works via `emit`.
-   */
-  it("should trigger a node execution from an event", async function () {
-    this.timeout(5000); // Ensure we have enough time to complete the test
-
-    const eventNode: Node<TestSchema> = {
-      name: "eventNode",
-      events: ["customEvent"],
-      execute: async (context) => {
-        context.value = (context.value ?? 0) + 1;
-      },
-      next: [],
-    };
-
-    graph.addNode(eventNode);
-
-    // Use a promise to ensure the event is properly handled
-    await new Promise<void>((resolve, reject) => {
-      const timeout = setTimeout(
-        () => reject(new Error("Event did not trigger")),
-        1500
-      );
-
-      graph.on("nodeCompleted", ({ name }) => {
-        if (name === "eventNode") {
-          clearTimeout(timeout);
-          resolve();
-        }
-      });
-
-      graph.emit("customEvent").catch(reject);
-    });
-
-    const context = graph.getContext();
-    expect(context.value).to.equal(1);
-  });
-
-  /**
-   * ✅ Ensure that removing a node works correctly.
+   * Tests node removal functionality
    */
   it("should remove a node from the graph", function () {
     const testNode: Node<TestSchema> = {
@@ -251,6 +265,9 @@ describe("Graph", function () {
     expect(graph.getNodes().length).to.equal(0);
   });
 
+  /**
+   * Tests graph reloading functionality
+   */
   it("should clear and reload the graph using `load`", function () {
     const nodeA: Node<TestSchema> = {
       name: "A",
@@ -275,7 +292,7 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Test input validation failure
+   * Tests input validation error handling
    */
   it("should throw error when node input validation fails", async function () {
     const nodeWithInput: Node<TestSchema, { amount: number }> = {
@@ -302,7 +319,7 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Test output validation failure
+   * Tests output validation error handling
    */
   it("should throw error when node output validation fails", async function () {
     const nodeWithOutput: Node<TestSchema> = {
@@ -329,7 +346,7 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Test successful input and output validation
+   * Tests successful input/output validation flow
    */
   it("should successfully validate both inputs and outputs", async function () {
     const validatedNode: Node<TestSchema, { increment: number }> = {
@@ -364,7 +381,7 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Test missing required inputs
+   * Tests handling of missing required inputs
    */
   it("should throw error when required inputs are missing", async function () {
     const nodeWithRequiredInput: Node<TestSchema, { required: string }> = {
@@ -387,9 +404,15 @@ describe("Graph", function () {
   });
 
   /**
-   * ✅ Test complex workflow with multiple branches
+   * Tests complex workflow execution with multiple branches
+   * Demonstrates:
+   * - Multiple execution paths
+   * - Node chaining
+   * - Parallel branch execution
+   * - Context accumulation across branches
+   * This validates the graph's ability to handle complex business processes
    */
-  it("should execute a complex workflow with multiple branches", async function () {
+  it("should execute a complex workflow with multiple nodes and accumulate the value", async function () {
     const nodeA: Node<TestSchema> = {
       name: "nodeA",
       execute: async (context) => {
@@ -417,20 +440,18 @@ describe("Graph", function () {
     const nodeC: Node<TestSchema> = {
       name: "nodeC",
       execute: async (context) => {
-        // Créer une copie du contexte pour éviter les modifications concurrentes
-        const newValue = (context.value ?? 0) + 5;
-        context.value = newValue;
+        context.value = (context.value ?? 0) + 5;
       },
     };
 
     [nodeA, nodeB1, nodeB2, nodeC].forEach((node) => graph.addNode(node));
 
     await graph.execute("nodeA");
-    expect(graph.getContext().value).to.equal(9);
+    expect(graph.getContext().value).to.equal(15);
   });
 
   /**
-   * ✅ Test conditional workflow branching
+   * Tests conditional branching in workflows
    */
   it("should execute different branches based on conditions", async function () {
     const startNode: Node<TestSchema> = {
@@ -438,141 +459,262 @@ describe("Graph", function () {
       execute: async (context) => {
         context.value = (context.value ?? 0) + 5;
       },
-      next: ["branchA", "branchB"],
+      next: ["end"],
     };
 
-    const branchA: Node<TestSchema> = {
-      name: "branchA",
-      condition: (context) => (context.value ?? 0) < 10,
+    const endNode: Node<TestSchema> = {
+      name: "end",
       execute: async (context) => {
-        context.value = (context.value ?? 0) * 2;
+        if ((context.value ?? 0) < 10) {
+          context.value = (context.value ?? 0) * 2;
+        } else {
+          context.value = (context.value ?? 0) + 1;
+        }
       },
-      next: ["end"],
     };
 
-    const branchB: Node<TestSchema> = {
-      name: "branchB",
-      condition: (context) => (context.value ?? 0) >= 10,
+    [startNode, endNode].forEach((node) => graph.addNode(node));
+
+    await graph.execute("start");
+    expect(graph.getContext().value).to.equal(10);
+  });
+
+  /**
+   * Tests parallel workflow execution using GraphController
+   * Validates:
+   * - Multiple graph execution in parallel
+   * - Independent context maintenance
+   * - Proper result aggregation
+   * - Concurrency control
+   * Essential for scaling workflow processing
+   */
+  it("should handle parallel workflows using GraphController", async function () {
+    // Graph 1
+    const graph1 = new GraphFlow("Graph1", {
+      name: "Graph1",
+      nodes: [],
+      context: { value: 0 },
+      schema: TestSchema,
+    });
+
+    const processNode1: Node<TestSchema> = {
+      name: "process1",
       execute: async (context) => {
-        context.value = (context.value ?? 0) + 10;
+        context.value = 1;
       },
-      next: ["end"],
+      next: ["finalize1"],
     };
 
-    const endNode: Node<TestSchema> = {
-      name: "end",
+    const finalizeNode1: Node<TestSchema> = {
+      name: "finalize1",
       execute: async (context) => {
-        context.value = (context.value ?? 0) + 1;
+        context.value = (context.value ?? 0) * 2;
       },
     };
 
-    [startNode, branchA, branchB, endNode].forEach((node) =>
-      graph.addNode(node)
-    );
-
-    await graph.load({
-      name: "TestGraph",
-      nodes: [startNode, branchA, branchB, endNode],
+    // Graph 2
+    const graph2 = new GraphFlow("Graph2", {
+      name: "Graph2",
+      nodes: [],
       context: { value: 0 },
       schema: TestSchema,
     });
 
-    await graph.execute("start");
-    expect(graph.getContext().value).to.equal(11);
+    const processNode2: Node<TestSchema> = {
+      name: "process2",
+      execute: async (context) => {
+        context.value = 2;
+      },
+      next: ["finalize2"],
+    };
+
+    const finalizeNode2: Node<TestSchema> = {
+      name: "finalize2",
+      execute: async (context) => {
+        context.value = (context.value ?? 0) + 3;
+      },
+    };
+
+    graph1.addNode(processNode1);
+    graph1.addNode(finalizeNode1);
+    graph2.addNode(processNode2);
+    graph2.addNode(finalizeNode2);
+
+    const results = await GraphFlowController.executeParallel(
+      [graph1, graph2],
+      ["process1", "process2"],
+      2,
+      [{}, {}]
+    );
+
+    expect(results[0].value).to.equal(2); // Graph1: 1 * 2
+    expect(results[1].value).to.equal(5); // Graph2: 2 + 3
   });
 
   /**
-   * ✅ Test complex event-driven workflow
+   * Tests sequential workflow execution using GraphController
    */
-  it("should handle complex event-driven workflows", async function () {
-    this.timeout(5000); // Augmenter le timeout pour les tests asynchrones
-    const eventCounter = { count: 0 };
+  it("should handle sequential workflows using GraphController", async function () {
+    // Graph 1
+    const graph1 = new GraphFlow("Graph1", {
+      name: "Graph1",
+      nodes: [],
+      context: { value: 1 },
+      schema: TestSchema,
+    });
 
-    const startNode: Node<TestSchema> = {
-      name: "start",
-      events: ["startWorkflow"],
+    const startNode1: Node<TestSchema> = {
+      name: "start1",
       execute: async (context) => {
-        context.value = 1;
+        context.value = (context.value ?? 0) * 2;
       },
-      next: ["process"],
     };
 
-    const processNode: Node<TestSchema> = {
-      name: "process",
-      events: ["processData"],
+    // Graph 2
+    const graph2 = new GraphFlow("Graph2", {
+      name: "Graph2",
+      nodes: [],
+      context: { value: 3 },
+      schema: TestSchema,
+    });
+
+    const startNode2: Node<TestSchema> = {
+      name: "start2",
       execute: async (context) => {
-        context.value = (context.value ?? 0) * 2;
+        context.value = (context.value ?? 0) + 2;
       },
-      next: ["finalize"],
     };
 
-    const finalizeNode: Node<TestSchema> = {
-      name: "finalize",
-      events: ["complete"],
-      execute: async (context) => {
-        context.value = (context.value ?? 0) + 3;
-        eventCounter.count++;
+    graph1.addNode(startNode1);
+    graph2.addNode(startNode2);
+
+    const results = await GraphFlowController.executeSequential(
+      [graph1, graph2],
+      ["start1", "start2"],
+      [{}, {}]
+    );
+
+    expect(results[0].value).to.equal(2); // Graph1: 1 * 2
+    expect(results[1].value).to.equal(5); // Graph2: 3 + 2
+  });
+
+  /**
+   * Tests event correlation functionality
+   * Demonstrates:
+   * - Event correlation based on transaction ID
+   * - Timeout handling
+   * - Multiple event synchronization
+   * - Context updates after correlation
+   * Critical for integrating with external event sources
+   */
+  it("should handle correlated events correctly", async function () {
+    this.timeout(10000);
+    const graph = new GraphFlow("test", {
+      name: "test",
+      nodes: [],
+      context: { value: 0 },
+      schema: TestSchema,
+      eventEmitter: new EventEmitter(),
+    });
+
+    let eventsReceived = 0;
+    const node = {
+      name: "testNode",
+      waitForEvents: {
+        events: ["eventA", "eventB"],
+        timeout: 5000,
+        strategy: "all" as const,
+      },
+      execute: async (context: GraphContext<typeof TestSchema>) => {
+        eventsReceived = 2;
+        context.value = 42;
       },
     };
 
-    [startNode, processNode, finalizeNode].forEach((node) =>
-      graph.addNode(node)
-    );
+    graph.addNode(node);
 
-    // Test sequential event triggering
-    await graph.emit("startWorkflow");
-    await graph.emit("processData");
-    await graph.emit("complete");
+    graph.execute("testNode");
 
-    expect(graph.getContext().value).to.equal(5); // (1 * 2) + 3
-    expect(eventCounter.count).to.equal(1);
+    await new Promise((resolve) => setTimeout(resolve, 500));
 
-    // Reset context for concurrent test
-    graph.load({
-      name: "TestGraph",
-      nodes: [startNode, processNode, finalizeNode],
+    await graph.emit("eventA", { eventPayload: { status: "A" } });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    await graph.emit("eventB", { eventPayload: { status: "B" } });
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    expect(eventsReceived).to.equal(2);
+    expect(graph.getContext().value).to.equal(42);
+  });
+
+  /**
+   * Tests multiple event waiting functionality
+   */
+  it("should wait for multiple events before continuing", async function () {
+    this.timeout(10000);
+    const graph = new GraphFlow("test", {
+      name: "test",
+      nodes: [],
       context: { value: 0 },
       schema: TestSchema,
+      eventEmitter: new EventEmitter(),
     });
 
-    // Test concurrent event handling
-    await Promise.all([
-      graph.emit("startWorkflow"),
-      graph.emit("processData"),
-      graph.emit("complete"),
-    ]);
+    const node = {
+      name: "testNode",
+      waitForEvents: {
+        events: ["event1", "event2"],
+        timeout: 5000,
+        strategy: "all" as const,
+      },
+      execute: async (context: GraphContext<typeof TestSchema>) => {
+        context.value = 42; // Ajouter une modification du contexte
+      },
+    };
+
+    graph.addNode(node);
+    graph.execute("testNode");
 
-    expect(eventCounter.count).to.equal(2);
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    await graph.emit("event1", { eventPayload: { status: "1" } });
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    await graph.emit("event2", { eventPayload: { status: "2" } });
+    expect(graph.getContext().value).to.equal(42);
   });
 
   /**
-   * ✅ Test cyclic workflow with conditional exit
+   * Tests single event waiting functionality
    */
-  it("should handle cyclic workflows with conditional exit", async function () {
-    const iterationCount = { count: 0 };
+  it("should wait for a single event before continuing", async function () {
+    this.timeout(5000);
 
-    const cycleNode: Node<TestSchema> = {
-      name: "cycle",
-      execute: async (context) => {
-        context.value = (context.value ?? 0) + 1;
-        iterationCount.count++;
+    const waitingNode: Node<TestSchema> = {
+      name: "waitingNode",
+      execute: async (context: GraphContext<typeof TestSchema>) => {
+        context.value = 1;
       },
-      next: ["checkExit"],
+      waitForEvent: true,
+      next: ["finalNode"],
     };
 
-    const checkExitNode: Node<TestSchema> = {
-      name: "checkExit",
-      execute: async () => {},
-      next: (context) => {
-        return (context.value ?? 0) < 5 ? ["cycle"] : [];
+    const finalNode: Node<TestSchema> = {
+      name: "finalNode",
+      execute: async (context: GraphContext<typeof TestSchema>) => {
+        context.value = (context.value ?? 0) + 5;
       },
     };
 
-    [cycleNode, checkExitNode].forEach((node) => graph.addNode(node));
+    [waitingNode, finalNode].forEach((node) => graph.addNode(node));
+
+    const resultPromise = graph.execute("waitingNode");
+
+    // Wait a bit to ensure the node is ready
+    await new Promise((resolve) => setTimeout(resolve, 500));
 
-    await graph.execute("cycle");
+    // Emit the event
+    await graph.emit("someEvent");
 
-    expect(graph.getContext().value).to.equal(5);
-    expect(iterationCount.count).to.equal(5);
+    const result = await resultPromise;
+    expect(result.value).to.equal(6); // 1 (waitingNode) + 5 (finalNode)
   });
 });