@bluelibs/runner 3.4.1 → 3.4.3

package/src/__tests__/tools/getCallerFile.test.ts

@@ -57,7 +57,7 @@ describe("generateCallerIdFromFile", () => {
   it("should generate a symbol from a path containing src", () => {
     const filePath =
       "/Users/theodordiaconu/Projects/runner/src/globals/resources/queue.resource.ts";
-    const expectedDescription = "globals.resources.queue.resource";
+    const expectedDescription = "src.globals.resources.queue.resource";
     expect(generateCallerIdFromFile(filePath).description).toEqual(
       expectedDescription
     );
@@ -83,7 +83,7 @@ describe("generateCallerIdFromFile", () => {
   it("should handle paths with backslashes", () => {
     const filePath =
       "C:\\Users\\theodordiaconu\\Projects\\runner\\src\\globals\\resources\\queue.resource.ts";
-    const expectedDescription = "globals.resources.queue.resource";
+    const expectedDescription = "src.globals.resources.queue.resource";
     expect(generateCallerIdFromFile(filePath).description).toEqual(
       expectedDescription
     );
@@ -92,7 +92,7 @@ describe("generateCallerIdFromFile", () => {
   it("should handle file names without extensions", () => {
     const filePath =
       "/Users/theodordiaconu/Projects/runner/src/globals/resources/queue.resource";
-    const expectedDescription = "globals.resources.queue.resource";
+    const expectedDescription = "src.globals.resources.queue.resource";
     expect(generateCallerIdFromFile(filePath).description).toEqual(
       expectedDescription
     );
@@ -101,7 +101,7 @@ describe("generateCallerIdFromFile", () => {
   it("should handle file names with multiple dots", () => {
     const filePath =
       "/Users/theodordiaconu/Projects/runner/src/globals/resources/queue.resource.test.ts";
-    const expectedDescription = "globals.resources.queue.resource.test";
+    const expectedDescription = "src.globals.resources.queue.resource.test";
     expect(generateCallerIdFromFile(filePath).description).toEqual(
       expectedDescription
     );
@@ -150,7 +150,7 @@ describe("generateCallerIdFromFile", () => {
 
     // Test case where 'src' is at the end, making relevantParts empty (triggers line 77 else branch)
     const result = generateCallerIdFromFile("/some/path/src", "suffix");
-    expect(result.description).toEqual(".suffix");
+    expect(result.description).toEqual(".some.path.src.suffix");
   });
 
   it("should use fallback parts when no src or node_modules found", () => {
@@ -161,4 +161,19 @@ describe("generateCallerIdFromFile", () => {
       expectedDescription
     );
   });
+
+  it("should handle path equal to process.cwd() (relative root)", () => {
+    const expectedDescription = ".suffix";
+    expect(
+      generateCallerIdFromFile(process.cwd(), "suffix").description
+    ).toEqual(expectedDescription);
+  });
+
+  it("should handle path ending with node_modules (no relevant parts)", () => {
+    const path = `${process.cwd()}/node_modules`;
+    const expectedDescription = ".suffix";
+    expect(generateCallerIdFromFile(path, "suffix").description).toEqual(
+      expectedDescription
+    );
+  });
 });

package/src/define.ts

@@ -41,6 +41,23 @@ import { generateCallerIdFromFile, getCallerFile } from "./tools/getCallerFile";
 
 // Helper function to get the caller file
 
+/**
+ * Define a task.
+ * Generates a strongly-typed task object with id, lifecycle events, dependencies,
+ * middleware, and metadata.
+ *
+ * - If `id` is omitted, an anonymous, file-based id is generated.
+ * - Wires lifecycle events: `beforeRun`, `afterRun`, `onError`.
+ * - Carries through dependencies, middleware, input schema, and metadata.
+ *
+ * @typeParam Input - Input type accepted by the task's `run` function.
+ * @typeParam Output - Promise type returned by the `run` function.
+ * @typeParam Deps - Dependency map type this task requires.
+ * @typeParam TOn - Event type or "*" this task listens to.
+ * @typeParam TMeta - Arbitrary metadata type carried by the task.
+ * @param taskConfig - The task definition config.
+ * @returns A branded task definition usable by the runner.
+ */
 export function defineTask<
   Input = undefined,
   Output extends Promise<any> = any,
@@ -50,12 +67,6 @@ export function defineTask<
 >(
   taskConfig: ITaskDefinition<Input, Output, Deps, TOn, TMeta>
 ): ITask<Input, Output, Deps, TOn, TMeta> {
-  /**
-   * 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");
@@ -118,10 +129,21 @@ export function defineResource<
   >
 ): IResource<TConfig, TValue, TDeps, TPrivate, TMeta> {
   /**
-   * 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
+   * Define a resource.
+   * Produces a strongly-typed resource with id, lifecycle events, registration hooks,
+   * and optional config schema.
+   *
+   * - If `id` is omitted, an anonymous, file-based id is generated (resource or index flavored).
+   * - Wires lifecycle events: `beforeInit`, `afterInit`, `onError`.
+   * - Provides `.with(config)` for config-bound registration with optional runtime validation.
+   *
+   * @typeParam TConfig - Configuration type accepted by the resource.
+   * @typeParam TValue - Promise type resolved by the resource `init`.
+   * @typeParam TDeps - Dependency map type this resource requires.
+   * @typeParam TPrivate - Private context type exposed to middleware during init.
+   * @typeParam TMeta - Arbitrary metadata type carried by the resource.
+   * @param constConfig - The resource definition config.
+   * @returns A branded resource definition usable by the runner.
    */
   // The symbolFilePath might already come from defineIndex() for example
   const filePath: string = constConfig[symbolFilePath] || getCallerFile();
@@ -149,10 +171,14 @@ export function defineResource<
         try {
           config = this.configSchema.parse(config);
         } catch (error) {
-          throw new ValidationError("Resource config", this.id, error instanceof Error ? error : new Error(String(error)));
+          throw new ValidationError(
+            "Resource config",
+            this.id,
+            error instanceof Error ? error : new Error(String(error))
+          );
         }
       }
-      
+
       return {
         [symbolResourceWithConfig]: true,
         id: this.id,
@@ -237,8 +263,13 @@ 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.
+   * Define an event.
+   * Generates a branded event definition with a stable id (anonymous if omitted)
+   * and file path metadata for better debugging.
+   *
+   * @typeParam TPayload - Payload type carried by the event.
+   * @param config - Optional event definition (id, etc.).
+   * @returns A branded event definition.
    */
   const callerFilePath = getCallerFile();
   const eventConfig = config || {};
@@ -261,20 +292,27 @@ export type MiddlewareEverywhereOptions = {
   resources?: boolean;
 };
 
+/**
+ * Define a middleware.
+ * Creates a middleware definition with anonymous id generation, `.with(config)`,
+ * and `.everywhere()` helpers.
+ *
+ * - `.with(config)` merges config (optionally validated via `configSchema`).
+ * - `.everywhere()` marks the middleware global (optionally scoping to tasks/resources).
+ *
+ * @typeParam TConfig - Configuration type accepted by the middleware.
+ * @typeParam TDependencies - Dependency map type required by the middleware.
+ * @param middlewareDef - The middleware definition config.
+ * @returns A branded middleware definition usable by the runner.
+ */
 export function defineMiddleware<
-  TConfig extends Record<string, any>,
-  TDependencies extends DependencyMapType
+  TConfig extends Record<string, any> = any,
+  TDependencies extends DependencyMapType = any
 >(
   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 = {
+  const base = {
     [symbolFilePath]: filePath,
     [symbolMiddleware]: true,
     config: {} as TConfig,
@@ -283,67 +321,112 @@ export function defineMiddleware<
     dependencies: middlewareDef.dependencies || ({} as TDependencies),
   } as IMiddleware<TConfig, TDependencies>;
 
-  return {
-    ...object,
-    with: (config: TConfig) => {
-      // Validate config with schema if provided (fail fast)
-      if (object.configSchema) {
-        try {
-          config = object.configSchema.parse(config);
-        } catch (error) {
-          throw new ValidationError("Middleware config", object.id, error instanceof Error ? error : new Error(String(error)));
+  // Wrap an object to ensure we always return chainable helpers
+  const wrap = (
+    obj: IMiddleware<TConfig, TDependencies>
+  ): IMiddleware<TConfig, TDependencies> => {
+    return {
+      ...obj,
+      with: (config: TConfig) => {
+        // Validate config with schema if provided (fail fast)
+        if (obj.configSchema) {
+          try {
+            config = obj.configSchema.parse(config);
+          } catch (error) {
+            throw new ValidationError(
+              "Middleware config",
+              obj.id,
+              error instanceof Error ? error : new Error(String(error))
+            );
+          }
         }
-      }
-      
-      return {
-        ...object,
-        [symbolMiddlewareConfigured]: true,
-        config: {
-          ...object.config,
-          ...config,
-        },
-      };
-    },
-    everywhere(options: MiddlewareEverywhereOptions = {}) {
-      const { tasks = true, resources = true } = options;
 
-      return {
-        ...object,
-        [symbolMiddlewareEverywhereTasks]: tasks,
-        [symbolMiddlewareEverywhereResources]: resources,
-        everywhere() {
-          throw new MiddlewareAlreadyGlobalError(object.id);
-        },
-      };
-    },
+        return wrap({
+          ...obj,
+          [symbolMiddlewareConfigured]: true,
+          config: {
+            ...(obj.config as TConfig),
+            ...config,
+          },
+        } as IMiddleware<TConfig, TDependencies>);
+      },
+      everywhere(options: MiddlewareEverywhereOptions = {}) {
+        const { tasks = true, resources = true } = options;
+
+        // If already global, prevent calling again
+        if (
+          obj[symbolMiddlewareEverywhereTasks] ||
+          obj[symbolMiddlewareEverywhereResources]
+        ) {
+          throw new MiddlewareAlreadyGlobalError(obj.id);
+        }
+
+        return wrap({
+          ...obj,
+          [symbolMiddlewareEverywhereTasks]: tasks,
+          [symbolMiddlewareEverywhereResources]: resources,
+        } as IMiddleware<TConfig, TDependencies>);
+      },
+    } as IMiddleware<TConfig, TDependencies>;
   };
+
+  return wrap(base);
 }
 
+/**
+ * Type guard: checks if a definition is a Task.
+ * @param definition - Any value to test.
+ * @returns True when `definition` is a branded Task.
+ */
 export function isTask(definition: any): definition is ITask {
   return definition && definition[symbolTask];
 }
 
+/**
+ * Type guard: checks if a definition is a Resource.
+ * @param definition - Any value to test.
+ * @returns True when `definition` is a branded Resource.
+ */
 export function isResource(definition: any): definition is IResource {
   return definition && definition[symbolResource];
 }
 
+/**
+ * Type guard: checks if a definition is a Resource that carries config via `.with()`.
+ * @param definition - Any value to test.
+ * @returns True when `definition` is a branded ResourceWithConfig.
+ */
 export function isResourceWithConfig(
   definition: any
 ): definition is IResourceWithConfig {
   return definition && definition[symbolResourceWithConfig];
 }
 
+/**
+ * Type guard: checks if a definition is an Event.
+ * @param definition - Any value to test.
+ * @returns True when `definition` is a branded Event.
+ */
 export function isEvent(definition: any): definition is IEvent {
   return definition && definition[symbolEvent];
 }
 
+/**
+ * Type guard: checks if a definition is a Middleware.
+ * @param definition - Any value to test.
+ * @returns True when `definition` is a branded Middleware.
+ */
 export function isMiddleware(definition: any): definition is IMiddleware {
   return definition && definition[symbolMiddleware];
 }
 
 /**
  * Override helper that preserves the original `id` and returns the same type.
- * You can override any property except `id`.
+ * You can override any property except `id`. The override is shallow-merged over the base.
+ *
+ * @param base - The base definition to override.
+ * @param patch - Properties to override (except `id`).
+ * @returns A definition of the same kind with overrides applied.
  */
 export function defineOverride<T extends ITask<any, any, any, any>>(
   base: T,
@@ -371,9 +454,14 @@ export function defineOverride(
 }
 
 /**
- * Creates a tag definition.
+ * Create a tag definition.
  * - `.with(config)` to create configured instances
- * - `.extract(tags)` to extract this tag from a list of tags
+ * - `.extract(tags)` to extract this tag from a list of tags or a taggable's meta
+ *
+ * @typeParam TConfig - Configuration type carried by configured tags.
+ * @typeParam TEnforceContract - Optional helper type to enforce a contract when tags are used.
+ * @param definition - The tag definition (id).
+ * @returns A tag object with helpers to configure and extract.
  */
 export function defineTag<TConfig = void, TEnforceContract = void>(
   definition: ITagDefinition<TConfig, TEnforceContract>

package/src/tools/getCallerFile.ts

@@ -44,18 +44,29 @@ export function generateCallerIdFromFile(
   suffix: string = "",
   fallbackParts: number = 4
 ): symbol {
-  filePath = filePath.replace(/\\/g, "/"); // Normalize path for consistency.
-  const parts = filePath.split("/");
-  const srcIndex = parts.lastIndexOf("src");
-  const nodeModulesIndex = parts.lastIndexOf("node_modules");
+  // Normalize paths for consistency across platforms
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const cwdNormalized = process.cwd().replace(/\\/g, "/");
 
-  const breakIndex = Math.max(srcIndex, nodeModulesIndex);
+  const parts = normalizedPath.split("/");
+  const nodeModulesIndex = parts.lastIndexOf("node_modules");
 
   let relevantParts: string[];
 
-  if (breakIndex !== -1) {
-    relevantParts = parts.slice(breakIndex + 1);
+  if (nodeModulesIndex !== -1) {
+    // If inside node_modules, generate id relative to the package path
+    relevantParts = parts.slice(nodeModulesIndex + 1);
+  } else if (
+    normalizedPath === cwdNormalized ||
+    normalizedPath.startsWith(cwdNormalized + "/")
+  ) {
+    // Prefer generating id relative to the workspace root (process.cwd())
+    const relativeToCwd = normalizedPath
+      .slice(cwdNormalized.length)
+      .replace(/^\//, "");
+    relevantParts = relativeToCwd.length > 0 ? relativeToCwd.split("/") : [""];
   } else {
+    // Fallback: use the last N parts if path is outside cwd and not in node_modules
     relevantParts = parts.slice(-fallbackParts);
   }