@bluelibs/runner 3.2.0 → 3.3.1

package/src/__tests__/typesafety.test.ts

@@ -3,6 +3,8 @@ import {
   defineTask,
   defineResource,
   defineMiddleware,
+  defineOverride,
+  defineTag,
 } from "../define";
 import {
   IEventDefinition,
@@ -12,8 +14,10 @@ import {
   ITaskDefinition,
   RegisterableItems,
 } from "../defs";
+import { createTestResource } from "..";
 
-describe("typesafety", () => {
+// This is skipped because we mostly check typesafety.
+describe.skip("typesafety", () => {
   it("tasks, resources: should have propper type safety for dependeices", async () => {
     type InputTask = {
       message: string;
@@ -209,4 +213,108 @@ describe("typesafety", () => {
 
     expect(true).toBe(true);
   });
+
+  it("createTestResource.runTask: should be type-safe", async () => {
+    type Input = { x: number };
+    type Output = Promise<number>;
+
+    const add = defineTask<Input, Output>({
+      id: "types.add",
+      run: async (i) => i.x + 1,
+    });
+
+    const depTask = defineTask<{ v: string }, Promise<string>>({
+      id: "types.dep",
+      run: async (i) => i.v.toUpperCase(),
+    });
+
+    const main = defineTask<Input, Output, { depTask: typeof depTask }>({
+      id: "types.main",
+      dependencies: { depTask },
+      run: async (i, d) => {
+        const v = await d.depTask({ v: String(i.x) });
+        return Number(v) + 1;
+      },
+    });
+
+    const app = defineResource({
+      id: "types.app",
+      register: [add, depTask, main],
+    });
+    const harness = createTestResource(app);
+
+    // Types: input must match, override deps must match, output is awaited number
+    const { value: t } = await (await import("../run")).run(harness);
+    const r1: number | undefined = await t.runTask(add, { x: 1 });
+    // @ts-expect-error wrong input type
+    await t.runTask(add, { z: 1 });
+    // @ts-expect-error missing input
+    await t.runTask(add);
+
+    const r2: number | undefined = await t.runTask(main, { x: 2 });
+
+    // @ts-expect-error wrong deps override type
+    await t.runTask(main, { x: 2 }, { depTask: async (i: number) => "x" });
+
+    expect(true).toBe(true);
+  });
+
+  it("should have propper type safety for overrides", async () => {
+    const task = defineTask({
+      id: "task",
+      run: async () => "Task executed",
+    });
+
+    // @ts-expect-error
+    const overrideTask = defineOverride(task, {
+      run: async () => 234,
+    });
+
+    const resource = defineResource({
+      id: "resource",
+      register: [task],
+      init: async () => "Resource executed",
+    });
+
+    const overrideResource = defineOverride(resource, {
+      init: async () => "Resource overridden",
+    });
+    // @ts-expect-error
+    defineOverride(resource, {
+      init: async () => 123, // bad type
+    });
+
+    const middleware = defineMiddleware({
+      id: "middleware",
+      run: async () => "Middleware executed",
+    });
+
+    expect(true).toBe(true);
+  });
+
+  it("should have propper type safety for tags", async () => {
+    const tag = defineTag({ id: "tag" });
+    const tag2 = defineTag<{ value: number }>({ id: "tag2" });
+    const tag2optional = defineTag<{ value?: number }>({ id: "tag2" });
+
+    const tag3 = tag2.with({ value: 123 });
+    // @ts-expect-error
+    const tag4 = tag.with({ value: 123 });
+
+    const task = defineTask({
+      id: "task",
+      meta: {
+        tags: [
+          tag,
+          // @ts-expect-error
+          tag2,
+          tag2optional,
+          tag2.with({ value: 123 }),
+          tag3,
+        ],
+      },
+    });
+
+    expect(true).toBe(true);
+  });
 });

package/src/define.ts

@@ -1,3 +1,10 @@
+/**
+ * Factory functions for defining tasks, resources, events and middleware.
+ *
+ * These helpers create strongly-typed definitions while also wiring internal
+ * metadata: anonymous IDs, file path tags (for better debugging), lifecycle
+ * events, and global middleware flags. See README for high-level concepts.
+ */
 import {
   ITask,
   ITaskDefinition,
@@ -6,7 +13,6 @@ import {
   IResourceDefinition,
   IEventDefinition,
   IMiddlewareDefinition,
-  symbols,
   DependencyMapType,
   DependencyValuesType,
   IMiddleware,
@@ -16,6 +22,17 @@ import {
   symbolMiddlewareConfigured,
   symbolFilePath,
   symbolIndexResource,
+  ITag,
+  ITagDefinition,
+  ITagWithConfig,
+  TagType,
+  ITaggable,
+  symbolTask,
+  symbolMiddlewareEverywhereTasks,
+  symbolMiddlewareEverywhereResources,
+  symbolResourceWithConfig,
+  symbolResource,
+  symbolMiddleware,
 } from "./defs";
 import { Errors } from "./errors";
 import { generateCallerIdFromFile, getCallerFile } from "./tools/getCallerFile";
@@ -30,12 +47,18 @@ export function defineTask<
 >(
   taskConfig: ITaskDefinition<Input, Output, Deps, TOn>
 ): ITask<Input, Output, Deps, TOn> {
+  /**
+   * Creates a task definition.
+   * - Generates an anonymous id based on file path when `id` is omitted
+   * - Wires lifecycle events: beforeRun, afterRun, onError
+   * - Carries through dependencies and middleware as declared
+   */
   const filePath = getCallerFile();
   const isAnonymous = !Boolean(taskConfig.id);
   const id = taskConfig.id || generateCallerIdFromFile(filePath, "task");
   return {
-    [symbols.task]: true,
-    [symbols.filePath]: filePath,
+    [symbolTask]: true,
+    [symbolFilePath]: filePath,
     id,
     dependencies: taskConfig.dependencies || ({} as Deps),
     middleware: taskConfig.middleware || [],
@@ -49,7 +72,7 @@ export function defineTask<
             ? Symbol(`anonymous-task.events.beforeRun`)
             : `${id as string}.events.beforeRun`,
         }),
-        [symbols.filePath]: getCallerFile(),
+        [symbolFilePath]: getCallerFile(),
       },
       afterRun: {
         ...defineEvent({
@@ -57,7 +80,7 @@ export function defineTask<
             ? Symbol(`anonymous-task.events.afterRun`)
             : `${id as string}.events.afterRun`,
         }),
-        [symbols.filePath]: getCallerFile(),
+        [symbolFilePath]: getCallerFile(),
       },
       onError: {
         ...defineEvent({
@@ -65,7 +88,7 @@ export function defineTask<
             ? Symbol(`anonymous-task.events.onError`)
             : `${id as string}.events.onError`,
         }),
-        [symbols.filePath]: getCallerFile(),
+        [symbolFilePath]: getCallerFile(),
       },
     },
     meta: taskConfig.meta || {},
@@ -81,6 +104,12 @@ export function defineResource<
 >(
   constConfig: IResourceDefinition<TConfig, TValue, TDeps, TPrivate>
 ): IResource<TConfig, TValue, TDeps, TPrivate> {
+  /**
+   * Creates a resource definition.
+   * - Generates anonymous id when omitted (resource or index flavor)
+   * - Wires lifecycle events: beforeInit, afterInit, onError
+   * - Exposes `.with(config)` for config‑bound registration
+   */
   // The symbolFilePath might already come from defineIndex() for example
   const filePath: string = constConfig[symbolFilePath] || getCallerFile();
   const isIndexResource = constConfig[symbolIndexResource] || false;
@@ -88,9 +117,11 @@ export function defineResource<
   const id =
     constConfig.id ||
     generateCallerIdFromFile(filePath, isIndexResource ? "index" : "resource");
+
   return {
-    [symbols.resource]: true,
-    [symbols.filePath]: filePath,
+    [symbolResource]: true,
+    [symbolFilePath]: filePath,
+    [symbolIndexResource]: isIndexResource,
     id,
     dependencies: constConfig.dependencies,
     dispose: constConfig.dispose,
@@ -100,7 +131,7 @@ export function defineResource<
     context: constConfig.context,
     with: function (config: TConfig) {
       return {
-        [symbols.resourceWithConfig]: true,
+        [symbolResourceWithConfig]: true,
         id: this.id,
         resource: this,
         config,
@@ -114,7 +145,7 @@ export function defineResource<
             ? Symbol(`anonymous-resource.events.beforeInit`)
             : `${id as string}.events.beforeInit`,
         }),
-        [symbols.filePath]: filePath,
+        [symbolFilePath]: filePath,
       },
       afterInit: {
         ...defineEvent({
@@ -122,7 +153,7 @@ export function defineResource<
             ? Symbol(`anonymous-resource.events.afterInit`)
             : `${id as string}.events.afterInit`,
         }),
-        [symbols.filePath]: filePath,
+        [symbolFilePath]: filePath,
       },
       onError: {
         ...defineEvent({
@@ -130,7 +161,7 @@ export function defineResource<
             ? Symbol(`anonymous-resource.events.onError`)
             : `${id as string}.events.onError`,
         }),
-        [symbols.filePath]: filePath,
+        [symbolFilePath]: filePath,
       },
     },
     meta: constConfig.meta || {},
@@ -152,6 +183,7 @@ export function defineIndex<
       : T[K];
   } & DependencyMapType
 >(items: T): IResource<void, DependencyValuesType<D>, D> {
+  // Build dependency map from given items; unwrap `.with()` to the base resource
   const dependencies = {} as D;
   const register: RegisterableItems[] = [];
 
@@ -173,20 +205,24 @@ export function defineIndex<
     async init(_, deps) {
       return deps as any;
     },
-    [symbols.filePath]: callerFilePath,
-    [symbols.indexResource]: true,
+    [symbolFilePath]: callerFilePath,
+    [symbolIndexResource]: true,
   });
 }
 
 export function defineEvent<TPayload = void>(
   config?: IEventDefinition<TPayload>
 ): IEvent<TPayload> {
+  /**
+   * Creates an event definition. Anonymous ids are generated from file path
+   * when omitted. The returned object is branded for runtime checks.
+   */
   const callerFilePath = getCallerFile();
   const eventConfig = config || {};
   return {
     ...eventConfig,
     id: eventConfig.id || generateCallerIdFromFile(callerFilePath, "event"),
-    [symbols.filePath]: callerFilePath,
+    [symbolFilePath]: callerFilePath,
     [symbolEvent]: true, // This is a workaround
   };
 }
@@ -208,10 +244,16 @@ export function defineMiddleware<
 >(
   middlewareDef: IMiddlewareDefinition<TConfig, TDependencies>
 ): IMiddleware<TConfig, TDependencies> {
+  /**
+   * Creates a middleware definition with:
+   * - Anonymous id generation when omitted
+   * - `.with(config)` to create configured instances
+   * - `.everywhere()` to mark as global (optionally scoping to tasks/resources)
+   */
   const filePath = getCallerFile();
   const object = {
-    [symbols.filePath]: filePath,
-    [symbols.middleware]: true,
+    [symbolFilePath]: filePath,
+    [symbolMiddleware]: true,
     config: {} as TConfig,
     id: middlewareDef.id || generateCallerIdFromFile(filePath, "middleware"),
     ...middlewareDef,
@@ -235,8 +277,8 @@ export function defineMiddleware<
 
       return {
         ...object,
-        [symbols.middlewareEverywhereTasks]: tasks,
-        [symbols.middlewareEverywhereResources]: resources,
+        [symbolMiddlewareEverywhereTasks]: tasks,
+        [symbolMiddlewareEverywhereResources]: resources,
         everywhere() {
           throw Errors.middlewareAlreadyGlobal(object.id);
         },
@@ -246,23 +288,85 @@ export function defineMiddleware<
 }
 
 export function isTask(definition: any): definition is ITask {
-  return definition && definition[symbols.task];
+  return definition && definition[symbolTask];
 }
 
 export function isResource(definition: any): definition is IResource {
-  return definition && definition[symbols.resource];
+  return definition && definition[symbolResource];
 }
 
 export function isResourceWithConfig(
   definition: any
 ): definition is IResourceWithConfig {
-  return definition && definition[symbols.resourceWithConfig];
+  return definition && definition[symbolResourceWithConfig];
 }
 
 export function isEvent(definition: any): definition is IEvent {
-  return definition && definition[symbols.event];
+  return definition && definition[symbolEvent];
 }
 
 export function isMiddleware(definition: any): definition is IMiddleware {
-  return definition && definition[symbols.middleware];
+  return definition && definition[symbolMiddleware];
+}
+
+/**
+ * Override helper that preserves the original `id` and returns the same type.
+ * You can override any property except `id`.
+ */
+export function defineOverride<T extends ITask<any, any, any, any>>(
+  base: T,
+  patch: Omit<Partial<T>, "id">
+): T;
+export function defineOverride<T extends IResource<any, any, any, any>>(
+  base: T,
+  patch: Omit<Partial<T>, "id">
+): T;
+export function defineOverride<T extends IMiddleware<any, any>>(
+  base: T,
+  patch: Omit<Partial<T>, "id">
+): T;
+export function defineOverride(
+  base: ITask | IResource | IMiddleware,
+  patch: Record<string | symbol, unknown>
+): ITask | IResource | IMiddleware {
+  const { id: _ignored, ...rest } = (patch || {}) as any;
+  // Ensure we never change the id, and merge overrides last
+  return {
+    ...(base as any),
+    ...rest,
+    id: (base as any).id,
+  } as any;
+}
+
+/**
+ * Creates a tag definition.
+ * - `.with(config)` to create configured instances
+ * - `.extract(tags)` to extract this tag from a list of tags
+ */
+export function defineTag<TConfig = void>(
+  definition: ITagDefinition<TConfig>
+): ITag<TConfig> {
+  const id = definition.id;
+
+  return {
+    id,
+    with(tagConfig: TConfig) {
+      return {
+        id,
+        tag: this,
+        config: tagConfig as any,
+      } as ITagWithConfig<TConfig>;
+    },
+    extract(target: TagType[] | ITaggable) {
+      const tags = Array.isArray(target) ? target : target?.meta?.tags || [];
+      for (const candidate of tags) {
+        if (typeof candidate === "string") continue;
+        // Configured instance
+        if (candidate.id === id) {
+          return candidate as ITagWithConfig<TConfig>;
+        }
+      }
+      return null;
+    },
+  } as ITag<TConfig>;
 }