@bluelibs/runner 2.2.4 → 3.1.0

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

@@ -5,7 +5,10 @@ import {
   defineEvent,
 } from "../../define";
 import { symbols } from "../../defs";
-import { getCallerFile } from "../../tools/getCallerFile";
+import {
+  getCallerFile,
+  generateCallerIdFromFile,
+} from "../../tools/getCallerFile";
 
 describe("getCallerFile", () => {
   it("should return the file name of the caller", () => {
@@ -38,14 +41,126 @@ describe("getCallerFile", () => {
       id: "event",
     });
 
-    expect(task[symbols.filePath]).toBeDefined();
-    expect(resource[symbols.filePath]).toBeDefined();
-    expect(middleware[symbols.filePath]).toBeDefined();
-    expect(event[symbols.filePath]).toBeDefined();
+    expect((task as any)[symbols.filePath]).toBeDefined();
+    expect((resource as any)[symbols.filePath]).toBeDefined();
+    expect((middleware as any)[symbols.filePath]).toBeDefined();
+    expect((event as any)[symbols.filePath]).toBeDefined();
+
+    expect((task as any)[symbols.filePath]).toContain("getCallerFile.test");
+    expect((resource as any)[symbols.filePath]).toContain("getCallerFile.test");
+    expect((middleware as any)[symbols.filePath]).toContain(
+      "getCallerFile.test"
+    );
+    expect((event as any)[symbols.filePath]).toContain("getCallerFile.test");
+  });
+});
+
+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";
+    expect(generateCallerIdFromFile(filePath).description).toEqual(
+      expectedDescription
+    );
+  });
+
+  it("should generate a symbol from a path not containing src", () => {
+    const filePath =
+      "/Users/theodordiaconu/Projects/runner/dist/globals/resources/queue.resource.ts";
+    const expectedDescription = "dist.globals.resources.queue.resource";
+    expect(generateCallerIdFromFile(filePath).description).toEqual(
+      expectedDescription
+    );
+  });
+
+  it("should handle paths with few parts when src is not present", () => {
+    const filePath = "a/b/c.ts";
+    const expectedDescription = "a.b.c";
+    expect(generateCallerIdFromFile(filePath).description).toEqual(
+      expectedDescription
+    );
+  });
+
+  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";
+    expect(generateCallerIdFromFile(filePath).description).toEqual(
+      expectedDescription
+    );
+  });
+
+  it("should handle file names without extensions", () => {
+    const filePath =
+      "/Users/theodordiaconu/Projects/runner/src/globals/resources/queue.resource";
+    const expectedDescription = "globals.resources.queue.resource";
+    expect(generateCallerIdFromFile(filePath).description).toEqual(
+      expectedDescription
+    );
+  });
+
+  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";
+    expect(generateCallerIdFromFile(filePath).description).toEqual(
+      expectedDescription
+    );
+  });
+
+  it("should generate a symbol from a path containing node_modules", () => {
+    const filePath =
+      "/Users/theodordiaconu/Projects/runner/node_modules/some-package/dist/index.js";
+    const expectedDescription = "some-package.dist.index";
+    expect(generateCallerIdFromFile(filePath).description).toEqual(
+      expectedDescription
+    );
+  });
+
+  it("should respect the fallbackParts argument", () => {
+    const filePath = "a/b/c/d/e.ts";
+    const expectedDescription = "d.e";
+    expect(generateCallerIdFromFile(filePath, "", 2).description).toEqual(
+      expectedDescription
+    );
+  });
+
+  it("should append the suffix to the symbol description", () => {
+    const filePath = "a/b/c.ts";
+    const expectedDescription = "a.b.c.my-suffix";
+    expect(generateCallerIdFromFile(filePath, "my-suffix").description).toEqual(
+      expectedDescription
+    );
+  });
+
+  it("should not append the suffix if it is already in the file name", () => {
+    const filePath = "a/b/c.resource.ts";
+    const expectedDescription = "a.b.c.resource";
+    expect(generateCallerIdFromFile(filePath, "resource").description).toEqual(
+      expectedDescription
+    );
+  });
+
+  it("should handle empty path or path with no relevant parts", () => {
+    // Test with empty string - this creates relevantParts = [""] which is not empty
+    const filePath = "";
+    const expectedDescription = ".suffix";
+    expect(generateCallerIdFromFile(filePath, "suffix").description).toEqual(
+      expectedDescription
+    );
+
+    // 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(task[symbols.filePath]).toContain("getCallerFile.test");
-    expect(resource[symbols.filePath]).toContain("getCallerFile.test");
-    expect(middleware[symbols.filePath]).toContain("getCallerFile.test");
-    expect(event[symbols.filePath]).toContain("getCallerFile.test");
+  it("should use fallback parts when no src or node_modules found", () => {
+    // Test path without src or node_modules to trigger the else branch (line 59)
+    const filePath = "/some/other/deep/path/file.js";
+    const expectedDescription = "other.deep.path.file";
+    expect(generateCallerIdFromFile(filePath, "", 4).description).toEqual(
+      expectedDescription
+    );
   });
 });

package/src/__tests__/typesafety.test.ts

@@ -1,5 +1,17 @@
-import { defineEvent, defineTask, defineResource } from "../define";
-import { RegisterableItems } from "../defs";
+import {
+  defineEvent,
+  defineTask,
+  defineResource,
+  defineMiddleware,
+} from "../define";
+import {
+  IEventDefinition,
+  IMiddlewareDefinition,
+  IResource,
+  IResourceWithConfig,
+  ITaskDefinition,
+  RegisterableItems,
+} from "../defs";
 
 describe("typesafety", () => {
   it("tasks, resources: should have propper type safety for dependeices", async () => {
@@ -7,10 +19,43 @@ describe("typesafety", () => {
       message: string;
     };
 
+    const middleware = defineMiddleware({
+      id: "middleware",
+      run: async (input, deps) => {
+        return input;
+      },
+    });
+
+    type MiddlewareConfig = {
+      message: string;
+    };
+
+    type MiddlewareOptionalConfig = {
+      message?: string;
+    };
+
+    const middlewareWithConfig = defineMiddleware({
+      id: "middleware.config",
+      run: async (input, deps, config: MiddlewareConfig) => {
+        return input;
+      },
+    });
+
+    const middlewareWithOptionalConfig = defineMiddleware({
+      id: "middleware.optional.config",
+      run: async (input, deps, config: MiddlewareOptionalConfig) => {
+        return input;
+      },
+    });
+
     const event = defineEvent<{ message: string }>({
       id: "event",
     });
 
+    const eventWithoutArguments = defineEvent({
+      id: "event",
+    });
+
     const baseTask = defineTask({
       id: "task",
       run: async (input: InputTask) => "Task executed",
@@ -58,7 +103,19 @@ describe("typesafety", () => {
 
     const testResource = defineResource({
       id: "test.resource",
-      dependencies: { task, dummyResource, event },
+      middleware: [
+        middleware,
+        // @ts-expect-error
+        middlewareWithConfig,
+        middlewareWithConfig.with({ message: "Hello, World!" }),
+        // @ts-expect-error
+        middlewareWithConfig.with({ message: 123 }),
+        middlewareWithOptionalConfig,
+        middlewareWithOptionalConfig.with({ message: "Hello, World!" }),
+        // @ts-expect-error
+        middlewareWithOptionalConfig.with({ message: 123 }),
+      ],
+      dependencies: { task, dummyResource, event, eventWithoutArguments },
       init: async (_, deps) => {
         const result = await deps.task({
           message: "Hello, World!",
@@ -69,6 +126,10 @@ describe("typesafety", () => {
         deps.event();
         // @ts-expect-error
         deps.event({ messagex: "Hello, World!" });
+        deps.eventWithoutArguments();
+        deps.eventWithoutArguments({});
+        // @ts-expect-error
+        deps.eventWithoutArguments({ something: false });
 
         // @ts-expect-error
         deps.dummyResource as number;
@@ -82,6 +143,13 @@ describe("typesafety", () => {
         deps.task2;
       },
       register: [
+        middleware,
+        middlewareWithConfig,
+        middlewareWithOptionalConfig,
+        middlewareWithOptionalConfig.with({ message: "Hello, World!" }),
+        middlewareWithConfig.with({ message: "Hello, World!" }),
+        // @ts-expect-error
+        middlewareWithConfig.with({ message: 123 }),
         dummyResourceNoConfig,
         // @ts-expect-error
         dummyResourceNoConfig.with("hello"),
@@ -141,42 +209,4 @@ describe("typesafety", () => {
 
     expect(true).toBe(true);
   });
-
-  it("should work with resources that register other resources and don't infer an any to them", async () => {
-    const resourceBase = defineResource({
-      id: "task",
-      init: async (_, deps) => {
-        deps.resource;
-        return "";
-      },
-      dependencies: () => ({
-        resource,
-      }),
-    });
-
-    const resource = defineResource({
-      id: "resource",
-      register: [],
-    });
-
-    resource.register = [resourceBase];
-
-    // @ts-expect-error
-    resource.DOES_NOT_EXIST;
-
-    expect(true).toBe(true);
-  });
-
-  it("should work to unit test with void arguments?", async () => {
-    const resourceBase = defineResource({
-      id: "task",
-      init: async (_, deps) => {
-        return "";
-      },
-    });
-
-    if (resourceBase.init) {
-      resourceBase.init(undefined, {});
-    }
-  });
 });

package/src/context.ts

@@ -0,0 +1,86 @@
+import { AsyncLocalStorage } from "async_hooks";
+import { defineMiddleware } from "./define";
+import { IMiddleware, IMiddlewareConfigured } from "./defs";
+import { requireContextMiddleware } from "./globals/middleware/requireContext.middleware";
+
+/**
+ * Error thrown whenever a requested context is not available.
+ */
+export class ContextError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ContextError";
+  }
+}
+
+/**
+ * The generic Context object returned by `createContext`.
+ */
+export interface Context<T> {
+  /** unique symbol used as key in the AsyncLocalStorage map */
+  readonly id: symbol;
+  /** Retrieve the current context value or throw */
+  use(): T;
+  /**
+   * Provide a value for this context during the lifetime of `fn()`
+   */
+  provide<R>(value: T, fn: () => Promise<R> | R): Promise<R> | R;
+  /**
+   * Generates a middleware that guarantees the context exists (and optionally
+   * enforces that certain keys are present on the context object).
+   */
+  require<K extends keyof T = never>(
+    keys?: K[]
+  ): IMiddlewareConfigured<{ context: Context<T> }>;
+}
+
+// The internal storage maps Context identifiers (symbols) to their values
+export const storage = new AsyncLocalStorage<Map<symbol, unknown>>();
+
+/** Returns the currently active store or undefined. */
+function getCurrentStore(): Map<symbol, unknown> | undefined {
+  return storage.getStore();
+}
+
+/**
+ * Create a new typed Context. The result contains helpers similar to React’s
+ * Context API but adapted for async usage in Runner.
+ */
+export function createContext<T>(name: string = "runner.context"): Context<T> {
+  const ctxId = Symbol(name);
+
+  function use(): T {
+    const store = getCurrentStore();
+    if (!store || !store.has(ctxId)) {
+      throw new ContextError(
+        `Context not available for symbol ${ctxId.toString()}`
+      );
+    }
+    return store.get(ctxId) as T;
+  }
+
+  function provide<R>(value: T, fn: () => Promise<R> | R): Promise<R> | R {
+    const currentStore = getCurrentStore();
+    const map = currentStore
+      ? new Map(currentStore)
+      : new Map<symbol, unknown>();
+    map.set(ctxId, value);
+
+    return storage.run(map, fn as any);
+  }
+
+  /**
+   * Generates a middleware that guarantees the context exists (and optionally
+   * enforces that certain keys are present on the context object).
+   */
+  function require(): IMiddlewareConfigured {
+    return requireContextMiddleware.with({ context: this as Context<T> });
+  }
+
+  return {
+    id: ctxId,
+    use,
+    provide,
+    require,
+  };
+}

package/src/define.ts

@@ -1,4 +1,3 @@
-import { get } from "node:http";
 import {
   ITask,
   ITaskDefinition,
@@ -11,13 +10,15 @@ import {
   DependencyMapType,
   DependencyValuesType,
   IMiddleware,
-  IHookDefinition,
   IEvent,
-  IEventDefinitionConfig,
   symbolEvent,
+  RegisterableItems,
+  symbolMiddlewareConfigured,
+  symbolFilePath,
+  symbolIndexResource,
 } from "./defs";
 import { Errors } from "./errors";
-import { getCallerFile } from "./tools/getCallerFile";
+import { generateCallerIdFromFile, getCallerFile } from "./tools/getCallerFile";
 
 // Helper function to get the caller file
 
@@ -30,30 +31,39 @@ export function defineTask<
   taskConfig: ITaskDefinition<Input, Output, Deps, TOn>
 ): ITask<Input, Output, Deps, TOn> {
   const filePath = getCallerFile();
+  const isAnonymous = !Boolean(taskConfig.id);
+  const id = taskConfig.id || generateCallerIdFromFile(filePath, "task");
   return {
     [symbols.task]: true,
     [symbols.filePath]: filePath,
-    id: taskConfig.id,
+    id,
     dependencies: taskConfig.dependencies || ({} as Deps),
     middleware: taskConfig.middleware || [],
     run: taskConfig.run,
     on: taskConfig.on,
+    listenerOrder: taskConfig.listenerOrder,
     events: {
       beforeRun: {
         ...defineEvent({
-          id: `${taskConfig.id}.events.beforeRun`,
+          id: isAnonymous
+            ? Symbol(`anonymous-task.events.beforeRun`)
+            : `${id as string}.events.beforeRun`,
         }),
         [symbols.filePath]: getCallerFile(),
       },
       afterRun: {
         ...defineEvent({
-          id: `${taskConfig.id}.events.afterRun`,
+          id: isAnonymous
+            ? Symbol(`anonymous-task.events.afterRun`)
+            : `${id as string}.events.afterRun`,
         }),
         [symbols.filePath]: getCallerFile(),
       },
       onError: {
         ...defineEvent({
-          id: `${taskConfig.id}.events.onError`,
+          id: isAnonymous
+            ? Symbol(`anonymous-task.events.onError`)
+            : `${id as string}.events.onError`,
         }),
         [symbols.filePath]: getCallerFile(),
       },
@@ -67,20 +77,27 @@ export function defineResource<
   TConfig = void,
   TValue = any,
   TDeps extends DependencyMapType = {},
-  THooks = any
+  TPrivate = any
 >(
-  constConfig: IResourceDefinition<TConfig, TValue, TDeps, THooks>
-): IResource<TConfig, TValue, TDeps> {
-  const filePath = getCallerFile();
+  constConfig: IResourceDefinition<TConfig, TValue, TDeps, TPrivate>
+): IResource<TConfig, TValue, TDeps, TPrivate> {
+  // The symbolFilePath might already come from defineIndex() for example
+  const filePath: string = constConfig[symbolFilePath] || getCallerFile();
+  const isIndexResource = constConfig[symbolIndexResource] || false;
+  const isAnonymous = !Boolean(constConfig.id);
+  const id =
+    constConfig.id ||
+    generateCallerIdFromFile(filePath, isIndexResource ? "index" : "resource");
   return {
     [symbols.resource]: true,
     [symbols.filePath]: filePath,
-    id: constConfig.id,
+    id,
     dependencies: constConfig.dependencies,
     dispose: constConfig.dispose,
     register: constConfig.register || [],
     overrides: constConfig.overrides || [],
-    init: constConfig.init || (async (...args: any[]) => undefined as TValue),
+    init: constConfig.init,
+    context: constConfig.context,
     with: function (config: TConfig) {
       return {
         [symbols.resourceWithConfig]: true,
@@ -93,19 +110,25 @@ export function defineResource<
     events: {
       beforeInit: {
         ...defineEvent({
-          id: `${constConfig.id}.events.beforeInit`,
+          id: isAnonymous
+            ? Symbol(`anonymous-resource.events.beforeInit`)
+            : `${id as string}.events.beforeInit`,
         }),
         [symbols.filePath]: filePath,
       },
       afterInit: {
         ...defineEvent({
-          id: `${constConfig.id}.events.afterInit`,
+          id: isAnonymous
+            ? Symbol(`anonymous-resource.events.afterInit`)
+            : `${id as string}.events.afterInit`,
         }),
         [symbols.filePath]: filePath,
       },
       onError: {
         ...defineEvent({
-          id: `${constConfig.id}.events.onError`,
+          id: isAnonymous
+            ? Symbol(`anonymous-resource.events.onError`)
+            : `${id as string}.events.onError`,
         }),
         [symbols.filePath]: filePath,
       },
@@ -115,34 +138,106 @@ export function defineResource<
   };
 }
 
-export function defineEvent<TPayload = any>(
-  config: IEventDefinitionConfig<TPayload>
-): IEventDefinition<TPayload> {
+/**
+ * Creates an "index" resource which groups multiple registerable items under
+ * a single dependency. The resulting resource registers every item, depends
+ * on the same items, and returns the resolved dependency map so users can
+ * access them naturally: `deps.services.myTask()` or `deps.services.myResource`.
+ */
+export function defineIndex<
+  T extends Record<string, RegisterableItems>,
+  D extends {
+    [K in keyof T]: T[K] extends IResourceWithConfig<any, any, any>
+      ? T[K]["resource"]
+      : T[K];
+  } & DependencyMapType
+>(items: T): IResource<void, DependencyValuesType<D>, D> {
+  const dependencies = {} as D;
+  const register: RegisterableItems[] = [];
+
+  for (const key of Object.keys(items) as (keyof T)[]) {
+    const item = items[key];
+    register.push(item);
+
+    if (isResourceWithConfig(item)) {
+      (dependencies as any)[key] = item.resource;
+    } else {
+      (dependencies as any)[key] = item as any;
+    }
+  }
+  const callerFilePath = getCallerFile();
+
+  return defineResource({
+    register,
+    dependencies,
+    async init(_, deps) {
+      return deps as any;
+    },
+    [symbols.filePath]: callerFilePath,
+    [symbols.indexResource]: true,
+  });
+}
+
+export function defineEvent<TPayload = void>(
+  config: IEventDefinition<TPayload>
+): IEvent<TPayload> {
+  const callerFilePath = getCallerFile();
   return {
-    [symbols.filePath]: getCallerFile(),
-    [symbolEvent]: true,
     ...config,
+    id: config.id || generateCallerIdFromFile(callerFilePath, "event"),
+    [symbols.filePath]: callerFilePath,
+    [symbolEvent]: true, // This is a workaround
   };
 }
 
-export function defineMiddleware<TDeps extends DependencyMapType = {}>(
-  config: IMiddlewareDefinition<TDeps>
-): IMiddleware<TDeps> {
+export type MiddlewareEverywhereOptions = {
+  /**
+   * Enable this for tasks. Default is true.
+   */
+  tasks?: boolean;
+  /**
+   * Enable this for resources. Default is true.
+   */
+  resources?: boolean;
+};
+
+export function defineMiddleware<
+  TConfig extends Record<string, any>,
+  TDependencies extends DependencyMapType
+>(
+  middlewareDef: IMiddlewareDefinition<TConfig, TDependencies>
+): IMiddleware<TConfig, TDependencies> {
+  const filePath = getCallerFile();
   const object = {
-    [symbols.filePath]: getCallerFile(),
+    [symbols.filePath]: filePath,
     [symbols.middleware]: true,
-    ...config,
-    dependencies: config.dependencies || ({} as TDeps),
-  };
+    config: {} as TConfig,
+    id: middlewareDef.id || generateCallerIdFromFile(filePath, "middleware"),
+    ...middlewareDef,
+    dependencies: middlewareDef.dependencies || ({} as TDependencies),
+  } as IMiddleware<TConfig, TDependencies>;
 
   return {
     ...object,
-    global() {
+    with: (config: TConfig) => {
+      return {
+        ...object,
+        [symbolMiddlewareConfigured]: true,
+        config: {
+          ...object.config,
+          ...config,
+        },
+      };
+    },
+    everywhere(options: MiddlewareEverywhereOptions = {}) {
+      const { tasks = true, resources = true } = options;
+
       return {
         ...object,
-        [symbols.middlewareGlobal]: true,
-        global() {
-          throw Errors.middlewareAlreadyGlobal(config.id);
+        [symbols.middlewareEverywhereTasks]: tasks,
+        [symbols.middlewareEverywhereResources]: resources,
+        everywhere() {
+          throw Errors.middlewareAlreadyGlobal(object.id);
         },
       };
     },
@@ -163,7 +258,7 @@ export function isResourceWithConfig(
   return definition && definition[symbols.resourceWithConfig];
 }
 
-export function isEvent(definition: any): definition is IEventDefinition {
+export function isEvent(definition: any): definition is IEvent {
   return definition && definition[symbols.event];
 }