@bluelibs/runner 3.3.0 → 3.3.2

package/dist/models/StoreTypes.d.ts

@@ -1,4 +1,4 @@
-import { DependencyMapType, DependencyValuesType, IEventDefinition, IResource, ITask, IMiddleware } from "../defs";
+import { DependencyMapType, DependencyValuesType, IEventDefinition, IResource, ITask, IMiddleware, IEvent } from "../defs";
 export type ResourceStoreElementType<C = any, V = any, D extends DependencyMapType = {}, TContext = any> = {
     resource: IResource<C, V, D>;
     computedDependencies?: DependencyValuesType<D>;
@@ -17,5 +17,5 @@ export type MiddlewareStoreElementType<TDeps extends DependencyMapType = any> =
     computedDependencies: DependencyValuesType<TDeps>;
 };
 export type EventStoreElementType = {
-    event: IEventDefinition;
+    event: IEvent<any>;
 };

package/dist/types/dependencies.d.ts

@@ -1,21 +1,50 @@
-interface ITask<TInput = any, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TOn extends "*" | IEventDefinition<any> | undefined = undefined> {
-    id: string;
-}
-interface IResource<TConfig = void, TValue = any, TDependencies extends DependencyMapType = any, TContext = any> {
-    id: string;
-}
-interface IEventDefinition<TPayload = void> {
-    id: string;
-}
-export type DependencyMapType = Record<string, ITask<any, any, any, any> | IResource<any, any, any> | IEventDefinition<any>>;
-type ExtractTaskInput<T> = T extends ITask<infer I, any, infer D> ? I : never;
-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;
-type TaskDependency<I, O> = (...args: I extends null | void ? [] : [I]) => O;
-type ResourceDependency<V> = V;
-type EventDependency<P> = (input: P) => Promise<void>;
-export type DependencyValueType<T> = T extends ITask<any, any, any> ? TaskDependency<ExtractTaskInput<T>, ExtractTaskOutput<T>> : T extends IResource<any, any> ? ResourceDependency<ExtractResourceValue<T>> : T extends IEventDefinition<any> ? EventDependency<ExtractEventParams<T>> : never;
+/**
+ * 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, any>;
+type ExtractTaskInput<T> = T extends {
+    run: (...args: any[]) => any;
+} ? any : never;
+type ExtractTaskOutput<T> = T extends {
+    run: (...args: any[]) => infer R;
+} ? R : never;
+type ExtractResourceValue<T> = T extends {
+    init?: (...args: any[]) => Promise<infer V>;
+} ? V : T extends {
+    init?: (...args: any[]) => infer V;
+} ? V : any;
+type ExtractEventParams<T> = T extends {
+    id: any;
+} ? any : never;
+/**
+ * Task dependencies transform into callable functions: call with the task input
+ * and you receive the task output.
+ */
+export type TaskDependency<I, O> = (...args: I extends null | void ? [] : [I]) => O;
+/**
+ * Resource dependencies resolve to the resource's value directly.
+ */
+export type ResourceDependency<V> = V;
+/**
+ * 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).
+ */
+export type EventDependency<P> = P extends void ? (() => Promise<void>) & ((input?: Record<string, never>) => Promise<void>) : (input: P) => Promise<void>;
+/**
+ * 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 {
+    run: (...args: any[]) => any;
+} ? TaskDependency<ExtractTaskInput<T>, ExtractTaskOutput<T>> : T extends {
+    init?: (...args: any[]) => any;
+} ? ResourceDependency<ExtractResourceValue<T>> : T extends {
+    id: any;
+} ? EventDependency<ExtractEventParams<T>> : any;
 export type DependencyValuesType<T extends DependencyMapType> = {
     [K in keyof T]: DependencyValueType<T[K]>;
 };

package/dist/types/event.d.ts

@@ -0,0 +1,49 @@
+import { symbolEvent } from './symbols';
+import type { IEventMeta } from './metadata';
+export type EventHandlerType<T = any> = (event: IEventEmission<T>) => any | Promise<any>;
+export interface IEventDefinition<TPayload = void> {
+    /** Stable identifier. Omit to get an anonymous id. */
+    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.
+     */
+    data: TPayload;
+    /**
+     * The timestamp when the event was created.
+     */
+    timestamp: Date;
+    /**
+     * The source of the event. This can be useful for debugging.
+     */
+    source: string | symbol;
+    /**
+     * Metadata associated with the event definition.
+     */
+    meta: IEventMeta;
+    /**
+     * Stops propagation to remaining event listeners.
+     */
+    stopPropagation(): void;
+    /**
+     * Returns true if propagation has been stopped.
+     */
+    isPropagationStopped(): boolean;
+}

package/dist/types/event.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const symbols_1 = require("./symbols");
+//# sourceMappingURL=event.js.map

package/dist/types/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../../src/types/event.ts"],"names":[],"mappings":";;AAAA,uCAAwC"}

package/dist/types/index.d.ts

@@ -1,14 +1,8 @@
 export * from './symbols';
-export * from './base';
-export * from './utilities';
+export * from './metadata';
 export * from './dependencies';
-export * from './events';
-export * from './tasks';
-export * from './resources';
+export * from './event';
 export * from './middleware';
-export * from './hooks';
-import type { IResourceWithConfig, IResource, ITaskDefinition, IMiddlewareDefinition, IEventDefinition } from './index';
-export type RegisterableItems<T = any> = IResourceWithConfig<any> | IResource<void, any, any, any> | IResource<{
-    [K in any]?: any;
-}, any, any, any> | ITaskDefinition<any, any, any, any> | IMiddlewareDefinition<any> | IEventDefinition<any>;
+export * from './task';
+export * from './resource';
 export { ICacheInstance } from "../globals/middleware/cache.middleware";

package/dist/types/index.js

@@ -14,14 +14,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// Re-export everything from individual modules
+// Symbols
 __exportStar(require("./symbols"), exports);
-__exportStar(require("./base"), exports);
-__exportStar(require("./utilities"), exports);
+// Metadata and tagging system
+__exportStar(require("./metadata"), exports);
+// Dependencies
 __exportStar(require("./dependencies"), exports);
-__exportStar(require("./events"), exports);
-__exportStar(require("./tasks"), exports);
-__exportStar(require("./resources"), exports);
+// Core types
+__exportStar(require("./event"), exports);
 __exportStar(require("./middleware"), exports);
-__exportStar(require("./hooks"), exports);
+__exportStar(require("./task"), exports);
+__exportStar(require("./resource"), exports);
 //# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA+C;AAC/C,4CAA0B;AAC1B,yCAAuB;AACvB,8CAA4B;AAC5B,iDAA+B;AAC/B,2CAAyB;AACzB,0CAAwB;AACxB,8CAA4B;AAC5B,+CAA6B;AAC7B,0CAAwB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,UAAU;AACV,4CAA0B;AAE1B,8BAA8B;AAC9B,6CAA2B;AAE3B,eAAe;AACf,iDAA+B;AAE/B,aAAa;AACb,0CAAwB;AACxB,+CAA6B;AAC7B,yCAAuB;AACvB,6CAA2B"}

package/dist/types/metadata.d.ts

@@ -0,0 +1,75 @@
+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?: TagType[];
+}
+export interface ITaskMeta extends IMeta {
+}
+export interface IResourceMeta extends IMeta {
+}
+export interface IEventMeta extends IMeta {
+}
+export interface IMiddlewareMeta extends IMeta {
+}

package/dist/types/metadata.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=metadata.js.map

package/dist/types/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/types/metadata.ts"],"names":[],"mappings":""}

package/dist/types/middleware.d.ts

@@ -1,21 +1,24 @@
-import { symbolMiddleware, symbolMiddlewareConfigured, symbolMiddlewareEverywhereTasks, symbolMiddlewareEverywhereResources } from './symbols';
-import type { IMiddlewareMeta } from './meta';
-import type { DependencyMapType, DependencyValuesType } from './dependency-core';
-import type { ITask, IResource } from './base-interfaces';
-export interface IMiddlewareExecutionInput<TTaskInput = any, TResourceConfig = any> {
-    task?: {
-        definition: ITask<TTaskInput>;
-        input: TTaskInput;
-    };
-    resource?: {
-        definition: IResource<TResourceConfig>;
-        config: TResourceConfig;
-    };
-    next: (taskInputOrResourceConfig?: TTaskInput | TResourceConfig) => Promise<any>;
-}
+import type { symbolMiddleware, symbolMiddlewareConfigured, symbolMiddlewareEverywhereTasks, symbolMiddlewareEverywhereResources } from './symbols';
+import type { IMiddlewareMeta } from './metadata';
+import type { DependencyMapType, DependencyValuesType } from './dependencies';
+export type MiddlewareEverywhereOptions = {
+    /**
+     * Enable this for tasks. Default is true.
+     */
+    tasks?: boolean;
+    /**
+     * Enable this for resources. Default is true.
+     */
+    resources?: boolean;
+};
 export interface IMiddlewareDefinition<TConfig = any, TDependencies extends DependencyMapType = any> {
-    id: string;
-    dependencies?: TDependencies | (() => TDependencies);
+    /** 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>, config: TConfig) => Promise<any>;
     meta?: IMiddlewareMeta;
 }
@@ -24,9 +27,15 @@ export interface IMiddleware<TConfig = any, TDependencies extends DependencyMapT
     [symbolMiddlewareConfigured]?: boolean;
     [symbolMiddlewareEverywhereTasks]?: boolean;
     [symbolMiddlewareEverywhereResources]?: boolean;
+    id: string | symbol;
     dependencies: TDependencies | (() => TDependencies);
-    everywhere(): IMiddleware<TConfig, 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>;
 }
 export interface IMiddlewareConfigured<TConfig = any, TDependencies extends DependencyMapType = any> extends IMiddleware<TConfig, TDependencies> {
@@ -36,3 +45,19 @@ export interface IMiddlewareDefinitionConfigured<C extends Record<string, any> =
     middleware: IMiddleware<C>;
     config?: C;
 }
+export interface IMiddlewareExecutionInput<TTaskInput = any, TResourceConfig = any> {
+    /** Task hook: present when wrapping a task run. */
+    task?: {
+        definition: any;
+        input: TTaskInput;
+    };
+    /** Resource hook: present when wrapping init/dispose. */
+    resource?: {
+        definition: any;
+        config: TResourceConfig;
+    };
+    next: (taskInputOrResourceConfig?: TTaskInput | TResourceConfig) => Promise<any>;
+}
+export type MiddlewareAttachments = IMiddleware<void> | IMiddleware<{
+    [K in any]?: any;
+}> | IMiddlewareConfigured<any>;

package/dist/types/middleware.js

@@ -1,6 +1,3 @@
 "use strict";
-// Layer 3: Component Definitions - Middleware
-// Imports from Layer 1 & 2
 Object.defineProperty(exports, "__esModule", { value: true });
-const symbols_1 = require("./symbols");
 //# sourceMappingURL=middleware.js.map

package/dist/types/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/types/middleware.ts"],"names":[],"mappings":";AAAA,8CAA8C;AAC9C,2BAA2B;;AAE3B,uCAKmB"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/types/middleware.ts"],"names":[],"mappings":""}

package/dist/types/resource.d.ts

@@ -0,0 +1,96 @@
+import type { symbolFilePath, symbolIndexResource } from './symbols';
+import type { IResourceMeta } from './metadata';
+import type { DependencyMapType, DependencyValuesType } from './dependencies';
+import type { IEvent } from './event';
+import type { MiddlewareAttachments } from './middleware';
+export type BeforeInitEventPayload<TConfig> = {
+    config: TConfig;
+};
+export type AfterInitEventPayload<TConfig, TValue> = {
+    config: TConfig;
+    value: TValue;
+};
+export type OnErrorEventPayloadResource = {
+    error: any;
+    /**
+     * This function can be called to suppress the error from being thrown.
+     */
+    suppress(): void;
+};
+/**
+ * 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> | IResource<{
+    [K in any]?: any;
+}, any, any, any> | any | any | any;
+export interface IResourceDefinition<TConfig = any, TValue = unknown, TDependencies extends DependencyMapType = {}, TContext = any, 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, 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 (undefined if no init method)
+     * @param config The configuration it received
+     * @param dependencies The dependencies it needed
+     * @returns Promise<void>
+     */
+    dispose?: (this: any, value: TValue, config: TConfig, dependencies: DependencyValuesType<TDependencies>, context: TContext) => Promise<void>;
+    meta?: IResourceMeta;
+    /**
+     * Safe overrides to swap behavior while preserving identities. See
+     * README: Overrides.
+     */
+    overrides?: Array<IResource | any | any | 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.
+     */
+    [symbolFilePath]?: string;
+    /**
+     * This is used internally when creating index resources.
+     */
+    [symbolIndexResource]?: boolean;
+}
+export interface IResource<TConfig = void, TValue = any, 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> | ((config: TConfig) => Array<RegisterableItems>);
+    /**
+     * These events are automatically populated after the task has been defined.
+     */
+    events: {
+        beforeInit: IEvent<BeforeInitEventPayload<TConfig>>;
+        afterInit: IEvent<AfterInitEventPayload<TConfig, TValue>>;
+        onError: IEvent<OnErrorEventPayloadResource>;
+    };
+    overrides: Array<IResource | any | any | IResourceWithConfig>;
+    middleware: MiddlewareAttachments[];
+}
+export interface IResourceWithConfig<TConfig = any, 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;
+}

package/dist/types/resource.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=resource.js.map

package/dist/types/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/types/resource.ts"],"names":[],"mappings":""}

package/dist/types/symbols.d.ts

@@ -1,3 +1,9 @@
+/**
+ * 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 declare const symbolTask: unique symbol;
 export declare const symbolResource: unique symbol;
 export declare const symbolResourceWithConfig: unique symbol;
@@ -7,13 +13,24 @@ export declare const symbolMiddlewareConfigured: unique symbol;
 export declare const symbolMiddlewareGlobal: unique symbol;
 export declare const symbolMiddlewareEverywhereTasks: unique symbol;
 export declare const symbolMiddlewareEverywhereResources: unique symbol;
+/** @internal Path to aid anonymous id generation and error messages */
 export declare const symbolFilePath: unique symbol;
+/** @internal Marks disposable instances */
 export declare const symbolDispose: unique symbol;
+/** @internal Link to internal Store */
 export declare const symbolStore: unique symbol;
+/** @internal Brand used by index() resources */
+export declare const symbolIndexResource: unique symbol;
+/**
+ * Convenience bag of internal symbols. Intended for framework internals;
+ * consumers should not rely on this shape.
+ * @internal
+ */
 export declare const symbols: {
     task: symbol;
     resource: symbol;
     resourceWithConfig: symbol;
+    indexResource: symbol;
     event: symbol;
     middleware: symbol;
     middlewareEverywhereTasks: symbol;

package/dist/types/symbols.js

@@ -1,8 +1,12 @@
 "use strict";
-// Layer 1: Foundation - Symbols and Constants
-// No dependencies
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.symbols = exports.symbolStore = exports.symbolDispose = exports.symbolFilePath = exports.symbolMiddlewareEverywhereResources = exports.symbolMiddlewareEverywhereTasks = exports.symbolMiddlewareGlobal = exports.symbolMiddlewareConfigured = exports.symbolMiddleware = exports.symbolEvent = exports.symbolResourceWithConfig = exports.symbolResource = exports.symbolTask = void 0;
+exports.symbols = exports.symbolIndexResource = exports.symbolStore = exports.symbolDispose = exports.symbolFilePath = exports.symbolMiddlewareEverywhereResources = exports.symbolMiddlewareEverywhereTasks = exports.symbolMiddlewareGlobal = exports.symbolMiddlewareConfigured = exports.symbolMiddleware = exports.symbolEvent = exports.symbolResourceWithConfig = exports.symbolResource = exports.symbolTask = void 0;
+/**
+ * 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
+ */
 exports.symbolTask = Symbol("runner.task");
 exports.symbolResource = Symbol("runner.resource");
 exports.symbolResourceWithConfig = Symbol("runner.resourceWithConfig");
@@ -12,13 +16,24 @@ exports.symbolMiddlewareConfigured = Symbol("runner.middlewareConfigured");
 exports.symbolMiddlewareGlobal = Symbol("runner.middlewareGlobal");
 exports.symbolMiddlewareEverywhereTasks = Symbol("runner.middlewareGlobalTasks");
 exports.symbolMiddlewareEverywhereResources = Symbol("runner.middlewareGlobalResources");
+/** @internal Path to aid anonymous id generation and error messages */
 exports.symbolFilePath = Symbol("runner.filePath");
+/** @internal Marks disposable instances */
 exports.symbolDispose = Symbol("runner.dispose");
+/** @internal Link to internal Store */
 exports.symbolStore = Symbol("runner.store");
+/** @internal Brand used by index() resources */
+exports.symbolIndexResource = Symbol("runner.indexResource");
+/**
+ * Convenience bag of internal symbols. Intended for framework internals;
+ * consumers should not rely on this shape.
+ * @internal
+ */
 exports.symbols = {
     task: exports.symbolTask,
     resource: exports.symbolResource,
     resourceWithConfig: exports.symbolResourceWithConfig,
+    indexResource: exports.symbolIndexResource,
     event: exports.symbolEvent,
     middleware: exports.symbolMiddleware,
     middlewareEverywhereTasks: exports.symbolMiddlewareEverywhereTasks,

package/dist/types/symbols.js.map

@@ -1 +1 @@
-{"version":3,"file":"symbols.js","sourceRoot":"","sources":["../../src/types/symbols.ts"],"names":[],"mappings":";AAAA,8CAA8C;AAC9C,kBAAkB;;;AAEL,QAAA,UAAU,GAAkB,MAAM,CAAC,aAAa,CAAC,CAAC;AAClD,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC1D,QAAA,wBAAwB,GAAkB,MAAM,CAC3D,2BAA2B,CAC5B,CAAC;AACW,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AACpD,QAAA,gBAAgB,GAAkB,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAC9D,QAAA,0BAA0B,GAAkB,MAAM,CAC7D,6BAA6B,CAC9B,CAAC;AACW,QAAA,sBAAsB,GAAkB,MAAM,CACzD,yBAAyB,CAC1B,CAAC;AACW,QAAA,+BAA+B,GAAkB,MAAM,CAClE,8BAA8B,CAC/B,CAAC;AACW,QAAA,mCAAmC,GAAkB,MAAM,CACtE,kCAAkC,CACnC,CAAC;AAEW,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC1D,QAAA,aAAa,GAAkB,MAAM,CAAC,gBAAgB,CAAC,CAAC;AACxD,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AAEpD,QAAA,OAAO,GAAG;IACrB,IAAI,EAAE,kBAAU;IAChB,QAAQ,EAAE,sBAAc;IACxB,kBAAkB,EAAE,gCAAwB;IAC5C,KAAK,EAAE,mBAAW;IAClB,UAAU,EAAE,wBAAgB;IAC5B,yBAAyB,EAAE,uCAA+B;IAC1D,6BAA6B,EAAE,2CAAmC;IAClE,QAAQ,EAAE,sBAAc;IACxB,OAAO,EAAE,qBAAa;IACtB,KAAK,EAAE,mBAAW;CACnB,CAAC"}
+{"version":3,"file":"symbols.js","sourceRoot":"","sources":["../../src/types/symbols.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACU,QAAA,UAAU,GAAkB,MAAM,CAAC,aAAa,CAAC,CAAC;AAClD,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC1D,QAAA,wBAAwB,GAAkB,MAAM,CAC3D,2BAA2B,CAC5B,CAAC;AACW,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AACpD,QAAA,gBAAgB,GAAkB,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAC9D,QAAA,0BAA0B,GAAkB,MAAM,CAC7D,6BAA6B,CAC9B,CAAC;AACW,QAAA,sBAAsB,GAAkB,MAAM,CACzD,yBAAyB,CAC1B,CAAC;AACW,QAAA,+BAA+B,GAAkB,MAAM,CAClE,8BAA8B,CAC/B,CAAC;AACW,QAAA,mCAAmC,GAAkB,MAAM,CACtE,kCAAkC,CACnC,CAAC;AAEF,uEAAuE;AAC1D,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AACvE,2CAA2C;AAC9B,QAAA,aAAa,GAAkB,MAAM,CAAC,gBAAgB,CAAC,CAAC;AACrE,uCAAuC;AAC1B,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AAEjE,gDAAgD;AACnC,QAAA,mBAAmB,GAAkB,MAAM,CACtD,sBAAsB,CACvB,CAAC;AAEF;;;;GAIG;AACU,QAAA,OAAO,GAAG;IACrB,IAAI,EAAE,kBAAU;IAChB,QAAQ,EAAE,sBAAc;IACxB,kBAAkB,EAAE,gCAAwB;IAC5C,aAAa,EAAE,2BAAmB;IAClC,KAAK,EAAE,mBAAW;IAClB,UAAU,EAAE,wBAAgB;IAC5B,yBAAyB,EAAE,uCAA+B;IAC1D,6BAA6B,EAAE,2CAAmC;IAClE,QAAQ,EAAE,sBAAc;IACxB,OAAO,EAAE,qBAAa;IACtB,KAAK,EAAE,mBAAW;CACnB,CAAC"}

package/dist/types/task.d.ts

@@ -0,0 +1,68 @@
+import type { ITaskMeta } from './metadata';
+import type { DependencyMapType, DependencyValuesType } from './dependencies';
+import type { IEventDefinition, IEvent, IEventEmission } from './event';
+import type { MiddlewareAttachments } from './middleware';
+export type BeforeRunEventPayload<TInput> = {
+    input: TInput;
+};
+export type AfterRunEventPayload<TInput, TOutput> = {
+    input: TInput;
+    output: TOutput extends Promise<infer U> ? U : TOutput;
+    setOutput(newOutput: TOutput extends Promise<infer U> ? U : TOutput): void;
+};
+export type OnErrorEventPayload = {
+    error: any;
+    /**
+     * This function can be called to suppress the error from being thrown.
+     */
+    suppress(): void;
+};
+type ExtractEventParams<T> = T extends IEventDefinition<infer P> ? P : never;
+export interface ITaskDefinition<TInput = any, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TOn extends "*" | IEventDefinition<any> | undefined = undefined> {
+    /**
+     * 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
+     */
+    on?: TOn;
+    /**
+     * This makes sense only when `on` is specified to provide the order of the execution.
+     * 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 : IEventEmission<TOn extends "*" ? any : ExtractEventParams<TOn>>, dependencies: DependencyValuesType<TDependencies>) => TOutput;
+}
+/**
+ * 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 = {}, TOn extends "*" | IEventDefinition<any> | undefined = undefined> extends ITaskDefinition<TInput, TOutput, TDependencies, TOn> {
+    id: string | symbol;
+    dependencies: TDependencies | (() => TDependencies);
+    computedDependencies?: DependencyValuesType<TDependencies>;
+    middleware: MiddlewareAttachments[];
+    /**
+     * These events are automatically populated after the task has been defined.
+     */
+    events: {
+        beforeRun: IEvent<BeforeRunEventPayload<TInput>>;
+        afterRun: IEvent<AfterRunEventPayload<TInput, TOutput>>;
+        onError: IEvent<OnErrorEventPayload>;
+    };
+}
+export {};

package/dist/types/task.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=task.js.map

package/dist/types/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/types/task.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluelibs/runner",
-  "version": "3.3.0",
+  "version": "3.3.2",
   "description": "BlueLibs Runner",
   "main": "dist/index.js",
   "repository": {