@bluelibs/runner 2.2.4 → 3.1.0

package/src/__tests__/globals/queue.resource.test.ts

@@ -0,0 +1,141 @@
+import { defineResource } from "../../define";
+import { run } from "../../run";
+import { queueResource } from "../../globals/resources/queue.resource";
+
+describe("Queue Resource", () => {
+  it("should provide queue functionality with proper isolation and disposal", async () => {
+    let callCount = 0;
+    const executionOrder: number[] = [];
+    let successCallCount = 0;
+
+    const app = defineResource({
+      id: "app",
+      // Don't register queueResource - it's already registered globally
+      dependencies: { queue: queueResource },
+      async init(_, { queue }) {
+        // Test 1: Initialize with empty queue map
+        expect(queue.map).toBeInstanceOf(Map);
+        expect(queue.map.size).toBe(0);
+        expect(typeof queue.run).toBe("function");
+
+        // Test 2: Create and reuse queues by ID
+        const task = async () => {
+          callCount++;
+          return `result-${callCount}`;
+        };
+
+        const result1 = await queue.run("test-queue", task);
+        expect(queue.map.size).toBe(1);
+        expect(queue.map.has("test-queue")).toBe(true);
+
+        const result2 = await queue.run("test-queue", task);
+        expect(queue.map.size).toBe(1);
+        expect(result1).toBe("result-1");
+        expect(result2).toBe("result-2");
+
+        // Test 3: Create separate queues for different IDs
+        const task1 = async () => "queue1-result";
+        const task2 = async () => "queue2-result";
+
+        await queue.run("queue-1", task1);
+        await queue.run("queue-2", task2);
+
+        expect(queue.map.size).toBe(3); // test-queue, queue-1, queue-2
+        expect(queue.map.has("queue-1")).toBe(true);
+        expect(queue.map.has("queue-2")).toBe(true);
+
+        // Test 4: Ensure tasks run sequentially within the same queue
+        const taskFactory = (id: number) => async () => {
+          executionOrder.push(id);
+          await new Promise((resolve) => setTimeout(resolve, 1));
+          return id;
+        };
+
+        const promises = [
+          queue.run("sequential-queue", taskFactory(1)),
+          queue.run("sequential-queue", taskFactory(2)),
+          queue.run("sequential-queue", taskFactory(3)),
+        ];
+
+        const results = await Promise.all(promises);
+        expect(results).toEqual([1, 2, 3]);
+        expect(executionOrder).toEqual([1, 2, 3]);
+        expect(queue.map.size).toBe(4); // Added sequential-queue
+
+        // Test 5: Handle async tasks properly
+        const asyncTask = async () => {
+          await new Promise((resolve) => setTimeout(resolve, 5));
+          return "async-result";
+        };
+
+        const asyncResult = await queue.run("async-queue", asyncTask);
+        expect(asyncResult).toBe("async-result");
+        expect(queue.map.size).toBe(5); // Added async-queue
+
+        // Test 6: Handle errors in tasks without breaking the queue
+        const errorTask = async () => {
+          throw new Error("Task failed");
+        };
+
+        const successTask = async () => {
+          successCallCount++;
+          return `success-${successCallCount}`;
+        };
+
+        await expect(queue.run("error-queue", errorTask)).rejects.toThrow(
+          "Task failed"
+        );
+
+        const successResult = await queue.run("error-queue", successTask);
+        expect(successResult).toBe("success-1");
+        expect(queue.map.size).toBe(6); // Added error-queue
+
+        return queue;
+      },
+    });
+
+    const result = await run(app);
+
+    // Test 7: Dispose all queues when resource is disposed
+    expect(result.value.map.size).toBe(6);
+
+    await result.dispose();
+
+    // Try to run a task on a disposed queue - should reject
+    await expect(
+      result.value.run("test-queue", async () => "test")
+    ).rejects.toThrow(/disposed/);
+  });
+
+  it("should propagate task exceptions to the caller", async () => {
+    const app = defineResource({
+      id: "exception-test-app",
+      dependencies: { queue: queueResource },
+      async init(_, { queue }) {
+        // Test that exceptions from tasks are properly propagated
+        const errorTask = async () => {
+          throw new Error("Queue resource task error");
+        };
+
+        const successTask = async () => "success";
+
+        // Exception should be catchable by the caller
+        await expect(queue.run("error-queue", errorTask)).rejects.toThrow(
+          "Queue resource task error"
+        );
+
+        // Queue should still work for subsequent tasks
+        await expect(queue.run("error-queue", successTask)).resolves.toBe(
+          "success"
+        );
+
+        // Multiple exceptions should all be catchable
+        await expect(queue.run("error-queue", errorTask)).rejects.toThrow(
+          "Queue resource task error"
+        );
+      },
+    });
+
+    await run(app);
+  });
+});

package/src/__tests__/globals/requireContext.middleware.test.ts

@@ -0,0 +1,98 @@
+import { requireContextMiddleware } from "../../globals/middleware/requireContext.middleware";
+import { ContextError } from "../../context";
+
+/**
+ * Utility function to build a fake Context implementation that allows us to
+ * control the behaviour of the `use()` call during each test.
+ */
+function createFakeContext<T>(useImplementation: () => T) {
+  return {
+    /** unique id is irrelevant for tests */
+    id: Symbol("fake-context"),
+    // `use` is what we care about – we wire whatever behaviour the test needs
+    use: jest.fn(useImplementation),
+    // The following members are not used by the middleware but are required
+    // to satisfy the `Context` interface.
+    provide: jest.fn(),
+    // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+    require: jest.fn() as any,
+  } as any;
+}
+
+describe("requireContextMiddleware", () => {
+  it("throws if the middleware receives no context in its config", async () => {
+    // Arrange → no context passed
+    const next = jest.fn();
+
+    // Act & Assert
+    await expect(
+      requireContextMiddleware.run({ next } as any, {} as any, {} as any)
+    ).rejects.toThrow(
+      "Context not available. Did you forget to pass 'context' to the middleware?"
+    );
+  });
+
+  it("throws ContextError when the context has not been provided", async () => {
+    // Arrange → a context whose `use` returns undefined, simulating missing provider
+    const fakeContext = createFakeContext(() => undefined);
+    const next = jest.fn();
+
+    // Act & Assert
+    await expect(
+      requireContextMiddleware.run(
+        { next } as any,
+        {} as any,
+        { context: fakeContext } as any
+      )
+    ).rejects.toBeInstanceOf(ContextError);
+  });
+
+  it("passes task.input to next() and returns its result when called within a task", async () => {
+    const fakeContext = createFakeContext(() => ({ user: "alice" }));
+    const task = { input: "payload" };
+    const expectedResult = "task-result";
+    const next = jest.fn().mockResolvedValue(expectedResult);
+
+    const result = await requireContextMiddleware.run(
+      { task, next } as any,
+      {} as any,
+      { context: fakeContext } as any
+    );
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(next).toHaveBeenCalledWith(task.input);
+    expect(result).toBe(expectedResult);
+  });
+
+  it("passes resource.config to next() and returns its result when called within a resource", async () => {
+    const fakeContext = createFakeContext(() => ({ user: "bob" }));
+    const resource = { config: { url: "https://example.com" } };
+    const expectedResult = "resource-result";
+    const next = jest.fn().mockResolvedValue(expectedResult);
+
+    const result = await requireContextMiddleware.run(
+      { resource, next } as any,
+      {} as any,
+      { context: fakeContext } as any
+    );
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(next).toHaveBeenCalledWith(resource.config);
+    expect(result).toBe(expectedResult);
+  });
+
+  it("calls next() with no arguments when neither task nor resource is provided", async () => {
+    const fakeContext = createFakeContext(() => ({ user: "charlie" }));
+    const next = jest.fn().mockResolvedValue("noop-result");
+
+    const result = await requireContextMiddleware.run(
+      { next } as any,
+      {} as any,
+      { context: fakeContext } as any
+    );
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(next).toHaveBeenCalledWith();
+    expect(result).toBe("noop-result");
+  });
+});

package/src/__tests__/globals/retry.middleware.test.ts

@@ -0,0 +1,157 @@
+import { defineResource, defineTask } from "../../define";
+import { retryMiddleware } from "../../globals/middleware/retry.middleware";
+import { run } from "../../run";
+
+describe("Retry Middleware", () => {
+  it("should retry failed operations with exponential backoff", async () => {
+    let attempt = 0;
+    const task = defineTask({
+      id: "flakyTask",
+      middleware: [
+        retryMiddleware.with({
+          retries: 3,
+          stopRetryIf: (e) => e.message.includes("FATAL"),
+        }),
+      ],
+      run: async () => {
+        attempt++;
+        if (attempt < 3) throw new Error("Temporary failure");
+        return "Success";
+      },
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [task],
+      dependencies: { task },
+      async init(_, { task }) {
+        const result = await task();
+        expect(result).toBe("Success");
+        expect(attempt).toBe(3);
+      },
+    });
+
+    await run(app);
+  });
+
+  it("should respect stopRetryIf condition", async () => {
+    const errorSpy = jest.fn();
+    const task = defineTask({
+      id: "fatalTask",
+      middleware: [
+        retryMiddleware.with({
+          retries: 3,
+          stopRetryIf: (e) => e.message === "FATAL",
+        }),
+      ],
+      run: async () => {
+        throw new Error("FATAL");
+      },
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [task],
+      dependencies: { task },
+      async init(_, { task }) {
+        await expect(task()).rejects.toThrow("FATAL");
+        expect(errorSpy).not.toHaveBeenCalled();
+        throw new Error("FATAL");
+      },
+    });
+
+    await run(app).catch(errorSpy);
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("should use custom delay strategy", async () => {
+    jest.useFakeTimers();
+    const delays: number[] = [];
+    const start = Date.now();
+
+    const task = defineTask({
+      id: "delayedTask",
+      middleware: [
+        retryMiddleware.with({
+          retries: 3,
+          delayStrategy: (attempt) => (attempt + 1) * 100, // Linear delay
+        }),
+      ],
+      run: async () => {
+        throw new Error("Retry me");
+      },
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [task],
+      dependencies: { task },
+      async init(_, { task }) {
+        task().catch(() => {});
+      },
+    });
+
+    await run(app);
+
+    // Advance timers through all retries
+    jest.advanceTimersByTime(1000);
+    const elapsed = Date.now() - start;
+
+    // Verify delay sequence: 100ms, 200ms, 300ms
+    expect(elapsed).toBeGreaterThanOrEqual(600); // 100+200+300=600
+    jest.useRealTimers();
+  });
+
+  it("should work with resource initialization", async () => {
+    let attempts = 0;
+    const resource = defineResource({
+      id: "flakyResource",
+      middleware: [
+        retryMiddleware.with({
+          retries: 2,
+        }),
+      ],
+      async init() {
+        attempts++;
+        if (attempts < 2) throw new Error("Resource init failed");
+        return "Resource ready";
+      },
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [resource],
+      dependencies: { resource },
+      async init(_, { resource }) {
+        expect(resource).toBe("Resource ready");
+        expect(attempts).toBe(2);
+      },
+    });
+
+    await run(app);
+  });
+
+  it("Should default to 3 retries", async () => {
+    let attempt = 0;
+    const task = defineTask({
+      id: "flakyTask",
+      middleware: [retryMiddleware],
+      run: async () => {
+        attempt++;
+        throw new Error("Temporary failure");
+      },
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [task],
+      dependencies: { task },
+      async init(_, { task }) {
+        await expect(task()).rejects.toThrow("Temporary failure");
+      },
+    });
+
+    await run(app);
+    expect(attempt).toBe(4); // fails once and retries 3 more times, logically
+  });
+});

package/src/__tests__/index.helper.test.ts

@@ -0,0 +1,55 @@
+import { defineTask, defineResource, defineIndex } from "../define";
+import { run } from "../run";
+import { index } from "../index";
+
+describe("index helper", () => {
+  it("should aggregate dependencies and expose proper types", async () => {
+    const userService = defineResource({
+      id: "user.service",
+      async init() {
+        return "USER";
+      },
+    });
+
+    const configuredService = defineResource({
+      id: "configured.service",
+      async init(config: { name: string }) {
+        return config.name;
+      },
+    });
+
+    const getUserTask = defineTask({
+      id: "task.getUser",
+      dependencies: { userService },
+      async run(_, { userService }) {
+        return userService;
+      },
+    });
+
+    // The helper under test
+    const services = index({
+      userService,
+      getUserTask,
+      configuredService: configuredService.with({ name: "configured" }),
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [services],
+      dependencies: { services },
+      async init(_, { services }) {
+        // Runtime assertions
+        expect(services.userService).toBe("USER");
+        const result = await services.getUserTask();
+        expect(result).toBe("USER");
+        expect(services.configuredService).toBe("configured");
+        // Type assertions
+        services.userService as string;
+        // @ts-expect-error – assigning to never should error
+        const neverValue: never = "bad";
+      },
+    });
+
+    await run(app);
+  });
+});

package/src/__tests__/models/EventManager.test.ts

@@ -1,10 +1,10 @@
-import { IEvent, IEventDefinition, symbolEvent } from "../../defs";
+import { IEvent, IEventEmission, symbolEvent } from "../../defs";
 import { Errors } from "../../errors";
 import { EventManager } from "../../models/EventManager";
 
 describe("EventManager", () => {
   let eventManager: EventManager;
-  let eventDefinition: IEventDefinition<string>;
+  let eventDefinition: IEvent<string>;
 
   beforeEach(() => {
     eventManager = new EventManager();
@@ -69,7 +69,7 @@ describe("EventManager", () => {
 
   it("should apply filters correctly", async () => {
     const handler = jest.fn();
-    const filter = (event: IEvent<string>) => event.data === "allowed";
+    const filter = (event: IEventEmission<string>) => event.data === "allowed";
 
     eventManager.addListener(eventDefinition, handler, { filter });
 
@@ -97,6 +97,7 @@ describe("EventManager", () => {
       expect.objectContaining({
         id: "testEvent",
         data: "testData",
+        timestamp: expect.any(Date),
       })
     );
   });
@@ -161,11 +162,11 @@ describe("EventManager", () => {
   });
 
   it("should handle multiple events", async () => {
-    const eventDef1: IEventDefinition<string> = {
+    const eventDef1: IEvent<string> = {
       id: "event1",
       [symbolEvent]: true,
     };
-    const eventDef2: IEventDefinition<string> = {
+    const eventDef2: IEvent<string> = {
       id: "event2",
       [symbolEvent]: true,
     };
@@ -184,6 +185,7 @@ describe("EventManager", () => {
       expect.objectContaining({
         id: "event1",
         data: "data1",
+        timestamp: expect.any(Date),
       })
     );
 
@@ -210,11 +212,11 @@ describe("EventManager", () => {
   });
 
   it("should handle listeners added to multiple events", async () => {
-    const eventDef1: IEventDefinition<string> = {
+    const eventDef1: IEvent<string> = {
       id: "event1",
       [symbolEvent]: true,
     };
-    const eventDef2: IEventDefinition<string> = {
+    const eventDef2: IEvent<string> = {
       id: "event2",
       [symbolEvent]: true,
     };
@@ -244,11 +246,11 @@ describe("EventManager", () => {
   });
 
   it("should not affect other events when emitting one", async () => {
-    const eventDef1: IEventDefinition<string> = {
+    const eventDef1: IEvent<string> = {
       id: "event1",
       [symbolEvent]: true,
     };
-    const eventDef2: IEventDefinition<string> = {
+    const eventDef2: IEvent<string> = {
       id: "event2",
       [symbolEvent]: true,
     };
@@ -367,7 +369,7 @@ describe("EventManager", () => {
 
   it("should handle filters in global listeners", async () => {
     const handler = jest.fn();
-    const filter = (event: IEvent<string>) => event.data === "allowed";
+    const filter = (event: IEventEmission<string>) => event.data === "allowed";
 
     eventManager.addGlobalListener(handler, { filter });
 
@@ -387,7 +389,7 @@ describe("EventManager", () => {
   it("should handle listeners with no data", async () => {
     const handler = jest.fn();
 
-    const voidEventDefinition: IEventDefinition<void> = {
+    const voidEventDefinition: IEvent<void> = {
       id: "voidEvent",
       [symbolEvent]: true,
     };
@@ -401,7 +403,151 @@ describe("EventManager", () => {
       expect.objectContaining({
         id: "voidEvent",
         data: undefined,
+        timestamp: expect.any(Date),
       })
     );
   });
+
+  describe("Performance Optimizations", () => {
+    it("should cache merged listeners for repeated emits", async () => {
+      const handler1 = jest.fn();
+      const handler2 = jest.fn();
+
+      eventManager.addListener(eventDefinition, handler1, { order: 1 });
+      eventManager.addGlobalListener(handler2, { order: 2 });
+
+      // First emit should build cache
+      await eventManager.emit(eventDefinition, "test1", "source");
+      // Second emit should use cache
+      await eventManager.emit(eventDefinition, "test2", "source");
+
+      expect(handler1).toHaveBeenCalledTimes(2);
+      expect(handler2).toHaveBeenCalledTimes(2);
+    });
+
+    it("should invalidate cache when adding event listeners", async () => {
+      const handler1 = jest.fn();
+      const handler2 = jest.fn();
+      const handler3 = jest.fn();
+
+      eventManager.addListener(eventDefinition, handler1, { order: 2 });
+      await eventManager.emit(eventDefinition, "test1", "source");
+
+      // Add new listener - should invalidate cache for this event
+      eventManager.addListener(eventDefinition, handler2, { order: 1 });
+      eventManager.addGlobalListener(handler3, { order: 3 });
+
+      await eventManager.emit(eventDefinition, "test2", "source");
+
+      expect(handler1).toHaveBeenCalledTimes(2);
+      expect(handler2).toHaveBeenCalledTimes(1);
+      expect(handler3).toHaveBeenCalledTimes(1);
+    });
+
+    it("should invalidate all caches when adding global listeners", async () => {
+      const event1: IEvent<string> = { id: "event1", [symbolEvent]: true };
+      const event2: IEvent<string> = { id: "event2", [symbolEvent]: true };
+
+      const handler1 = jest.fn();
+      const handler2 = jest.fn();
+      const globalHandler = jest.fn();
+
+      eventManager.addListener(event1, handler1);
+      eventManager.addListener(event2, handler2);
+
+      // Emit to build caches
+      await eventManager.emit(event1, "test1", "source");
+      await eventManager.emit(event2, "test2", "source");
+
+      // Add global listener - should invalidate all caches
+      eventManager.addGlobalListener(globalHandler);
+
+      // Emit again - global handler should be called
+      await eventManager.emit(event1, "test3", "source");
+      await eventManager.emit(event2, "test4", "source");
+
+      expect(globalHandler).toHaveBeenCalledTimes(2);
+    });
+
+    it("should optimize for empty listener scenarios", async () => {
+      const emptyEventDef: IEvent<string> = {
+        id: "emptyEvent",
+        [symbolEvent]: true,
+      };
+
+      // Should return immediately without creating event object
+      await eventManager.emit(emptyEventDef, "test", "source");
+
+      // No errors should occur
+      expect(true).toBe(true);
+    });
+
+    it("should handle high-frequency emissions efficiently", async () => {
+      const handler = jest.fn();
+      eventManager.addListener(eventDefinition, handler);
+      eventManager.addGlobalListener(jest.fn());
+
+      const emitCount = 1000;
+      const startTime = Date.now();
+
+      for (let i = 0; i < emitCount; i++) {
+        await eventManager.emit(eventDefinition, `test${i}`, "source");
+      }
+
+      const endTime = Date.now();
+      const duration = endTime - startTime;
+
+      expect(handler).toHaveBeenCalledTimes(emitCount);
+      // Should complete reasonably fast (adjust threshold as needed)
+      expect(duration).toBeLessThan(5000); // 5 seconds max for 1000 emissions
+    });
+
+    it("should efficiently handle mixed event and global listeners", async () => {
+      const results: string[] = [];
+
+      // Add many listeners with different orders
+      for (let i = 0; i < 10; i++) {
+        eventManager.addListener(
+          eventDefinition,
+          () => results.push(`event${i}`),
+          { order: i * 2 }
+        );
+        eventManager.addGlobalListener(() => results.push(`global${i}`), {
+          order: i * 2 + 1,
+        });
+      }
+
+      await eventManager.emit(eventDefinition, "test", "source");
+
+      // Should maintain correct order and call all listeners
+      expect(results).toHaveLength(20);
+      expect(results[0]).toBe("event0");
+      expect(results[1]).toBe("global0");
+      expect(results[18]).toBe("event9");
+      expect(results[19]).toBe("global9");
+    });
+
+    it("should reuse cached results across different event types", async () => {
+      const event1: IEvent<string> = { id: "event1", [symbolEvent]: true };
+      const event2: IEvent<string> = { id: "event2", [symbolEvent]: true };
+
+      const handler1 = jest.fn();
+      const handler2 = jest.fn();
+      const globalHandler = jest.fn();
+
+      eventManager.addListener(event1, handler1);
+      eventManager.addListener(event2, handler2);
+      eventManager.addGlobalListener(globalHandler);
+
+      // Multiple emits should use cached merged listeners
+      await eventManager.emit(event1, "test1", "source");
+      await eventManager.emit(event2, "test2", "source");
+      await eventManager.emit(event1, "test3", "source");
+      await eventManager.emit(event2, "test4", "source");
+
+      expect(handler1).toHaveBeenCalledTimes(2);
+      expect(handler2).toHaveBeenCalledTimes(2);
+      expect(globalHandler).toHaveBeenCalledTimes(4);
+    });
+  });
 });