@agentica/core 0.18.0 → 0.19.1

package/src/utils/AsyncQueue.spec.ts

@@ -0,0 +1,355 @@
+import { AsyncQueue } from "./AsyncQueue";
+
+describe("the AsyncQueue", () => {
+  describe("basic functionality", () => {
+    it("enqueue and dequeue test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Enqueue items
+      queue.enqueue(1);
+      queue.enqueue(2);
+      queue.enqueue(3);
+
+      // Dequeue items
+      const result1 = await queue.dequeue();
+      const result2 = await queue.dequeue();
+      const result3 = await queue.dequeue();
+
+      expect(result1.value).toBe(1);
+      expect(result1.done).toBe(false);
+      expect(result2.value).toBe(2);
+      expect(result2.done).toBe(false);
+      expect(result3.value).toBe(3);
+      expect(result3.done).toBe(false);
+    });
+
+    it("isEmpty test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      expect(queue.isEmpty()).toBe(true);
+
+      queue.enqueue(1);
+      expect(queue.isEmpty()).toBe(false);
+
+      await queue.dequeue();
+      expect(queue.isEmpty()).toBe(true);
+    });
+
+    it("isClosed test", () => {
+      const queue = new AsyncQueue<number>();
+
+      expect(queue.isClosed()).toBe(false);
+
+      queue.close();
+      expect(queue.isClosed()).toBe(true);
+    });
+
+    it("done test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      expect(queue.done()).toBe(false);
+
+      queue.enqueue(1);
+      expect(queue.done()).toBe(false);
+
+      await queue.dequeue();
+      expect(queue.done()).toBe(false);
+
+      queue.close();
+      expect(queue.done()).toBe(true);
+    });
+  });
+
+  describe("close functionality", () => {
+    it("close test with empty queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.close();
+
+      const result = await queue.dequeue();
+      expect(result.done).toBe(true);
+      expect(result.value).toBeUndefined();
+    });
+
+    it("close test with non-empty queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.enqueue(1);
+      queue.enqueue(2);
+      queue.close();
+
+      const result1 = await queue.dequeue();
+      const result2 = await queue.dequeue();
+      const result3 = await queue.dequeue();
+
+      expect(result1.value).toBe(1);
+      expect(result1.done).toBe(false);
+      expect(result2.value).toBe(2);
+      expect(result2.done).toBe(false);
+      expect(result3.done).toBe(true);
+      expect(result3.value).toBeUndefined();
+    });
+
+    it("close test with waiting dequeue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Start dequeue before enqueue
+      const dequeuePromise = queue.dequeue();
+
+      // Close the queue
+      queue.close();
+
+      const result = await dequeuePromise;
+      expect(result.done).toBe(true);
+      expect(result.value).toBeUndefined();
+    });
+  });
+
+  describe("waitUntilEmpty functionality", () => {
+    it("waitUntilEmpty test with empty queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Should resolve immediately since queue is empty
+      await queue.waitUntilEmpty();
+
+      queue.enqueue(1);
+      const result = await queue.dequeue();
+      expect(result.value).toBe(1);
+      expect(result.done).toBe(false);
+    });
+
+    it("waitUntilEmpty test with non-empty queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.enqueue(1);
+      queue.enqueue(2);
+
+      // waitUntilEmpty should not resolve since queue is not empty
+      const waitPromise = queue.waitUntilEmpty();
+
+      // Dequeue first value
+      const result1 = await queue.dequeue();
+      expect(result1.value).toBe(1);
+
+      // Dequeue second value
+      const result2 = await queue.dequeue();
+      expect(result2.value).toBe(2);
+
+      // Now queue is empty, waitUntilEmpty should resolve\
+      await waitPromise;
+    });
+  });
+
+  describe("waitClosed functionality", () => {
+    it("waitClosed test with unclosed queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // waitClosed should not resolve since queue is not closed
+      const waitPromise = queue.waitClosed();
+
+      queue.enqueue(1);
+      const result = await queue.dequeue();
+      expect(result.value).toBe(1);
+
+      // Close the queue
+      queue.close();
+
+      // Now queue is closed, waitClosed should resolve
+      await waitPromise;
+    });
+
+    it("waitClosed test with already closed queue", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.close();
+
+      // waitClosed should resolve immediately since queue is already closed
+      await queue.waitClosed();
+    });
+
+    it("multiple waitClosed calls test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Create multiple waitClosed promises
+      const waitPromises = [queue.waitClosed(), queue.waitClosed(), queue.waitClosed()];
+
+      // Close the queue
+      queue.close();
+
+      // All promises should resolve
+      await Promise.all(waitPromises);
+    });
+
+    it("waitClosed test with delayed close", async () => {
+      const queue = new AsyncQueue<string>();
+
+      // Start waiting for close
+      const closePromise = queue.waitClosed();
+
+      // Close after delay
+      setTimeout(() => {
+        queue.close();
+      }, 10);
+
+      await closePromise; // Should resolve when queue is closed
+    });
+  });
+
+  describe("dequeue behavior", () => {
+    it("dequeue before enqueue test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Start dequeue before enqueue
+      const dequeuePromise = queue.dequeue();
+
+      // Enqueue after a small delay
+      setTimeout(() => {
+        queue.enqueue(42);
+      }, 10);
+
+      const result = await dequeuePromise;
+      expect(result.value).toBe(42);
+      expect(result.done).toBe(false);
+    });
+
+    it("multiple dequeue calls test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      // Start multiple dequeue calls
+      const dequeuePromises = [
+        queue.dequeue(),
+        queue.dequeue(),
+        queue.dequeue(),
+      ];
+
+      // Enqueue values
+      queue.enqueue(1);
+      queue.enqueue(2);
+      queue.enqueue(3);
+
+      const results = await Promise.all(dequeuePromises);
+
+      expect(results[0]?.value).toBe(1);
+      expect(results[0]?.done).toBe(false);
+      expect(results[1]?.value).toBe(2);
+      expect(results[1]?.done).toBe(false);
+      expect(results[2]?.value).toBe(3);
+      expect(results[2]?.done).toBe(false);
+    });
+
+    it("dequeue after close test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.enqueue(1);
+      queue.close();
+
+      const result1 = await queue.dequeue();
+      expect(result1.value).toBe(1);
+      expect(result1.done).toBe(false);
+
+      const result2 = await queue.dequeue();
+      expect(result2.done).toBe(true);
+      expect(result2.value).toBeUndefined();
+    });
+
+    it("duplicate dequeue test", async () => {
+      const queue = new AsyncQueue<string>();
+
+      // Start dequeue operation that will wait for an item
+      const pendingDequeue = queue.dequeue();
+
+      // Add item after a small delay
+      setTimeout(() => {
+        queue.enqueue("delayed item");
+      }, 10);
+
+      const delayedResult = await pendingDequeue;
+      expect(delayedResult.value).toBe("delayed item");
+      expect(delayedResult.done).toBe(false);
+
+      // Check for duplicate dequeue
+      const duplicatedResult = await Promise.race([
+        queue.dequeue(),
+        new Promise(resolve => setTimeout(resolve, 0, false)),
+      ]) as false | IteratorResult<string, undefined>;
+
+      // If duplicatedResult is false, it means the race timed out (expected)
+      // If it's an IteratorResult, it should not have the same value
+      if (duplicatedResult !== false) {
+        expect(duplicatedResult.value).not.toBe("delayed item");
+      }
+    });
+  });
+
+  describe("edge cases and error handling", () => {
+    it("enqueue after close test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.close();
+      queue.enqueue(1); // Should still work, but dequeue will return done: true
+
+      const result = await queue.dequeue();
+      expect(result.done).toBe(true);
+      expect(result.value).toBeUndefined();
+    });
+
+    it("multiple close calls test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.close();
+      queue.close(); // Second close should not cause issues
+
+      const result = await queue.dequeue();
+      expect(result.done).toBe(true);
+      expect(result.value).toBeUndefined();
+    });
+
+    it("waitUntilEmpty with multiple calls test", async () => {
+      const queue = new AsyncQueue<number>();
+
+      queue.enqueue(1);
+
+      // Create multiple waitUntilEmpty promises
+      const waitPromises = [queue.waitUntilEmpty(), queue.waitUntilEmpty()];
+
+      // Dequeue the value
+      await queue.dequeue();
+
+      // All promises should resolve
+      await Promise.all(waitPromises);
+    });
+
+    it("concurrent enqueue and dequeue test", async () => {
+      const queue = new AsyncQueue<number>();
+      const results: number[] = [];
+
+      // Start multiple dequeue operations
+      const dequeuePromises = Array.from({ length: 5 }).fill(0).map(async () => queue.dequeue());
+
+      // Enqueue values with small delays
+      for (let i = 0; i < 5; i++) {
+        setTimeout(() => {
+          queue.enqueue(i);
+        }, i * 10);
+      }
+
+      // Wait for all dequeue operations to complete
+      const dequeuedResults = await Promise.all(dequeuePromises);
+
+      // Collect values
+      dequeuedResults.forEach((result) => {
+        if (result.value !== undefined) {
+          results.push(result.value);
+        }
+      });
+
+      // Check that all values were dequeued
+      expect(results.length).toBe(5);
+      expect(results).toContain(0);
+      expect(results).toContain(1);
+      expect(results).toContain(2);
+      expect(results).toContain(3);
+      expect(results).toContain(4);
+    });
+  });
+});

package/src/utils/AsyncQueue.ts

@@ -1,3 +1,10 @@
+export class AsyncQueueClosedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AsyncQueueClosedError";
+  }
+}
+
 export class AsyncQueue<T> {
   private queue: T[] = [];
   private resolvers: ((value: IteratorResult<T, undefined>) => void)[] = [];
@@ -6,6 +13,11 @@ export class AsyncQueue<T> {
   private closed = false;
 
   enqueue(item: T) {
+    if (this.closed) {
+      console.error(new AsyncQueueClosedError("Cannot enqueue item: queue is closed."));
+      return;
+    }
+
     this.queue.push(item);
     if (this.resolvers.length > 0) {
       this.resolvers.shift()?.({ value: this.queue.shift()!, done: false });
@@ -13,16 +25,25 @@ export class AsyncQueue<T> {
   }
 
   async dequeue(): Promise<IteratorResult<T, undefined>> {
-    if (this.queue.length > 0) {
-      return { value: this.queue.shift()!, done: false };
-    }
-    if (this.closed) {
-      if (this.emptyResolvers.length > 0) {
-        this.emptyResolvers.forEach(resolve => resolve());
-        this.emptyResolvers = [];
+    const item = (() => {
+      if (!this.isEmpty()) {
+        return { value: this.queue.shift()!, done: false } as const;
+      }
+      if (this.isClosed()) {
+        return { value: undefined, done: true } as const;
       }
-      return { value: undefined, done: true };
+      return null;
+    })();
+
+    if (this.isEmpty() && this.emptyResolvers.length !== 0) {
+      this.emptyResolvers.forEach(resolve => resolve());
+      this.emptyResolvers = [];
     }
+
+    if (item !== null) {
+      return item;
+    }
+
     return new Promise(resolve => this.resolvers.push(resolve));
   }
 
@@ -46,6 +67,13 @@ export class AsyncQueue<T> {
     this.closeResolvers.forEach(resolve => resolve());
   }
 
+  /**
+   * Wait until the queue is empty
+   *
+   * if the queue is closed, it will not resolve promise
+   * this function only check the queue is empty
+   * @returns A promise that resolves when the queue is empty
+   */
   async waitUntilEmpty() {
     if (this.isEmpty()) {
       return Promise.resolve();

package/src/utils/MPSC.spec.ts

@@ -0,0 +1,276 @@
+import { MPSC } from "./MPSC";
+
+describe("the MPSC", () => {
+  describe("basic functionality", () => {
+    it("basic MPSC functionality test", async () => {
+      const mpsc = new MPSC<number>();
+      const reader = mpsc.consumer.getReader();
+
+      // Produce values
+      mpsc.produce(10);
+      mpsc.produce(20);
+      mpsc.produce(30);
+
+      const read1 = await reader.read();
+      const read2 = await reader.read();
+      const read3 = await reader.read();
+
+      expect(read1.value).toBe(10);
+      expect(read1.done).toBe(false);
+      expect(read2.value).toBe(20);
+      expect(read2.done).toBe(false);
+      expect(read3.value).toBe(30);
+      expect(read3.done).toBe(false);
+    });
+
+    it("close functionality test", async () => {
+      const mpsc = new MPSC<number>();
+      const reader = mpsc.consumer.getReader();
+
+      mpsc.produce(10);
+      mpsc.close();
+
+      await reader.read();
+
+      expect(mpsc.done()).toBe(true);
+    });
+
+    it("multiple producers scenario test", async () => {
+      const multiMpsc = new MPSC<string>();
+      const multiReader = multiMpsc.consumer.getReader();
+
+      // Simulate multiple producers
+      for (let i = 1; i <= 5; i++) {
+        multiMpsc.produce(`producer-${i}`);
+      }
+
+      // Read all values
+      const multiResults: string[] = [];
+      for (let i = 0; i < 5; i++) {
+        const { value } = await multiReader.read();
+        if (value != null) {
+          multiResults.push(value);
+        }
+      }
+
+      expect(multiResults.length).toBe(5);
+      expect(multiResults).toContain("producer-1");
+      expect(multiResults).toContain("producer-2");
+      expect(multiResults).toContain("producer-3");
+      expect(multiResults).toContain("producer-4");
+      expect(multiResults).toContain("producer-5");
+
+      multiMpsc.close();
+
+      const multiAfterClose = await multiReader.read();
+      expect(multiAfterClose.done).toBe(true);
+    });
+
+    it("reading before producing test", async () => {
+      const delayMpsc = new MPSC<number>();
+      const delayReader = delayMpsc.consumer.getReader();
+
+      // Start reading before producing
+      const readPromise = delayReader.read();
+
+      // Produce after a small delay
+      setTimeout(() => {
+        delayMpsc.produce(42);
+      }, 10);
+
+      const delayResult = await readPromise;
+      expect(delayResult.value).toBe(42);
+      expect(delayResult.done).toBe(false);
+
+      delayMpsc.close();
+    });
+
+    it("producer-first, then consumer test", async () => {
+      const laterMpsc = new MPSC<string>();
+
+      // Produce values first
+      laterMpsc.produce("first");
+      laterMpsc.produce("second");
+      laterMpsc.produce("third");
+
+      // Then get reader and read
+      const laterReader = laterMpsc.consumer.getReader();
+      const laterResult1 = await laterReader.read();
+      const laterResult2 = await laterReader.read();
+      const laterResult3 = await laterReader.read();
+
+      expect(laterResult1.value).toBe("first");
+      expect(laterResult1.done).toBe(false);
+      expect(laterResult2.value).toBe("second");
+      expect(laterResult2.done).toBe(false);
+      expect(laterResult3.value).toBe("third");
+      expect(laterResult3.done).toBe(false);
+
+      laterMpsc.close();
+    });
+  });
+
+  describe("waitClosed functionality", () => {
+    it("basic waitClosed functionality test", async () => {
+      const mpsc = new MPSC<string>();
+      const reader = mpsc.consumer.getReader();
+
+      mpsc.produce("message");
+      const readResult = await reader.read();
+
+      expect(readResult.value).toBe("message");
+      expect(readResult.done).toBe(false);
+
+      // Call waitClose then execute close
+      const closePromise = mpsc.waitClosed();
+      mpsc.close();
+      await closePromise; // Should resolve when closed
+
+      const afterClose = await reader.read();
+      expect(afterClose.done).toBe(true);
+    });
+
+    it("call waitClose on already closed queue test", async () => {
+      const mpsc2 = new MPSC<number>();
+
+      mpsc2.close(); // Close first
+      const alreadyClosedPromise = mpsc2.waitClosed();
+      // Should resolve immediately since already closed
+      await alreadyClosedPromise;
+    });
+
+    it("multiple waitClose calls test", async () => {
+      const mpsc3 = new MPSC<number>();
+
+      // Create multiple waitClose promises
+      const waitPromises = [mpsc3.waitClosed(), mpsc3.waitClosed(), mpsc3.waitClosed()];
+
+      // All promises should resolve
+      mpsc3.close();
+      await Promise.all(waitPromises);
+    });
+
+    it("verify waitClose doesn't block other operations", async () => {
+      const mpsc4 = new MPSC<string>();
+      const reader4 = mpsc4.consumer.getReader();
+
+      // Call waitClose
+      const waitPromise4 = mpsc4.waitClosed();
+
+      // Check if value production and consumption still work
+      mpsc4.produce("first");
+      mpsc4.produce("second");
+
+      const read1 = await reader4.read();
+      const read2 = await reader4.read();
+
+      expect(read1.value).toBe("first");
+      expect(read1.done).toBe(false);
+      expect(read2.value).toBe("second");
+      expect(read2.done).toBe(false);
+
+      mpsc4.close();
+      await waitPromise4;
+
+      const afterClose4 = await reader4.read();
+      expect(afterClose4.done).toBe(true);
+    });
+
+    it("waitClose resolution after async close test", async () => {
+      const mpsc5 = new MPSC<number>();
+      const reader5 = mpsc5.consumer.getReader();
+
+      mpsc5.produce(100);
+
+      // Call waitClose
+      const waitPromise5 = mpsc5.waitClosed();
+
+      // Perform async close
+      setTimeout(() => {
+        mpsc5.close();
+      }, 50);
+
+      // Wait for waitClose to resolve
+      await waitPromise5;
+      await reader5.read();
+
+      const afterClose5 = await reader5.read();
+      expect(afterClose5.done).toBe(true);
+    });
+  });
+
+  describe("waitUntilEmpty functionality", () => {
+    it("waitUntilEmpty test when queue is empty", async () => {
+      const mpsc = new MPSC<number>();
+      const reader = mpsc.consumer.getReader();
+
+      // Should resolve immediately since queue is empty
+      await mpsc.waitUntilEmpty();
+
+      mpsc.produce(1);
+      const readResult = await reader.read();
+      expect(readResult.value).toBe(1);
+      expect(readResult.done).toBe(false);
+
+      mpsc.close();
+    });
+
+    it("waitUntilEmpty test when queue is not empty", async () => {
+      const mpsc = new MPSC<number>();
+      const reader = mpsc.consumer.getReader();
+
+      mpsc.produce(1);
+      mpsc.produce(2);
+
+      // waitUntilEmpty should not resolve since queue is not empty
+      const waitPromise = mpsc.waitUntilEmpty();
+
+      // Read first value
+      const read1 = await reader.read();
+      expect(read1.value).toBe(1);
+
+      // Read second value
+      const read2 = await reader.read();
+      expect(read2.value).toBe(2);
+      mpsc.close();
+
+      const read3 = await reader.read();
+      expect(read3.done).toBe(true);
+
+      // Now queue is empty, waitUntilEmpty should resolve
+      await waitPromise;
+    });
+
+    it("waitUntilEmpty test on closed queue", async () => {
+      const mpsc = new MPSC<number>();
+      const reader = mpsc.consumer.getReader();
+
+      mpsc.produce(1);
+      mpsc.close();
+
+      // waitUntilEmpty should resolve since queue is closed
+      await mpsc.waitUntilEmpty();
+
+      const readResult = await reader.read();
+      expect(readResult.value).toBe(1);
+      expect(readResult.done).toBe(false);
+
+      const afterClose = await reader.read();
+      expect(afterClose.done).toBe(true);
+    });
+  });
+
+  describe("done functionality", () => {
+    it("done test on unclosed queue", async () => {
+      const mpsc = new MPSC<number>();
+      expect(mpsc.done()).toBe(false);
+
+      mpsc.produce(1);
+      expect(mpsc.done()).toBe(false);
+
+      mpsc.close();
+      await mpsc.consumer.getReader().read();
+      expect(mpsc.done()).toBe(true);
+    });
+  });
+});