@bluelibs/runner 3.2.0 → 3.3.0

package/src/__tests__/override.test.ts

@@ -0,0 +1,104 @@
+import { definitions, task, resource, middleware, override } from "..";
+
+describe("override() helper", () => {
+  it("should preserve id and override run for tasks", async () => {
+    const base = task({
+      id: "test.task",
+      run: async () => "base",
+    });
+
+    const changed = override(base, {
+      run: async () => "changed",
+      meta: { title: "Updated" },
+    });
+
+    expect(changed).not.toBe(base);
+    expect(changed.id).toBe(base.id);
+    expect(await base.run(undefined as any, {} as any)).toBe("base");
+    expect(await changed.run(undefined as any, {} as any)).toBe("changed");
+    expect(changed.meta?.title).toBe("Updated");
+  });
+
+  it("should preserve id and override init for resources", async () => {
+    const base = resource({
+      id: "test.resource",
+      init: async () => 1,
+    });
+
+    const changed = override(base, {
+      init: async () => 2,
+      meta: { description: "Updated" },
+    });
+
+    expect(changed).not.toBe(base);
+    expect(changed.id).toBe(base.id);
+    // Call the init functions directly (without runner) to validate override
+    // Signatures: init(config, deps, ctx)
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const v1 = await base.init!(undefined as any, {} as any, undefined as any);
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const v2 = await changed.init!(
+      undefined as any,
+      {} as any,
+      undefined as any
+    );
+    expect(v1).toBe(1);
+    expect(v2).toBe(2);
+    expect(changed.meta?.description).toBe("Updated");
+  });
+
+  it("should preserve id and override run for middleware", async () => {
+    const mw = middleware({
+      id: "test.middleware",
+      run: async ({ next }) => {
+        return next();
+      },
+    });
+
+    const changed = override(mw, {
+      run: async ({ task, next }) => {
+        const result = await next(task?.input as any);
+        return { wrapped: result } as any;
+      },
+    });
+
+    expect(changed).not.toBe(mw);
+    expect(changed.id).toBe(mw.id);
+
+    const input = {
+      task: { definition: undefined as any, input: 123 },
+      next: async () => 456,
+    } as definitions.IMiddlewareExecutionInput<any, any>;
+
+    const baseResult = await mw.run(input, {} as any, undefined as any);
+    const changedResult = await changed.run(input, {} as any, undefined as any);
+    expect(baseResult).toBe(456);
+    expect(changedResult).toEqual({ wrapped: 456 });
+  });
+
+  it("should be type-safe: cannot override id on task/resource/middleware", () => {
+    const t = task({ id: "tt", run: async () => undefined });
+    const r = resource({ id: "rr", init: async () => undefined });
+    const m = middleware({ id: "mm", run: async ({ next }) => next() });
+
+    // @ts-expect-error id cannot be overridden
+    override(t, { id: "new" });
+
+    // @ts-expect-error id cannot be overridden
+    override(r, { id: "new" });
+
+    // @ts-expect-error id cannot be overridden
+    override(m, { id: "new" });
+
+    expect(true).toBe(true);
+  });
+
+  it("should handle undefined patch (robustness)", () => {
+    const base = task({ id: "robust.task", run: async () => 1 });
+    const changed = (override as any)(base, undefined);
+
+    expect(changed).not.toBe(base);
+    expect(changed.id).toBe(base.id);
+    expect(changed.run).toBe(base.run);
+  });
+});

package/src/__tests__/run.overrides.test.ts

@@ -4,6 +4,7 @@ import {
   defineResource,
   defineEvent,
   defineMiddleware,
+  defineOverride,
 } from "../define";
 import { Errors } from "../errors";
 import { run } from "../run";
@@ -16,8 +17,7 @@ describe("run.overrides", () => {
       run: async () => "Task executed",
     });
 
-    const override = defineTask({
-      id: "task",
+    const overrideTask = defineOverride(task, {
       run: async () => "Task overridden",
     });
 
@@ -27,7 +27,7 @@ describe("run.overrides", () => {
       dependencies: {
         task,
       },
-      overrides: [override],
+      overrides: [overrideTask],
       async init(_, deps) {
         return await deps.task();
       },
@@ -43,15 +43,14 @@ describe("run.overrides", () => {
       run: async () => "Task executed",
     });
 
-    const override = defineTask({
-      id: "task",
+    const overrideTask = defineOverride(task, {
       run: async () => "Task overridden",
     });
 
     const middle = defineResource({
       id: "app",
       register: [task],
-      overrides: [override],
+      overrides: [overrideTask],
     });
 
     const root = defineResource({
@@ -73,15 +72,14 @@ describe("run.overrides", () => {
       run: async () => "Task executed",
     });
 
-    const override = defineTask({
-      id: "task",
+    const overrideTask = defineOverride(task, {
       run: async () => "Task overridden",
     });
 
     const middle = defineResource<{ test: string }>({
       id: "app",
       register: [task],
-      overrides: [override],
+      overrides: [overrideTask],
     });
 
     const root = defineResource({
@@ -103,8 +101,7 @@ describe("run.overrides", () => {
       run: async () => "Task executed",
     });
 
-    const override = defineTask({
-      id: "task",
+    const overrideTask = defineOverride(task, {
       run: async () => "Task overridden",
     });
 
@@ -112,10 +109,9 @@ describe("run.overrides", () => {
       id: "resource",
     });
 
-    const resourceOverride = {
-      ...resource,
-      overrides: [override],
-    };
+    const resourceOverride = defineOverride(resource, {
+      overrides: [overrideTask],
+    });
 
     const middle = defineResource({
       id: "app",
@@ -142,8 +138,7 @@ describe("run.overrides", () => {
       run: async () => "Task executed",
     });
 
-    const override = defineTask({
-      id: "task",
+    const overrideTask = defineOverride(task, {
       run: async () => "Task overridden",
     });
 
@@ -153,7 +148,7 @@ describe("run.overrides", () => {
 
     const resourceOverride: definitions.IResource<any> = {
       ...resource,
-      overrides: [override],
+      overrides: [overrideTask],
       async init(config: { test: string }) {
         return "Resource init";
       },
@@ -186,8 +181,7 @@ describe("run.overrides", () => {
       },
     });
 
-    const override = defineMiddleware({
-      id: "middleware",
+    const middlewareOverride = defineOverride(middleware, {
       run: async ({ next }) => {
         return `Override: ${await next()}`;
       },
@@ -203,7 +197,7 @@ describe("run.overrides", () => {
       id: "resource",
       register: [middleware, task],
       dependencies: { task },
-      overrides: [override],
+      overrides: [middlewareOverride],
       async init(_, deps) {
         return deps.task();
       },
@@ -392,4 +386,39 @@ describe("run.overrides", () => {
     const result = await run(app);
     expect(result.value).toBe("Task overriden.");
   });
+
+  it("should choose precedence when two overrides target the same id", async () => {
+    const baseTask = defineTask({
+      id: "task.same",
+      run: async () => "Original",
+    });
+
+    const middleOverride = defineOverride(baseTask, {
+      run: async () => "Middle",
+    });
+
+    const rootOverride = defineOverride(baseTask, {
+      run: async () => "Root",
+    });
+
+    const middle = defineResource({
+      id: "middle",
+      register: [baseTask],
+      overrides: [middleOverride],
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [middle],
+      dependencies: { t: baseTask },
+      overrides: [rootOverride],
+      async init(_, deps) {
+        return await deps.t();
+      },
+    });
+
+    const result = await run(app);
+    // Since root is visited after middle, its override takes precedence.
+    expect(result.value).toBe("Root");
+  });
 });

package/src/__tests__/run.test.ts

@@ -16,12 +16,17 @@ describe("main exports", () => {
     expect(typeof mainExports.resource).toBe("function");
     expect(typeof mainExports.event).toBe("function");
     expect(typeof mainExports.middleware).toBe("function");
+    expect(typeof mainExports.index).toBe("function");
+    expect(typeof mainExports.tag).toBe("function");
     expect(typeof mainExports.run).toBe("function");
+    expect(typeof mainExports.createContext).toBe("function");
     expect(typeof mainExports.globals).toBe("object");
     expect(typeof mainExports.definitions).toBe("object");
     expect(typeof mainExports.Store).toBe("function");
     expect(typeof mainExports.EventManager).toBe("function");
     expect(typeof mainExports.TaskRunner).toBe("function");
+    expect(typeof mainExports.Queue).toBe("function");
+    expect(typeof mainExports.Semaphore).toBe("function");
 
     // Test that aliases work the same as direct imports
     const directTask = defineTask({ id: "test", run: async () => "direct" });
@@ -33,6 +38,20 @@ describe("main exports", () => {
     expect(directTask.id).toBe("test");
     expect(aliasTask.id).toBe("test2");
 
+    // Test tag exports work
+    const testTag = mainExports.tag<{ value: number }>({ id: "test.tag" });
+    const testTag2 = mainExports.tag<{ name: string }>({ id: "test.tag2" });
+
+    expect(testTag.id).toBe("test.tag");
+    expect(testTag2.id).toBe("test.tag2");
+    expect(typeof testTag.with).toBe("function");
+    expect(typeof testTag2.extract).toBe("function");
+
+    // Test createContext export
+    const TestContext = mainExports.createContext<string>("test.context");
+    expect(typeof TestContext.provide).toBe("function");
+    expect(typeof TestContext.use).toBe("function");
+
     // Test globals sub-properties for complete coverage
     expect(typeof mainExports.globals.events).toBe("object");
     expect(typeof mainExports.globals.resources).toBe("object");

package/src/__tests__/tags.test.ts

@@ -0,0 +1,396 @@
+import {
+  defineTag,
+  defineTask,
+  defineResource,
+  defineEvent,
+  defineMiddleware,
+} from "../define";
+import { run } from "../run";
+
+describe("Configurable Tags", () => {
+  describe("Tag Definition", () => {
+    it("should create a tag with string id", () => {
+      const performanceTag = defineTag<{ alertAboveMs: number }>({
+        id: "performance.track",
+      });
+
+      expect(performanceTag.id).toBe("performance.track");
+      expect(typeof performanceTag.with).toBe("function");
+      expect(typeof performanceTag.extract).toBe("function");
+    });
+
+    it("should create a tag with symbol id", () => {
+      const symbolId = Symbol("test.tag");
+      const testTag = defineTag<{ value: string }>({ id: symbolId });
+
+      expect(testTag.id).toBe(symbolId);
+    });
+
+    it("should create a tag without configuration", () => {
+      const simpleTag = defineTag({ id: "simple.tag" });
+
+      expect(simpleTag.id).toBe("simple.tag");
+      expect(typeof simpleTag.with).toBe("function");
+      expect(typeof simpleTag.extract).toBe("function");
+    });
+  });
+
+  describe("Tag Configuration with .with()", () => {
+    it("should create a configured tag instance", () => {
+      const performanceTag = defineTag<{ alertAboveMs: number }>({
+        id: "performance.track",
+      });
+
+      const configuredTag = performanceTag.with({ alertAboveMs: 200 });
+
+      expect(configuredTag.id).toBe("performance.track");
+      expect(configuredTag.config).toEqual({ alertAboveMs: 200 });
+      expect(configuredTag.tag).toBe(performanceTag);
+    });
+
+    it("should allow multiple configurations of the same tag", () => {
+      const cacheTag = defineTag<{ ttl: number }>({ id: "cache.config" });
+
+      const shortCache = cacheTag.with({ ttl: 300 });
+      const longCache = cacheTag.with({ ttl: 3600 });
+
+      expect(shortCache.config.ttl).toBe(300);
+      expect(longCache.config.ttl).toBe(3600);
+      expect(shortCache.tag).toBe(cacheTag);
+      expect(longCache.tag).toBe(cacheTag);
+    });
+  });
+
+  describe("Tag Extraction with .extract()", () => {
+    it("should extract configured tag from tags array", () => {
+      const performanceTag = defineTag<{ alertAboveMs: number }>({
+        id: "performance.track",
+      });
+
+      const tags = [
+        "simple-string-tag",
+        performanceTag.with({ alertAboveMs: 200 }),
+        "another-string",
+      ];
+
+      const extracted = performanceTag.extract(tags);
+
+      expect(extracted).not.toBeNull();
+      expect(extracted?.id).toBe("performance.track");
+      expect(extracted?.config).toEqual({ alertAboveMs: 200 });
+    });
+
+    it("should extract unconfigured tag from tags array", () => {
+      const simpleTag = defineTag({ id: "simple.tag" });
+
+      const tags = ["string-tag", simpleTag, "another-string"];
+
+      const extracted = simpleTag.extract(tags);
+
+      expect(extracted).not.toBeNull();
+      expect(extracted?.id).toBe("simple.tag");
+      expect(extracted?.config).toBeUndefined();
+    });
+
+    it("should return null if tag not found", () => {
+      const performanceTag = defineTag<{ alertAboveMs: number }>({
+        id: "performance.track",
+      });
+
+      const tags = ["string-tag", "another-string"];
+
+      const extracted = performanceTag.extract(tags);
+
+      expect(extracted).toBeNull();
+    });
+
+    it("should ignore string tags during extraction", () => {
+      const performanceTag = defineTag<{ alertAboveMs: number }>({
+        id: "performance.track",
+      });
+
+      const tags = [
+        "performance.track", // This is a string, not the tag
+        performanceTag.with({ alertAboveMs: 100 }),
+      ];
+
+      const extracted = performanceTag.extract(tags);
+
+      expect(extracted).not.toBeNull();
+      expect(extracted?.config).toEqual({ alertAboveMs: 100 });
+    });
+
+    it("should handle symbol ids correctly", () => {
+      const symbolId = Symbol("test.tag");
+      const testTag = defineTag<{ data: string }>({ id: symbolId });
+
+      const tags = [testTag.with({ data: "test" })];
+
+      const extracted = testTag.extract(tags);
+
+      expect(extracted).not.toBeNull();
+      expect(extracted?.id).toBe(symbolId);
+      expect(extracted?.config).toEqual({ data: "test" });
+    });
+
+    it("should extract configured tag from a taggable object (task.definition)", () => {
+      const performanceTag = defineTag<{ alertAboveMs: number }>({
+        id: "performance.track",
+      });
+
+      const task = defineTask({
+        id: "task.with.tags",
+        meta: {
+          tags: [performanceTag.with({ alertAboveMs: 123 })],
+        },
+        run: async () => "ok",
+      });
+
+      const extracted = performanceTag.extract(task);
+      expect(extracted).not.toBeNull();
+      expect(extracted?.config).toEqual({ alertAboveMs: 123 });
+    });
+
+    it("should return null when taggable has no tags", () => {
+      const t = defineTag({ id: "x" });
+      const task = defineTask({ id: "no.tags", run: async () => "ok" });
+      expect(t.extract(task)).toBeNull();
+    });
+
+    it("should work with a simple taggable carrying meta.tags directly", () => {
+      const t = defineTag<{ p: number }>({ id: "pp" });
+      const taggable = { meta: { tags: [t.with({ p: 9 })] } } as any;
+      const extracted = t.extract(taggable);
+      expect(extracted?.config).toEqual({ p: 9 });
+    });
+  });
+
+  describe("Integration with Tasks", () => {
+    it("should work with task metadata", () => {
+      const performanceTag = defineTag<{ alertAboveMs: number }>({
+        id: "performance.track",
+      });
+
+      const testTask = defineTask({
+        id: "test.task",
+        meta: {
+          tags: [
+            "api",
+            performanceTag.with({ alertAboveMs: 200 }),
+            "important",
+          ],
+        },
+        run: async () => {
+          return "success";
+        },
+      });
+
+      expect(testTask.meta?.tags).toHaveLength(3);
+      expect(testTask.meta?.tags?.[0]).toBe("api");
+      expect(testTask.meta?.tags?.[2]).toBe("important");
+
+      const extracted = performanceTag.extract(testTask.meta?.tags || []);
+      expect(extracted).not.toBeNull();
+      expect(extracted?.config).toEqual({ alertAboveMs: 200 });
+    });
+
+    it("should work with middleware checking tags", async () => {
+      const performanceTag = defineTag<{ alertAboveMs: number }>({
+        id: "performance.track",
+      });
+
+      const middlewareExecutions: Array<{ taskId: string; config: any }> = [];
+
+      const performanceMiddleware = defineMiddleware({
+        id: "performance.middleware",
+        run: async ({ task, next }) => {
+          if (task?.definition.meta?.tags) {
+            const extracted = performanceTag.extract(task.definition.meta.tags);
+            if (extracted) {
+              middlewareExecutions.push({
+                taskId: task.definition.id as string,
+                config: extracted.config,
+              });
+            }
+          }
+          return next(task?.input);
+        },
+      });
+
+      const fastTask = defineTask({
+        id: "fast.task",
+        meta: {
+          tags: [performanceTag.with({ alertAboveMs: 100 })],
+        },
+        run: async () => "fast",
+      });
+
+      const slowTask = defineTask({
+        id: "slow.task",
+        meta: {
+          tags: [performanceTag.with({ alertAboveMs: 500 })],
+        },
+        run: async () => "slow",
+      });
+
+      const normalTask = defineTask({
+        id: "normal.task",
+        meta: {
+          tags: ["just-a-string"],
+        },
+        run: async () => "normal",
+      });
+
+      const app = defineResource({
+        id: "test.app",
+        register: [
+          fastTask,
+          slowTask,
+          normalTask,
+          performanceMiddleware.everywhere(),
+        ],
+        dependencies: { fastTask, slowTask, normalTask },
+        init: async (_, { fastTask, slowTask, normalTask }) => {
+          await fastTask();
+          await slowTask();
+          await normalTask();
+          return "done";
+        },
+      });
+
+      const { dispose } = await run(app);
+      await dispose();
+
+      expect(middlewareExecutions).toHaveLength(2);
+      expect(middlewareExecutions).toEqual([
+        { taskId: "fast.task", config: { alertAboveMs: 100 } },
+        { taskId: "slow.task", config: { alertAboveMs: 500 } },
+      ]);
+    });
+  });
+
+  describe("Integration with Resources", () => {
+    it("should work with resource metadata", () => {
+      const dbTag = defineTag<{ connectionTimeout: number }>({
+        id: "db.config",
+      });
+
+      const database = defineResource({
+        id: "database",
+        meta: {
+          tags: ["database", dbTag.with({ connectionTimeout: 5000 })],
+        },
+        init: async () => ({ query: () => "result" }),
+      });
+
+      expect(database.meta?.tags).toHaveLength(2);
+      const extracted = dbTag.extract(database.meta?.tags || []);
+      expect(extracted?.config).toEqual({ connectionTimeout: 5000 });
+    });
+  });
+
+  describe("Integration with Events", () => {
+    it("should work with event metadata", () => {
+      const auditTag = defineTag<{ sensitive: boolean }>({
+        id: "audit.config",
+      });
+
+      const userEvent = defineEvent<{ userId: string }>({
+        id: "user.created",
+        meta: {
+          tags: ["user-event", auditTag.with({ sensitive: true })],
+        },
+      });
+
+      expect(userEvent.meta?.tags).toHaveLength(2);
+      const extracted = auditTag.extract(userEvent.meta?.tags || []);
+      expect(extracted?.config).toEqual({ sensitive: true });
+    });
+  });
+
+  describe("Integration with Middleware", () => {
+    it("should work with middleware metadata", () => {
+      const rateLimitTag = defineTag<{ requestsPerMinute: number }>({
+        id: "rate-limit",
+      });
+
+      const rateLimitMiddleware = defineMiddleware({
+        id: "rate.limit.middleware",
+        meta: {
+          tags: ["security", rateLimitTag.with({ requestsPerMinute: 60 })],
+        },
+        run: async ({ next, task }) => {
+          return next(task?.input);
+        },
+      });
+
+      expect(rateLimitMiddleware.meta?.tags).toHaveLength(2);
+      const extracted = rateLimitTag.extract(
+        rateLimitMiddleware.meta?.tags || []
+      );
+      expect(extracted?.config).toEqual({ requestsPerMinute: 60 });
+    });
+  });
+
+  describe("Backward Compatibility", () => {
+    it("should work with existing string tags", () => {
+      const task = defineTask({
+        id: "legacy.task",
+        meta: {
+          tags: ["api", "legacy", "important"],
+        },
+        run: async () => "success",
+      });
+
+      // String tags should still work
+      expect(task.meta?.tags).toEqual(["api", "legacy", "important"]);
+
+      // New tags should not interfere with string tags
+      const performanceTag = defineTag<{ alertAboveMs: number }>({
+        id: "performance.track",
+      });
+
+      const extracted = performanceTag.extract(task.meta?.tags || []);
+      expect(extracted).toBeNull(); // Should not find the tag
+    });
+
+    it("should allow mixing string tags and configurable tags", () => {
+      const performanceTag = defineTag<{ alertAboveMs: number }>({
+        id: "performance.track",
+      });
+
+      const task = defineTask({
+        id: "mixed.task",
+        meta: {
+          tags: [
+            "api", // string tag
+            performanceTag.with({ alertAboveMs: 200 }), // configurable tag
+            "important", // string tag
+          ],
+        },
+        run: async () => "success",
+      });
+
+      expect(task.meta?.tags).toHaveLength(3);
+      expect(task.meta?.tags?.[0]).toBe("api");
+      expect(task.meta?.tags?.[2]).toBe("important");
+
+      const extracted = performanceTag.extract(task.meta?.tags || []);
+      expect(extracted?.config).toEqual({ alertAboveMs: 200 });
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle null/undefined config", () => {
+      const optionalTag = defineTag<{ value?: string }>({
+        id: "optional.config",
+      });
+
+      const configuredTag = optionalTag.with({});
+      expect(configuredTag.config).toEqual({});
+
+      const extracted = optionalTag.extract([configuredTag]);
+      expect(extracted?.config).toEqual({});
+    });
+  });
+});