@bluelibs/runner 3.4.2 → 4.0.1

package/src/models/StoreValidator.ts

@@ -1,43 +0,0 @@
-import { DependencyNotFoundError, DuplicateRegistrationError } from "../errors";
-import {
-  TaskStoreElementType,
-  MiddlewareStoreElementType,
-  ResourceStoreElementType,
-  EventStoreElementType,
-} from "./StoreTypes";
-
-export class StoreValidator {
-  constructor(
-    private tasks: Map<string | symbol, TaskStoreElementType>,
-    private resources: Map<string | symbol, ResourceStoreElementType>,
-    private events: Map<string | symbol, EventStoreElementType>,
-    private middlewares: Map<string | symbol, MiddlewareStoreElementType>
-  ) {}
-
-  checkIfIDExists(id: string | symbol): void | never {
-    if (this.tasks.has(id)) {
-      throw new DuplicateRegistrationError("Task", id);
-    }
-    if (this.resources.has(id)) {
-      throw new DuplicateRegistrationError("Resource", id);
-    }
-    if (this.events.has(id)) {
-      throw new DuplicateRegistrationError("Event", id);
-    }
-    if (this.middlewares.has(id)) {
-      throw new DuplicateRegistrationError("Middleware", id);
-    }
-  }
-
-  runSanityChecks() {
-    for (const task of this.tasks.values()) {
-      task.task.middleware.forEach((middleware) => {
-        if (!this.middlewares.has(middleware.id)) {
-          throw new DependencyNotFoundError(
-            `Middleware ${middleware.id.toString()} in Task ${task.task.id.toString()}`
-          );
-        }
-      });
-    }
-  }
-}

package/src/models/TaskRunner.ts

@@ -1,203 +0,0 @@
-import { DependencyMapType, DependencyValuesType, ITask } from "../defs";
-import { EventManager } from "./EventManager";
-import { globalEvents } from "../globals/globalEvents";
-import { Store } from "./Store";
-import { MiddlewareStoreElementType } from "./StoreTypes";
-import { Logger } from "./Logger";
-import { ValidationError } from "../errors";
-
-export class TaskRunner {
-  protected readonly runnerStore = new Map<
-    string | symbol,
-    (input: any) => Promise<any>
-  >();
-
-  constructor(
-    protected readonly store: Store,
-    protected readonly eventManager: EventManager,
-    protected readonly logger: Logger
-  ) {}
-
-  /**
-   * 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
-   */
-  public async run<
-    TInput,
-    TOutput extends Promise<any>,
-    TDeps extends DependencyMapType
-  >(
-    task: ITask<TInput, TOutput, TDeps>,
-    input: TInput
-  ): Promise<TOutput | undefined> {
-    let runner = this.runnerStore.get(task.id);
-    if (!runner) {
-      runner = this.createRunnerWithMiddleware<TInput, TOutput, TDeps>(task);
-
-      this.runnerStore.set(task.id, runner);
-    }
-
-    const isGlobalEventListener = task.on === "*";
-
-    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(
-        globalEvents.tasks.beforeRun,
-        {
-          task,
-          input,
-        },
-        task.id
-      );
-    }
-
-    let error;
-    try {
-      // craft the next function starting from the first next function
-      const result = {
-        output: await runner(input),
-      };
-      const setOutput = (newOutput: any) => {
-        result.output = newOutput;
-      };
-
-      // If it's a global event listener, we stop emitting so we don't get into an infinite loop.
-      if (!isGlobalEventListener) {
-        await this.eventManager.emit(
-          task.events.afterRun,
-          {
-            input,
-            get output() {
-              return result.output;
-            },
-            setOutput,
-          },
-          task.id
-        );
-      }
-
-      if (
-        !isGlobalEventListener &&
-        task.on !== globalEvents.tasks.beforeRun &&
-        task.on !== globalEvents.tasks.afterRun
-      ) {
-        // If it's a lifecycle listener we prevent from emitting further events.
-        await this.eventManager.emit(
-          globalEvents.tasks.afterRun,
-          {
-            task,
-            input,
-            get output() {
-              return result.output;
-            },
-            setOutput,
-          },
-          task.id
-        );
-      }
-
-      return result.output;
-    } catch (e) {
-      let isSuppressed = false;
-      function suppress() {
-        isSuppressed = true;
-      }
-
-      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, suppress },
-        task.id
-      );
-      await this.eventManager.emit(
-        globalEvents.tasks.onError,
-        {
-          task,
-          error,
-          suppress,
-        },
-        task.id
-      );
-
-      if (!isSuppressed) 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>) {
-    const storeTask = this.store.tasks.get(task.id);
-
-    // this is the final next()
-    let next = async (input: any) => {
-      // Validate input with schema if provided
-      if (task.inputSchema) {
-        try {
-          input = task.inputSchema.parse(input);
-        } catch (error) {
-          throw new ValidationError("Task input", task.id, error instanceof Error ? error : new Error(String(error)));
-        }
-      }
-      
-      return task.run.call(null, input, storeTask?.computedDependencies as any);
-    };
-
-    const existingMiddlewares = task.middleware;
-    const createdMiddlewares = [
-      ...this.store.getEverywhereMiddlewareForTasks(
-        existingMiddlewares.map((x) => x.id)
-      ),
-      ...existingMiddlewares,
-    ];
-
-    if (createdMiddlewares.length === 0) {
-      return next;
-    }
-
-    // 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(
-          {
-            task: {
-              definition: task as any,
-              input,
-            },
-            next: nextFunction,
-          },
-          storeMiddleware.computedDependencies,
-          middleware.config
-        );
-      };
-    }
-
-    return next;
-  }
-}

package/src/models/index.ts

@@ -1,8 +0,0 @@
-export * from "./DependencyProcessor";
-export * from "./EventManager";
-export * from "./Logger";
-export * from "./Store";
-export * from "./TaskRunner";
-export * from "./ResourceInitializer";
-export * from "./Semaphore";
-export * from "./Queue";

package/src/run.ts

@@ -1,116 +0,0 @@
-import { TaskRunner } from "./models/TaskRunner";
-import {
-  DependencyMapType,
-  ITaskDefinition,
-  IResourceDefinition,
-  IEventDefinition,
-  IMiddlewareDefinition,
-  DependencyValuesType,
-  IResource,
-} from "./defs";
-import { DependencyProcessor } from "./models/DependencyProcessor";
-import { EventManager } from "./models/EventManager";
-import { globalEvents } from "./globals/globalEvents";
-import { Store } from "./models/Store";
-import { findCircularDependencies } from "./tools/findCircularDependencies";
-import { CircularDependenciesError } from "./errors";
-import { globalResources } from "./globals/globalResources";
-import { Logger } from "./models/Logger";
-
-export type ResourcesStoreElementType<
-  C = any,
-  V extends Promise<any> = any,
-  D extends DependencyMapType = {}
-> = {
-  resource: IResourceDefinition<C, V, D>;
-  computedDependencies?: DependencyValuesType<D>;
-  config: C;
-  value: V;
-};
-
-export type TasksStoreElementType<
-  Input = any,
-  Output extends Promise<any> = any,
-  D extends DependencyMapType = {}
-> = {
-  task: ITaskDefinition<Input, Output, D>;
-  computedDependencies?: DependencyValuesType<D>;
-};
-
-export type MiddlewareStoreElementType = {
-  middleware: IMiddlewareDefinition;
-};
-
-export type EventStoreElementType = {
-  event: IEventDefinition;
-};
-
-export type RunnerState = {
-  tasks: Record<string, TasksStoreElementType>;
-  resources: Record<string, ResourcesStoreElementType>;
-  events: Record<string, EventStoreElementType>;
-  middleware: Record<string, MiddlewareStoreElementType>;
-};
-
-export async function run<C, V>(
-  resource: IResource<C, V extends Promise<any> ? V : Promise<any>>,
-  config?: C
-): Promise<{
-  value: V extends Promise<infer U> ? U : V;
-  dispose: () => Promise<void>;
-}> {
-  const eventManager = new EventManager();
-
-  // ensure for logger, that it can be used only after: computeAllDependencies() has executed
-  const logger = new Logger(eventManager);
-
-  const store = new Store(eventManager, logger);
-  const taskRunner = new TaskRunner(store, eventManager, logger);
-  const processor = new DependencyProcessor(
-    store,
-    eventManager,
-    taskRunner,
-    logger
-  );
-
-  // 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
-  const dependentNodes = store.getDependentNodes();
-  const circularDependencies = findCircularDependencies(dependentNodes);
-  if (circularDependencies.cycles.length > 0) {
-    throw new CircularDependenciesError(circularDependencies.cycles);
-  }
-
-  // the overrides that were registered now will override the other registered resources
-  await store.processOverrides();
-
-  // a form of hooking, we create the events for all tasks and store them so they can be referenced
-  await store.storeEventsForAllTasks();
-  await processor.attachListeners();
-  await processor.computeAllDependencies();
-
-  // After this stage, logger print policy could have been set.
-  await logger.debug("All elements have been initalized..");
-
-  // Now we can safely compute dependencies without being afraid of an infinite loop.
-  // The hooking part is done here.
-  await eventManager.emit(globalEvents.beforeInit, null, resource.id);
-
-  // Now we can initialise the root resource
-  await processor.initializeRoot();
-
-  await eventManager.emit(globalEvents.afterInit, null, resource.id);
-  await logger.debug("System initialized and operational.");
-
-  // disallow manipulation or attaching more
-  store.lock();
-
-  return {
-    value: store.root.value,
-    dispose: () => store.dispose(),
-  };
-}

package/src/testing.ts

@@ -1,66 +0,0 @@
-import { defineResource } from "./define";
-import { globalResources } from "./globals/globalResources";
-import {
-  IResource,
-  IResourceWithConfig,
-  IMiddleware,
-  ITask,
-  RegisterableItems,
-  IEvent,
-  IEventEmission,
-  DependencyMapType,
-  DependencyValuesType,
-} from "./defs";
-import { EventManager, Logger, Store, TaskRunner } from "./models";
-
-let testResourceCounter = 0;
-
-/**
- * Helper to create a minimal test harness resource that wraps a root app (or any registerable)
- * and exposes convenient testing utilities while running the full ecosystem
- * (registration, overrides, middleware, events) without modifying the core API.
- */
-export function createTestResource(
-  root: RegisterableItems,
-  options?: {
-    overrides?: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
-  }
-): IResource<void, Promise<ReturnType<typeof buildTestFacade>>> {
-  return defineResource({
-    id: `tests.createTestResource.${++testResourceCounter}`,
-    register: [root],
-    overrides: options?.overrides || [],
-    dependencies: {
-      taskRunner: globalResources.taskRunner,
-      store: globalResources.store,
-      logger: globalResources.logger,
-      eventManager: globalResources.eventManager,
-    },
-    async init(_, deps) {
-      return buildTestFacade(deps);
-    },
-  });
-}
-
-function buildTestFacade(deps: {
-  taskRunner: TaskRunner;
-  store: Store;
-  logger: Logger;
-  eventManager: EventManager;
-}) {
-  return {
-    // Run a task within the fully initialized ecosystem
-    runTask: <I, O extends Promise<any>, D extends DependencyMapType>(
-      task: ITask<I, O, D>,
-      input: I
-    ): Promise<Awaited<O> | undefined> =>
-      deps.taskRunner.run(task, input) as any,
-    // Access a resource value by id (string or symbol)
-    getResource: (id: string | symbol) => deps.store.resources.get(id)?.value,
-    // Expose internals when needed in tests (not recommended for app usage)
-    taskRunner: deps.taskRunner,
-    store: deps.store,
-    logger: deps.logger,
-    eventManager: deps.eventManager,
-  };
-}

package/src/tools/findCircularDependencies.ts

@@ -1,69 +0,0 @@
-/**
- * A node that has dependencies.
- */
-export interface IDependentNode {
-  id: string;
-  dependencies: Record<string, IDependentNode>;
-}
-
-interface FindCircularDependenciesResult {
-  cycles: string[];
-  missingDependencies: Array<{ nodeId: string; dependencyId: string }>;
-}
-
-export function findCircularDependencies(
-  nodes: IDependentNode[]
-): FindCircularDependenciesResult {
-  const result: FindCircularDependenciesResult = {
-    cycles: [],
-    missingDependencies: [],
-  };
-  const visited: Set<string> = new Set();
-  const stack: Set<string> = new Set();
-  const path: string[] = [];
-
-  function dfs(node: IDependentNode): void {
-    if (stack.has(node.id)) {
-      const cycleStartIndex = path.indexOf(node.id);
-      const cycle = path.slice(cycleStartIndex).concat(node.id).join(" -> ");
-      result.cycles.push(cycle);
-      return;
-    }
-
-    if (visited.has(node.id)) return;
-
-    visited.add(node.id);
-    stack.add(node.id);
-    path.push(node.id);
-
-    if (node.dependencies && typeof node.dependencies === "object") {
-      for (const [depKey, dependentNode] of Object.entries(node.dependencies)) {
-        if (!dependentNode) {
-          result.missingDependencies.push({
-            nodeId: node.id,
-            dependencyId: depKey,
-          });
-          continue;
-        }
-        dfs(dependentNode);
-      }
-    } else {
-      result.missingDependencies.push({
-        nodeId: node.id,
-        dependencyId: "unknown",
-      });
-    }
-
-    stack.delete(node.id);
-    path.pop();
-  }
-
-  for (const node of nodes) {
-    if (!visited.has(node.id)) {
-      dfs(node);
-    }
-  }
-
-  result.cycles = Array.from(new Set(result.cycles)); // Remove duplicate cycles
-  return result;
-}

package/src/tools/getCallerFile.ts

@@ -1,96 +0,0 @@
-export function getCallerFile(): string {
-  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 as string; // Return the file name of the caller above
-  } finally {
-    Error.prepareStackTrace = originalFunc;
-  }
-}
-
-/**
- * Gets a file path, looks at all the parts between current path and 'src' and generates a unique symbol based on that.
- * If there is no 'src' to be found, it will rely on using the last 4 parts of the path.
- * This is useful for generating unique IDs for tasks, resources, etc.
- * @param filePath
- * @returns
- */
-export function generateCallerIdFromFile(
-  filePath: string,
-  suffix: string = "",
-  fallbackParts: number = 4
-): symbol {
-  // Normalize paths for consistency across platforms
-  const normalizedPath = filePath.replace(/\\/g, "/");
-  const cwdNormalized = process.cwd().replace(/\\/g, "/");
-
-  const parts = normalizedPath.split("/");
-  const nodeModulesIndex = parts.lastIndexOf("node_modules");
-
-  let relevantParts: string[];
-
-  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);
-  }
-
-  if (relevantParts.length > 0) {
-    const lastPartIndex = relevantParts.length - 1;
-    const lastPart = relevantParts[lastPartIndex];
-    const dotIndex = lastPart.lastIndexOf(".");
-    if (dotIndex !== -1 && dotIndex > 0) {
-      const extension = lastPart.substring(dotIndex + 1);
-      const knownExtensions = ["ts", "js", "tsx", "jsx", "json", "node"];
-      if (knownExtensions.includes(extension)) {
-        relevantParts[lastPartIndex] = lastPart.substring(0, dotIndex);
-      }
-    }
-  }
-
-  const id = relevantParts.join(".");
-  const lastPart =
-    relevantParts.length > 0 ? relevantParts[relevantParts.length - 1] : "";
-
-  let finalId = id;
-  if (suffix && !lastPart.includes(suffix)) {
-    finalId += "." + suffix;
-  }
-
-  return Symbol(finalId);
-}