@bluelibs/runner 1.5.4 → 2.1.0

package/src/define.ts

@@ -16,17 +16,21 @@ import {
   symbolEvent,
 } from "./defs";
 import { Errors } from "./errors";
+import { getCallerFile } from "./tools/getCallerFile";
+
+// Helper function to get the caller file
 
 export function defineTask<
   Input = undefined,
   Output extends Promise<any> = any,
   Deps extends DependencyMapType = any,
-  Test = any
+  TOn extends "*" | IEventDefinition | undefined = undefined
 >(
-  taskConfig: ITaskDefinition<Input, Output, Deps, Test>
-): ITask<Input, Output, Deps, Test> {
+  taskConfig: ITaskDefinition<Input, Output, Deps, TOn>
+): ITask<Input, Output, Deps, TOn> {
   return {
     [symbols.task]: true,
+    [symbols.filePath]: getCallerFile(),
     id: taskConfig.id,
     dependencies: taskConfig.dependencies || ({} as Deps),
     middleware: taskConfig.middleware || [],
@@ -58,9 +62,9 @@ export function defineResource<
 ): IResource<TConfig, TValue, TDeps> {
   return {
     [symbols.resource]: true,
+    [symbols.filePath]: getCallerFile(),
     id: constConfig.id,
     dependencies: constConfig.dependencies,
-    hooks: constConfig.hooks || [],
     dispose: constConfig.dispose,
     register: constConfig.register || [],
     overrides: constConfig.overrides || [],
@@ -94,6 +98,7 @@ export function defineEvent<TPayload = any>(
   config: IEventDefinitionConfig<TPayload>
 ): IEventDefinition<TPayload> {
   return {
+    [symbols.filePath]: getCallerFile(),
     [symbolEvent]: true,
     ...config,
   };
@@ -103,6 +108,7 @@ export function defineMiddleware<TDeps extends DependencyMapType = {}>(
   config: IMiddlewareDefinition<TDeps>
 ): IMiddleware<TDeps> {
   const object = {
+    [symbols.filePath]: getCallerFile(),
     [symbols.middleware]: true,
     ...config,
     dependencies: config.dependencies || ({} as TDeps),

package/src/defs.ts

@@ -9,6 +9,8 @@ export const symbolMiddlewareGlobal: unique symbol = Symbol(
   "runner.middlewareGlobal"
 );
 
+export const symbolFilePath: unique symbol = Symbol("runner.filePath");
+
 export const symbols = {
   task: symbolTask,
   resource: symbolResource,
@@ -16,6 +18,7 @@ export const symbols = {
   event: symbolEvent,
   middleware: symbolMiddleware,
   middlewareGlobal: symbolMiddlewareGlobal,
+  filePath: symbolFilePath,
 };
 
 export interface IMeta {
@@ -32,7 +35,7 @@ export interface IMiddlewareMeta extends IMeta {}
 // DependencyMap types
 export type DependencyMapType = Record<
   string,
-  ITask<any, any, any> | IResource<any, any, any> | IEventDefinition<any>
+  ITask<any, any, any, any> | IResource<any, any, any> | IEventDefinition<any>
 >;
 
 // Helper Types for Extracting Generics
@@ -61,19 +64,39 @@ export type DependencyValuesType<T extends DependencyMapType> = {
   [K in keyof T]: DependencyValueType<T[K]>;
 };
 
+type Optional<T> = {
+  [K in keyof T]?: T[K];
+};
+
+// Utility type to check if a type is void
+type IsVoid<T> = [T] extends [void] ? true : false;
+
+// Utility type to check if a type is optional (can be undefined)
+type IsOptional<T> = undefined extends T ? true : false;
+
+// IReso
+
+// Conditional type to allow `void`, optional, or any type
+type OptionalOrVoidOrAnything<T> = IsVoid<T> extends true
+  ? void
+  : IsOptional<T> extends true
+  ? Optional<T>
+  : T;
+
 // RegisterableItems Type with Conditional Inclusion
-export type RegisterableItems =
+export type RegisterableItems<T = any> =
   | IResourceWithConfig<any>
   | IResource<void, any, any>
-  | ITaskDefinition
-  | IMiddlewareDefinition
-  | IEventDefinition;
+  | IResource<OptionalOrVoidOrAnything<T>, any, any>
+  | ITaskDefinition<any, any, any, any>
+  | IMiddlewareDefinition<any>
+  | IEventDefinition<any>;
 
 export interface ITaskDefinition<
   TInput = any,
   TOutput extends Promise<any> = any,
   TDependencies extends DependencyMapType = {},
-  TEventDefinitionInput = null
+  TOn extends "*" | IEventDefinition<any> | undefined = undefined // Adding a generic to track 'on' type
 > {
   id: string;
   dependencies?: TDependencies | (() => TDependencies);
@@ -81,7 +104,7 @@ export interface ITaskDefinition<
   /**
    * Listen to events in a simple way
    */
-  on?: IEventDefinition<TEventDefinitionInput>;
+  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.
@@ -89,7 +112,12 @@ export interface ITaskDefinition<
   listenerOrder?: number;
   meta?: ITaskMeta;
   run: (
-    input: TEventDefinitionInput extends null ? TInput : TEventDefinitionInput,
+    input: TOn extends undefined ? TInput : IEvent<ExtractEventParams<TOn>>,
+    // input: TOn extends "*"
+    //   ? IEvent<any>
+    //   : TEventDefinitionInput extends null | void
+    //   ? TInput
+    // : IEvent<TEventDefinitionInput>,
     dependencies: DependencyValuesType<TDependencies>
   ) => TOutput;
 }
@@ -127,13 +155,8 @@ export interface ITask<
   TInput = any,
   TOutput extends Promise<any> = any,
   TDependencies extends DependencyMapType = {},
-  TEventDefinitionInput = null
-> extends ITaskDefinition<
-    TInput,
-    TOutput,
-    TDependencies,
-    TEventDefinitionInput
-  > {
+  TOn extends "*" | IEventDefinition<any> | undefined = undefined
+> extends ITaskDefinition<TInput, TOutput, TDependencies, TOn> {
   dependencies: TDependencies | (() => TDependencies);
   computedDependencies?: DependencyValuesType<TDependencies>;
   middleware: IMiddlewareDefinition[];
@@ -156,9 +179,6 @@ export interface IResourceDefinition<
 > {
   id: string;
   dependencies?: TDependencies | ((config: TConfig) => TDependencies);
-  hooks?:
-    | IHookDefinition<TDependencies, THooks>[]
-    | ((config: TConfig) => IHookDefinition<TDependencies, THooks>[]);
   register?:
     | Array<RegisterableItems>
     | ((config: TConfig) => Array<RegisterableItems>);
@@ -201,10 +221,6 @@ export interface IResource<
     afterInit: IEventDefinition<AfterInitEventPayload<TConfig, TValue>>;
     onError: IEventDefinition<OnErrorEventPayload>;
   };
-  hooks:
-    | IHookDefinition<TDependencies>[]
-    | ((config: TConfig) => IHookDefinition<TDependencies>[]);
-
   overrides: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
   middleware: IMiddlewareDefinition[];
 }

package/src/globalEvents.ts

@@ -5,12 +5,29 @@ import { ILog } from "./models/Logger";
 export const globalEvents = {
   beforeInit: defineEvent({
     id: "global.beforeInit",
+    meta: {
+      title: "Before Initialization",
+      description:
+        "Triggered before any resource or system-wide initialization occurs.",
+      tags: ["system"],
+    },
   }),
   afterInit: defineEvent({
     id: "global.afterInit",
+    meta: {
+      title: "After Initialization",
+      description:
+        "Fired after the system or resource initialization is completed.",
+      tags: ["system"],
+    },
   }),
   log: defineEvent<ILog>({
     id: "global.log",
+    meta: {
+      title: "Log Event",
+      description: "Used to log events and messages across the system.",
+      tags: ["system"],
+    },
   }),
   tasks: {
     beforeRun: defineEvent<{
@@ -18,6 +35,12 @@ export const globalEvents = {
       input: any;
     }>({
       id: "global.tasks.beforeRun",
+      meta: {
+        title: "Before Task Execution",
+        description:
+          "Triggered before a task starts running, providing access to the input data.",
+        tags: ["system"],
+      },
     }),
     afterRun: defineEvent<{
       task: ITask<any, any, any>;
@@ -25,6 +48,12 @@ export const globalEvents = {
       output: any;
     }>({
       id: "global.tasks.afterRun",
+      meta: {
+        title: "After Task Execution",
+        description:
+          "Fired after a task has completed, providing both the input and output data.",
+        tags: ["system"],
+      },
     }),
     onError: defineEvent<{
       error: any;
@@ -32,6 +61,12 @@ export const globalEvents = {
       task: ITask<any, any, any>;
     }>({
       id: "global.tasks.onError",
+      meta: {
+        title: "Task Error",
+        description:
+          "Triggered when an error occurs during task execution. Allows error suppression.",
+        tags: ["system"],
+      },
     }),
   },
   resources: {
@@ -40,6 +75,12 @@ export const globalEvents = {
       config: any;
     }>({
       id: "global.resources.beforeInit",
+      meta: {
+        title: "Before Resource Initialization",
+        description:
+          "Fired before a resource is initialized, with access to the configuration.",
+        tags: ["system"],
+      },
     }),
     afterInit: defineEvent<{
       resource: IResource<any, any, any>;
@@ -47,6 +88,12 @@ export const globalEvents = {
       value: any;
     }>({
       id: "global.resources.afterInit",
+      meta: {
+        title: "After Resource Initialization",
+        description:
+          "Fired after a resource has been initialized, providing the final value.",
+        tags: ["system"],
+      },
     }),
     onError: defineEvent<{
       error: Error;
@@ -54,6 +101,12 @@ export const globalEvents = {
       resource: IResource<any, any, any>;
     }>({
       id: "global.resources.onError",
+      meta: {
+        title: "Resource Error",
+        description:
+          "Triggered when an error occurs during resource initialization. Allows error suppression.",
+        tags: ["system"],
+      },
     }),
   },
 };

package/src/globalResources.ts

@@ -7,6 +7,12 @@ import { TaskRunner } from "./models/TaskRunner";
 const store = defineResource({
   id: "global.store",
   init: async (store: Store) => store,
+  meta: {
+    title: "Store",
+    description:
+      "A global store that can be used to store and retrieve tasks, resources, events and middleware",
+    tags: ["internal"],
+  },
 });
 
 export const globalResources = {
@@ -14,13 +20,30 @@ export const globalResources = {
   eventManager: defineResource({
     id: "global.eventManager",
     init: async (em: EventManager) => em,
+    meta: {
+      title: "Event Manager",
+      description:
+        "Manages all events and event listeners. This is meant to be used internally for most use-cases.",
+      tags: ["internal"],
+    },
   }),
   taskRunner: defineResource({
     id: "global.taskRunner",
     init: async (runner: TaskRunner) => runner,
+    meta: {
+      title: "Task Runner",
+      description:
+        "Manages the execution of tasks and task dependencies. This is meant to be used internally for most use-cases.",
+      tags: ["internal"],
+    },
   }),
   logger: defineResource({
     id: "global.logger",
     init: async (logger: Logger) => logger,
+    meta: {
+      title: "Logger",
+      description:
+        "Logs all events and errors. This is meant to be used internally for most use-cases. Emits a global.log event for each log.",
+    },
   }),
 };

package/src/models/DependencyProcessor.ts

@@ -5,6 +5,7 @@ import {
   IResource,
   IHookDefinition,
   IEventDefinition,
+  IEvent,
 } from "../defs";
 import { ResourceStoreElementType, Store, TaskStoreElementType } from "./Store";
 import * as utils from "../define";
@@ -68,32 +69,6 @@ export class DependencyProcessor {
       deps,
       task.task.id
     );
-
-    let eventDefinition = task.task.on;
-    if (eventDefinition) {
-      if (this.store.events.get(eventDefinition.id) === undefined) {
-        throw Errors.eventNotFound(eventDefinition.id);
-      }
-
-      this.eventManager.addListener(
-        eventDefinition,
-        async (receivedEvent) => {
-          this.logger.debug({
-            message: `Task ${task.task.id} listened to event: ${eventDefinition.id}`,
-            event: receivedEvent,
-          });
-
-          return this.taskRunner.run(
-            task.task,
-            receivedEvent,
-            task.computedDependencies
-          );
-        },
-        {
-          order: task.task.listenerOrder || 0,
-        }
-      );
-    }
   }
 
   // Most likely these are resources that no-one has dependencies towards
@@ -145,62 +120,49 @@ export class DependencyProcessor {
   /**
    * Processes all hooks, should run before emission of any event.
    */
-  public attachHooks() {
-    for (const resource of this.store.resources.values()) {
-      if (resource.resource.hooks) {
-        this.attachHooksToResource(resource);
-      }
-    }
-  }
+  public attachListeners() {
+    for (const task of this.store.tasks.values()) {
+      if (task.task.on) {
+        let eventDefinition = task.task.on;
+
+        const handler = async (receivedEvent: IEvent<any>) => {
+          if (receivedEvent.source === task.task.id) {
+            // we don't want to trigger the same task that emitted the event
+            // process.exit(0);
+            return;
+          }
 
-  /**
-   * Processes the hooks for resources
-   * @param hooks
-   * @param deps
-   */
-  public attachHooksToResource(
-    resourceStoreElement: ResourceStoreElementType<any, any, {}>
-  ) {
-    let hooks = resourceStoreElement.resource.hooks;
-    if (typeof hooks === "function") {
-      hooks = hooks(resourceStoreElement.config);
-    }
+          this.logger.debug(
+            {
+              message:
+                eventDefinition === "*"
+                  ? `Task ${task.task.id} being triggered by all events`
+                  : `Task ${task.task.id} being triggered by event: ${eventDefinition.id}`,
 
-    if (hooks.length === 0) {
-      return;
-    }
+              event: receivedEvent,
+            },
+            task.task.id
+          );
+
+          return this.taskRunner.run(
+            task.task,
+            receivedEvent,
+            task.computedDependencies
+          );
+        };
 
-    for (const hook of hooks) {
-      const event = hook.event;
-      const order = hook.order || 0;
-      if (event === "*") {
-        this.eventManager.addGlobalListener(
-          async (receivedEvent) => {
-            return hook.run(
-              receivedEvent,
-              resourceStoreElement.computedDependencies as DependencyValuesType<{}>
-            );
-          },
-          {
-            order,
+        if (eventDefinition === "*") {
+          this.eventManager.addGlobalListener(handler, {
+            order: task.task.listenerOrder || 0,
+          });
+        } else {
+          if (this.store.events.get(eventDefinition.id) === undefined) {
+            throw Errors.eventNotFound(eventDefinition.id);
           }
-        );
-      } else {
-        if (this.store.events.has(event.id) === false) {
-          throw Errors.eventNotFound(event.id);
+          this.eventManager.addListener(eventDefinition, handler, {
+            order: task.task.listenerOrder || 0,
+          });
         }
-        this.eventManager.addListener(
-          event,
-          async (receivedEvent) => {
-            return hook.run(
-              receivedEvent,
-              resourceStoreElement.computedDependencies as DependencyValuesType<{}>
-            );
-          },
-          {
-            order,
-          }
-        );
       }
     }
   }
@@ -241,9 +203,12 @@ export class DependencyProcessor {
   ) {
     return async (input) => {
       // runs it in background.
-      this.logger.debug({
-        message: `Event ${object.id} was emitted from ${source}`,
-      });
+      this.logger.debug(
+        {
+          message: `Event ${object.id} was emitted from ${source}`,
+        },
+        source
+      );
 
       return this.eventManager.emit(object, input, source);
     };

package/src/models/EventManager.ts

@@ -13,6 +13,10 @@ interface IListenerStorage {
 export interface IEventHandlerOptions<T = any> {
   order?: number;
   filter?: (event: IEvent<T>) => boolean;
+  /**
+   * Represents the listener ID. Use this to avoid a listener calling himself.
+   */
+  id?: string;
 }
 
 export class EventManager {

package/src/models/ResourceInitializer.ts

@@ -68,13 +68,15 @@ export class ResourceInitializer {
         resource.id
       );
 
-      this.logger.debug(`Resource ${resource.id} initialized`);
+      this.logger.debug(`Resource ${resource.id} initialized`, resource.id);
 
       return value;
     } catch (e) {
       error = e;
       let isSuppressed = false;
-      const suppress = () => (isSuppressed = true);
+      function suppress() {
+        isSuppressed = true;
+      }
 
       // If you want to rewthrow the error, this should be done inside the onError event.
       await this.eventManager.emit(

package/src/models/Store.ts

@@ -34,9 +34,10 @@ export type ResourceStoreElementType<
 export type TaskStoreElementType<
   Input = any,
   Output extends Promise<any> = any,
-  D extends DependencyMapType = any
+  D extends DependencyMapType = any,
+  TOn extends "*" | IEventDefinition | undefined = any
 > = {
-  task: ITask<Input, Output, D>;
+  task: ITask<Input, Output, D, TOn>;
   computedDependencies: DependencyValuesType<D>;
   isInitialized: boolean;
 };

package/src/models/TaskRunner.ts

@@ -50,43 +50,63 @@ export class TaskRunner {
       this.runnerStore.set(task.id, runner);
     }
 
-    // begin by dispatching the event of creating it.
-    // then ensure the hooks are called
-    // then ensure the middleware are called
-    await this.eventManager.emit(task.events.beforeRun, { input }, task.id);
-    await this.eventManager.emit(
-      globalEvents.tasks.beforeRun,
-      {
-        task,
-        input,
-      },
-      task.id
-    );
+    const isGlobalEventListener = task.on === "*";
 
-    let error;
-    try {
-      // craft the next function starting from the first next function
-      const output = await runner(input);
+    if (!isGlobalEventListener) {
+      await this.eventManager.emit(task.events.beforeRun, { input }, task.id);
+    }
 
+    if (
+      !isGlobalEventListener &&
+      task.on !== globalEvents.tasks.beforeRun &&
+      task.on !== globalEvents.tasks.afterRun
+    ) {
       await this.eventManager.emit(
-        task.events.afterRun,
-        { input, output },
-        task.id
-      );
-      await this.eventManager.emit(
-        globalEvents.tasks.afterRun,
+        globalEvents.tasks.beforeRun,
         {
           task,
           input,
-          output,
         },
         task.id
       );
+    }
+
+    let error;
+    try {
+      // craft the next function starting from the first next function
+      const output = await runner(input);
+
+      if (!isGlobalEventListener) {
+        await this.eventManager.emit(
+          task.events.afterRun,
+          { input, output },
+          task.id
+        );
+      }
+
+      if (
+        !isGlobalEventListener &&
+        task.on !== globalEvents.tasks.beforeRun &&
+        task.on !== globalEvents.tasks.afterRun
+      ) {
+        await this.eventManager.emit(
+          globalEvents.tasks.afterRun,
+          {
+            task,
+            input,
+            output,
+          },
+          task.id
+        );
+      }
 
       return output;
     } catch (e) {
       let isSuppressed = false;
-      const suppress = () => (isSuppressed = true);
+      function suppress() {
+        isSuppressed = true;
+      }
+
       error = e;
 
       // If you want to rewthrow the error, this should be done inside the onError event.
@@ -126,10 +146,13 @@ export class TaskRunner {
   ) {
     // this is the final next()
     let next = async (input) => {
-      this.logger.debug({
-        message: `Running task ${task.id}`,
-        input,
-      });
+      this.logger.debug(
+        {
+          message: `Running task ${task.id}`,
+          input,
+        },
+        task.id
+      );
 
       return task.run.call(null, input, taskDependencies as any);
     };

package/src/run.ts

@@ -87,7 +87,7 @@ export async function run<C, V>(
 
   // a form of hooking, we create the events for all tasks and store them so they can be referenced
   await store.storeEventsForAllTasks();
-  await processor.attachHooks();
+  await processor.attachListeners();
   await processor.computeAllDependencies();
 
   // After this stage, logger print policy could have been set.

package/src/tools/getCallerFile.ts

@@ -0,0 +1,33 @@
+export function getCallerFile(): string | undefined {
+  const originalFunc = Error.prepareStackTrace;
+
+  try {
+    const err = new Error();
+    let callerfile;
+    let currentfile;
+
+    // Safeguard prepareStackTrace
+    Error.prepareStackTrace = (err, stack) => stack;
+
+    const stack = err.stack as unknown as NodeJS.CallSite[];
+
+    // Don't know how to test this.
+    // if (stack.length < 3) {
+    //   // We need at least 3 frames: current function, its caller, and one above
+    //   return undefined;
+    // }
+
+    // Remove the first frame (getCallerFile itself)
+    stack.shift();
+
+    // Remove the second frame (the direct caller of getCallerFile)
+    currentfile = stack.shift()?.getFileName();
+
+    // The third frame (the caller above the immediate one)
+    callerfile = stack.shift()?.getFileName();
+
+    return callerfile; // Return the file name of the caller above
+  } finally {
+    Error.prepareStackTrace = originalFunc;
+  }
+}