@bluelibs/runner 1.0.0

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

@@ -0,0 +1,217 @@
+import {
+  findCircularDependencies,
+  IDependentNode,
+} from "../../tools/findCircularDependencies";
+
+describe("checkCircularDependencies", () => {
+  test("should detect a simple cycle (A -> B -> C -> A)", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    const nodeB: IDependentNode = { id: "B", dependencies: {} };
+    const nodeC: IDependentNode = { id: "C", dependencies: {} };
+
+    nodeA.dependencies["B"] = nodeB;
+    nodeB.dependencies["C"] = nodeC;
+    nodeC.dependencies["A"] = nodeA;
+
+    const nodes: IDependentNode[] = [nodeA, nodeB, nodeC];
+    const result = findCircularDependencies(nodes);
+
+    expect(result.cycles).toEqual(["A -> B -> C -> A"]);
+    expect(result.missingDependencies).toEqual([]);
+  });
+
+  test("should detect multiple cycles", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    const nodeB: IDependentNode = { id: "B", dependencies: {} };
+    const nodeC: IDependentNode = { id: "C", dependencies: {} };
+    const nodeD: IDependentNode = { id: "D", dependencies: {} };
+
+    nodeA.dependencies["B"] = nodeB;
+    nodeB.dependencies["C"] = nodeC;
+    nodeC.dependencies["A"] = nodeA; // Cycle: A -> B -> C -> A
+    nodeC.dependencies["D"] = nodeD;
+    nodeD.dependencies["B"] = nodeB; // Cycle: B -> C -> D -> B
+
+    const nodes: IDependentNode[] = [nodeA, nodeB, nodeC, nodeD];
+    const result = findCircularDependencies(nodes);
+
+    // The order of cycles in the result array might vary
+    expect(result.cycles).toContain("A -> B -> C -> A");
+    expect(result.cycles).toContain("B -> C -> D -> B");
+    expect(result.cycles.length).toBe(2);
+    expect(result.missingDependencies).toEqual([]);
+  });
+
+  test("should return empty arrays when there are no cycles", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    const nodeB: IDependentNode = { id: "B", dependencies: {} };
+    const nodeC: IDependentNode = { id: "C", dependencies: {} };
+
+    nodeA.dependencies["B"] = nodeB;
+    nodeB.dependencies["C"] = nodeC;
+
+    const nodes: IDependentNode[] = [nodeA, nodeB, nodeC];
+    const result = findCircularDependencies(nodes);
+
+    expect(result.cycles).toEqual([]);
+    expect(result.missingDependencies).toEqual([]);
+  });
+
+  test("should detect a self-referential cycle (A -> A)", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    nodeA.dependencies["A"] = nodeA; // Cycle: A -> A
+
+    const nodes: IDependentNode[] = [nodeA];
+    const result = findCircularDependencies(nodes);
+
+    expect(result.cycles).toEqual(["A -> A"]);
+    expect(result.missingDependencies).toEqual([]);
+  });
+
+  test("should handle complex graphs with shared nodes", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    const nodeB: IDependentNode = { id: "B", dependencies: {} };
+    const nodeC: IDependentNode = { id: "C", dependencies: {} };
+    const nodeD: IDependentNode = { id: "D", dependencies: {} };
+    const nodeE: IDependentNode = { id: "E", dependencies: {} };
+
+    nodeA.dependencies["B"] = nodeB;
+    nodeB.dependencies["C"] = nodeC;
+    nodeC.dependencies["D"] = nodeD;
+    nodeD.dependencies["B"] = nodeB; // Cycle: B -> C -> D -> B
+    nodeC.dependencies["E"] = nodeE;
+    nodeE.dependencies["C"] = nodeC; // Cycle: C -> E -> C
+
+    const nodes: IDependentNode[] = [nodeA, nodeB, nodeC, nodeD, nodeE];
+    const result = findCircularDependencies(nodes);
+
+    expect(result.cycles).toContain("B -> C -> D -> B");
+    expect(result.cycles).toContain("C -> E -> C");
+    expect(result.cycles.length).toBe(2);
+    expect(result.missingDependencies).toEqual([]);
+  });
+
+  test("should handle multiple independent cycles", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    const nodeB: IDependentNode = { id: "B", dependencies: {} };
+    const nodeC: IDependentNode = { id: "C", dependencies: {} };
+    const nodeD: IDependentNode = { id: "D", dependencies: {} };
+    const nodeE: IDependentNode = { id: "E", dependencies: {} };
+    const nodeF: IDependentNode = { id: "F", dependencies: {} };
+
+    // Cycle 1: A -> B -> A
+    nodeA.dependencies["B"] = nodeB;
+    nodeB.dependencies["A"] = nodeA;
+
+    // Cycle 2: C -> D -> E -> C
+    nodeC.dependencies["D"] = nodeD;
+    nodeD.dependencies["E"] = nodeE;
+    nodeE.dependencies["C"] = nodeC;
+
+    // Cycle 3: F -> F
+    nodeF.dependencies["F"] = nodeF;
+
+    const nodes: IDependentNode[] = [nodeA, nodeB, nodeC, nodeD, nodeE, nodeF];
+    const result = findCircularDependencies(nodes);
+
+    expect(result.cycles).toContain("A -> B -> A");
+    expect(result.cycles).toContain("C -> D -> E -> C");
+    expect(result.cycles).toContain("F -> F");
+    expect(result.cycles.length).toBe(3);
+    expect(result.missingDependencies).toEqual([]);
+  });
+
+  test("should handle disconnected graphs", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    const nodeB: IDependentNode = { id: "B", dependencies: {} };
+    const nodeC: IDependentNode = { id: "C", dependencies: {} };
+    const nodeD: IDependentNode = { id: "D", dependencies: {} };
+
+    // Cycle 1: A -> B -> A
+    nodeA.dependencies["B"] = nodeB;
+    nodeB.dependencies["A"] = nodeA;
+
+    // Cycle 2: C -> D -> C
+    nodeC.dependencies["D"] = nodeD;
+    nodeD.dependencies["C"] = nodeC;
+
+    const nodes: IDependentNode[] = [nodeA, nodeB, nodeC, nodeD];
+    const result = findCircularDependencies(nodes);
+
+    expect(result.cycles).toContain("A -> B -> A");
+    expect(result.cycles).toContain("C -> D -> C");
+    expect(result.cycles.length).toBe(2);
+    expect(result.missingDependencies).toEqual([]);
+  });
+
+  test("should handle nodes with no dependencies", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    const nodeB: IDependentNode = { id: "B", dependencies: {} };
+
+    const nodes: IDependentNode[] = [nodeA, nodeB];
+    const result = findCircularDependencies(nodes);
+
+    expect(result.cycles).toEqual([]);
+    expect(result.missingDependencies).toEqual([]);
+  });
+
+  test("should handle dependencies that do not form cycles", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    const nodeB: IDependentNode = { id: "B", dependencies: {} };
+    const nodeC: IDependentNode = { id: "C", dependencies: {} };
+    const nodeD: IDependentNode = { id: "D", dependencies: {} };
+
+    nodeA.dependencies["B"] = nodeB;
+    nodeB.dependencies["C"] = nodeC;
+    nodeC.dependencies["D"] = nodeD;
+
+    const nodes: IDependentNode[] = [nodeA, nodeB, nodeC, nodeD];
+    const result = findCircularDependencies(nodes);
+
+    expect(result.cycles).toEqual([]);
+    expect(result.missingDependencies).toEqual([]);
+  });
+
+  test("should report missing dependencies", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    // nodeB is missing
+    nodeA.dependencies["B"] = undefined as any; // Force undefined dependency
+
+    const nodes: IDependentNode[] = [nodeA];
+    const result = findCircularDependencies(nodes);
+
+    expect(result.cycles).toEqual([]);
+    expect(result.missingDependencies).toEqual([
+      { nodeId: "A", dependencyId: "B" },
+    ]);
+  });
+
+  test("should handle complex graph with multiple overlapping cycles", () => {
+    const nodeA: IDependentNode = { id: "A", dependencies: {} };
+    const nodeB: IDependentNode = { id: "B", dependencies: {} };
+    const nodeC: IDependentNode = { id: "C", dependencies: {} };
+    const nodeD: IDependentNode = { id: "D", dependencies: {} };
+    const nodeE: IDependentNode = { id: "E", dependencies: {} };
+    const nodeF: IDependentNode = { id: "F", dependencies: {} };
+
+    // Construct cycles:
+    // A -> B -> C -> A
+    // C -> D -> E -> F -> C
+
+    nodeA.dependencies["B"] = nodeB;
+    nodeB.dependencies["C"] = nodeC;
+    nodeC.dependencies["A"] = nodeA;
+    nodeC.dependencies["D"] = nodeD;
+    nodeD.dependencies["E"] = nodeE;
+    nodeE.dependencies["F"] = nodeF;
+    nodeF.dependencies["C"] = nodeC;
+
+    const nodes: IDependentNode[] = [nodeA, nodeB, nodeC, nodeD, nodeE, nodeF];
+    const result = findCircularDependencies(nodes);
+
+    expect(result.cycles).toContain("A -> B -> C -> A");
+    expect(result.cycles).toContain("C -> D -> E -> F -> C");
+    expect(result.cycles.length).toBe(2);
+    expect(result.missingDependencies).toEqual([]);
+  });
+});

package/src/define.ts

@@ -0,0 +1,142 @@
+import {
+  ITask,
+  ITaskDefinition,
+  IResource,
+  IResourceWithConfig,
+  IResourceDefinintion,
+  IEventDefinition,
+  IMiddlewareDefinition,
+  symbols,
+  DependencyMapType,
+  DependencyValuesType,
+  IMiddleware,
+} from "./defs";
+import { Errors } from "./errors";
+
+export function defineTask<
+  Input = undefined,
+  Output extends Promise<any> = any,
+  Deps extends DependencyMapType = any,
+  Test = any
+>(
+  config: ITaskDefinition<Input, Output, Deps, Test>
+): ITask<Input, Output, Deps, Test> {
+  const autorun: any = {};
+  // if (config.autorun) {
+  //   if (config.autorun.on) {
+  //     autorun.on = Array.isArray(config.autorun.on);
+  //     autorun.schedule = config.autorun.schedule;
+  //   }
+  // }
+
+  return {
+    [symbols.task]: true,
+    id: config.id,
+    dependencies: config.dependencies || ({} as Deps),
+    middleware: config.middleware || [],
+    run: config.run,
+    on: config.on,
+    events: {
+      beforeRun: defineEvent({
+        id: `${config.id}.beforeRun`,
+      }),
+      afterRun: defineEvent({
+        id: `${config.id}.afterRun`,
+      }),
+      onError: defineEvent({
+        id: `${config.id}.onError`,
+      }),
+    },
+    // autorun,
+  };
+}
+
+export function defineResource<
+  TConfig = void,
+  TValue = any,
+  TDeps extends DependencyMapType = {}
+>(
+  constConfig: IResourceDefinintion<TConfig, TValue, TDeps>
+): IResource<TConfig, TValue, TDeps> {
+  return {
+    [symbols.resource]: true,
+    id: constConfig.id,
+    dependencies: constConfig.dependencies,
+    hooks: constConfig.hooks || [],
+    register: constConfig.register || [],
+    init: constConfig.init,
+    with: function (config: TConfig) {
+      return {
+        [symbols.resourceWithConfig]: true,
+        resource: this,
+        config,
+      };
+    },
+
+    events: {
+      beforeInit: defineEvent({
+        id: `${constConfig.id}.beforeInit`,
+      }),
+      afterInit: defineEvent({
+        id: `${constConfig.id}.afterInit`,
+      }),
+      onError: defineEvent({
+        id: `${constConfig.id}.onError`,
+      }),
+    },
+  };
+}
+
+export function defineEvent<TPayload = any>(
+  config: IEventDefinition<TPayload>
+): IEventDefinition<TPayload> {
+  return {
+    [symbols.event]: true,
+    ...config,
+  };
+}
+
+export function defineMiddleware<TDeps extends DependencyMapType = {}>(
+  config: IMiddlewareDefinition<TDeps>
+): IMiddleware<TDeps> {
+  const object = {
+    [symbols.middleware]: true,
+    ...config,
+    dependencies: config.dependencies || ({} as TDeps),
+  };
+
+  return {
+    ...object,
+    global() {
+      return {
+        ...object,
+        [symbols.middlewareGlobal]: true,
+        global() {
+          throw Errors.middlewareAlreadyGlobal(config.id);
+        },
+      };
+    },
+  };
+}
+
+export function isTask(definition: any): definition is ITask {
+  return definition && definition[symbols.task];
+}
+
+export function isResource(definition: any): definition is IResource {
+  return definition && definition[symbols.resource];
+}
+
+export function isResourceWithConfig(
+  definition: any
+): definition is IResourceWithConfig {
+  return definition && definition[symbols.resourceWithConfig];
+}
+
+export function isEvent(definition: any): definition is IEventDefinition {
+  return definition && definition[symbols.event];
+}
+
+export function isMiddleware(definition: any): definition is IMiddleware {
+  return definition && definition[symbols.middleware];
+}

package/src/defs.ts

@@ -0,0 +1,221 @@
+export const symbols = {
+  task: Symbol("task"),
+  resource: Symbol("resource"),
+  resourceWithConfig: Symbol("resourceWithConfig"),
+  event: Symbol("event"),
+  middleware: Symbol("middleware"),
+  middlewareGlobal: Symbol("middlewareGlobal"),
+};
+
+export interface IMeta {
+  title?: string;
+  description?: string;
+  tags: string[];
+}
+
+export interface ITaskMeta extends IMeta {}
+export interface IResourceMeta extends IMeta {}
+export interface IEventMeta extends IMeta {}
+export interface IMiddlewareMeta extends IMeta {}
+
+// DependencyMap types
+export type DependencyMapType = Record<
+  string,
+  ITask | IResource | IEventDefinition
+>;
+
+export type DependencyValueType<T> = T extends ITask<
+  infer I,
+  infer O,
+  /** The infer D, while not used is crucial for making this work correctly, otherwise it forces input: unknown to a dependency that has a dependency. */
+  infer D
+>
+  ? (...args: I extends unknown ? [] : [I]) => O
+  : T extends IResource<any, infer V>
+  ? V
+  : T extends IEventDefinition<infer P>
+  ? (input: P) => Promise<void> | never
+  : never;
+
+export type DependencyValuesType<T extends DependencyMapType> = {
+  [K in keyof T]: DependencyValueType<T[K]>;
+};
+
+// RegisterableItems Type with Conditional Inclusion
+export type RegisterableItems =
+  | IResource<void> // Always include IResource<void>
+  | IResourceWithConfig<any>
+  | ITaskDefinition
+  | IMiddlewareDefinition
+  | IEventDefinition;
+
+export interface ITaskDefinition<
+  TInput = any,
+  TOutput extends Promise<any> = any,
+  TDependencies extends DependencyMapType = {},
+  TEventDefinitionInput = null
+> {
+  id: string;
+  dependencies?: TDependencies | (() => TDependencies);
+  middleware?: IMiddlewareDefinition[];
+  on?: IEventDefinition<TEventDefinitionInput>;
+  meta?: ITaskMeta;
+  run: (
+    input: TEventDefinitionInput extends null ? TInput : TEventDefinitionInput,
+    dependencies: DependencyValuesType<TDependencies>
+  ) => TOutput;
+}
+
+export type BeforeRunEventPayload<TInput> = {
+  input: TInput;
+};
+
+export type AfterRunEventPayload<TInput, TOutput> = {
+  input: TInput;
+  output: TOutput;
+};
+
+export type OnErrorEventPayload = {
+  error: any;
+};
+
+export type BeforeInitEventPayload<TConfig> = {
+  config: TConfig;
+};
+
+export type AfterInitEventPayload<TConfig, TValue> = {
+  config: TConfig;
+  value: TValue;
+};
+
+/**
+ * This is the response after the definition has been prepared. TODO: better naming?
+ */
+export interface ITask<
+  TInput = any,
+  TOutput extends Promise<any> = any,
+  TDependencies extends DependencyMapType = {},
+  TEventDefinitionInput = null
+> extends ITaskDefinition<
+    TInput,
+    TOutput,
+    TDependencies,
+    TEventDefinitionInput
+  > {
+  dependencies: TDependencies | (() => TDependencies);
+  computedDependencies?: DependencyValuesType<TDependencies>;
+  middleware: IMiddlewareDefinition[];
+  /**
+   * These events are automatically populated after the task has been defined.
+   */
+  events: {
+    beforeRun: IEventDefinition<BeforeRunEventPayload<TInput>>;
+    afterRun: IEventDefinition<AfterRunEventPayload<TInput, TOutput>>;
+    onError: IEventDefinition<OnErrorEventPayload>;
+  };
+}
+// Resource interfaces
+export interface IResourceDefinintion<
+  TConfig = void,
+  TValue = unknown,
+  TDependencies extends DependencyMapType = {}
+> {
+  id: string;
+  dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+  hooks?:
+    | IHookDefinition<TDependencies>[]
+    | ((config: TConfig) => IHookDefinition<TDependencies>[]);
+  register?:
+    | Array<RegisterableItems>
+    | ((config: TConfig) => Array<RegisterableItems>);
+  init?: (
+    config: TConfig,
+    dependencies: DependencyValuesType<TDependencies>
+  ) => Promise<TValue>;
+  meta?: IResourceMeta;
+}
+
+export interface IResource<
+  TConfig = void,
+  TValue = any,
+  TDependencies extends DependencyMapType = any
+> extends IResourceDefinintion<TConfig, TValue, TDependencies> {
+  with(config: TConfig): IResourceWithConfig<TConfig, TValue, TDependencies>;
+  register:
+    | Array<RegisterableItems>
+    | ((config: TConfig) => Array<RegisterableItems>);
+  /**
+   * These events are automatically populated after the task has been defined.
+   */
+  events: {
+    beforeInit: IEventDefinition<BeforeInitEventPayload<TConfig>>;
+    afterInit: IEventDefinition<AfterInitEventPayload<TConfig, TValue>>;
+    onError: IEventDefinition<OnErrorEventPayload>;
+  };
+  hooks:
+    | IHookDefinition<TDependencies>[]
+    | ((config: TConfig) => IHookDefinition<TDependencies>[]);
+}
+
+export interface IResourceWithConfig<
+  TConfig = any,
+  TValue = any,
+  TDependencies extends DependencyMapType = any
+> {
+  resource: IResource<TConfig, TValue, TDependencies>;
+  config: TConfig;
+}
+
+export interface IEvent<TPayload = any> {
+  id: string;
+  data: TPayload;
+}
+
+export type EventHandlerType<T = any> = (
+  event: IEvent<T>
+) => any | Promise<any>;
+
+// Other necessary interfaces
+export interface IEventDefinition<TPayload = void> {
+  id: string;
+  meta?: IEventMeta;
+}
+
+export interface IMiddlewareDefinition<
+  TDependencies extends DependencyMapType = any
+> {
+  id: string;
+  dependencies?: TDependencies | (() => TDependencies);
+  run: (
+    input: IMiddlewareExecutionInput,
+    dependencies: DependencyValuesType<TDependencies>
+  ) => Promise<any>;
+  meta?: IMiddlewareMeta;
+}
+
+export interface IMiddleware<TDependencies extends DependencyMapType = any>
+  extends IMiddlewareDefinition<TDependencies> {
+  dependencies: TDependencies | (() => TDependencies);
+  global(): IMiddleware<TDependencies>;
+}
+
+export interface IMiddlewareDefinitionConfigured<
+  C extends Record<string, any> = {}
+> {
+  middleware: IMiddleware<C>;
+  config?: C;
+}
+
+export interface IMiddlewareExecutionInput {
+  taskDefinition?: ITask;
+  input: any;
+  next: (input?: any) => Promise<any>;
+}
+
+export interface IHookDefinition<D extends DependencyMapType = {}> {
+  event: IEventDefinition;
+  run: (
+    event: IEvent,
+    dependencies: DependencyValuesType<D>
+  ) => Promise<void> | void;
+}

package/src/errors.ts

@@ -0,0 +1,22 @@
+import { ITask, IResource } from "./defs";
+
+export const Errors = {
+  duplicateRegistration: (type: string, id: string) =>
+    new Error(`${type} "${id}" already registered`),
+
+  dependencyNotFound: (key: string) =>
+    new Error(
+      `Dependency ${key} not found. Did you forget to register it through a resource?`
+    ),
+
+  unknownItemType: (item: any) => new Error(`Unknown item type: ${item}`),
+
+  circularDependencies: (cycles: string[]) =>
+    new Error(`Circular dependencies detected: ${cycles.join(", ")}`),
+
+  eventNotFound: (id: string) =>
+    new Error(`Event "${id}" not found. Did you forget to register it?`),
+
+  middlewareAlreadyGlobal: (id: string) =>
+    new Error("Cannot call global on a global middleware: " + id),
+};

package/src/globalEvents.ts

@@ -0,0 +1,64 @@
+import { defineEvent } from "./define";
+import { ITask, IResource } from "./defs";
+
+export const globalEvents = {
+  beforeInit: defineEvent({
+    id: "global.beforeInit",
+  }),
+  afterInit: defineEvent({
+    id: "global.afterInit",
+  }),
+  tasks: {
+    beforeRun: defineEvent<{
+      task: ITask<any, any, any>;
+      input: any;
+    }>({
+      id: "global.tasks.beforeRun",
+    }),
+    afterRun: defineEvent<{
+      task: ITask<any, any, any>;
+      input: any;
+      output: any;
+    }>({
+      id: "global.tasks.afterRun",
+    }),
+    onError: defineEvent<{
+      error: Error;
+      task: ITask<any, any, any>;
+    }>({
+      id: "global.tasks.onError",
+    }),
+  },
+  resources: {
+    beforeInit: defineEvent<{
+      resource: IResource<any, any, any>;
+      config: any;
+    }>({
+      id: "global.resources.beforeInit",
+    }),
+    afterInit: defineEvent<{
+      resource: IResource<any, any, any>;
+      config: any;
+      value: any;
+    }>({
+      id: "global.resources.afterInit",
+    }),
+    onError: defineEvent<{
+      error: Error;
+      resource: IResource<any, any, any>;
+    }>({
+      id: "global.resources.onError",
+    }),
+  },
+};
+
+export const globalEventsArray = [
+  globalEvents.beforeInit,
+  globalEvents.afterInit,
+  globalEvents.tasks.beforeRun,
+  globalEvents.tasks.afterRun,
+  globalEvents.tasks.onError,
+  globalEvents.resources.beforeInit,
+  globalEvents.resources.afterInit,
+  globalEvents.resources.onError,
+];

package/src/globalResources.ts

@@ -0,0 +1,19 @@
+import { defineResource } from "./define";
+import { EventManager } from "./EventManager";
+import { Store } from "./Store";
+import { TaskRunner } from "./TaskRunner";
+
+export const globalResources = {
+  store: defineResource<Store>({
+    id: "global.store",
+    init: async (store) => store,
+  }),
+  eventManager: defineResource<EventManager>({
+    id: "global.eventManager",
+    init: async (em) => em,
+  }),
+  taskRunner: defineResource<TaskRunner>({
+    id: "global.taskRunner",
+    init: async (runner) => runner,
+  }),
+};