@bluelibs/runner 3.2.0 → 3.3.1

package/src/defs.ts

@@ -1,8 +1,30 @@
-import { index } from ".";
+/**
+ * Core public TypeScript types for BlueLibs Runner.
+ *
+ * This file contains the strongly-typed contract for tasks, resources, events
+ * and middleware. It mirrors the mental model described in the README:
+ * - Tasks are functions (with lifecycle events)
+ * - Resources are singletons (with init/dispose hooks and lifecycle events)
+ * - Events are simple, strongly-typed emissions
+ * - Middleware can target both tasks and resources
+ *
+ * DX goals:
+ * - Crystal‑clear generics and helper types that infer dependency shapes
+ * - Friendly JSDoc you can hover in editors to understand usage instantly
+ * - Safe overrides and strong typing around config and register mechanics
+ */
+
 import { MiddlewareEverywhereOptions } from "./define";
 
+// Re-export public cache type so consumers don’t import from internals.
 export { ICacheInstance } from "./globals/middleware/cache.middleware";
-
+export * from "./models/StoreTypes";
+/**
+ * Internal brand symbols used to tag created objects at runtime and help with
+ * type‑narrowing. Prefer the `isTask`/`isResource`/`isEvent`/`isMiddleware`
+ * helpers instead of touching these directly.
+ * @internal
+ */
 export const symbolTask: unique symbol = Symbol("runner.task");
 export const symbolResource: unique symbol = Symbol("runner.resource");
 export const symbolResourceWithConfig: unique symbol = Symbol(
@@ -23,32 +45,89 @@ export const symbolMiddlewareEverywhereResources: unique symbol = Symbol(
   "runner.middlewareGlobalResources"
 );
 
+/** @internal Path to aid anonymous id generation and error messages */
 export const symbolFilePath: unique symbol = Symbol("runner.filePath");
+/** @internal Marks disposable instances */
 export const symbolDispose: unique symbol = Symbol("runner.dispose");
+/** @internal Link to internal Store */
 export const symbolStore: unique symbol = Symbol("runner.store");
 
+/** @internal Brand used by index() resources */
 export const symbolIndexResource: unique symbol = Symbol(
   "runner.indexResource"
 );
 
-export const symbols = {
-  task: symbolTask,
-  resource: symbolResource,
-  resourceWithConfig: symbolResourceWithConfig,
-  indexResource: symbolIndexResource,
-  event: symbolEvent,
-  middleware: symbolMiddleware,
-  middlewareEverywhereTasks: symbolMiddlewareEverywhereTasks,
-  middlewareEverywhereResources: symbolMiddlewareEverywhereResources,
-  filePath: symbolFilePath,
-  dispose: symbolDispose,
-  store: symbolStore,
-};
+export interface ITagDefinition<TConfig = void> {
+  id: string | symbol;
+}
+
+/**
+ * A configured instance of a tag as produced by `ITag.with()`.
+ */
+export interface ITagWithConfig<TConfig = void> {
+  id: string | symbol;
+  /** The tag definition used to produce this configured instance. */
+  tag: ITag<TConfig>;
+  /** The configuration captured for this tag instance. */
+  config: TConfig;
+}
 
+/**
+ * A tag definition (builder). Use `.with(config)` to obtain configured instances,
+ * and `.extract(tags)` to find either a configured instance or the bare tag in a list.
+ */
+export interface ITag<TConfig = void> extends ITagDefinition<TConfig> {
+  /**
+   * Creates a configured instance of the tag.
+   */
+  with(config: TConfig): ITagWithConfig<TConfig>;
+  /**
+   * Extracts either a configured instance or the bare tag from a list of tags
+   * or from a taggable object (`{ meta: { tags?: [] } }`).
+   */
+  extract(target: TagType[] | ITaggable): ExtractedTagResult<TConfig> | null;
+  [symbolFilePath]: string;
+}
+
+/**
+ * Restrict bare tags to those whose config can be omitted (void or optional object),
+ * mirroring the same principle used for resources in `RegisterableItems`.
+ * Required-config tags must appear as configured instances.
+ */
+export type TagType =
+  | string
+  | ITag<void>
+  | ITag<{ [K in any]?: any }>
+  | ITagWithConfig<any>;
+
+/**
+ * Conditional result type for `ITag.extract`:
+ * - For void config → just the identifier
+ * - For optional object config → identifier with optional config
+ * - For required config → identifier with required config
+ */
+export type ExtractedTagResult<TConfig> = {} extends TConfig
+  ? { id: string | symbol; config?: TConfig }
+  : { id: string | symbol; config: TConfig };
+
+/**
+ * Any object that can carry tags via metadata. This mirrors how tasks,
+ * resources, events, and middleware expose `meta.tags`.
+ */
+export interface ITaggable {
+  meta?: {
+    tags?: TagType[];
+  };
+}
+
+/**
+ * Common metadata you can attach to tasks/resources/events/middleware.
+ * Useful for docs, filtering and middleware decisions.
+ */
 export interface IMeta {
   title?: string;
   description?: string;
-  tags?: string[];
+  tags?: TagType[];
 }
 
 export interface ITaskMeta extends IMeta {}
@@ -56,7 +135,11 @@ export interface IResourceMeta extends IMeta {}
 export interface IEventMeta extends IMeta {}
 export interface IMiddlewareMeta extends IMeta {}
 
-// DependencyMap types
+/**
+ * A mapping of dependency keys to Runner definitions. Used in `dependencies`
+ * for tasks and resources. Values are later transformed into the actual
+ * callable/value shape by `DependencyValuesType`.
+ */
 export type DependencyMapType = Record<
   string,
   ITask<any, any, any, any> | IResource<any, any, any> | IEventDefinition<any>
@@ -72,21 +155,28 @@ type ExtractResourceValue<T> = T extends IResource<any, infer V, infer D>
 type ExtractEventParams<T> = T extends IEvent<infer P> ? P : never;
 
 /**
- * This represents a task dependency function that can be called with or without parameters.
+ * Task dependencies transform into callable functions: call with the task input
+ * and you receive the task output.
  */
 type TaskDependency<I, O> = (...args: I extends null | void ? [] : [I]) => O;
 /**
- * This represents the resource's value type.
+ * Resource dependencies resolve to the resource's value directly.
  */
 type ResourceDependency<V> = V;
 /**
- * This represents an event emission function that can be called with or without parameters.
+ * Event dependencies resolve to an emitter function. If the payload type is
+ * `void`, the function can be called with zero args (or an empty object).
  */
 type EventDependency<P> = P extends void
   ? (() => Promise<void>) & ((input?: Record<string, never>) => Promise<void>)
   : (input: P) => Promise<void>;
 
-// Main DependencyValueType Definition
+/**
+ * Transforms a dependency definition into the usable shape inside `run`/`init`:
+ * - Task -> callable function
+ * - Resource -> resolved value
+ * - Event -> emit function
+ */
 export type DependencyValueType<T> = T extends ITask<any, any, any>
   ? TaskDependency<ExtractTaskInput<T>, ExtractTaskOutput<T>>
   : T extends IResource<any, any>
@@ -99,7 +189,13 @@ export type DependencyValuesType<T extends DependencyMapType> = {
   [K in keyof T]: DependencyValueType<T[K]>;
 };
 
-// RegisterableItems Type with Conditional Inclusion
+/**
+ * Anything you can put inside a resource's `register: []`.
+ * - Resources (with or without `.with()`)
+ * - Tasks
+ * - Middleware
+ * - Events
+ */
 export type RegisterableItems<T = any> =
   | IResourceWithConfig<any>
   | IResource<void, any, any, any> // For void configs
@@ -119,8 +215,17 @@ export interface ITaskDefinition<
   TDependencies extends DependencyMapType = {},
   TOn extends "*" | IEventDefinition<any> | undefined = undefined // Adding a generic to track 'on' type
 > {
+  /**
+   * Stable identifier. If omitted, an anonymous id is generated from file path
+   * (see README: Anonymous IDs).
+   */
   id?: string | symbol;
+  /**
+   * Access other tasks/resources/events. Can be an object or a function when
+   * you need late or config‑dependent resolution.
+   */
   dependencies?: TDependencies | (() => TDependencies);
+  /** Middleware applied around task execution. */
   middleware?: MiddlewareAttachments[];
   /**
    * Listen to events in a simple way
@@ -131,7 +236,12 @@ export interface ITaskDefinition<
    * The event with the lowest order will be executed first.
    */
   listenerOrder?: number;
+  /** Optional metadata used for docs, filtering and tooling. */
   meta?: ITaskMeta;
+  /**
+   * The task body. If `on` is set, the input is an `IEventEmission`. Otherwise,
+   * it's the declared input type.
+   */
   run: (
     input: TOn extends undefined
       ? TInput
@@ -188,6 +298,8 @@ export interface ITask<
     afterRun: IEvent<AfterRunEventPayload<TInput, TOutput>>;
     onError: IEvent<OnErrorEventPayload>;
   };
+  [symbolFilePath]: string;
+  [symbolTask]: true;
 }
 
 export interface IResourceDefinition<
@@ -198,11 +310,20 @@ export interface IResourceDefinition<
   THooks = any,
   TRegisterableItems = any
 > {
+  /** Stable identifier. Omit to get an anonymous id. */
   id?: string | symbol;
+  /** Static or lazy dependency map. Receives `config` when provided. */
   dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+  /**
+   * Register other registerables (resources/tasks/middleware/events). Accepts a
+   * static array or a function of `config` to support dynamic wiring.
+   */
   register?:
     | Array<RegisterableItems>
     | ((config: TConfig) => Array<RegisterableItems>);
+  /**
+   * Initialize and return the resource value. Called once during boot.
+   */
   init?: (
     this: any,
     config: TConfig,
@@ -225,11 +346,20 @@ export interface IResourceDefinition<
     context: TContext
   ) => Promise<void>;
   meta?: IResourceMeta;
+  /**
+   * Safe overrides to swap behavior while preserving identities. See
+   * README: Overrides.
+   */
   overrides?: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
+  /** Middleware applied around init/dispose. */
   middleware?: MiddlewareAttachments[];
+  /**
+   * Create a private, mutable context shared between `init` and `dispose`.
+   */
   context?: () => TContext;
   /**
    * This is optional and used from an index resource to get the correct caller.
+   * This is the reason we allow it here as well.
    */
   [symbolFilePath]?: string;
   /**
@@ -259,6 +389,9 @@ export interface IResource<
   };
   overrides: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
   middleware: MiddlewareAttachments[];
+  [symbolFilePath]: string;
+  [symbolIndexResource]: boolean;
+  [symbolResource]: true;
 }
 
 export interface IResourceWithConfig<
@@ -266,8 +399,11 @@ export interface IResourceWithConfig<
   TValue = any,
   TDependencies extends DependencyMapType = any
 > {
+  /** The id of the underlying resource. */
   id: string;
+  /** The underlying resource definition. */
   resource: IResource<TConfig, TValue, TDependencies>;
+  /** The configuration captured by `.with(config)`. */
   config: TConfig;
 }
 
@@ -276,6 +412,7 @@ export type EventHandlerType<T = any> = (
 ) => any | Promise<any>;
 
 export interface IEventDefinition<TPayload = void> {
+  /** Stable identifier. Omit to get an anonymous id. */
   id?: string | symbol;
   meta?: IEventMeta;
 }
@@ -286,6 +423,7 @@ export interface IEvent<TPayload = any> extends IEventDefinition<TPayload> {
    * 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;
+  [symbolFilePath]: string;
 }
 
 /**
@@ -327,8 +465,13 @@ export interface IMiddlewareDefinition<
   TConfig = any,
   TDependencies extends DependencyMapType = any
 > {
+  /** Stable identifier. Omit to get an anonymous id. */
   id?: string | symbol;
+  /** Static or lazy dependency map. */
   dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+  /**
+   * The middleware body, called with task/resource execution input.
+   */
   run: (
     input: IMiddlewareExecutionInput,
     dependencies: DependencyValuesType<TDependencies>,
@@ -348,11 +491,18 @@ export interface IMiddleware<
 
   id: string | symbol;
   dependencies: TDependencies | (() => TDependencies);
+  /**
+   * Attach this middleware globally. Use options to scope to tasks/resources.
+   */
   everywhere(
     config?: MiddlewareEverywhereOptions
   ): IMiddleware<TConfig, TDependencies>;
+  /** Current configuration object (empty by default). */
   config: TConfig;
+  /** Configure the middleware and return a marked, configured instance. */
   with: (config: TConfig) => IMiddlewareConfigured<TConfig, TDependencies>;
+  [symbolFilePath]: string;
+  [symbolMiddleware]: true;
 }
 
 export interface IMiddlewareConfigured<
@@ -373,10 +523,12 @@ export interface IMiddlewareExecutionInput<
   TTaskInput = any,
   TResourceConfig = any
 > {
+  /** Task hook: present when wrapping a task run. */
   task?: {
     definition: ITask<TTaskInput>;
     input: TTaskInput;
   };
+  /** Resource hook: present when wrapping init/dispose. */
   resource?: {
     definition: IResource<TResourceConfig>;
     config: TResourceConfig;

package/src/globals/globalMiddleware.ts

@@ -3,6 +3,7 @@ import { defineMiddleware } from "../define";
 import { cacheMiddleware } from "./middleware/cache.middleware";
 import { requireContextMiddleware } from "./middleware/requireContext.middleware";
 import { retryMiddleware } from "./middleware/retry.middleware";
+import { timeoutMiddleware } from "./middleware/timeout.middleware";
 
 /**
  * Global middlewares
@@ -11,4 +12,5 @@ export const globalMiddlewares = {
   requireContext: requireContextMiddleware,
   retry: retryMiddleware,
   cache: cacheMiddleware,
+  timeout: timeoutMiddleware,
 };

package/src/globals/middleware/timeout.middleware.ts

@@ -0,0 +1,46 @@
+import { defineMiddleware } from "../../define";
+
+export interface TimeoutMiddlewareConfig {
+  /**
+   * Maximum time in milliseconds before the wrapped operation is aborted
+   * and a timeout error is thrown. Defaults to 5000ms.
+   */
+  ttl: number;
+}
+
+export const timeoutMiddleware = defineMiddleware({
+  id: "globals.middleware.timeout",
+  async run({ task, resource, next }, _deps, config: TimeoutMiddlewareConfig) {
+    const input = task ? task.input : resource?.config;
+
+    const ttl = Math.max(0, config.ttl);
+    const message = `Operation timed out after ${ttl}ms`;
+
+    // Fast-path: immediate timeout
+    if (ttl === 0) {
+      const error = new Error(message);
+      (error as any).name = "TimeoutError";
+      throw error;
+    }
+
+    const controller = new AbortController();
+
+    // Create a timeout promise that rejects when aborted
+    const timeoutPromise = new Promise((_, reject) => {
+      const timeoutId = setTimeout(() => {
+        controller.abort();
+        const error = new Error(message);
+        (error as any).name = "TimeoutError";
+        reject(error);
+      }, ttl);
+
+      // Clean up timeout if abort signal fires for other reasons
+      controller.signal.addEventListener("abort", () => {
+        clearTimeout(timeoutId);
+      });
+    });
+
+    // Race between the actual operation and the timeout
+    return Promise.race([next(input), timeoutPromise]);
+  },
+});

package/src/index.ts

@@ -4,12 +4,15 @@ import {
   defineEvent,
   defineMiddleware,
   defineIndex,
+  defineTag,
+  defineOverride,
 } from "./define";
 import { createContext } from "./context";
 import { globalEvents } from "./globals/globalEvents";
 import { globalResources } from "./globals/globalResources";
 import { globalMiddlewares } from "./globals/globalMiddleware";
 import { run } from "./run";
+import { createTestResource } from "./testing";
 
 const globals = {
   events: globalEvents,
@@ -24,8 +27,11 @@ export {
   defineEvent as event,
   defineMiddleware as middleware,
   defineIndex as index,
+  defineTag as tag,
+  defineOverride as override,
   run,
   createContext,
+  createTestResource,
 };
 
 export * as definitions from "./defs";

package/src/models/DependencyProcessor.ts

@@ -139,11 +139,7 @@ export class DependencyProcessor {
             return;
           }
 
-          return this.taskRunner.run(
-            task.task,
-            receivedEvent,
-            task.computedDependencies
-          );
+          return this.taskRunner.run(task.task, receivedEvent);
         };
 
         if (eventDefinition === "*") {
@@ -217,11 +213,7 @@ export class DependencyProcessor {
     }
 
     return (input: any) => {
-      return this.taskRunner.run(
-        storeTask.task,
-        input,
-        storeTask.computedDependencies
-      );
+      return this.taskRunner.run(storeTask.task, input);
     };
   }
 

package/src/models/StoreConstants.ts

@@ -1,6 +1,7 @@
 import { globalResources } from "../globals/globalResources";
 import { requireContextMiddleware } from "../globals/middleware/requireContext.middleware";
 import { retryMiddleware } from "../globals/middleware/retry.middleware";
+import { timeoutMiddleware } from "../globals/middleware/timeout.middleware";
 import { EventManager } from "./EventManager";
 import { Store } from "./Store";
 
@@ -13,5 +14,5 @@ export function getBuiltInResources(eventManager: EventManager, store: Store) {
 }
 
 export function getBuiltInMiddlewares() {
-  return [requireContextMiddleware, retryMiddleware];
+  return [requireContextMiddleware, retryMiddleware, timeoutMiddleware];
 }

package/src/models/TaskRunner.ts

@@ -23,7 +23,6 @@ export class TaskRunner {
    * 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
-   * @param taskDependencies optional dependencies to be passed to the task, if not provided, the dependencies will be the ones already computed from the store.
    */
   public async run<
     TInput,
@@ -31,8 +30,7 @@ export class TaskRunner {
     TDeps extends DependencyMapType
   >(
     task: ITask<TInput, TOutput, TDeps>,
-    input: TInput,
-    taskDependencies?: DependencyValuesType<TDeps>
+    input: TInput
   ): Promise<TOutput | undefined> {
     let runner = this.runnerStore.get(task.id);
     if (!runner) {

package/src/testing.ts

@@ -0,0 +1,66 @@
+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, 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,
+  };
+}