@bluelibs/runner 2.2.3 → 3.0.0

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,
 };

package/src/globals/middleware/cache.middleware.ts

@@ -0,0 +1,115 @@
+import { defineMiddleware, defineResource, defineTask } from "../../define";
+import { LRUCache } from "lru-cache";
+import { IResource, ITask } from "../../defs";
+
+export interface ICacheInstance {
+  set(key: string, value: any): void;
+  get(key: string): any;
+  clear(): void;
+}
+
+// Default cache factory task that can be overridden
+export const cacheFactoryTask = defineTask({
+  id: "globals.tasks.cacheFactory",
+  run: async (options: any) => {
+    return new LRUCache(options) as ICacheInstance;
+  },
+});
+
+type CacheResourceConfig = {
+  defaultOptions?: any;
+  /**
+   * This specifies whether the cache handler is async or not (get, set, clear)
+   * This is for speed purposes.
+   */
+  async?: boolean;
+};
+
+type CacheMiddlewareConfig = {
+  keyBuilder?: (taskId: string, input: any) => string;
+} & any;
+
+export const cacheResource = defineResource({
+  id: "globals.resources.cache",
+  register: [cacheFactoryTask],
+  dependencies: {
+    cacheFactoryTask,
+  },
+  init: async (config: CacheResourceConfig, { cacheFactoryTask }) => {
+    return {
+      map: new Map<string, ICacheInstance>(),
+      cacheFactoryTask,
+      async: config.async,
+      defaultOptions: {
+        ttl: 10 * 1000,
+        max: 100, // Maximum number of items in cache
+        ttlAutopurge: true, // Automatically purge expired items
+        ...config.defaultOptions,
+      },
+    };
+  },
+  dispose: async (cache) => {
+    for (const cacheInstance of cache.map.values()) {
+      await cacheInstance.clear();
+    }
+  },
+});
+
+const defaultKeyBuilder = (taskId: string, input: any) =>
+  `${taskId}-${JSON.stringify(input)}`;
+
+export const cacheMiddleware = defineMiddleware({
+  id: "globals.middleware.cache",
+  dependencies: { cache: cacheResource },
+  async run({ task, resource, next }, deps, config: CacheMiddlewareConfig) {
+    const { cache } = deps;
+    config = {
+      keyBuilder: defaultKeyBuilder,
+      ttl: 10 * 1000,
+      max: 100, // Maximum number of items in cache
+      ttlAutopurge: true, // Automatically purge expired items
+      ...config,
+    };
+
+    if (!task) {
+      throw new Error("Cache middleware can only be used in tasks");
+    }
+
+    const taskId = task.definition.id;
+    const isAsync = cache.async;
+    let cacheHolderForTask = cache.map.get(taskId);
+    if (!cacheHolderForTask) {
+      // Extract only LRUCache options, excluding keyBuilder
+      const { keyBuilder, ...lruOptions } = config;
+      const cacheOptions = {
+        ...cache.defaultOptions,
+        ...lruOptions,
+      };
+
+      // Use the factory task to create the cache instance
+      cacheHolderForTask = await cache.cacheFactoryTask(cacheOptions);
+
+      cache.map.set(taskId, cacheHolderForTask);
+    }
+
+    const key = config.keyBuilder!(taskId, task.input);
+
+    const cachedValue = isAsync
+      ? await cacheHolderForTask.get(key)
+      : cacheHolderForTask.get(key);
+
+    if (cachedValue) {
+      return cachedValue;
+    }
+
+    const result = await next(task.input);
+
+    if (isAsync) {
+      await cacheHolderForTask.set(key, result);
+    } else {
+      cacheHolderForTask.set(key, result);
+    }
+
+    return result;
+  },
+});

package/src/globals/middleware/requireContext.middleware.ts

@@ -0,0 +1,36 @@
+import { Context, ContextError } from "../../context";
+import { defineMiddleware } from "../../define";
+
+type RequireContextMiddlewareConfig = {
+  context: Context<any>;
+};
+
+export const requireContextMiddleware = defineMiddleware({
+  id: "globals.middleware.requireContext",
+  async run(
+    { task, resource, next },
+    deps,
+    config: RequireContextMiddlewareConfig
+  ) {
+    if (!config.context) {
+      throw new Error(
+        "Context not available. Did you forget to pass 'context' to the middleware?"
+      );
+    }
+
+    const ctx = config.context.use();
+    if (!ctx) {
+      throw new ContextError(
+        "Context not available. Did you forget to provide the context via ContextName.provide()?"
+      );
+    }
+    if (task) {
+      return next(task.input);
+    }
+    if (resource) {
+      return next(resource.config);
+    }
+
+    return next();
+  },
+});

package/src/globals/middleware/retry.middleware.ts

@@ -0,0 +1,56 @@
+import { defineMiddleware } from "../../define";
+
+/**
+ * Configuration options for the retry middleware
+ */
+export interface RetryMiddlewareConfig {
+  /**
+   * Maximum number of retry attempts (default: 3)
+   */
+  retries?: number;
+  /**
+   * Callback to determine if retry should stop based on error
+   * @default () => false (retry all errors)
+   */
+  stopRetryIf?: (error: Error) => boolean;
+  /**
+   * Custom delay strategy function
+   * @default Exponential backoff starting at 100ms
+   */
+  delayStrategy?: (attempt: number, error: Error) => number;
+}
+
+export const retryMiddleware = defineMiddleware({
+  id: "globals.middleware.retry",
+  async run({ task, resource, next }, deps, config: RetryMiddlewareConfig) {
+    const input = task ? task.input : resource?.config;
+    let attempts = 0;
+
+    // Set defaults for required parameters
+    const maxRetries = config.retries ?? 3;
+    const shouldStop = config.stopRetryIf ?? (() => false);
+
+    while (true) {
+      try {
+        return await next(input);
+      } catch (error) {
+        const err = error as Error;
+
+        if (shouldStop(err) || attempts >= maxRetries) {
+          throw error;
+        }
+
+        // Calculate delay using custom strategy or default exponential backoff
+        const delay = config.delayStrategy
+          ? config.delayStrategy(attempts, err)
+          : 100 * Math.pow(2, attempts);
+
+        if (delay > 0) {
+          await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+
+        attempts++;
+      }
+    }
+  },
+});

package/src/globals/resources/queue.resource.ts

@@ -0,0 +1,34 @@
+import { defineResource } from "../../define";
+import { Queue } from "../../models/Queue";
+
+export const queueResource = defineResource({
+  id: "globals.resources.queue",
+  context: () => ({
+    map: new Map<string, Queue>(),
+  }),
+  init: async (_, deps, context) => {
+    const map = context.map;
+
+    return {
+      map,
+      run: <T>(
+        id: string,
+        task: (signal: AbortSignal) => Promise<T>
+      ): Promise<T> => {
+        if (!map.has(id)) {
+          map.set(id, new Queue());
+        }
+
+        return map.get(id)!.run(task);
+      },
+    };
+  },
+  dispose: async (value, _, deps, context) => {
+    context.map.forEach((queue) => queue.dispose());
+  },
+  meta: {
+    title: "Queue Map",
+    description:
+      "A global map that can be used to store and retrieve queues. You can run exclusive tasks based on using an id. queue.run(id, task) will run the task in the queue with the given id. If the queue does not exist, it will be created.",
+  },
+});

package/src/index.ts

@@ -3,14 +3,18 @@ import {
   defineResource,
   defineEvent,
   defineMiddleware,
+  defineIndex,
 } from "./define";
-import { globalEvents } from "./globalEvents";
-import { globalResources } from "./globalResources";
+import { createContext } from "./context";
+import { globalEvents } from "./globals/globalEvents";
+import { globalResources } from "./globals/globalResources";
+import { globalMiddlewares } from "./globals/globalMiddleware";
 import { run } from "./run";
 
 const globals = {
   events: globalEvents,
   resources: globalResources,
+  middlewares: globalMiddlewares,
 };
 
 export { globals };
@@ -19,10 +23,10 @@ export {
   defineResource as resource,
   defineEvent as event,
   defineMiddleware as middleware,
+  defineIndex as index,
   run,
+  createContext,
 };
 
 export * as definitions from "./defs";
-export { Store } from "./models/Store";
-export { EventManager } from "./models/EventManager";
-export { TaskRunner } from "./models/TaskRunner";
+export { Semaphore, Store, EventManager, TaskRunner, Queue } from "./models";

package/src/models/DependencyProcessor.ts

@@ -7,7 +7,8 @@ import {
   IEventDefinition,
   IEvent,
 } from "../defs";
-import { ResourceStoreElementType, Store, TaskStoreElementType } from "./Store";
+import { Store } from "./Store";
+import { ResourceStoreElementType, TaskStoreElementType } from "./StoreTypes";
 import * as utils from "../define";
 import { EventManager } from "./EventManager";
 import { ResourceInitializer } from "./ResourceInitializer";
@@ -81,11 +82,14 @@ export class DependencyProcessor {
         resource.resource.id !== this.store.root.resource.id
       ) {
         await this.processResourceDependencies(resource);
-        resource.value = await this.resourceInitializer.initializeResource(
-          resource.resource,
-          resource.config,
-          resource.computedDependencies as DependencyValuesType<{}>
-        );
+        const { value, context } =
+          await this.resourceInitializer.initializeResource(
+            resource.resource,
+            resource.config,
+            resource.computedDependencies as DependencyValuesType<{}>
+          );
+        resource.context = context;
+        resource.value = value;
       }
     }
   }
@@ -107,13 +111,16 @@ export class DependencyProcessor {
   public async initializeRoot() {
     const storeResource = this.store.root;
 
-    storeResource.value = await this.resourceInitializer.initializeResource(
-      storeResource.resource,
-      storeResource.config,
-      // They are already computed
-      storeResource.computedDependencies as DependencyValuesType<{}>
-    );
+    const { value, context } =
+      await this.resourceInitializer.initializeResource(
+        storeResource.resource,
+        storeResource.config,
+        // They are already computed
+        storeResource.computedDependencies as DependencyValuesType<{}>
+      );
 
+    storeResource.context = context;
+    storeResource.value = value;
     storeResource.isInitialized = true;
   }
 
@@ -132,18 +139,6 @@ export class DependencyProcessor {
             return;
           }
 
-          this.logger.debug(
-            {
-              message:
-                eventDefinition === "*"
-                  ? `Task ${task.task.id} being triggered by all events`
-                  : `Task ${task.task.id} being triggered by event: ${eventDefinition.id}`,
-
-              event: receivedEvent,
-            },
-            task.task.id
-          );
-
           return this.taskRunner.run(
             task.task,
             receivedEvent,
@@ -180,7 +175,7 @@ export class DependencyProcessor {
     return object;
   }
 
-  async extractDependency(object, source: string) {
+  async extractDependency(object: any, source: string) {
     if (utils.isResource(object)) {
       return this.extractResourceDependency(object);
     } else if (utils.isTask(object)) {
@@ -201,15 +196,7 @@ export class DependencyProcessor {
     object: IEventDefinition<Record<string, any>>,
     source: string
   ) {
-    return async (input) => {
-      // runs it in background.
-      this.logger.debug(
-        {
-          message: `Event ${object.id} was emitted from ${source}`,
-        },
-        source
-      );
-
+    return async (input: any) => {
       return this.eventManager.emit(object, input, source);
     };
   }
@@ -232,7 +219,7 @@ export class DependencyProcessor {
       );
     }
 
-    return (input) => {
+    return (input: any) => {
       return this.taskRunner.run(
         storeTask.task,
         input,
@@ -256,11 +243,20 @@ export class DependencyProcessor {
       storeResource.isInitialized = true;
 
       // check if it has an initialisation function that provides the value
-      storeResource.value = await this.resourceInitializer.initializeResource(
-        resource,
-        config,
-        await this.extractDependencies(resource.dependencies || {}, resource.id)
-      );
+      if (resource.init) {
+        const { value, context } =
+          await this.resourceInitializer.initializeResource(
+            resource,
+            config,
+            await this.extractDependencies(
+              resource.dependencies || {},
+              resource.id
+            )
+          );
+
+        storeResource.context = context;
+        storeResource.value = value;
+      }
     }
 
     return storeResource.value;

package/src/models/EventManager.ts

@@ -22,6 +22,8 @@ export interface IEventHandlerOptions<T = any> {
 export class EventManager {
   private listeners: Map<string, IListenerStorage[]> = new Map();
   private globalListeners: IListenerStorage[] = [];
+  private cachedMergedListeners: Map<string, IListenerStorage[]> = new Map();
+  private globalListenersCacheValid = true;
   #isLocked = false;
 
   get isLocked() {
@@ -57,16 +59,47 @@ export class EventManager {
     return result;
   }
 
+  private getCachedMergedListeners(eventId: string): IListenerStorage[] {
+    if (!this.globalListenersCacheValid) {
+      this.cachedMergedListeners.clear();
+      this.globalListenersCacheValid = true;
+    }
+
+    let cached = this.cachedMergedListeners.get(eventId);
+    if (!cached) {
+      const eventListeners = this.listeners.get(eventId) || [];
+      if (eventListeners.length === 0 && this.globalListeners.length === 0) {
+        cached = [];
+      } else if (eventListeners.length === 0) {
+        cached = this.globalListeners;
+      } else if (this.globalListeners.length === 0) {
+        cached = eventListeners;
+      } else {
+        cached = this.mergeSortedListeners(eventListeners, this.globalListeners);
+      }
+      this.cachedMergedListeners.set(eventId, cached);
+    }
+    return cached;
+  }
+
+  private invalidateCache(eventId?: string): void {
+    if (eventId) {
+      this.cachedMergedListeners.delete(eventId);
+    } else {
+      this.globalListenersCacheValid = false;
+    }
+  }
+
   async emit<TInput>(
     eventDefinition: IEventDefinition<TInput>,
     data: TInput,
     source: string
   ): Promise<void> {
-    const eventListeners = this.listeners.get(eventDefinition.id) || [];
-    const allListeners = this.mergeSortedListeners(
-      eventListeners,
-      this.globalListeners
-    );
+    const allListeners = this.getCachedMergedListeners(eventDefinition.id);
+    
+    if (allListeners.length === 0) {
+      return;
+    }
 
     const event: IEvent = {
       id: eventDefinition.id,
@@ -121,6 +154,7 @@ export class EventManager {
       } else {
         this.listeners.set(eventId, [newListener]);
       }
+      this.invalidateCache(eventId);
     }
   }
 
@@ -135,5 +169,11 @@ export class EventManager {
       filter: options.filter,
     };
     this.insertListener(this.globalListeners, newListener);
+    this.invalidateCache();
+  }
+
+  hasListeners<T>(eventDefinition: IEventDefinition<T>): boolean {
+    const eventListeners = this.listeners.get(eventDefinition.id) || [];
+    return eventListeners.length > 0 || this.globalListeners.length > 0;
   }
 }