@bluelibs/runner 2.2.4 → 3.1.0

package/src/defs.ts

@@ -1,3 +1,8 @@
+import { index } from ".";
+import { MiddlewareEverywhereOptions } from "./define";
+
+export { ICacheInstance } from "./globals/middleware/cache.middleware";
+
 export const symbolTask: unique symbol = Symbol("runner.task");
 export const symbolResource: unique symbol = Symbol("runner.resource");
 export const symbolResourceWithConfig: unique symbol = Symbol(
@@ -5,20 +10,39 @@ export const symbolResourceWithConfig: unique symbol = Symbol(
 );
 export const symbolEvent: unique symbol = Symbol("runner.event");
 export const symbolMiddleware: unique symbol = Symbol("runner.middleware");
+export const symbolMiddlewareConfigured: unique symbol = Symbol(
+  "runner.middlewareConfigured"
+);
 export const symbolMiddlewareGlobal: unique symbol = Symbol(
   "runner.middlewareGlobal"
 );
+export const symbolMiddlewareEverywhereTasks: unique symbol = Symbol(
+  "runner.middlewareGlobalTasks"
+);
+export const symbolMiddlewareEverywhereResources: unique symbol = Symbol(
+  "runner.middlewareGlobalResources"
+);
 
 export const symbolFilePath: unique symbol = Symbol("runner.filePath");
+export const symbolDispose: unique symbol = Symbol("runner.dispose");
+export const symbolStore: unique symbol = Symbol("runner.store");
+
+export const symbolIndexResource: unique symbol = Symbol(
+  "runner.indexResource"
+);
 
 export const symbols = {
   task: symbolTask,
   resource: symbolResource,
   resourceWithConfig: symbolResourceWithConfig,
+  indexResource: symbolIndexResource,
   event: symbolEvent,
   middleware: symbolMiddleware,
-  middlewareGlobal: symbolMiddlewareGlobal,
+  middlewareEverywhereTasks: symbolMiddlewareEverywhereTasks,
+  middlewareEverywhereResources: symbolMiddlewareEverywhereResources,
   filePath: symbolFilePath,
+  dispose: symbolDispose,
+  store: symbolStore,
 };
 
 export interface IMeta {
@@ -44,12 +68,23 @@ type ExtractTaskOutput<T> = T extends ITask<any, infer O, infer D> ? O : never;
 type ExtractResourceValue<T> = T extends IResource<any, infer V, infer D>
   ? V
   : never;
-type ExtractEventParams<T> = T extends IEventDefinition<infer P> ? P : never;
 
-// Helper Types for Dependency Value Construction
+type ExtractEventParams<T> = T extends IEvent<infer P> ? P : never;
+
+/**
+ * This represents a task dependency function that can be called with or without parameters.
+ */
 type TaskDependency<I, O> = (...args: I extends null | void ? [] : [I]) => O;
+/**
+ * This represents the resource's value type.
+ */
 type ResourceDependency<V> = V;
-type EventDependency<P> = (input: P) => Promise<void>;
+/**
+ * This represents an event emission function that can be called with or without parameters.
+ */
+type EventDependency<P> = P extends void
+  ? (() => Promise<void>) & ((input?: Record<string, never>) => Promise<void>)
+  : (input: P) => Promise<void>;
 
 // Main DependencyValueType Definition
 export type DependencyValueType<T> = T extends ITask<any, any, any>
@@ -64,33 +99,19 @@ 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<T = any> =
   | IResourceWithConfig<any>
-  // | IResource<void, any, any>
-  | IResource<OptionalOrVoidOrAnything<T>, any, any>
-  | ITaskDefinition<any, any, any, any>
-  | IMiddlewareDefinition<any>
-  | IEventDefinition<any>;
+  | IResource<void, any, any, any> // For void configs
+  | IResource<{ [K in any]?: any }, any, any, any> // For optional config
+  | ITask<any, any, any, any>
+  | IMiddleware<any>
+  | IEvent<any>;
+
+export type MiddlewareAttachments =
+  | IMiddleware<void>
+  | IMiddleware<{ [K in any]?: any }>
+  | IMiddlewareConfigured<any>;
 
 export interface ITaskDefinition<
   TInput = any,
@@ -98,9 +119,9 @@ export interface ITaskDefinition<
   TDependencies extends DependencyMapType = {},
   TOn extends "*" | IEventDefinition<any> | undefined = undefined // Adding a generic to track 'on' type
 > {
-  id: string;
+  id?: string | symbol;
   dependencies?: TDependencies | (() => TDependencies);
-  middleware?: IMiddlewareDefinition[];
+  middleware?: MiddlewareAttachments[];
   /**
    * Listen to events in a simple way
    */
@@ -114,12 +135,7 @@ export interface ITaskDefinition<
   run: (
     input: TOn extends undefined
       ? TInput
-      : IEvent<TOn extends "*" ? any : ExtractEventParams<TOn>>,
-    // input: TOn extends "*"
-    //   ? IEvent<any>
-    //   : TEventDefinitionInput extends null | void
-    //   ? TInput
-    // : IEvent<TEventDefinitionInput>,
+      : IEventEmission<TOn extends "*" ? any : ExtractEventParams<TOn>>,
     dependencies: DependencyValuesType<TDependencies>
   ) => TOutput;
 }
@@ -130,7 +146,8 @@ export type BeforeRunEventPayload<TInput> = {
 
 export type AfterRunEventPayload<TInput, TOutput> = {
   input: TInput;
-  output: TOutput;
+  output: TOutput extends Promise<infer U> ? U : TOutput;
+  setOutput(newOutput: TOutput extends Promise<infer U> ? U : TOutput): void;
 };
 
 export type OnErrorEventPayload = {
@@ -159,68 +176,75 @@ export interface ITask<
   TDependencies extends DependencyMapType = {},
   TOn extends "*" | IEventDefinition<any> | undefined = undefined
 > extends ITaskDefinition<TInput, TOutput, TDependencies, TOn> {
+  id: string | symbol;
   dependencies: TDependencies | (() => TDependencies);
   computedDependencies?: DependencyValuesType<TDependencies>;
-  middleware: IMiddlewareDefinition[];
+  middleware: MiddlewareAttachments[];
   /**
    * These events are automatically populated after the task has been defined.
    */
   events: {
-    beforeRun: IEventDefinition<BeforeRunEventPayload<TInput>>;
-    afterRun: IEventDefinition<AfterRunEventPayload<TInput, TOutput>>;
-    onError: IEventDefinition<OnErrorEventPayload>;
+    beforeRun: IEvent<BeforeRunEventPayload<TInput>>;
+    afterRun: IEvent<AfterRunEventPayload<TInput, TOutput>>;
+    onError: IEvent<OnErrorEventPayload>;
   };
 }
 
-type IsExactlyUnknown<T> = unknown extends T
-  ? T extends unknown
-    ? true
-    : false
-  : false;
-
-// Resource interfaces
 export interface IResourceDefinition<
   TConfig = any,
   TValue = unknown,
   TDependencies extends DependencyMapType = {},
+  TContext = any,
+  THooks = any,
   TRegisterableItems = any
 > {
-  id: string;
+  id?: string | symbol;
   dependencies?: TDependencies | ((config: TConfig) => TDependencies);
   register?:
     | Array<RegisterableItems>
     | ((config: TConfig) => Array<RegisterableItems>);
   init?: (
+    this: any,
     config: TConfig,
-    dependencies: DependencyValuesType<TDependencies>
+    dependencies: DependencyValuesType<TDependencies>,
+    context: TContext
   ) => Promise<TValue>;
   /**
    * Clean-up function for the resource. This is called when the resource is no longer needed.
    *
-   * @param value The value of the resource
+   * @param value The value of the resource (undefined if no init method)
    * @param config The configuration it received
    * @param dependencies The dependencies it needed
-   * @returns
+   * @returns Promise<void>
    */
   dispose?: (
+    this: any,
     value: TValue,
     config: TConfig,
-    dependencies: DependencyValuesType<TDependencies>
-  ) => Promise<TValue>;
+    dependencies: DependencyValuesType<TDependencies>,
+    context: TContext
+  ) => Promise<void>;
   meta?: IResourceMeta;
   overrides?: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
-  middleware?: IMiddlewareDefinition[];
+  middleware?: MiddlewareAttachments[];
+  context?: () => TContext;
+  /**
+   * This is optional and used from an index resource to get the correct caller.
+   */
+  [symbolFilePath]?: string;
+  /**
+   * This is used internally when creating index resources.
+   */
+  [symbolIndexResource]?: boolean;
 }
 
 export interface IResource<
   TConfig = void,
   TValue = any,
-  TDependencies extends DependencyMapType = any
-> extends IResourceDefinition<TConfig, TValue, TDependencies> {
-  init: (
-    config: TConfig,
-    dependencies: DependencyValuesType<TDependencies>
-  ) => Promise<TValue>;
+  TDependencies extends DependencyMapType = any,
+  TContext = any
+> extends IResourceDefinition<TConfig, TValue, TDependencies, TContext> {
+  id: string | symbol;
   with(config: TConfig): IResourceWithConfig<TConfig, TValue, TDependencies>;
   register:
     | Array<RegisterableItems>
@@ -229,12 +253,12 @@ export interface IResource<
    * These events are automatically populated after the task has been defined.
    */
   events: {
-    beforeInit: IEventDefinition<BeforeInitEventPayload<TConfig>>;
-    afterInit: IEventDefinition<AfterInitEventPayload<TConfig, TValue>>;
-    onError: IEventDefinition<OnErrorEventPayload>;
+    beforeInit: IEvent<BeforeInitEventPayload<TConfig>>;
+    afterInit: IEvent<AfterInitEventPayload<TConfig, TValue>>;
+    onError: IEvent<OnErrorEventPayload>;
   };
   overrides: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
-  middleware: IMiddlewareDefinition[];
+  middleware: MiddlewareAttachments[];
 }
 
 export interface IResourceWithConfig<
@@ -247,8 +271,32 @@ export interface IResourceWithConfig<
   config: TConfig;
 }
 
-export interface IEvent<TPayload = any> {
-  id: string;
+export type EventHandlerType<T = any> = (
+  event: IEventEmission<T>
+) => any | Promise<any>;
+
+export interface IEventDefinition<TPayload = void> {
+  id?: string | symbol;
+  meta?: IEventMeta;
+}
+
+export interface IEvent<TPayload = any> extends IEventDefinition<TPayload> {
+  id: string | symbol;
+  /**
+   * We use this event to discriminate between resources with just 'id' and 'events' as they collide. This is a workaround, should be redone using classes and instanceof.
+   */
+  [symbolEvent]: true;
+}
+
+/**
+ * This represents the object that is passed to event handlers
+ */
+export interface IEventEmission<TPayload = any> {
+  /**
+   * The ID of the event. This is the same as the event's ID.
+   * This is useful for global event listeners.
+   */
+  id: string | symbol;
   /**
    * The data that the event carries. It can be anything.
    */
@@ -260,44 +308,46 @@ export interface IEvent<TPayload = any> {
   /**
    * The source of the event. This can be useful for debugging.
    */
-  source: string;
-}
-
-export type EventHandlerType<T = any> = (
-  event: IEvent<T>
-) => any | Promise<any>;
-
-// Other necessary interfaces
-export interface IEventDefinitionConfig<TPayload = void> {
-  id: string;
-  meta?: IEventMeta;
-}
-
-export interface IEventDefinition<TPayload = void> {
-  id: string;
-  /**
-   * We use this event to discriminate between resources with just 'id' and 'events' as they collide. This is a workaround, should be redone using classes and instanceof.
-   */
-  [symbolEvent]: true;
-  meta?: IEventMeta;
+  source: string | symbol;
 }
 
 export interface IMiddlewareDefinition<
+  TConfig = any,
   TDependencies extends DependencyMapType = any
 > {
-  id: string;
+  id?: string | symbol;
   dependencies?: TDependencies | (() => TDependencies);
   run: (
     input: IMiddlewareExecutionInput,
-    dependencies: DependencyValuesType<TDependencies>
+    dependencies: DependencyValuesType<TDependencies>,
+    config: TConfig
   ) => Promise<any>;
   meta?: IMiddlewareMeta;
 }
 
-export interface IMiddleware<TDependencies extends DependencyMapType = any>
-  extends IMiddlewareDefinition<TDependencies> {
+export interface IMiddleware<
+  TConfig = any,
+  TDependencies extends DependencyMapType = any
+> extends IMiddlewareDefinition<TConfig, TDependencies> {
+  [symbolMiddleware]: true;
+  [symbolMiddlewareConfigured]?: boolean;
+  [symbolMiddlewareEverywhereTasks]?: boolean;
+  [symbolMiddlewareEverywhereResources]?: boolean;
+
+  id: string | symbol;
   dependencies: TDependencies | (() => TDependencies);
-  global(): IMiddleware<TDependencies>;
+  everywhere(
+    config?: MiddlewareEverywhereOptions
+  ): IMiddleware<TConfig, TDependencies>;
+  config: TConfig;
+  with: (config: TConfig) => IMiddlewareConfigured<TConfig, TDependencies>;
+}
+
+export interface IMiddlewareConfigured<
+  TConfig = any,
+  TDependencies extends DependencyMapType = any
+> extends IMiddleware<TConfig, TDependencies> {
+  [symbolMiddlewareConfigured]: true;
 }
 
 export interface IMiddlewareDefinitionConfigured<
@@ -307,32 +357,19 @@ export interface IMiddlewareDefinitionConfigured<
   config?: C;
 }
 
-export interface IMiddlewareExecutionInput {
-  taskDefinition?: ITask;
-  resourceDefinition?: IResource;
-  config?: any;
-  input?: any;
-  next: (taskInputOrResourceConfig?: any) => Promise<any>;
-}
-
-export interface IHookDefinition<
-  D extends DependencyMapType = {},
-  T = any,
-  B extends boolean = false
+export interface IMiddlewareExecutionInput<
+  TTaskInput = any,
+  TResourceConfig = any
 > {
-  event: "*" | IEventDefinition<T>;
-  /**
-   * The higher the number, the higher the priority.
-   * We recommend using numbers between -1000 and 1000.
-   */
-  order?: number;
-  /**
-   * These are hooks that run before any resource instantiation.
-   * @param event
-   */
-  early?: B;
-  run: (
-    event: IEvent<T>,
-    dependencies: T extends true ? void : DependencyValuesType<D>
-  ) => Promise<void> | void;
+  task?: {
+    definition: ITask<TTaskInput>;
+    input: TTaskInput;
+  };
+  resource?: {
+    definition: IResource<TResourceConfig>;
+    config: TResourceConfig;
+  };
+  next: (
+    taskInputOrResourceConfig?: TTaskInput | TResourceConfig
+  ) => Promise<any>;
 }

package/src/errors.ts

@@ -1,12 +1,12 @@
 import { ITask, IResource } from "./defs";
 
 export const Errors = {
-  duplicateRegistration: (type: string, id: string) =>
-    new Error(`${type} "${id}" already registered`),
+  duplicateRegistration: (type: string, id: string | symbol) =>
+    new Error(`${type} "${id.toString()}" already registered`),
 
-  dependencyNotFound: (key: string) =>
+  dependencyNotFound: (key: string | symbol) =>
     new Error(
-      `Dependency ${key} not found. Did you forget to register it through a resource?`
+      `Dependency ${key.toString()} not found. Did you forget to register it through a resource?`
     ),
 
   unknownItemType: (item: any) => new Error(`Unknown item type: ${item}`),
@@ -14,14 +14,19 @@ export const Errors = {
   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?`),
+  eventNotFound: (id: string | symbol) =>
+    new Error(
+      `Event "${id.toString()}" not found. Did you forget to register it?`
+    ),
 
-  middlewareAlreadyGlobal: (id: string) =>
-    new Error("Cannot call global on a global middleware: " + id),
+  middlewareAlreadyGlobal: (id: string | symbol) =>
+    new Error(
+      "Cannot call .everywhere() on an already global middleware: " +
+        id.toString
+    ),
 
-  locked: (what: string) =>
-    new Error(`Cannot modify the ${what} when it is locked.`),
+  locked: (what: string | symbol) =>
+    new Error(`Cannot modify the ${what.toString()} when it is locked.`),
 
   storeAlreadyInitialized: () =>
     new Error("Store already initialized. Cannot reinitialize."),

package/src/{globalEvents.ts → globals/globalEvents.ts}

@@ -1,10 +1,10 @@
-import { defineEvent } from "./define";
-import { ITask, IResource, IEvent } from "./defs";
-import { ILog } from "./models/Logger";
+import { defineEvent } from "../define";
+import { ITask, IResource, IEvent } from "../defs";
+import { ILog } from "../models/Logger";
 
 export const globalEvents = {
   beforeInit: defineEvent({
-    id: "global.events.beforeInit",
+    id: "globals.events.beforeInit",
     meta: {
       title: "Before Initialization",
       description:
@@ -13,7 +13,7 @@ export const globalEvents = {
     },
   }),
   afterInit: defineEvent({
-    id: "global.events.afterInit",
+    id: "globals.events.afterInit",
     meta: {
       title: "After Initialization",
       description:
@@ -22,7 +22,7 @@ export const globalEvents = {
     },
   }),
   log: defineEvent<ILog>({
-    id: "global.events.log",
+    id: "globals.events.log",
     meta: {
       title: "Log Event",
       description: "Used to log events and messages across the system.",
@@ -34,7 +34,7 @@ export const globalEvents = {
       task: ITask<any, any, any>;
       input: any;
     }>({
-      id: "global.events.tasks.beforeRun",
+      id: "globals.events.tasks.beforeRun",
       meta: {
         title: "Before Task Execution",
         description:
@@ -46,8 +46,9 @@ export const globalEvents = {
       task: ITask<any, any, any>;
       input: any;
       output: any;
+      setOutput: (newOutput: any) => void;
     }>({
-      id: "global.events.tasks.afterRun",
+      id: "globals.events.tasks.afterRun",
       meta: {
         title: "After Task Execution",
         description:
@@ -60,7 +61,7 @@ export const globalEvents = {
       suppress: () => void;
       task: ITask<any, any, any>;
     }>({
-      id: "global.events.tasks.onError",
+      id: "globals.events.tasks.onError",
       meta: {
         title: "Task Error",
         description:
@@ -74,7 +75,7 @@ export const globalEvents = {
       resource: IResource<any, any, any>;
       config: any;
     }>({
-      id: "global.events.resources.beforeInit",
+      id: "globals.events.resources.beforeInit",
       meta: {
         title: "Before Resource Initialization",
         description:
@@ -87,7 +88,7 @@ export const globalEvents = {
       config: any;
       value: any;
     }>({
-      id: "global.events.resources.afterInit",
+      id: "globals.events.resources.afterInit",
       meta: {
         title: "After Resource Initialization",
         description:
@@ -100,7 +101,7 @@ export const globalEvents = {
       suppress: () => void;
       resource: IResource<any, any, any>;
     }>({
-      id: "global.events.resources.onError",
+      id: "globals.events.resources.onError",
       meta: {
         title: "Resource Error",
         description:

package/src/globals/globalMiddleware.ts

@@ -0,0 +1,14 @@
+import { Context, ContextError } from "../context";
+import { defineMiddleware } from "../define";
+import { cacheMiddleware } from "./middleware/cache.middleware";
+import { requireContextMiddleware } from "./middleware/requireContext.middleware";
+import { retryMiddleware } from "./middleware/retry.middleware";
+
+/**
+ * Global middlewares
+ */
+export const globalMiddlewares = {
+  requireContext: requireContextMiddleware,
+  retry: retryMiddleware,
+  cache: cacheMiddleware,
+};

package/src/{globalResources.ts → globals/globalResources.ts}

@@ -1,11 +1,13 @@
-import { defineResource } from "./define";
-import { EventManager } from "./models/EventManager";
-import { Logger } from "./models/Logger";
-import { Store } from "./models/Store";
-import { TaskRunner } from "./models/TaskRunner";
+import { defineResource } from "../define";
+import { EventManager } from "../models/EventManager";
+import { Logger } from "../models/Logger";
+import { Store } from "../models/Store";
+import { TaskRunner } from "../models/TaskRunner";
+import { cacheResource } from "./middleware/cache.middleware";
+import { queueResource } from "./resources/queue.resource";
 
 const store = defineResource({
-  id: "global.resources.store",
+  id: "globals.resources.store",
   init: async (store: Store) => store,
   meta: {
     title: "Store",
@@ -18,7 +20,7 @@ const store = defineResource({
 export const globalResources = {
   store,
   eventManager: defineResource({
-    id: "global.resources.eventManager",
+    id: "globals.resources.eventManager",
     init: async (em: EventManager) => em,
     meta: {
       title: "Event Manager",
@@ -28,7 +30,7 @@ export const globalResources = {
     },
   }),
   taskRunner: defineResource({
-    id: "global.resources.taskRunner",
+    id: "globals.resources.taskRunner",
     init: async (runner: TaskRunner) => runner,
     meta: {
       title: "Task Runner",
@@ -38,12 +40,14 @@ export const globalResources = {
     },
   }),
   logger: defineResource({
-    id: "global.resources.logger",
+    id: "globals.resources.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.",
+        "Logs all events and errors. This is meant to be used internally for most use-cases. Emits a globals.log event for each log.",
     },
   }),
+  cache: cacheResource,
+  queue: queueResource,
 };