@bluelibs/runner 1.0.0

package/src/Store.ts

@@ -0,0 +1,250 @@
+import {
+  DependencyMapType,
+  DependencyValuesType,
+  IMiddlewareDefinition,
+  IEventDefinition,
+  IResource,
+  ITask,
+  IResourceWithConfig,
+  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";
+import { EventManager } from "./EventManager";
+import { TaskRunner } from "./TaskRunner";
+
+export type ResourceStoreElementType<
+  C = any,
+  V = any,
+  D extends DependencyMapType = {}
+> = {
+  resource: IResource<C, V, D>;
+  computedDependencies?: DependencyValuesType<D>;
+  config: C;
+  value: V;
+  isInitialized?: boolean;
+};
+
+export type TaskStoreElementType<
+  Input = any,
+  Output extends Promise<any> = any,
+  D extends DependencyMapType = any
+> = {
+  task: ITask<Input, Output, D>;
+  computedDependencies: DependencyValuesType<D>;
+  isInitialized: boolean;
+};
+
+export type MiddlewareStoreElementType<TDeps extends DependencyMapType = any> =
+  {
+    middleware: IMiddleware<TDeps>;
+    computedDependencies: DependencyValuesType<TDeps>;
+  };
+
+export type EventStoreElementType = {
+  event: IEventDefinition;
+};
+
+/**
+ * @internal This should be used for testing purposes only.
+ */
+export class Store {
+  root!: ResourceStoreElementType;
+  public tasks: Map<string, TaskStoreElementType> = new Map();
+  public resources: Map<string, ResourceStoreElementType> = new Map();
+  public events: Map<string, EventStoreElementType> = new Map();
+  public middlewares: Map<string, MiddlewareStoreElementType> = new Map();
+
+  constructor(protected readonly eventManager: EventManager) {}
+
+  /**
+   * Store the root before beginning registration
+   * @param root
+   * @param config
+   */
+  initializeStore(root: IResource<any>, config: any) {
+    this.storeGenericItem(globalResources.eventManager.with(this.eventManager));
+    this.storeGenericItem(globalResources.store.with(this));
+
+    root.dependencies =
+      typeof root.dependencies === "function"
+        ? root.dependencies(config)
+        : root.dependencies;
+
+    this.root = {
+      resource: root,
+      computedDependencies: {},
+      config,
+      value: undefined,
+      isInitialized: false,
+    };
+
+    // register global events
+    globalEventsArray.forEach((event) => {
+      this.storeEvent(event);
+    });
+
+    this.resources.set(root.id, this.root);
+  }
+
+  /**
+   * Beginning with the root, we perform registering to the container all the resources, tasks, middleware and events.
+   * @param element
+   * @param config
+   */
+  computeRegisterOfResource<C>(element: IResource<C>, config?: C) {
+    const items =
+      typeof element.register === "function"
+        ? element.register(config as C)
+        : element.register;
+
+    for (const item of items) {
+      this.storeGenericItem<C>(item);
+    }
+  }
+
+  /**
+   * middlewares are already stored in their final form and the check for them would be redundant
+   * @param id
+   */
+  protected checkIfIDExists(id: string): void | never {
+    if (this.tasks.has(id)) {
+      throw Errors.duplicateRegistration("Task", id);
+    }
+    if (this.resources.has(id)) {
+      throw Errors.duplicateRegistration("Resource", id);
+    }
+    if (this.events.has(id)) {
+      throw Errors.duplicateRegistration("Event", id);
+    }
+  }
+
+  public getGlobalMiddlewares(excludingIds: string[]): IMiddleware[] {
+    return Array.from(this.middlewares.values())
+      .filter((x) => x.middleware[symbols.middlewareGlobal])
+      .filter((x) => !excludingIds.includes(x.middleware.id))
+      .map((x) => x.middleware);
+  }
+
+  /**
+   * If you want to register something to the store you can use this function.
+   * @param item
+   */
+  public storeGenericItem<C>(item: RegisterableItems) {
+    if (utils.isTask(item)) {
+      this.storeTask<C>(item);
+    } else if (utils.isResource(item)) {
+      // Registration a simple resource, which is interpreted as a resource with no configuration.
+      this.storeResource<C>(item);
+    } 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: {},
+      });
+    } else if (utils.isResourceWithConfig(item)) {
+      this.storeResourceWithConfig<C>(item);
+    } else {
+      throw Errors.unknownItemType(item);
+    }
+  }
+
+  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);
+
+    this.resources.set(item.resource.id, {
+      resource: item.resource,
+      config: item.config,
+      value: undefined,
+      isInitialized: false,
+    });
+
+    this.computeRegisterOfResource(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);
+
+    item.dependencies =
+      typeof item.dependencies === "function"
+        ? item.dependencies()
+        : item.dependencies;
+
+    this.resources.set(item.id, {
+      resource: item,
+      config: {},
+      value: undefined,
+      isInitialized: false,
+    });
+
+    this.computeRegisterOfResource(item, {});
+  }
+
+  private storeTask<C>(item: ITask<any, any, {}>) {
+    this.checkIfIDExists(item.id);
+
+    item.dependencies =
+      typeof item.dependencies === "function"
+        ? item.dependencies()
+        : item.dependencies;
+
+    this.storeEvent(item.events.beforeRun);
+    this.storeEvent(item.events.afterRun);
+    this.storeEvent(item.events.onError);
+
+    this.tasks.set(item.id, {
+      task: item,
+      computedDependencies: {},
+      isInitialized: false,
+    });
+  }
+
+  getDependentNodes(): IDependentNode[] {
+    const depenedants: IDependentNode[] = [];
+    for (const task of this.tasks.values()) {
+      depenedants.push({
+        id: task.task.id,
+        dependencies: task.task.dependencies,
+      });
+    }
+    for (const middleware of this.middlewares.values()) {
+      depenedants.push({
+        id: middleware.middleware.id,
+        dependencies: middleware.middleware.dependencies,
+      });
+    }
+    for (const resource of this.resources.values()) {
+      depenedants.push({
+        id: resource.resource.id,
+        dependencies: resource.resource.dependencies || {},
+      });
+    }
+
+    return depenedants;
+  }
+}

package/src/TaskRunner.ts

@@ -0,0 +1,135 @@
+import { DependencyMapType, DependencyValuesType, ITask } from "./defs";
+import { Errors } from "./errors";
+import { EventManager } from "./EventManager";
+import { globalEvents } from "./globalEvents";
+import {
+  MiddlewareStoreElementType,
+  Store,
+  TaskStoreElementType,
+} from "./Store";
+
+export class TaskRunner {
+  protected readonly runnerStore = new Map<
+    string,
+    (input: any) => Promise<any>
+  >();
+
+  constructor(
+    protected readonly store: Store,
+    protected readonly eventManager: EventManager
+  ) {}
+
+  /**
+   * 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
+   */
+  public async run<
+    TInput,
+    TOutput extends Promise<any>,
+    TDeps extends DependencyMapType
+  >(
+    task: ITask<TInput, TOutput, TDeps>,
+    input: TInput,
+    taskDependencies?: DependencyValuesType<TDeps>
+  ): Promise<TOutput | undefined> {
+    let runner = this.runnerStore.get(task.id);
+    if (!runner) {
+      const storeTask = this.store.tasks.get(task.id) as TaskStoreElementType;
+      const deps = taskDependencies || storeTask.computedDependencies;
+
+      runner = this.createRunnerWithMiddleware<TInput, TOutput, TDeps>(
+        task,
+        deps
+      );
+
+      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 });
+    await this.eventManager.emit(globalEvents.tasks.beforeRun, {
+      task,
+      input,
+    });
+
+    let error;
+    try {
+      // craft the next function starting from the first next function
+      const output = await runner(input);
+
+      await this.eventManager.emit(task.events.afterRun, { input, output });
+      await this.eventManager.emit(globalEvents.tasks.afterRun, {
+        task,
+        input,
+        output,
+      });
+
+      return output;
+    } catch (e) {
+      error = e;
+
+      // If you want to rewthrow the error, this should be done inside the onError event.
+      await this.eventManager.emit(task.events.onError, { error });
+      await this.eventManager.emit(globalEvents.tasks.onError, {
+        task,
+        error,
+      });
+
+      throw e;
+    }
+  }
+
+  /**
+   * Creates the function with the chain of middleware.
+   * @param task
+   * @param input
+   * @param taskDependencies
+   * @returns
+   */
+  protected createRunnerWithMiddleware<
+    TInput,
+    TOutput extends Promise<any>,
+    TDeps extends DependencyMapType
+  >(
+    task: ITask<TInput, TOutput, TDeps>,
+    taskDependencies: DependencyValuesType<{}>
+  ) {
+    // this is the final next()
+    let next = async (input) => {
+      return task.run.call(null, input, taskDependencies as any);
+    };
+
+    const existingMiddlewares = task.middleware;
+    const createdMiddlewares = [
+      ...this.store.getGlobalMiddlewares(existingMiddlewares.map((x) => x.id)),
+      ...existingMiddlewares,
+    ];
+
+    if (createdMiddlewares.length > 0) {
+      // we need to run the middleware in reverse order
+      // so we can chain the next function
+      for (let i = createdMiddlewares.length - 1; i >= 0; i--) {
+        const middleware = createdMiddlewares[i];
+        const storeMiddleware = this.store.middlewares.get(
+          middleware.id
+        ) as MiddlewareStoreElementType; // we know it exists because at this stage all sanity checks have been done.
+
+        const nextFunction = next;
+        next = async (input) => {
+          return storeMiddleware.middleware.run(
+            {
+              taskDefinition: task as any,
+              input,
+              next: nextFunction,
+            },
+            storeMiddleware.computedDependencies
+          );
+        };
+      }
+    }
+
+    return next;
+  }
+}

package/src/__tests__/EventManager.test.ts

@@ -0,0 +1,96 @@
+import { IEvent, IEventDefinition } from "../defs";
+import { EventManager } from "../EventManager";
+
+describe("EventManager", () => {
+  let eventManager: EventManager;
+
+  beforeEach(() => {
+    eventManager = new EventManager();
+  });
+
+  const testEvent: IEventDefinition<string> = {
+    id: "test-event",
+  };
+
+  const createEvent = (data: string): IEvent<string> => ({
+    id: testEvent.id,
+    data,
+  });
+
+  describe("emit", () => {
+    it("should emit an event and call the appropriate listeners", async () => {
+      const listener1 = jest.fn();
+      const listener2 = jest.fn();
+
+      eventManager.addListener(testEvent, listener1);
+      eventManager.addListener(testEvent, listener2);
+
+      await eventManager.emit(testEvent, "test data");
+
+      expect(listener1).toHaveBeenCalledWith(createEvent("test data"));
+      expect(listener2).toHaveBeenCalledWith(createEvent("test data"));
+    });
+
+    it("should respect the order of listeners", async () => {
+      const calls: number[] = [];
+      const listener1 = jest.fn(() => calls.push(1));
+      const listener2 = jest.fn(() => calls.push(2));
+      const listener3 = jest.fn(() => calls.push(3));
+
+      eventManager.addListener(testEvent, listener2, { order: 2 });
+      eventManager.addListener(testEvent, listener1, { order: 1 });
+      eventManager.addListener(testEvent, listener3, { order: 3 });
+
+      await eventManager.emit(testEvent, "test data");
+
+      expect(calls).toEqual([1, 2, 3]);
+    });
+
+    it("should apply filters to listeners", async () => {
+      const listener = jest.fn();
+      const filter = jest.fn((event: IEvent<string>) => event.data === "pass");
+
+      eventManager.addListener(testEvent, listener, { filter });
+
+      await eventManager.emit(testEvent, "pass");
+      await eventManager.emit(testEvent, "fail");
+
+      expect(listener).toHaveBeenCalledTimes(1);
+      expect(listener).toHaveBeenCalledWith(createEvent("pass"));
+    });
+  });
+
+  describe("addListener", () => {
+    it("should add a listener for a single event", () => {
+      const listener = jest.fn();
+      eventManager.addListener(testEvent, listener);
+
+      // @ts-ignore: Accessing private property for testing
+      expect(eventManager.listeners.get(testEvent.id)).toHaveLength(1);
+    });
+
+    it("should add a listener for multiple events", () => {
+      const listener = jest.fn();
+      const event1: IEventDefinition = { id: "event1" };
+      const event2: IEventDefinition = { id: "event2" };
+
+      eventManager.addListener([event1, event2], listener);
+
+      // @ts-ignore: Accessing private property for testing
+      expect(eventManager.listeners.get(event1.id)).toHaveLength(1);
+      // @ts-ignore: Accessing private property for testing
+      expect(eventManager.listeners.get(event2.id)).toHaveLength(1);
+    });
+  });
+
+  describe("addGlobalListener", () => {
+    it("should add a global listener", async () => {
+      const globalListener = jest.fn();
+      eventManager.addGlobalListener(globalListener);
+
+      await eventManager.emit(testEvent, "test data");
+
+      expect(globalListener).toHaveBeenCalledWith(createEvent("test data"));
+    });
+  });
+});

package/src/__tests__/ResourceInitializer.test.ts

@@ -0,0 +1,109 @@
+import { ResourceInitializer } from "../ResourceInitializer";
+import { Store } from "../Store";
+import { EventManager } from "../EventManager";
+import { defineResource } from "../define";
+
+describe("ResourceInitializer", () => {
+  let store: Store;
+  let eventManager: EventManager;
+  let resourceInitializer: ResourceInitializer;
+
+  beforeEach(() => {
+    eventManager = new EventManager();
+    store = new Store(eventManager);
+    resourceInitializer = new ResourceInitializer(store, eventManager);
+  });
+
+  it("should initialize a resource and emit events", async () => {
+    const mockResource = defineResource({
+      id: "testResource",
+      init: jest.fn().mockResolvedValue("initialized value"),
+    });
+
+    const mockConfig = undefined;
+    const mockDependencies = {};
+
+    const emitSpy = jest.spyOn(eventManager, "emit");
+
+    const result = await resourceInitializer.initializeResource(
+      mockResource,
+      mockConfig,
+      mockDependencies
+    );
+
+    expect(result).toBe("initialized value");
+    expect(mockResource.init).toHaveBeenCalledWith(
+      mockConfig,
+      mockDependencies
+    );
+    expect(emitSpy).toHaveBeenCalledWith(mockResource.events.beforeInit, {
+      config: mockConfig,
+    });
+    expect(emitSpy).toHaveBeenCalledWith(mockResource.events.afterInit, {
+      config: mockConfig,
+      value: "initialized value",
+    });
+  });
+
+  it("should handle errors and emit onError event", async () => {
+    const mockError = new Error("Initialization error");
+    const mockResource = defineResource({
+      id: "testResource",
+      init: jest.fn().mockRejectedValue(mockError),
+    });
+
+    const mockConfig = undefined;
+    const mockDependencies = {};
+
+    const emitSpy = jest.spyOn(eventManager, "emit");
+
+    let result;
+    try {
+      result = await resourceInitializer.initializeResource(
+        mockResource,
+        mockConfig,
+        mockDependencies
+      );
+    } catch (e) {}
+
+    expect(result).toBeUndefined();
+    expect(mockResource.init).toHaveBeenCalledWith(
+      mockConfig,
+      mockDependencies
+    );
+    expect(emitSpy).toHaveBeenCalledTimes(4);
+    expect(emitSpy).toHaveBeenCalledWith(mockResource.events.beforeInit, {
+      config: mockConfig,
+    });
+    expect(emitSpy).toHaveBeenCalledWith(mockResource.events.onError, {
+      error: mockError,
+    });
+  });
+
+  it("should handle resources without init function", async () => {
+    const mockResource = defineResource<number>({
+      id: "testResource",
+    });
+
+    const mockConfig = 42;
+    const mockDependencies = {};
+
+    const emitSpy = jest.spyOn(eventManager, "emit");
+
+    const result = await resourceInitializer.initializeResource(
+      mockResource,
+      mockConfig,
+      mockDependencies
+    );
+
+    expect(result).toBeUndefined();
+    expect(emitSpy).toHaveBeenCalledTimes(4);
+    expect(emitSpy).toHaveBeenCalledWith(mockResource.events.beforeInit, {
+      config: mockConfig,
+    });
+    expect(emitSpy).toHaveBeenCalledWith(mockResource.events.afterInit, {
+      config: mockConfig,
+      value: undefined,
+    });
+  });
+});