@bluelibs/runner 3.2.0 → 3.3.1

package/dist/types/task.d.ts

@@ -0,0 +1,68 @@
+import type { ITaskMeta } from './metadata';
+import type { DependencyMapType, DependencyValuesType } from './dependencies';
+import type { IEventDefinition, IEvent, IEventEmission } from './event';
+import type { MiddlewareAttachments } from './middleware';
+export type BeforeRunEventPayload<TInput> = {
+    input: TInput;
+};
+export type AfterRunEventPayload<TInput, TOutput> = {
+    input: TInput;
+    output: TOutput extends Promise<infer U> ? U : TOutput;
+    setOutput(newOutput: TOutput extends Promise<infer U> ? U : TOutput): void;
+};
+export type OnErrorEventPayload = {
+    error: any;
+    /**
+     * This function can be called to suppress the error from being thrown.
+     */
+    suppress(): void;
+};
+type ExtractEventParams<T> = T extends IEventDefinition<infer P> ? P : never;
+export interface ITaskDefinition<TInput = any, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TOn extends "*" | IEventDefinition<any> | undefined = undefined> {
+    /**
+     * Stable identifier. If omitted, an anonymous id is generated from file path
+     * (see README: Anonymous IDs).
+     */
+    id?: string | symbol;
+    /**
+     * Access other tasks/resources/events. Can be an object or a function when
+     * you need late or config‑dependent resolution.
+     */
+    dependencies?: TDependencies | (() => TDependencies);
+    /** Middleware applied around task execution. */
+    middleware?: MiddlewareAttachments[];
+    /**
+     * Listen to events in a simple way
+     */
+    on?: TOn;
+    /**
+     * This makes sense only when `on` is specified to provide the order of the execution.
+     * The event with the lowest order will be executed first.
+     */
+    listenerOrder?: number;
+    /** Optional metadata used for docs, filtering and tooling. */
+    meta?: ITaskMeta;
+    /**
+     * The task body. If `on` is set, the input is an `IEventEmission`. Otherwise,
+     * it's the declared input type.
+     */
+    run: (input: TOn extends undefined ? TInput : IEventEmission<TOn extends "*" ? any : ExtractEventParams<TOn>>, dependencies: DependencyValuesType<TDependencies>) => TOutput;
+}
+/**
+ * This is the response after the definition has been prepared. TODO: better naming?
+ */
+export interface ITask<TInput = any, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TOn extends "*" | IEventDefinition<any> | undefined = undefined> extends ITaskDefinition<TInput, TOutput, TDependencies, TOn> {
+    id: string | symbol;
+    dependencies: TDependencies | (() => TDependencies);
+    computedDependencies?: DependencyValuesType<TDependencies>;
+    middleware: MiddlewareAttachments[];
+    /**
+     * These events are automatically populated after the task has been defined.
+     */
+    events: {
+        beforeRun: IEvent<BeforeRunEventPayload<TInput>>;
+        afterRun: IEvent<AfterRunEventPayload<TInput, TOutput>>;
+        onError: IEvent<OnErrorEventPayload>;
+    };
+}
+export {};

package/dist/types/task.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=task.js.map

package/dist/types/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/types/task.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluelibs/runner",
-  "version": "3.2.0",
+  "version": "3.3.1",
   "description": "BlueLibs Runner",
   "main": "dist/index.js",
   "repository": {
@@ -26,10 +26,10 @@
     "@types/graphql": "^0.11.3",
     "@types/jest": "^27.0.0",
     "@types/node": "^20.0.0",
-    "@typescript-eslint/eslint-plugin": "2.3.0",
-    "@typescript-eslint/parser": "2.3.0",
+    "@typescript-eslint/eslint-plugin": "8.39.0",
+    "@typescript-eslint/parser": "8.39.0",
     "benchmark": "^2.1.4",
-    "eslint": "^6.6.0",
+    "eslint": "^9.32.0",
     "eslint-config-prettier": "6.3.0",
     "eslint-plugin-prettier": "3.1.1",
     "express": "^5.1.0",

package/src/__tests__/benchmark/task-benchmark.test.ts

@@ -0,0 +1,132 @@
+import { defineTask, defineResource, defineMiddleware } from "../../define";
+import { run } from "../../run";
+
+// Benchmarks are environment-sensitive; keep skipped by default.
+describe("Task benchmarks - sync vs async", () => {
+  const iterations = 500;
+
+  it("compares sync vs async task execution without middleware", async () => {
+    const syncTask = defineTask<number, any>({
+      id: "bench.syncTask",
+      // Intentionally synchronous
+      run: ((n: number) => {
+        let acc = 0;
+        for (let i = 0; i < 200; i++) acc += (n + i) % 7;
+        return acc;
+      }) as any,
+    } as any);
+
+    const asyncTask = defineTask<number, Promise<number>>({
+      id: "bench.asyncTask",
+      run: async (n: number) => {
+        let acc = 0;
+        for (let i = 0; i < 200; i++) acc += (n + i) % 7;
+        return acc;
+      },
+    });
+
+    const app = defineResource({
+      id: "bench.app",
+      register: [syncTask, asyncTask],
+      dependencies: { syncTask, asyncTask },
+      async init(_, { syncTask, asyncTask }) {
+        // Warm-up
+        await asyncTask(0);
+        await syncTask(0 as any);
+
+        const syncStart = performance.now();
+        for (let i = 0; i < iterations; i++) {
+          // Note: sync path still awaited at the TaskRunner boundary
+          await syncTask(i as any);
+        }
+        const syncTime = performance.now() - syncStart;
+
+        const asyncStart = performance.now();
+        for (let i = 0; i < iterations; i++) {
+          await asyncTask(i);
+        }
+        const asyncTime = performance.now() - asyncStart;
+
+        // Log metrics for manual inspection
+        // eslint-disable-next-line no-console
+        console.log(
+          `Task benchmark (iterations=${iterations}) -> sync: ${syncTime.toFixed(
+            2
+          )}ms, async: ${asyncTime.toFixed(2)}ms`
+        );
+      },
+    });
+
+    const { dispose } = await run(app);
+    await dispose();
+  });
+
+  it("compares with a chain of pass-through middlewares", async () => {
+    const chainLength = 10;
+
+    const middlewares = Array.from({ length: chainLength }, (_, idx) =>
+      defineMiddleware({
+        id: `mw.${idx}`,
+        // Return the result of next() directly; no extra async wrapper here
+        run: ({ next }: any) => next(),
+      })
+    );
+
+    const syncTask = defineTask<number, any>({
+      id: "bench.syncTask.withMw",
+      middleware: middlewares,
+      // Intentionally synchronous
+      run: ((n: number) => {
+        let acc = 0;
+        for (let i = 0; i < 200; i++) acc += (n + i) % 7;
+        return acc;
+      }) as any,
+    } as any);
+
+    const asyncTask = defineTask<number, Promise<number>>({
+      id: "bench.asyncTask.withMw",
+      middleware: middlewares,
+      run: async (n: number) => {
+        let acc = 0;
+        for (let i = 0; i < 200; i++) acc += (n + i) % 7;
+        return acc;
+      },
+    });
+
+    const app = defineResource({
+      id: "bench.app.mw",
+      register: [...middlewares, syncTask, asyncTask],
+      dependencies: { syncTask, asyncTask },
+      async init(_, { syncTask, asyncTask }) {
+        // Warm-up
+        await asyncTask(0);
+        await syncTask(0 as any);
+
+        const iters = 5000;
+        const t0 = process.hrtime.bigint();
+        for (let i = 0; i < iters; i++) {
+          await syncTask(i as any);
+        }
+        const t1 = process.hrtime.bigint();
+        const syncNs = Number(t1 - t0);
+
+        const t2 = process.hrtime.bigint();
+        for (let i = 0; i < iters; i++) {
+          await asyncTask(i);
+        }
+        const t3 = process.hrtime.bigint();
+        const asyncNs = Number(t3 - t2);
+
+        // eslint-disable-next-line no-console
+        console.log(
+          `Task benchmark with ${chainLength} middlewares (iterations=${iters}) -> sync: ${(
+            syncNs / 1e6
+          ).toFixed(2)}ms, async: ${(asyncNs / 1e6).toFixed(2)}ms`
+        );
+      },
+    });
+
+    const { dispose } = await run(app);
+    await dispose();
+  });
+});

package/src/__tests__/createTestResource.test.ts

@@ -0,0 +1,139 @@
+import {
+  task,
+  resource,
+  override,
+  run,
+  createTestResource,
+  globals,
+  event,
+} from "..";
+
+describe("createTestResource", () => {
+  it("runs tasks within the full ecosystem and returns results", async () => {
+    const double = task({ id: "t.double", run: async (x: number) => x * 2 });
+
+    const app = resource({
+      id: "app.root",
+      register: [double],
+    });
+
+    const harness = createTestResource(app);
+    const { value: t, dispose } = await run(harness);
+
+    const result = await t.runTask(double, 21);
+    expect(result).toBe(42);
+
+    await dispose();
+  });
+
+  it("supports overrides for integration tests", async () => {
+    const db = resource({ id: "db", init: async () => ({ kind: "real" }) });
+    const getDbKind = task({
+      id: "t.db.kind",
+      dependencies: { db },
+      run: async (_, { db }) => db.kind,
+    });
+    const app = resource({ id: "app", register: [db, getDbKind] });
+
+    const mockDb = override(db, { init: async () => ({ kind: "mock" }) });
+
+    const harness = createTestResource(app, { overrides: [mockDb] });
+    const { value: t, dispose } = await run(harness);
+
+    const kind = await t.runTask(getDbKind, undefined);
+    expect(kind).toBe("mock");
+
+    await dispose();
+  });
+
+  it("allows accessing resource values and subscribing to events", async () => {
+    const eventsSeen: Array<any> = [];
+
+    const say = task({ id: "t.say", run: async (m: string) => m });
+
+    const listener = task({
+      id: "tests.log-listener",
+      on: globals.events.tasks.beforeRun,
+      run: async (e: any) => eventsSeen.push(e.data),
+    });
+
+    const app = resource({ id: "app2", register: [say, listener] });
+
+    const harness = createTestResource(app);
+    const { value: t, dispose } = await run(harness);
+
+    // Subscribe via facade as well (no-op if using global path instead)
+    // t.on(globals.events.log, (e) => eventsSeen.push(e.data));
+
+    await t.runTask(say, "hello");
+
+    // We can also query resource values (will often be undefined for pure tasks)
+    expect(t.getResource("app2")).toBeUndefined();
+
+    // At least one event was recorded via the listener
+    expect(Array.isArray(eventsSeen)).toBe(true);
+
+    await dispose();
+  });
+
+  it("supports multiple harness instances without id collisions", async () => {
+    const add1 = task({ id: "t.add1", run: async (n: number) => n + 1 });
+    const app = resource({ id: "app.multi", register: [add1] });
+
+    const h1 = createTestResource(app);
+    const h2 = createTestResource(app);
+
+    const [r1, r2] = await Promise.all([run(h1), run(h2)]);
+
+    const v1 = await r1.value.runTask(add1, 1);
+    const v2 = await r2.value.runTask(add1, 2);
+    expect(v1).toBe(2);
+    expect(v2).toBe(3);
+
+    await Promise.all([r1.dispose(), r2.dispose()]);
+  });
+
+  it("runTask is typesafe in tests", async () => {
+    const sum = task<{ a: number; b: number }, Promise<number>>({
+      id: "t.sum",
+      run: async (i) => i.a + i.b,
+    });
+
+    const upper = task<{ v: string }, Promise<string>>({
+      id: "t.upper",
+      run: async (i) => i.v.toUpperCase(),
+    });
+
+    const usesUpper = task<
+      { n: number },
+      Promise<number>,
+      { upper: typeof upper }
+    >({
+      id: "t.usesUpper",
+      dependencies: { upper },
+      run: async (i, d) => Number(await d.upper({ v: String(i.n) })),
+    });
+
+    const app = resource({
+      id: "app.types",
+      register: [sum, upper, usesUpper],
+    });
+    const { value: t, dispose } = await run(createTestResource(app));
+
+    const ok1: number | undefined = await t.runTask(sum, { a: 1, b: 2 });
+    // Type-only checks (do not execute)
+    const typeOnly = () => {
+      // @ts-expect-error bad input
+      t.runTask(sum, { a: 1 });
+      // @ts-expect-error missing input
+      t.runTask(sum as any);
+    };
+    void typeOnly;
+
+    const ok2: number | undefined = await t.runTask(usesUpper, {
+      n: 3,
+    } as const);
+
+    await dispose();
+  });
+});

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

@@ -0,0 +1,88 @@
+import { defineResource, defineTask } from "../../define";
+import { run } from "../../run";
+import { timeoutMiddleware } from "../../globals/middleware/timeout.middleware";
+
+const sleep = (ms: number) => new Promise((res) => setTimeout(res, ms));
+
+describe("Timeout Middleware", () => {
+  it("should abort long-running tasks after ttl", async () => {
+    const slowTask = defineTask({
+      id: "timeout.slowTask",
+      middleware: [timeoutMiddleware.with({ ttl: 20 })],
+      run: async () => {
+        await sleep(50);
+        return "done";
+      },
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [slowTask],
+      dependencies: { slowTask },
+      async init(_, { slowTask }) {
+        await expect(slowTask()).rejects.toThrow(/timed out/i);
+      },
+    });
+
+    await run(app);
+  });
+
+  it("should allow tasks to complete before ttl", async () => {
+    const fastTask = defineTask({
+      id: "timeout.fastTask",
+      middleware: [timeoutMiddleware.with({ ttl: 50 })],
+      run: async () => {
+        await sleep(10);
+        return "ok";
+      },
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [fastTask],
+      dependencies: { fastTask },
+      async init(_, { fastTask }) {
+        await expect(fastTask()).resolves.toBe("ok");
+      },
+    });
+
+    await run(app);
+  });
+
+  it("should timeout resource initialization", async () => {
+    const slowResource = defineResource({
+      id: "timeout.slowResource",
+      middleware: [timeoutMiddleware.with({ ttl: 20 })],
+      async init() {
+        await sleep(50);
+        return "ready";
+      },
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [slowResource],
+    });
+
+    await expect(run(app)).rejects.toThrow(/timed out/i);
+  });
+
+  it("should throw immediately when ttl is 0", async () => {
+    const task = defineTask({
+      id: "timeout.immediate",
+      middleware: [timeoutMiddleware.with({ ttl: 0 })],
+      run: async () => "never",
+    });
+
+    const app = defineResource({
+      id: "app",
+      register: [task],
+      dependencies: { task },
+      async init(_, { task }) {
+        await expect(task()).rejects.toThrow(/timed out/i);
+      },
+    });
+
+    await run(app);
+  });
+});

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

@@ -1,4 +1,9 @@
-import { IEvent, IEventEmission, symbolEvent } from "../../defs";
+import {
+  IEvent,
+  IEventEmission,
+  symbolEvent,
+  symbolFilePath,
+} from "../../defs";
 import { Errors } from "../../errors";
 import { EventManager } from "../../models/EventManager";
 
@@ -8,7 +13,11 @@ describe("EventManager", () => {
 
   beforeEach(() => {
     eventManager = new EventManager();
-    eventDefinition = { id: "testEvent", [symbolEvent]: true };
+    eventDefinition = {
+      id: "testEvent",
+      [symbolEvent]: true,
+      [symbolFilePath]: "test.ts",
+    };
   });
 
   it("should add and emit event listener", async () => {
@@ -165,10 +174,12 @@ describe("EventManager", () => {
     const eventDef1: IEvent<string> = {
       id: "event1",
       [symbolEvent]: true,
+      [symbolFilePath]: "test.ts",
     };
     const eventDef2: IEvent<string> = {
       id: "event2",
       [symbolEvent]: true,
+      [symbolFilePath]: "test.ts",
     };
 
     const handler1 = jest.fn();
@@ -215,10 +226,12 @@ describe("EventManager", () => {
     const eventDef1: IEvent<string> = {
       id: "event1",
       [symbolEvent]: true,
+      [symbolFilePath]: "test.ts",
     };
     const eventDef2: IEvent<string> = {
       id: "event2",
       [symbolEvent]: true,
+      [symbolFilePath]: "test.ts",
     };
 
     const handler = jest.fn();
@@ -249,10 +262,12 @@ describe("EventManager", () => {
     const eventDef1: IEvent<string> = {
       id: "event1",
       [symbolEvent]: true,
+      [symbolFilePath]: "test.ts",
     };
     const eventDef2: IEvent<string> = {
       id: "event2",
       [symbolEvent]: true,
+      [symbolFilePath]: "test.ts",
     };
 
     const handler1 = jest.fn();
@@ -392,6 +407,7 @@ describe("EventManager", () => {
     const voidEventDefinition: IEvent<void> = {
       id: "voidEvent",
       [symbolEvent]: true,
+      [symbolFilePath]: "test.ts",
     };
 
     eventManager.addListener(voidEventDefinition, handler);
@@ -445,8 +461,16 @@ describe("EventManager", () => {
     });
 
     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 event1: IEvent<string> = {
+        id: "event1",
+        [symbolEvent]: true,
+        [symbolFilePath]: "test.ts",
+      };
+      const event2: IEvent<string> = {
+        id: "event2",
+        [symbolEvent]: true,
+        [symbolFilePath]: "test.ts",
+      };
 
       const handler1 = jest.fn();
       const handler2 = jest.fn();
@@ -473,6 +497,7 @@ describe("EventManager", () => {
       const emptyEventDef: IEvent<string> = {
         id: "emptyEvent",
         [symbolEvent]: true,
+        [symbolFilePath]: "test.ts",
       };
 
       // Should return immediately without creating event object
@@ -528,8 +553,16 @@ describe("EventManager", () => {
     });
 
     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 event1: IEvent<string> = {
+        id: "event1",
+        [symbolEvent]: true,
+        [symbolFilePath]: "test.ts",
+      };
+      const event2: IEvent<string> = {
+        id: "event2",
+        [symbolEvent]: true,
+        [symbolFilePath]: "test.ts",
+      };
 
       const handler1 = jest.fn();
       const handler2 = jest.fn();

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

@@ -178,7 +178,7 @@ describe("Semaphore", () => {
 
       const elapsed = Date.now() - startTime;
       expect(elapsed).toBeGreaterThanOrEqual(100);
-      expect(elapsed).toBeLessThan(200); // Should not wait much longer
+      expect(elapsed).toBeLessThan(300); // Should not wait much longer
     });
 
     it("should timeout withPermit operation", async () => {

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);
+  });
+});