@bluelibs/runner 5.1.0 → 5.2.1

package/dist/types/types/inputFile.d.ts

@@ -0,0 +1,34 @@
+export interface InputFileMeta {
+    name: string;
+    type?: string;
+    size?: number;
+    lastModified?: number;
+    extra?: Record<string, unknown>;
+}
+/** Universal interface exposed to tasks for streamed files. */
+export interface InputFile<TStream = unknown> extends InputFileMeta {
+    /**
+     * Resolve the underlying stream for one-time consumption.
+     * Implementations must enforce single-use semantics.
+     */
+    resolve(): Promise<{
+        stream: TStream;
+    }>;
+    /**
+     * Return the underlying stream (single-use). Should throw if already consumed.
+     */
+    stream(): TStream;
+    /**
+     * Persist the stream to a temporary file on disk and return its path and number of bytes written.
+     */
+    toTempFile(dir?: string): Promise<{
+        path: string;
+        bytesWritten: number;
+    }>;
+}
+/** Client-side sentinel to declare file presence in an input structure. */
+export interface RunnerFileSentinel {
+    $runnerFile: "File";
+    id: string;
+    meta: InputFileMeta;
+}

package/dist/types/types/meta.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Common metadata you can attach to tasks/resources/events/middleware.
+ * Useful for docs, filtering and middleware decisions.
+ */
+export interface IMeta {
+    title?: string;
+    description?: string;
+}
+export interface ITaskMeta extends IMeta {
+}
+export interface IResourceMeta extends IMeta {
+}
+export interface IEventMeta extends IMeta {
+}
+export interface IMiddlewareMeta extends IMeta {
+}
+export interface ITagMeta extends IMeta {
+}
+export interface IErrorMeta extends IMeta {
+}
+export interface IAsyncContextMeta extends IMeta {
+}

package/dist/types/types/resource.d.ts

@@ -0,0 +1,133 @@
+import { DependencyMapType, IOptionalDependency, IValidationSchema, OverridableElements, RegisterableItems, ResourceDependencyValuesType } from "./utilities";
+import { IResourceMiddleware, ResourceMiddlewareAttachmentType } from "./resourceMiddleware";
+import { TagType } from "./tag";
+import { IResourceMeta } from "./meta";
+import type { ThrowsList } from "./error";
+import { symbolFilePath, symbolResource, symbolResourceWithConfig, symbolResourceForkedFrom } from "./symbols";
+import { EnsureInputSatisfiesContracts, EnsureOutputSatisfiesContracts, HasInputContracts, HasOutputContracts, InferInputOrViolationFromContracts } from "./contracts";
+export type { DependencyMapType, IOptionalDependency, IValidationSchema, OverridableElements, RegisterableItems, ResourceDependencyValuesType, } from "./utilities";
+export type { ResourceMiddlewareAttachmentType } from "./resourceMiddleware";
+export type { TagType } from "./tag";
+export type { IResourceMeta } from "./meta";
+export type ResourceForkRegisterMode = "keep" | "drop" | "deep";
+export interface ResourceForkOptions {
+    /**
+     * Control whether the fork keeps the base `register` list.
+     * - "keep" (default) keeps registration items
+     * - "drop" clears registration items
+     * - "deep" deep-forks registered resources with new ids (resource tree)
+     */
+    register?: ResourceForkRegisterMode;
+    /**
+     * Used with `register: "deep"` to derive ids for deep-forked resources.
+     * Defaults to `(id) => \`\${newId}.\${id}\``.
+     */
+    reId?: (id: string) => string;
+}
+export interface ResourceForkInfo {
+    /** The id of the resource that was forked. */
+    readonly fromId: string;
+    /** Best-effort call-site file path for the fork operation. */
+    readonly forkedAtFilePath: string;
+}
+export type IsAny<T> = 0 extends 1 & T ? true : false;
+export type IsUnspecified<T> = [T] extends [undefined] ? true : [T] extends [void] ? true : IsAny<T> extends true ? true : false;
+export interface IResourceDefinition<TConfig = any, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = {}, TContext = any, _THooks = any, _TRegisterableItems = any, TMeta extends IResourceMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends ResourceMiddlewareAttachmentType[] = ResourceMiddlewareAttachmentType[]> {
+    /** Stable identifier. */
+    id: string;
+    /** 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?: (config: HasInputContracts<[...TTags, ...TMiddleware]> extends true ? IsUnspecified<TConfig> extends true ? InferInputOrViolationFromContracts<[...TTags, ...TMiddleware]> : EnsureInputSatisfiesContracts<[...TTags, ...TMiddleware], TConfig> : TConfig, dependencies: ResourceDependencyValuesType<TDependencies>, context: TContext) => HasOutputContracts<[...TTags, ...TMiddleware]> extends true ? EnsureOutputSatisfiesContracts<[...TTags, ...TMiddleware], TValue> : TValue;
+    /**
+     * Optional validation schema for the resource's resolved value.
+     * When provided, the value will be validated immediately after `init` resolves,
+     * without considering middleware.
+     */
+    resultSchema?: IValidationSchema<TValue extends Promise<infer U> ? U : 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 extends Promise<infer U> ? U : TValue, config: TConfig, dependencies: ResourceDependencyValuesType<TDependencies>, context: TContext) => Promise<void>;
+    meta?: TMeta;
+    /**
+     * Declares which typed errors are part of this resource's contract.
+     *
+     * This is a declarative contract only:
+     * - It does not imply dependency injection
+     * - It does not enforce that only these errors can be thrown
+     *
+     * Use string ids or Error helpers.
+     */
+    throws?: ThrowsList;
+    /**
+     * Optional validation schema for runtime config validation.
+     * When provided, resource config will be validated when .with() is called.
+     */
+    configSchema?: IValidationSchema<TConfig>;
+    /**
+     * Safe overrides to swap behavior while preserving identities. See
+     * README: Overrides.
+     */
+    overrides?: Array<OverridableElements>;
+    /** Middleware applied around init/dispose. */
+    middleware?: TMiddleware;
+    /**
+     * 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;
+    tags?: TTags;
+}
+/**
+ * Helper alias describing the canonical resource init call signature.
+ * Shared with fluent builders to keep init typing consistent.
+ */
+export type ResourceInitFn<TConfig, TValue extends Promise<any>, TDependencies extends DependencyMapType, TContext, TMeta extends IResourceMeta, TTags extends TagType[], TMiddleware extends ResourceMiddlewareAttachmentType[]> = NonNullable<IResourceDefinition<TConfig, TValue, TDependencies, TContext, any, any, TMeta, TTags, TMiddleware>["init"]>;
+export interface IResource<TConfig = void, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = any, TContext = any, TMeta extends IResourceMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends ResourceMiddlewareAttachmentType[] = ResourceMiddlewareAttachmentType[]> extends IResourceDefinition<TConfig, TValue, TDependencies, TContext, any, any, TMeta, TTags, TMiddleware> {
+    id: string;
+    with(config: HasInputContracts<[...TTags, ...TMiddleware]> extends true ? IsUnspecified<TConfig> extends true ? InferInputOrViolationFromContracts<[...TTags, ...TMiddleware]> : TConfig : TConfig): IResourceWithConfig<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>;
+    register: Array<RegisterableItems> | ((config: TConfig) => Array<RegisterableItems>);
+    overrides: Array<OverridableElements>;
+    middleware: TMiddleware;
+    [symbolFilePath]: string;
+    [symbolResource]: true;
+    /** Present only on forked resources. */
+    [symbolResourceForkedFrom]?: ResourceForkInfo;
+    /** Normalized list of error ids declared via `throws`. */
+    throws?: readonly string[];
+    /** Return an optional dependency wrapper for this resource. */
+    optional: () => IOptionalDependency<IResource<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>>;
+    tags: TTags;
+    /**
+     * Create a new resource with a different id but the same definition.
+     * Useful for creating multiple instances of a "template" resource.
+     * The forked resource should be exported and used as a dependency.
+     */
+    fork(newId: string, options?: ResourceForkOptions): IResource<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>;
+}
+export interface IResourceWithConfig<TConfig = any, TValue extends Promise<any> = Promise<any>, TDependencies extends DependencyMapType = any, TContext = any, TMeta extends IResourceMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends IResourceMiddleware<any, any, any, any>[] = IResourceMiddleware[]> {
+    [symbolResourceWithConfig]: true;
+    /** The id of the underlying resource. */
+    id: string;
+    /** The underlying resource definition. */
+    resource: IResource<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>;
+    /** The configuration captured by `.with(config)`. */
+    config: TConfig;
+}

package/dist/types/types/resourceMiddleware.d.ts

@@ -0,0 +1,48 @@
+import { DependencyMapType, DependencyValuesType, IValidationSchema } from "./utilities";
+import type { IResource } from "./resource";
+import { TagType } from "./tag";
+import { IMiddlewareMeta } from "./meta";
+import { symbolFilePath, symbolMiddlewareConfigured, symbolResourceMiddleware } from "./symbols";
+import { IContractable } from "./contracts";
+export interface IResourceMiddlewareDefinition<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> {
+    id: string;
+    /** Static or lazy dependency map. */
+    dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+    /**
+     * Optional validation schema for runtime config validation.
+     * When provided, middleware config will be validated when .with() is called.
+     */
+    configSchema?: IValidationSchema<TConfig>;
+    /**
+     * The middleware body, called with resource execution input.
+     */
+    run: (input: IResourceMiddlewareExecutionInput<TEnforceInputContract extends void ? any : TEnforceInputContract, TEnforceOutputContract extends void ? any : TEnforceOutputContract>, dependencies: DependencyValuesType<TDependencies>, config: TConfig) => Promise<any>;
+    meta?: IMiddlewareMeta;
+    tags?: TagType[];
+    everywhere?: boolean | ((resource: IResource<any, any, any, any, any>) => boolean);
+}
+export interface IResourceMiddleware<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> extends IResourceMiddlewareDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>, IContractable<TConfig, TEnforceInputContract, TEnforceOutputContract> {
+    [symbolResourceMiddleware]: true;
+    id: string;
+    dependencies: TDependencies | ((config: TConfig) => TDependencies);
+    /** Current configuration object (empty by default). */
+    config: TConfig;
+    /** Configure the middleware and return a marked, configured instance. */
+    with: (config: TConfig) => IResourceMiddlewareConfigured<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+    [symbolFilePath]: string;
+    tags: TagType[];
+}
+export interface IResourceMiddlewareConfigured<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> extends IResourceMiddleware<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies> {
+    [symbolMiddlewareConfigured]: true;
+}
+export interface IResourceMiddlewareExecutionInput<TResourceConfig = any, TResourceOutput = any> {
+    /** Resource hook */
+    resource: {
+        definition: IResource<TResourceConfig, any, any, any, any>;
+        config: TResourceConfig;
+    };
+    next: (resourceConfig?: TResourceConfig) => Promise<TResourceOutput>;
+}
+export type ResourceMiddlewareAttachmentType = IResourceMiddleware<void, any, any, any> | IResourceMiddleware<{
+    [K in any]?: any;
+}, any, any, any> | IResourceMiddlewareConfigured<any, any, any, any>;

package/dist/types/types/runner.d.ts

@@ -0,0 +1,68 @@
+import { DebugFriendlyConfig } from "../globals/resources/debug";
+import { LogLevels, PrintStrategy } from "../models/Logger";
+import { OnUnhandledError } from "../models/UnhandledError";
+export type RunOptions = {
+    /**
+     * Defaults to undefined. If true, we introduce logging to the console.
+     */
+    debug?: DebugFriendlyConfig;
+    /**
+     * Configure logging settings.
+     */
+    logs?: {
+        /**
+         * Defaults to info. Use null to disable logging.
+         */
+        printThreshold?: null | LogLevels;
+        /**
+         * Defaults to PRETTY. How to print the logs.
+         */
+        printStrategy?: PrintStrategy;
+        /**
+         * Defaults to false. If true, we buffer logs until the root resource is ready.
+         * This provides you with the chance to see the logs before the root resource is ready.
+         */
+        bufferLogs?: boolean;
+    };
+    /**
+     * When true (default), installs a central error boundary that catches uncaught errors
+     * from process-level events and routes them to `onUnhandledError`.
+     */
+    errorBoundary?: boolean;
+    /**
+     * When true (default), installs SIGINT/SIGTERM handlers that call dispose() on the root allowing for graceful shutdown.
+     */
+    shutdownHooks?: boolean;
+    /**
+     * Custom handler for any unhandled error caught by Runner. Defaults to logging via the created logger.
+     */
+    onUnhandledError?: OnUnhandledError;
+    /**
+     * Defaults to false.
+     *
+     * Dry run mode. When true, the runner will setup the system, ensure there are no errors, but will not start the system.
+     * Your resources will not be initialized, and no events will be emitted. This is useful for testing and debugging.
+     *
+     * Note: this cannot catch init() errors that happen within resources.
+     */
+    dryRun?: boolean;
+    /**
+     * Defaults to true.
+     * When set, forces runtime cycle detection for event emissions. Disable if you're sure
+     * you don't have event deadlocks to improve event emission performance.
+     */
+    runtimeEventCycleDetection?: boolean;
+    /**
+     * Specify in which mode to run "dev", "prod" or "test".
+     * If inside Node this is automatically detected from the NODE_ENV environment variable if not provided.
+     */
+    mode?: RunnerMode;
+};
+/**
+ * The mode in which the runner is operating
+ */
+export declare enum RunnerMode {
+    TEST = "test",
+    DEV = "dev",
+    PROD = "prod"
+}

package/dist/types/types/storeTypes.d.ts

@@ -0,0 +1,46 @@
+import { DependencyMapType, DependencyValuesType, ResourceDependencyValuesType } from "./utilities";
+import { IResource } from "./resource";
+import { ITask } from "./task";
+import { IHook } from "./hook";
+import { ITaskMiddleware } from "./taskMiddleware";
+import { IResourceMiddleware } from "./resourceMiddleware";
+import { IEvent } from "./event";
+import { IEventDefinition } from "./event";
+import { TaskLocalInterceptor } from "./utilities";
+export declare enum HookDependencyState {
+    Pending = "pending",
+    Computing = "computing",
+    Ready = "ready"
+}
+export type ResourceStoreElementType<C = any, V extends Promise<any> = any, D extends DependencyMapType = {}, TContext = any> = {
+    resource: IResource<C, V, D, TContext>;
+    computedDependencies?: ResourceDependencyValuesType<D>;
+    config: C;
+    value: V;
+    context: TContext;
+    isInitialized?: boolean;
+};
+export type TaskStoreElementType<Input = any, Output extends Promise<any> = any, D extends DependencyMapType = any> = {
+    task: ITask<Input, Output, D>;
+    computedDependencies: DependencyValuesType<D>;
+    isInitialized: boolean;
+    interceptors?: Array<TaskLocalInterceptor<any, any>>;
+};
+export type HookStoreElementType<D extends DependencyMapType = any, TOn extends "*" | IEventDefinition = any> = {
+    hook: IHook<D, TOn>;
+    computedDependencies: DependencyValuesType<D>;
+    dependencyState: HookDependencyState;
+};
+export type TaskMiddlewareStoreElementType<TDeps extends DependencyMapType = any> = {
+    middleware: ITaskMiddleware<any, any, any, TDeps>;
+    computedDependencies: DependencyValuesType<TDeps>;
+    isInitialized: boolean;
+};
+export type ResourceMiddlewareStoreElementType<TDeps extends DependencyMapType = any> = {
+    middleware: IResourceMiddleware<any, any, any, TDeps>;
+    computedDependencies: DependencyValuesType<TDeps>;
+    isInitialized: boolean;
+};
+export type EventStoreElementType = {
+    event: IEvent<any>;
+};

package/dist/types/types/symbols.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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;
+/** Marks a task as a phantom task (no-op run; meant to be tunneled/routed). */
+export declare const symbolPhantomTask: unique symbol;
+export declare const symbolResource: unique symbol;
+/** @internal Marks forked resources and records fork provenance */
+export declare const symbolResourceForkedFrom: unique symbol;
+export declare const symbolResourceWithConfig: unique symbol;
+export declare const symbolEvent: unique symbol;
+/** @internal Marks an error helper definition */
+export declare const symbolError: unique symbol;
+export declare const symbolMiddleware: unique symbol;
+/** New brands for separated middleware kinds */
+export declare const symbolTaskMiddleware: unique symbol;
+export declare const symbolResourceMiddleware: unique symbol;
+export declare const symbolMiddlewareConfigured: unique symbol;
+/** Records which tunnel resource owns the task patching (exclusivity). */
+export declare const symbolTunneledBy: unique symbol;
+/** @internal Marks hook definitions (event listeners without middleware) */
+export declare const symbolHook: unique symbol;
+/** @internal Marks a tag definition */
+export declare const symbolTag: unique symbol;
+export declare const symbolTagConfigured: unique symbol;
+/** @internal Marks an optional dependency wrapper */
+export declare const symbolOptionalDependency: unique symbol;
+/** @internal Path to aid anonymous id generation and error messages */
+export declare const symbolFilePath: unique symbol;
+/** @internal Marks an async context definition */
+export declare const symbolAsyncContext: unique symbol;

package/dist/types/types/tag.d.ts

@@ -0,0 +1,45 @@
+import { IContractable } from "./contracts";
+import { ITagMeta } from "./meta";
+import { IValidationSchema, RequiredKeys, symbolFilePath, symbolTag, symbolTagConfigured } from "./utilities";
+export interface ITaggable {
+    tags: TagType[];
+}
+export interface ITagDefinition<TConfig = void, _TEnforceInputContract = void, _TEnforceOutputContract = void> {
+    id: string;
+    meta?: ITagMeta;
+    configSchema?: IValidationSchema<TConfig>;
+    /**
+     * Utilizing config at definition level stores its defaults
+     */
+    config?: TConfig;
+}
+export interface ITag<TConfig = void, TEnforceInputContract = void, TEnforceOutputContract = void> extends ITagDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract>, IContractable<TConfig, TEnforceInputContract, TEnforceOutputContract> {
+    /**
+     * A special validation property.
+     * It resolves to `true` if TConfig only has optional keys, otherwise `false`.
+     */
+    readonly __configHasOnlyOptionalKeys: RequiredKeys<TConfig> extends never ? true : false;
+    config?: TConfig;
+    /**
+     * Checks if the tag exists in a taggable or a list of tags.
+     */
+    exists(target: ITaggable | TagType[]): boolean;
+    /**
+     * Creates a configured instance of the tag.
+     */
+    with(config: TConfig): ITagConfigured<TConfig, TEnforceInputContract, TEnforceOutputContract>;
+    /**
+     * Extracts the configuration of the tag from a taggable or a list of tags.
+     */
+    extract(target: ITaggable | TagType[]): TConfig | undefined;
+    [symbolFilePath]: string;
+    [symbolTag]: true;
+}
+export type ITagWithOptionalConfig<_TValue, TEnforceInputContract, TEnforceOutputContract> = ITag<any, TEnforceInputContract, TEnforceOutputContract> & {
+    readonly __configHasOnlyOptionalKeys: true;
+};
+export interface ITagConfigured<TConfig = void, TEnforceInputContract = void, TEnforceOutputContract = void> extends ITag<TConfig, TEnforceInputContract, TEnforceOutputContract> {
+    [symbolTagConfigured]: true;
+    config: TConfig;
+}
+export type TagType = ITag<void, any, any> | ITagWithOptionalConfig<any, any, any> | ITagConfigured<any, any, any>;

package/dist/types/types/task.d.ts

@@ -0,0 +1,76 @@
+import { DependencyMapType, DependencyValuesType, IOptionalDependency, IValidationSchema } from "./utilities";
+import { TaskMiddlewareAttachmentType } from "./taskMiddleware";
+import { TagType } from "./tag";
+import { ITaskMeta } from "./meta";
+import type { ThrowsList } from "./error";
+import type { ExecutionJournal } from "./executionJournal";
+import { symbolFilePath, symbolTask, symbolPhantomTask, symbolTunneledBy } from "./symbols";
+import { EnsureInputSatisfiesContracts, EnsureOutputSatisfiesContracts, HasInputContracts, HasOutputContracts, InferInputOrViolationFromContracts } from "./contracts";
+export type { DependencyMapType, DependencyValuesType, IOptionalDependency, } from "./utilities";
+export type { TaskMiddlewareAttachmentType } from "./taskMiddleware";
+export type { TagType } from "./tag";
+export type { ITaskMeta } from "./meta";
+export interface ITaskDefinition<TInput = undefined, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]> {
+    id: string;
+    /**
+     * 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?: TMiddleware;
+    /** Optional metadata used for docs, filtering and tooling. */
+    meta?: TMeta;
+    /**
+     * Optional validation schema for runtime input validation.
+     * When provided, task input will be validated before execution.
+     */
+    inputSchema?: IValidationSchema<TInput>;
+    /**
+     * Optional validation schema for the task result.
+     * When provided, the result will be validated immediately after the task's
+     * `run` resolves, without considering middleware.
+     */
+    resultSchema?: IValidationSchema<TOutput extends Promise<infer U> ? U : never>;
+    /**
+     * Declares which typed errors are part of this task's contract.
+     *
+     * This is a declarative contract only:
+     * - It does not imply dependency injection
+     * - It does not enforce that only these errors can be thrown
+     *
+     * Use string ids or Error helpers.
+     */
+    throws?: ThrowsList;
+    run: (input: HasInputContracts<[...TTags, ...TMiddleware]> extends true ? [TInput] extends [undefined] ? InferInputOrViolationFromContracts<[...TTags, ...TMiddleware]> : EnsureInputSatisfiesContracts<[...TTags, ...TMiddleware], TInput> : TInput, dependencies: DependencyValuesType<TDependencies>, context?: {
+        journal: ExecutionJournal;
+    }) => HasOutputContracts<[...TTags, ...TMiddleware]> extends true ? EnsureOutputSatisfiesContracts<[...TTags, ...TMiddleware], TOutput> : TOutput;
+    /**
+     * Tags applied to the task that might define its behvaiour or impact the systems.
+     */
+    tags?: TTags;
+}
+export interface ITask<TInput = any, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]> extends ITaskDefinition<TInput, TOutput, TDependencies, TMeta, TTags, TMiddleware> {
+    [symbolFilePath]: string;
+    [symbolTask]: true;
+    /** Present only for phantom tasks. */
+    [symbolPhantomTask]?: true;
+    /** Indicates if the task is tunneled through a tunnel client. */
+    isTunneled?: boolean;
+    /** Records which tunnel resource owns the task (exclusivity). */
+    [symbolTunneledBy]?: string;
+    id: string;
+    dependencies: TDependencies | (() => TDependencies);
+    computedDependencies?: DependencyValuesType<TDependencies>;
+    middleware: TMiddleware;
+    /** Normalized list of error ids declared via `throws`. */
+    throws?: readonly string[];
+    /** Return an optional dependency wrapper for this task. */
+    optional: () => IOptionalDependency<ITask<TInput, TOutput, TDependencies, TMeta, TTags, TMiddleware>>;
+    tags: TTags;
+}
+export type AnyTask = ITask<any, any, any, any, any, any>;
+/** Narrowed type for phantom tasks (no-op run by default). */
+export type IPhantomTask<TInput = any, TResolved = any, TDependencies extends DependencyMapType = {}, TMeta extends ITaskMeta = any, TTags extends TagType[] = TagType[], TMiddleware extends TaskMiddlewareAttachmentType[] = TaskMiddlewareAttachmentType[]> = ITask<TInput, Promise<TResolved>, TDependencies, TMeta, TTags, TMiddleware> & {
+    [symbolPhantomTask]: true;
+};

package/dist/types/types/taskMiddleware.d.ts

@@ -0,0 +1,55 @@
+import { DependencyMapType, DependencyValuesType, IValidationSchema } from "./utilities";
+import type { ITask } from "./task";
+import type { ExecutionJournal } from "./executionJournal";
+import { TagType } from "./tag";
+import { IMiddlewareMeta } from "./meta";
+import { symbolFilePath, symbolMiddlewareConfigured, symbolTaskMiddleware } from "./symbols";
+import { IContractable } from "./contracts";
+export type { DependencyMapType, DependencyValuesType } from "./utilities";
+export type { TagType } from "./tag";
+export type { IMiddlewareMeta } from "./meta";
+export interface ITaskMiddlewareDefinition<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> {
+    id: string;
+    /** Static or lazy dependency map. */
+    dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+    /**
+     * Optional validation schema for runtime config validation.
+     * When provided, middleware config will be validated when .with() is called.
+     */
+    configSchema?: IValidationSchema<TConfig>;
+    /**
+     * The middleware body, called with task execution input.
+     */
+    run: (input: ITaskMiddlewareExecutionInput<TEnforceInputContract extends void ? any : TEnforceInputContract, TEnforceOutputContract extends void ? any : TEnforceOutputContract>, dependencies: DependencyValuesType<TDependencies>, config: TConfig) => Promise<any>;
+    meta?: IMiddlewareMeta;
+    tags?: TagType[];
+    everywhere?: boolean | ((task: ITask<any, any, any, any>) => boolean);
+}
+export interface ITaskMiddleware<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> extends ITaskMiddlewareDefinition<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>, IContractable<TConfig, TEnforceInputContract, TEnforceOutputContract> {
+    [symbolTaskMiddleware]: true;
+    [symbolFilePath]: string;
+    id: string;
+    dependencies: TDependencies | ((config: TConfig) => TDependencies);
+    /** Current configuration object (empty by default). */
+    config: TConfig;
+    /** Configure the middleware and return a marked, configured instance. */
+    with: (config: TConfig) => ITaskMiddlewareConfigured<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies>;
+    tags: TagType[];
+}
+export interface ITaskMiddlewareConfigured<TConfig = any, TEnforceInputContract = void, TEnforceOutputContract = void, TDependencies extends DependencyMapType = any> extends ITaskMiddleware<TConfig, TEnforceInputContract, TEnforceOutputContract, TDependencies> {
+    [symbolMiddlewareConfigured]: true;
+    config: TConfig;
+}
+export interface ITaskMiddlewareExecutionInput<TTaskInput = any, TTaskOutput = any> {
+    /** Task hook */
+    task: {
+        definition: ITask<TTaskInput, any, any, any>;
+        input: TTaskInput;
+    };
+    next: (taskInput?: TTaskInput) => Promise<TTaskOutput>;
+    /** Per-execution registry for sharing state between middleware and task */
+    journal: ExecutionJournal;
+}
+export type TaskMiddlewareAttachmentType = ITaskMiddleware<void, any, any, any> | ITaskMiddleware<{
+    [K in any]?: any;
+}, any, any, any> | ITaskMiddlewareConfigured<any, any, any, any>;