@bluelibs/runner 1.1.0 → 1.2.0

package/src/defs.ts

@@ -21,7 +21,7 @@ export interface IMiddlewareMeta extends IMeta {}
 // DependencyMap types
 export type DependencyMapType = Record<
   string,
-  ITask | IResource | IEventDefinition
+  ITask | IResource | IEventDefinition | IResourceWithConfig<any, any>
 >;
 
 export type DependencyValueType<T> = T extends ITask<
@@ -146,6 +146,7 @@ export interface IResourceDefinintion<
     dependencies: DependencyValuesType<TDependencies>
   ) => Promise<TValue>;
   meta?: IResourceMeta;
+  overrides?: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
 }
 
 export interface IResource<
@@ -168,6 +169,8 @@ export interface IResource<
   hooks:
     | IHookDefinition<TDependencies>[]
     | ((config: TConfig) => IHookDefinition<TDependencies>[]);
+
+  overrides: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
 }
 
 export interface IResourceWithConfig<
@@ -225,10 +228,10 @@ export interface IMiddlewareExecutionInput {
   next: (input?: any) => Promise<any>;
 }
 
-export interface IHookDefinition<D extends DependencyMapType = {}> {
-  event: IEventDefinition;
+export interface IHookDefinition<D extends DependencyMapType = {}, T = any> {
+  event: IEventDefinition<T>;
   run: (
-    event: IEvent,
+    event: IEvent<T>,
     dependencies: DependencyValuesType<D>
   ) => Promise<void> | void;
 }

package/src/globalEvents.ts

@@ -1,5 +1,6 @@
 import { defineEvent } from "./define";
 import { ITask, IResource } from "./defs";
+import { ILog } from "./models/Logger";
 
 export const globalEvents = {
   beforeInit: defineEvent({
@@ -8,6 +9,9 @@ export const globalEvents = {
   afterInit: defineEvent({
     id: "global.afterInit",
   }),
+  log: defineEvent<ILog>({
+    id: "global.log",
+  }),
   tasks: {
     beforeRun: defineEvent<{
       task: ITask<any, any, any>;

package/src/globalResources.ts

@@ -1,7 +1,8 @@
 import { defineResource } from "./define";
-import { EventManager } from "./EventManager";
-import { Store } from "./Store";
-import { TaskRunner } from "./TaskRunner";
+import { EventManager } from "./models/EventManager";
+import { Logger } from "./models/Logger";
+import { Store } from "./models/Store";
+import { TaskRunner } from "./models/TaskRunner";
 
 const store = defineResource({
   id: "global.store",
@@ -18,4 +19,8 @@ export const globalResources = {
     id: "global.taskRunner",
     init: async (runner: TaskRunner) => runner,
   }),
+  logger: defineResource({
+    id: "global.logger",
+    init: async (logger: Logger) => logger,
+  }),
 };

package/src/index.ts

@@ -23,6 +23,6 @@ export {
 };
 
 export * as definitions from "./defs";
-export { Store } from "./Store";
-export { EventManager } from "./EventManager";
-export { TaskRunner } from "./TaskRunner";
+export { Store } from "./models/Store";
+export { EventManager } from "./models/EventManager";
+export { TaskRunner } from "./models/TaskRunner";

package/src/{DependencyProcessor.ts → models/DependencyProcessor.ts}

@@ -5,13 +5,13 @@ import {
   IResource,
   IHookDefinition,
   IEventDefinition,
-} from "./defs";
+} from "../defs";
 import { ResourceStoreElementType, Store } from "./Store";
-import * as utils from "./define";
+import * as utils from "../define";
 import { EventManager } from "./EventManager";
 import { ResourceInitializer } from "./ResourceInitializer";
 import { TaskRunner } from "./TaskRunner";
-import { Errors } from "./errors";
+import { Errors } from "../errors";
 
 /**
  * This class is responsible of setting up dependencies with their respective computedValues.
@@ -113,11 +113,11 @@ export class DependencyProcessor {
    * Processes all hooks, should run before emission of any event.
    * @returns
    */
-  public processHooks() {
+  public attachHooks() {
     // iterate through resources and send them to processHooks
     for (const resource of this.store.resources.values()) {
       if (resource.resource.hooks) {
-        this.processHooksForResource(resource);
+        this.attachHooksToResource(resource);
       }
     }
   }
@@ -127,7 +127,7 @@ export class DependencyProcessor {
    * @param hooks
    * @param deps
    */
-  public processHooksForResource(
+  public attachHooksToResource(
     resourceStoreElement: ResourceStoreElementType<any, any, {}>
   ) {
     let hooks = resourceStoreElement.resource.hooks;

package/src/{EventManager.ts → models/EventManager.ts}

@@ -1,5 +1,5 @@
-import { EventHandlerType, IEvent, IEventDefinition } from "./defs";
-import { Errors } from "./errors";
+import { EventHandlerType, IEvent, IEventDefinition } from "../defs";
+import { Errors } from "../errors";
 
 const HandlerOptionsDefaults = { order: 0 };
 

package/src/models/Logger.ts

@@ -0,0 +1,100 @@
+import { globalEvents } from "../globalEvents";
+import { EventManager } from "./EventManager";
+
+export type LogLevels =
+  | "trace"
+  | "debug"
+  | "info"
+  | "warn"
+  | "error"
+  | "critical";
+
+export interface ILog {
+  level: string;
+  context?: string;
+  data: any;
+  timestamp: Date;
+}
+
+export class Logger {
+  public static defaultContext = "app";
+
+  public severity = {
+    trace: 0,
+    debug: 1,
+    info: 2,
+    warn: 3,
+    error: 4,
+    critical: 5,
+  };
+
+  constructor(private eventManager: EventManager) {}
+
+  /**
+   * @param level
+   * @param message
+   */
+  public async log(level: LogLevels, data: any): Promise<void> {
+    const log: ILog = {
+      level,
+      data,
+      timestamp: new Date(),
+    };
+
+    await this.eventManager.emit(globalEvents.log, log);
+  }
+
+  public async print(log: ILog) {
+    // Extract the relevant information from the log
+    const { level, context, data, timestamp } = log;
+
+    // Format the timestamp to a more readable format
+    const formattedTimestamp = timestamp.toISOString();
+
+    // Format the log level for better visibility
+    const levelStr = `[${level.toUpperCase()}]`;
+
+    // Format the context, if provided
+    const contextStr = context ? `(${context})` : "";
+
+    // Handle different data types, especially if it's an error
+    let dataStr: string;
+    if (data instanceof Error) {
+      dataStr = `Error: ${data.name} - ${data.message}\nStack Trace:\n${data.stack}`;
+    } else if (typeof data === "object") {
+      dataStr = JSON.stringify(data, null, 2); // Pretty-print JSON objects
+    } else {
+      dataStr = String(data); // Convert any other type to string
+    }
+
+    // Construct the final log message
+    const logMessage = `${formattedTimestamp} ${levelStr} ${contextStr} - ${dataStr}`;
+
+    // Print the log message
+    console.log(logMessage);
+  }
+
+  public async info(data: any) {
+    await this.log("info", data);
+  }
+
+  public async error(data: any) {
+    await this.log("error", data);
+  }
+
+  public async warn(data: any) {
+    await this.log("warn", data);
+  }
+
+  public async debug(data: any) {
+    await this.log("debug", data);
+  }
+
+  public async trace(data: any) {
+    await this.log("trace", data);
+  }
+
+  public async critical(data: any) {
+    await this.log("critical", data);
+  }
+}

package/src/{ResourceInitializer.ts → models/ResourceInitializer.ts}

@@ -3,9 +3,9 @@ import {
   DependencyValuesType,
   ITask,
   IResource,
-} from "./defs";
+} from "../defs";
 import { EventManager } from "./EventManager";
-import { globalEvents } from "./globalEvents";
+import { globalEvents } from "../globalEvents";
 import { Store } from "./Store";
 
 export class ResourceInitializer {

package/src/{Store.ts → models/Store.ts}

@@ -9,12 +9,12 @@ import {
   RegisterableItems,
   symbols,
   IMiddleware,
-} from "./defs";
-import * as utils from "./define";
-import { IDependentNode } from "./tools/findCircularDependencies";
-import { globalEventsArray } from "./globalEvents";
-import { Errors } from "./errors";
-import { globalResources } from "./globalResources";
+} from "../defs";
+import * as utils from "../define";
+import { IDependentNode } from "../tools/findCircularDependencies";
+import { globalEventsArray } from "../globalEvents";
+import { Errors } from "../errors";
+import { globalResources } from "../globalResources";
 import { EventManager } from "./EventManager";
 import { TaskRunner } from "./TaskRunner";
 
@@ -59,6 +59,11 @@ export class Store {
   public resources: Map<string, ResourceStoreElementType> = new Map();
   public events: Map<string, EventStoreElementType> = new Map();
   public middlewares: Map<string, MiddlewareStoreElementType> = new Map();
+  public overrides: Map<
+    string,
+    IResource | IMiddleware | ITask | IResourceWithConfig
+  > = new Map();
+
   #isLocked = false;
   #isInitialized = false;
 
@@ -71,11 +76,6 @@ export class Store {
   lock() {
     this.#isLocked = true;
     this.eventManager.lock();
-    // freeze the maps so they can't be modified
-    Object.freeze(this.tasks);
-    Object.freeze(this.resources);
-    Object.freeze(this.events);
-    Object.freeze(this.middlewares);
   }
 
   checkLock() {
@@ -115,10 +115,13 @@ export class Store {
       this.storeEvent(event);
     });
 
-    this.computeRegisterOfResource(root, config);
-
+    this.computeRegistrationDeeply(root, config);
     this.resources.set(root.id, this.root);
 
+    for (const resource of this.resources.values()) {
+      this.storeOverridesDeeply(resource.resource);
+    }
+
     this.#isInitialized = true;
   }
 
@@ -127,17 +130,37 @@ export class Store {
    * @param element
    * @param config
    */
-  private computeRegisterOfResource<C>(element: IResource<C>, config?: C) {
+  private computeRegistrationDeeply<C>(element: IResource<C>, config?: C) {
     const items =
       typeof element.register === "function"
         ? element.register(config as C)
         : element.register;
 
     for (const item of items) {
+      // will call registration if it detects another resource.
       this.storeGenericItem<C>(item);
     }
   }
 
+  /**
+   * @param element
+   */
+  private storeOverridesDeeply<C>(element: IResource<C, any, any>) {
+    element.overrides.forEach((override) => {
+      // the one on top has priority of setting the last override.
+      if (utils.isResource(override)) {
+        this.storeOverridesDeeply(override);
+      }
+
+      if (utils.isResourceWithConfig(override)) {
+        this.storeOverridesDeeply(override.resource);
+        this.overrides.set(override.resource.id, override);
+      } else {
+        this.overrides.set(override.id, override);
+      }
+    });
+  }
+
   /**
    * middlewares are already stored in their final form and the check for them would be redundant
    * @param id
@@ -152,8 +175,14 @@ export class Store {
     if (this.events.has(id)) {
       throw Errors.duplicateRegistration("Event", id);
     }
+    if (this.middlewares.has(id)) {
+      throw Errors.duplicateRegistration("Middleware", id);
+    }
   }
 
+  /**
+   * Cleanup
+   */
   public async dispose() {
     for (const resource of this.resources.values()) {
       if (resource.resource.dispose) {
@@ -166,6 +195,45 @@ export class Store {
     }
   }
 
+  /**
+   * When this is called, all overrides should have been stored in the "overrides" store.
+   */
+  public processOverrides() {
+    // If we are trying to use override on something that wasn't previously registered, we throw an error.
+    for (const override of this.overrides.values()) {
+      let hasAnyItem = false;
+      if (utils.isTask(override)) {
+        hasAnyItem = this.tasks.has(override.id);
+      } else if (utils.isResource(override)) {
+        hasAnyItem = this.resources.has(override.id);
+      } else if (utils.isMiddleware(override)) {
+        hasAnyItem = this.middlewares.has(override.id);
+      } else if (utils.isResourceWithConfig(override)) {
+        hasAnyItem = this.resources.has(override.resource.id);
+      }
+
+      if (!hasAnyItem) {
+        const id = utils.isResourceWithConfig(override)
+          ? override.resource.id
+          : override.id;
+
+        throw Errors.dependencyNotFound(id);
+      }
+    }
+
+    for (const override of this.overrides.values()) {
+      if (utils.isTask(override)) {
+        this.storeTask(override, false);
+      } else if (utils.isResource(override)) {
+        this.storeResource(override, false);
+      } else if (utils.isMiddleware(override)) {
+        this.storeMiddleware(override, false);
+      } else if (utils.isResourceWithConfig(override)) {
+        this.storeResourceWithConfig(override, false);
+      }
+    }
+  }
+
   public getGlobalMiddlewares(excludingIds: string[]): IMiddleware[] {
     return Array.from(this.middlewares.values())
       .filter((x) => x.middleware[symbols.middlewareGlobal])
@@ -186,19 +254,7 @@ export class Store {
     } else if (utils.isEvent(item)) {
       this.storeEvent<C>(item);
     } else if (utils.isMiddleware(item)) {
-      if (this.middlewares.has(item.id)) {
-        throw Errors.duplicateRegistration("Middleware", item.id);
-      }
-
-      item.dependencies =
-        typeof item.dependencies === "function"
-          ? item.dependencies()
-          : item.dependencies;
-
-      this.middlewares.set(item.id, {
-        middleware: item,
-        computedDependencies: {},
-      });
+      this.storeMiddleware<C>(item);
     } else if (utils.isResourceWithConfig(item)) {
       this.storeResourceWithConfig<C>(item);
     } else {
@@ -206,14 +262,33 @@ export class Store {
     }
   }
 
+  private storeMiddleware<C>(item: IMiddleware<any>, check = true) {
+    check && this.checkIfIDExists(item.id);
+
+    item.dependencies =
+      typeof item.dependencies === "function"
+        ? item.dependencies()
+        : item.dependencies;
+
+    this.middlewares.set(item.id, {
+      middleware: item,
+      computedDependencies: {},
+    });
+  }
+
   public storeEvent<C>(item: IEventDefinition<void>) {
     this.checkIfIDExists(item.id);
 
     this.events.set(item.id, { event: item });
   }
 
-  private storeResourceWithConfig<C>(item: IResourceWithConfig<any, any, any>) {
-    this.checkIfIDExists(item.resource.id);
+  private storeResourceWithConfig<C>(
+    item: IResourceWithConfig<any, any, any>,
+    check = true
+  ) {
+    check && this.checkIfIDExists(item.resource.id);
+
+    this.prepareResource(item.resource, item.config);
 
     this.resources.set(item.resource.id, {
       resource: item.resource,
@@ -222,20 +297,17 @@ export class Store {
       isInitialized: false,
     });
 
-    this.computeRegisterOfResource(item.resource, item.config);
+    this.computeRegistrationDeeply(item.resource, item.config);
   }
 
-  private storeResource<C>(item: IResource<any, any, any>) {
-    this.checkIfIDExists(item.id);
-
-    this.storeEvent(item.events.beforeInit);
-    this.storeEvent(item.events.afterInit);
-    this.storeEvent(item.events.onError);
+  /**
+   * This is for storing a resource without a config.
+   * @param item
+   */
+  private storeResource<C>(item: IResource<any, any, any>, check = true) {
+    check && this.checkIfIDExists(item.id);
 
-    item.dependencies =
-      typeof item.dependencies === "function"
-        ? item.dependencies()
-        : item.dependencies;
+    this.prepareResource(item, {});
 
     this.resources.set(item.id, {
       resource: item,
@@ -244,20 +316,46 @@ export class Store {
       isInitialized: false,
     });
 
-    this.computeRegisterOfResource(item, {});
+    this.computeRegistrationDeeply(item, {});
   }
 
-  private storeTask<C>(item: ITask<any, any, {}>) {
-    this.checkIfIDExists(item.id);
+  public storeEventsForAllTasks() {
+    for (const task of this.tasks.values()) {
+      this.storeEvent(task.task.events.beforeRun);
+      this.storeEvent(task.task.events.afterRun);
+      this.storeEvent(task.task.events.onError);
+    }
 
+    for (const resource of this.resources.values()) {
+      this.storeEvent(resource.resource.events.beforeInit);
+      this.storeEvent(resource.resource.events.afterInit);
+      this.storeEvent(resource.resource.events.onError);
+    }
+  }
+
+  /**
+   * This is for storing a resource without a config.
+   * @param item
+   */
+  private prepareResource<C>(
+    item: IResource<any, any, any>,
+    config: any
+  ): IResource<any, any, any> {
     item.dependencies =
       typeof item.dependencies === "function"
-        ? item.dependencies()
+        ? item.dependencies(config)
         : item.dependencies;
 
-    this.storeEvent(item.events.beforeRun);
-    this.storeEvent(item.events.afterRun);
-    this.storeEvent(item.events.onError);
+    return item;
+  }
+
+  private storeTask<C>(item: ITask<any, any, {}>, check = true) {
+    check && this.checkIfIDExists(item.id);
+
+    item.dependencies =
+      typeof item.dependencies === "function"
+        ? item.dependencies()
+        : item.dependencies;
 
     this.tasks.set(item.id, {
       task: item,

package/src/{TaskRunner.ts → models/TaskRunner.ts}

@@ -1,7 +1,7 @@
-import { DependencyMapType, DependencyValuesType, ITask } from "./defs";
-import { Errors } from "./errors";
+import { DependencyMapType, DependencyValuesType, ITask } from "../defs";
+import { Errors } from "../errors";
 import { EventManager } from "./EventManager";
-import { globalEvents } from "./globalEvents";
+import { globalEvents } from "../globalEvents";
 import {
   MiddlewareStoreElementType,
   Store,
@@ -22,6 +22,9 @@ export class TaskRunner {
   /**
    * Begins the execution of an task. These are registered tasks and all sanity checks have been performed at this stage to ensure consistency of the object.
    * This function can throw only if any of the event listeners or run function throws
+   * @param task the task to be run
+   * @param input the input to be passed to the task
+   * @param taskDependencies optional dependencies to be passed to the task, if not provided, the dependencies will be the ones already computed from the store.
    */
   public async run<
     TInput,

package/src/models/index.ts

@@ -0,0 +1,5 @@
+export * from "./DependencyProcessor";
+export * from "./EventManager";
+export * from "./Logger";
+export * from "./Store";
+export * from "./TaskRunner";

package/src/run.ts

@@ -1,4 +1,4 @@
-import { TaskRunner } from "./TaskRunner";
+import { TaskRunner } from "./models/TaskRunner";
 import {
   DependencyMapType,
   ITaskDefinition,
@@ -8,13 +8,14 @@ import {
   DependencyValuesType,
   IResource,
 } from "./defs";
-import { DependencyProcessor } from "./DependencyProcessor";
-import { EventManager } from "./EventManager";
+import { DependencyProcessor } from "./models/DependencyProcessor";
+import { EventManager } from "./models/EventManager";
 import { globalEvents } from "./globalEvents";
-import { Store } from "./Store";
+import { Store } from "./models/Store";
 import { findCircularDependencies } from "./tools/findCircularDependencies";
 import { Errors } from "./errors";
 import { globalResources } from "./globalResources";
+import { Logger } from "./models/Logger";
 
 export type ResourcesStoreElementType<
   C = any,
@@ -65,9 +66,11 @@ export async function run<C, V>(
   const store = new Store(eventManager);
   const taskRunner = new TaskRunner(store, eventManager);
   const processor = new DependencyProcessor(store, eventManager, taskRunner);
+  const logger = new Logger(eventManager);
 
   // In the registration phase we register deeply all the resources, tasks, middleware and events
   store.initializeStore(resource, config);
+  store.storeGenericItem(globalResources.logger.with(logger));
   store.storeGenericItem(globalResources.taskRunner.with(taskRunner));
 
   // We verify that there isn't any circular dependencies before we begin computing the dependencies
@@ -77,14 +80,17 @@ export async function run<C, V>(
     throw Errors.circularDependencies(circularDependencies.cycles);
   }
 
-  await processor.processHooks();
+  await store.processOverrides();
+
+  // a form of hooking, we store the events for all tasks
+  await store.storeEventsForAllTasks();
+  await processor.attachHooks();
+  await processor.computeAllDependencies();
 
   // Now we can safely compute dependencies without being afraid of an infinite loop.
   // The hooking part is done here.
   await eventManager.emit(globalEvents.beforeInit);
 
-  await processor.computeAllDependencies();
-
   // leftovers that were registered but not depended upon, except root
   await processor.initializeUninitializedResources();