@bluelibs/runner 3.2.0 → 3.3.0

package/src/__tests__/typesafety.test.ts

@@ -3,6 +3,8 @@ import {
   defineTask,
   defineResource,
   defineMiddleware,
+  defineOverride,
+  defineTag,
 } from "../define";
 import {
   IEventDefinition,
@@ -12,8 +14,10 @@ import {
   ITaskDefinition,
   RegisterableItems,
 } from "../defs";
+import { createTestResource } from "..";
 
-describe("typesafety", () => {
+// This is skipped because we mostly check typesafety.
+describe.skip("typesafety", () => {
   it("tasks, resources: should have propper type safety for dependeices", async () => {
     type InputTask = {
       message: string;
@@ -209,4 +213,108 @@ describe("typesafety", () => {
 
     expect(true).toBe(true);
   });
+
+  it("createTestResource.runTask: should be type-safe", async () => {
+    type Input = { x: number };
+    type Output = Promise<number>;
+
+    const add = defineTask<Input, Output>({
+      id: "types.add",
+      run: async (i) => i.x + 1,
+    });
+
+    const depTask = defineTask<{ v: string }, Promise<string>>({
+      id: "types.dep",
+      run: async (i) => i.v.toUpperCase(),
+    });
+
+    const main = defineTask<Input, Output, { depTask: typeof depTask }>({
+      id: "types.main",
+      dependencies: { depTask },
+      run: async (i, d) => {
+        const v = await d.depTask({ v: String(i.x) });
+        return Number(v) + 1;
+      },
+    });
+
+    const app = defineResource({
+      id: "types.app",
+      register: [add, depTask, main],
+    });
+    const harness = createTestResource(app);
+
+    // Types: input must match, override deps must match, output is awaited number
+    const { value: t } = await (await import("../run")).run(harness);
+    const r1: number | undefined = await t.runTask(add, { x: 1 });
+    // @ts-expect-error wrong input type
+    await t.runTask(add, { z: 1 });
+    // @ts-expect-error missing input
+    await t.runTask(add);
+
+    const r2: number | undefined = await t.runTask(main, { x: 2 });
+
+    // @ts-expect-error wrong deps override type
+    await t.runTask(main, { x: 2 }, { depTask: async (i: number) => "x" });
+
+    expect(true).toBe(true);
+  });
+
+  it("should have propper type safety for overrides", async () => {
+    const task = defineTask({
+      id: "task",
+      run: async () => "Task executed",
+    });
+
+    // @ts-expect-error
+    const overrideTask = defineOverride(task, {
+      run: async () => 234,
+    });
+
+    const resource = defineResource({
+      id: "resource",
+      register: [task],
+      init: async () => "Resource executed",
+    });
+
+    const overrideResource = defineOverride(resource, {
+      init: async () => "Resource overridden",
+    });
+    // @ts-expect-error
+    defineOverride(resource, {
+      init: async () => 123, // bad type
+    });
+
+    const middleware = defineMiddleware({
+      id: "middleware",
+      run: async () => "Middleware executed",
+    });
+
+    expect(true).toBe(true);
+  });
+
+  it("should have propper type safety for tags", async () => {
+    const tag = defineTag({ id: "tag" });
+    const tag2 = defineTag<{ value: number }>({ id: "tag2" });
+    const tag2optional = defineTag<{ value?: number }>({ id: "tag2" });
+
+    const tag3 = tag2.with({ value: 123 });
+    // @ts-expect-error
+    const tag4 = tag.with({ value: 123 });
+
+    const task = defineTask({
+      id: "task",
+      meta: {
+        tags: [
+          tag,
+          // @ts-expect-error
+          tag2,
+          tag2optional,
+          tag2.with({ value: 123 }),
+          tag3,
+        ],
+      },
+    });
+
+    expect(true).toBe(true);
+  });
 });

package/src/define.ts

@@ -1,3 +1,10 @@
+/**
+ * Factory functions for defining tasks, resources, events and middleware.
+ *
+ * These helpers create strongly-typed definitions while also wiring internal
+ * metadata: anonymous IDs, file path tags (for better debugging), lifecycle
+ * events, and global middleware flags. See README for high-level concepts.
+ */
 import {
   ITask,
   ITaskDefinition,
@@ -16,6 +23,11 @@ import {
   symbolMiddlewareConfigured,
   symbolFilePath,
   symbolIndexResource,
+  ITag,
+  ITagDefinition,
+  ITagWithConfig,
+  TagType,
+  ITaggable,
 } from "./defs";
 import { Errors } from "./errors";
 import { generateCallerIdFromFile, getCallerFile } from "./tools/getCallerFile";
@@ -30,6 +42,12 @@ export function defineTask<
 >(
   taskConfig: ITaskDefinition<Input, Output, Deps, TOn>
 ): ITask<Input, Output, Deps, TOn> {
+  /**
+   * Creates a task definition.
+   * - Generates an anonymous id based on file path when `id` is omitted
+   * - Wires lifecycle events: beforeRun, afterRun, onError
+   * - Carries through dependencies and middleware as declared
+   */
   const filePath = getCallerFile();
   const isAnonymous = !Boolean(taskConfig.id);
   const id = taskConfig.id || generateCallerIdFromFile(filePath, "task");
@@ -81,6 +99,12 @@ export function defineResource<
 >(
   constConfig: IResourceDefinition<TConfig, TValue, TDeps, TPrivate>
 ): IResource<TConfig, TValue, TDeps, TPrivate> {
+  /**
+   * Creates a resource definition.
+   * - Generates anonymous id when omitted (resource or index flavor)
+   * - Wires lifecycle events: beforeInit, afterInit, onError
+   * - Exposes `.with(config)` for config‑bound registration
+   */
   // The symbolFilePath might already come from defineIndex() for example
   const filePath: string = constConfig[symbolFilePath] || getCallerFile();
   const isIndexResource = constConfig[symbolIndexResource] || false;
@@ -152,6 +176,7 @@ export function defineIndex<
       : T[K];
   } & DependencyMapType
 >(items: T): IResource<void, DependencyValuesType<D>, D> {
+  // Build dependency map from given items; unwrap `.with()` to the base resource
   const dependencies = {} as D;
   const register: RegisterableItems[] = [];
 
@@ -181,6 +206,10 @@ export function defineIndex<
 export function defineEvent<TPayload = void>(
   config?: IEventDefinition<TPayload>
 ): IEvent<TPayload> {
+  /**
+   * Creates an event definition. Anonymous ids are generated from file path
+   * when omitted. The returned object is branded for runtime checks.
+   */
   const callerFilePath = getCallerFile();
   const eventConfig = config || {};
   return {
@@ -208,6 +237,12 @@ export function defineMiddleware<
 >(
   middlewareDef: IMiddlewareDefinition<TConfig, TDependencies>
 ): IMiddleware<TConfig, TDependencies> {
+  /**
+   * Creates a middleware definition with:
+   * - Anonymous id generation when omitted
+   * - `.with(config)` to create configured instances
+   * - `.everywhere()` to mark as global (optionally scoping to tasks/resources)
+   */
   const filePath = getCallerFile();
   const object = {
     [symbols.filePath]: filePath,
@@ -266,3 +301,65 @@ export function isEvent(definition: any): definition is IEvent {
 export function isMiddleware(definition: any): definition is IMiddleware {
   return definition && definition[symbols.middleware];
 }
+
+/**
+ * Override helper that preserves the original `id` and returns the same type.
+ * You can override any property except `id`.
+ */
+export function defineOverride<T extends ITask<any, any, any, any>>(
+  base: T,
+  patch: Omit<Partial<T>, "id">
+): T;
+export function defineOverride<T extends IResource<any, any, any, any>>(
+  base: T,
+  patch: Omit<Partial<T>, "id">
+): T;
+export function defineOverride<T extends IMiddleware<any, any>>(
+  base: T,
+  patch: Omit<Partial<T>, "id">
+): T;
+export function defineOverride(
+  base: ITask | IResource | IMiddleware,
+  patch: Record<string | symbol, unknown>
+): ITask | IResource | IMiddleware {
+  const { id: _ignored, ...rest } = (patch || {}) as any;
+  // Ensure we never change the id, and merge overrides last
+  return {
+    ...(base as any),
+    ...rest,
+    id: (base as any).id,
+  } as any;
+}
+
+/**
+ * Creates a tag definition.
+ * - `.with(config)` to create configured instances
+ * - `.extract(tags)` to extract this tag from a list of tags
+ */
+export function defineTag<TConfig = void>(
+  definition: ITagDefinition<TConfig>
+): ITag<TConfig> {
+  const id = definition.id;
+
+  return {
+    id,
+    with(tagConfig: TConfig) {
+      return {
+        id,
+        tag: this,
+        config: tagConfig as any,
+      } as ITagWithConfig<TConfig>;
+    },
+    extract(target: TagType[] | ITaggable) {
+      const tags = Array.isArray(target) ? target : target?.meta?.tags || [];
+      for (const candidate of tags) {
+        if (typeof candidate === "string") continue;
+        // Configured instance
+        if (candidate.id === id) {
+          return candidate as ITagWithConfig<TConfig>;
+        }
+      }
+      return null;
+    },
+  } as ITag<TConfig>;
+}

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";
 
+/**
+ * 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,14 +45,23 @@ 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"
 );
 
+/**
+ * Convenience bag of internal symbols. Intended for framework internals;
+ * consumers should not rely on this shape.
+ * @internal
+ */
 export const symbols = {
   task: symbolTask,
   resource: symbolResource,
@@ -44,11 +75,76 @@ export const symbols = {
   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;
+}
+
+/**
+ * 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 +152,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 +172,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 +206,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 +232,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 +253,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
@@ -198,11 +325,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,8 +361,16 @@ 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.
@@ -266,8 +410,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 +423,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;
 }
@@ -327,8 +475,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,10 +501,15 @@ 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>;
 }
 
@@ -373,10 +531,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";