@bluelibs/runner 5.1.0 → 5.2.1

package/dist/types/models/LogPrinter.d.ts

@@ -0,0 +1,56 @@
+export type PrintStrategy = "pretty" | "plain" | "json" | "json_pretty";
+export type LogLevels = "trace" | "debug" | "info" | "warn" | "error" | "critical";
+export interface PrintableLog {
+    level: LogLevels;
+    source?: string;
+    message: any;
+    timestamp: Date;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    data?: Record<string, any>;
+    context?: Record<string, any>;
+}
+export type ColorTheme = {
+    trace: string;
+    debug: string;
+    info: string;
+    warn: string;
+    error: string;
+    critical: string;
+    reset: string;
+    bold: string;
+    dim: string;
+    blue: string;
+    cyan: string;
+    gray: string;
+};
+export declare class LogPrinter {
+    private strategy;
+    private colors;
+    constructor(options: {
+        strategy: PrintStrategy;
+        useColors: boolean;
+        colorTheme?: Partial<ColorTheme>;
+    });
+    print(log: PrintableLog): void;
+    private pickWriter;
+    private formatTime;
+    private formatLevel;
+    private formatSource;
+    private formatMessage;
+    private formatError;
+    private formatData;
+    private formatContext;
+    private normalizeForJson;
+    private static NO_COLORS;
+    private static readonly DEFAULT_WRITERS;
+    private static writers;
+    static setWriters(writers: Partial<{
+        log: (msg: any) => void;
+        error?: (msg: any) => void;
+    }>): void;
+    static resetWriters(): void;
+}

package/dist/types/models/Logger.d.ts

@@ -0,0 +1,85 @@
+import { LogPrinter, PrintStrategy as PrinterStrategy } from "./LogPrinter";
+export type LogLevels = "trace" | "debug" | "info" | "warn" | "error" | "critical";
+export interface ILogInfo {
+    source?: string;
+    error?: unknown | Error;
+    data?: Record<string, any>;
+    context?: Record<string, any>;
+    [key: string]: any;
+}
+export interface ILog {
+    level: LogLevels;
+    source?: string;
+    message: any;
+    timestamp: Date;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    data?: Record<string, any>;
+    context?: Record<string, any>;
+}
+export type PrintStrategy = PrinterStrategy;
+export declare class Logger {
+    private printThreshold;
+    private printStrategy;
+    private bufferLogs;
+    private buffer;
+    private boundContext;
+    private isLocked;
+    private useColors;
+    private printer;
+    private source?;
+    private rootLogger?;
+    localListeners: Array<(log: ILog) => void | Promise<void>>;
+    static Severity: {
+        trace: number;
+        debug: number;
+        info: number;
+        warn: number;
+        error: number;
+        critical: number;
+    };
+    constructor(options: {
+        printThreshold: null | LogLevels;
+        printStrategy: PrintStrategy;
+        bufferLogs: boolean;
+        useColors?: boolean;
+    }, boundContext?: Record<string, any>, source?: string, printer?: LogPrinter);
+    private detectColorSupport;
+    /**
+     * Creates a new logger instance with additional bound context
+     */
+    with({ source, additionalContext: context, }: {
+        source?: string;
+        additionalContext?: Record<string, any>;
+    }): Logger;
+    /**
+     * Core logging method with structured LogInfo
+     */
+    log(level: LogLevels, message: any, logInfo?: ILogInfo): Promise<void>;
+    private extractErrorInfo;
+    info(message: any, logInfo?: ILogInfo): Promise<void>;
+    error(message: any, logInfo?: ILogInfo): Promise<void>;
+    warn(message: any, logInfo?: ILogInfo): Promise<void>;
+    debug(message: any, logInfo?: ILogInfo): Promise<void>;
+    trace(message: any, logInfo?: ILogInfo): Promise<void>;
+    critical(message: any, logInfo?: ILogInfo): Promise<void>;
+    /**
+     * Direct print for tests and advanced scenarios. Delegates to LogPrinter.
+     */
+    print(log: ILog): void;
+    /**
+     * @param listener - A listener that will be triggered for every log.
+     */
+    onLog(listener: (log: ILog) => any): void;
+    /**
+     * Marks the logger as ready.
+     * This is used to trigger the local listeners and print the buffered logs (if they exists)
+     * @returns A promise that resolves when the logger is ready.
+     */
+    lock(): Promise<void>;
+    private canPrint;
+    private triggerLogListeners;
+}

package/dist/types/models/MiddlewareManager.d.ts

@@ -0,0 +1,73 @@
+import { DependencyMapType, ITask, IResource } from "../defs";
+import { Store } from "./Store";
+import { ITaskMiddleware, IResourceMiddleware } from "../defs";
+import { TaskMiddlewareInterceptor, ResourceMiddlewareInterceptor } from "./middleware/types";
+export type { TaskMiddlewareInterceptor, ResourceMiddlewareInterceptor };
+/**
+ * Centralizes middleware composition and execution for both tasks and resources.
+ * Keeps observability emissions and unhandled error routing consistent.
+ *
+ * This is a facade that delegates to specialized composer classes for maintainability.
+ */
+export declare class MiddlewareManager {
+    protected readonly store: Store;
+    private readonly interceptorRegistry;
+    private readonly middlewareResolver;
+    private readonly taskComposer;
+    private readonly resourceComposer;
+    constructor(store: Store, _eventManager: unknown, _logger: unknown);
+    /**
+     * @internal
+     */
+    get taskMiddlewareInterceptors(): readonly TaskMiddlewareInterceptor[];
+    /**
+     * @internal
+     */
+    get resourceMiddlewareInterceptors(): readonly ResourceMiddlewareInterceptor[];
+    /**
+     * Gets the current lock status of the MiddlewareManager
+     */
+    get isLocked(): boolean;
+    /**
+     * Locks the MiddlewareManager, preventing any further modifications to interceptors
+     */
+    lock(): void;
+    /**
+     * Adds an interceptor for task or resource middleware execution
+     * Interceptors are executed in the order they are added, with the ability to
+     * modify, log, or prevent middleware execution
+     *
+     * @param kind - The type of middleware to intercept ("task" or "resource")
+     * @param interceptor - The interceptor function to add
+     */
+    intercept(kind: "task", interceptor: TaskMiddlewareInterceptor): void;
+    intercept(kind: "resource", interceptor: ResourceMiddlewareInterceptor): void;
+    /**
+     * Adds an interceptor for a specific middleware instance with better type safety
+     * This method automatically determines the type and provides type-safe access
+     *
+     * @param middleware - The middleware instance to intercept
+     * @param interceptor - The interceptor function with proper typing
+     */
+    interceptMiddleware(middleware: ITaskMiddleware<any, any, any, any>, interceptor: TaskMiddlewareInterceptor): void;
+    interceptMiddleware(middleware: IResourceMiddleware<any, any, any, any>, interceptor: ResourceMiddlewareInterceptor): void;
+    /**
+     * Compose a runner for a task with its local interceptors and applicable middlewares.
+     * Returns a function that accepts the task input and resolves to the task output.
+     */
+    composeTaskRunner<TInput, TOutput extends Promise<any>, TDeps extends DependencyMapType>(task: ITask<TInput, TOutput, TDeps>): (input: TInput, parentJournal?: import("..").ExecutionJournal) => Promise<Awaited<TOutput>>;
+    /**
+     * Run a resource init wrapped with its applicable middlewares.
+     */
+    runResourceInit<C, V extends Promise<any>, D extends DependencyMapType, TContext>(resource: IResource<C, V, D, TContext>, config: C, dependencies: any, context: TContext): Promise<V | undefined>;
+    /**
+     * Gets all "everywhere" middlewares that apply to the given task
+     * @deprecated Internal method exposed for testing - may be removed in future versions
+     */
+    getEverywhereMiddlewareForTasks(task: ITask<any, any, any>): ITaskMiddleware[];
+    /**
+     * Gets all "everywhere" middlewares that apply to the given resource
+     * @deprecated Internal method exposed for testing - may be removed in future versions
+     */
+    getEverywhereMiddlewareForResources(resource: IResource<any, any, any, any>): IResourceMiddleware[];
+}

package/dist/types/models/OverrideManager.d.ts

@@ -0,0 +1,13 @@
+import { IResource, ITaskMiddleware, IResourceMiddleware, ITask, IResourceWithConfig, RegisterableItems, IHook } from "../defs";
+import { StoreRegistry } from "./StoreRegistry";
+export declare class OverrideManager {
+    private readonly registry;
+    overrides: Map<string, IResource | ITaskMiddleware | IResourceMiddleware | ITask | IResourceWithConfig | IHook>;
+    overrideRequests: Set<{
+        source: string;
+        override: RegisterableItems;
+    }>;
+    constructor(registry: StoreRegistry);
+    storeOverridesDeeply<C>(element: IResource<C, any, any>): void;
+    processOverrides(): void;
+}

package/dist/types/models/Queue.d.ts

@@ -0,0 +1,40 @@
+export type QueueEventType = "enqueue" | "start" | "finish" | "error" | "cancel" | "disposed";
+export type QueueEvent = {
+    type: QueueEventType;
+    taskId: number;
+    disposed: boolean;
+    error?: Error;
+};
+/**
+ * Cooperative task queue.
+ *  • Tasks run one‑after‑another (FIFO ordering).
+ *  • Dead‑lock detection prevents nesting.
+ *  • dispose() drains or cancels outstanding tasks, then rejects new ones.
+ */
+export declare class Queue {
+    private tail;
+    private disposed;
+    private abortController;
+    private readonly eventManager;
+    private nextTaskId;
+    private listenerId;
+    private activeListeners;
+    private readonly executionContext;
+    private readonly hasAsyncLocalStorage;
+    /**
+     * Schedule an asynchronous task.
+     * @param task – receives an AbortSignal so it can cancel early if desired.
+     */
+    run<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /**
+     * Disposes the queue.
+     * @param options.cancel – if true, broadcasts AbortSignal to running task.
+     *                         default: false (waits for tasks to finish).
+     */
+    dispose(options?: {
+        cancel?: boolean;
+    }): Promise<void>;
+    on(type: QueueEventType, handler: (event: QueueEvent) => any): () => void;
+    once(type: QueueEventType, handler: (event: QueueEvent) => any): () => void;
+    private emit;
+}

package/dist/types/models/ResourceInitializer.d.ts

@@ -0,0 +1,20 @@
+import { DependencyMapType, IResource, ResourceDependencyValuesType } from "../defs";
+import { EventManager } from "./EventManager";
+import { Store } from "./Store";
+import { Logger } from "./Logger";
+export declare class ResourceInitializer {
+    protected readonly store: Store;
+    protected readonly eventManager: EventManager;
+    protected readonly logger: Logger;
+    constructor(store: Store, eventManager: EventManager, logger: Logger);
+    private readonly middlewareManager;
+    /**
+     * Begins the execution of a task. These are registered tasks and all sanity checks have been performed at this stage to ensure consistency of the object.
+     * This function can throw only if any of the event listeners or run function throws
+     */
+    initializeResource<TConfig = null, TValue extends Promise<any> = Promise<any>, TDeps extends DependencyMapType = {}, TContext = any>(resource: IResource<TConfig, TValue, TDeps>, config: TConfig, dependencies: ResourceDependencyValuesType<TDeps>): Promise<{
+        value: TValue | undefined;
+        context: TContext;
+    }>;
+    initWithMiddleware<C, V extends Promise<any>, D extends DependencyMapType, TContext>(resource: IResource<C, V, D, TContext>, config: C, dependencies: ResourceDependencyValuesType<D>, context: TContext): Promise<V | undefined>;
+}

package/dist/types/models/RunResult.d.ts

@@ -0,0 +1,41 @@
+import { DependencyMapType, IEvent, ITask } from "../defs";
+import { IResource } from "../defs";
+import { EventManager } from "./EventManager";
+import { Logger } from "./Logger";
+import { Store } from "./Store";
+import { TaskRunner } from "./TaskRunner";
+export declare class RunResult<V> {
+    readonly value: V;
+    readonly logger: Logger;
+    readonly store: Store;
+    private readonly eventManager;
+    private readonly taskRunner;
+    private readonly disposeFn;
+    constructor(value: V, logger: Logger, store: Store, eventManager: EventManager, taskRunner: TaskRunner, disposeFn: () => Promise<void>);
+    /**
+     * Run a task within the context of the run result.
+     * @param task - The task to run.
+     * @param args - The arguments to pass to the task.
+     * @returns The result of the task.
+     */
+    runTask: <I = undefined, O extends Promise<any> = any, D extends DependencyMapType = any>(task: ITask<I, O, D> | string, ...args: I extends undefined | void ? [] : [I]) => Promise<O | undefined>;
+    /**
+     * Emit an event within the context of the run result.
+     * @param event - The event to emit.
+     * @param payload - The payload to emit.
+     */
+    emitEvent: <P>(event: IEvent<P> | string, payload?: P extends undefined | void ? undefined : P) => Promise<void>;
+    /**
+     * Get the value of a resource from the run result.
+     * @param resource - The resource to get the value of.
+     * @returns The value of the resource.
+     */
+    getResourceValue: <Output extends Promise<any>>(resource: string | IResource<any, Output, any, any, any>) => Output extends Promise<infer U> ? U : Output;
+    /**
+     * Get the config of a resource from the run result.
+     * @param resource - The resource to get the config of.
+     * @returns The config passed for the resource.
+     */
+    getResourceConfig: <Config>(resource: string | IResource<Config, any, any, any, any>) => Config;
+    dispose: () => Promise<void>;
+}

package/dist/types/models/Semaphore.d.ts

@@ -0,0 +1,80 @@
+export type SemaphoreEventType = "queued" | "acquired" | "released" | "timeout" | "aborted" | "disposed";
+export type SemaphoreEvent = {
+    type: SemaphoreEventType;
+    permits: number;
+    waiting: number;
+    maxPermits: number;
+    disposed: boolean;
+};
+/**
+ * A semaphore that limits the number of concurrent operations.
+ * Used to prevent connection pool exhaustion by limiting concurrent
+ * database operations to the pool size.
+ */
+export declare class Semaphore {
+    private permits;
+    private waitingHead;
+    private waitingTail;
+    private waitingCount;
+    private disposed;
+    private readonly maxPermits;
+    private readonly eventManager;
+    private listenerId;
+    private activeListeners;
+    constructor(maxPermits: number);
+    /**
+     * Acquire a permit. If no permits are available, waits until one becomes available.
+     */
+    acquire(options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Release a permit, allowing waiting operations to proceed.
+     */
+    release(): void;
+    private removeFromQueue;
+    /**
+     * Execute a function with a permit, automatically releasing it afterwards.
+     */
+    withPermit<T>(fn: () => Promise<T>, options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    /**
+     * Dispose the semaphore, rejecting all waiting operations and preventing new ones.
+     */
+    dispose(): void;
+    /**
+     * Get current number of available permits (for debugging)
+     */
+    getAvailablePermits(): number;
+    /**
+     * Get current number of waiting operations (for debugging)
+     */
+    getWaitingCount(): number;
+    /**
+     * Get maximum number of permits
+     */
+    getMaxPermits(): number;
+    /**
+     * Check if the semaphore has been disposed
+     */
+    isDisposed(): boolean;
+    /**
+     * Get metrics about the current state of the semaphore
+     */
+    getMetrics(): {
+        availablePermits: number;
+        waitingCount: number;
+        maxPermits: number;
+        utilization: number;
+        disposed: boolean;
+    };
+    on(type: SemaphoreEventType, handler: (event: SemaphoreEvent) => any): () => void;
+    once(type: SemaphoreEventType, handler: (event: SemaphoreEvent) => any): () => void;
+    private enqueue;
+    private dequeue;
+    private emit;
+    private buildEvent;
+}

package/dist/types/models/Store.d.ts

@@ -0,0 +1,76 @@
+import { IResource, RegisterableItems, ITag, ITaskMiddleware, IResourceMiddleware } from "../defs";
+import { EventManager } from "./EventManager";
+import { Logger } from "./Logger";
+import { ResourceStoreElementType, TaskStoreElementType, EventStoreElementType } from "../types/storeTypes";
+import { TaskRunner } from "./TaskRunner";
+import { OnUnhandledError } from "./UnhandledError";
+import { MiddlewareManager } from "./MiddlewareManager";
+import { RunnerMode } from "../types/runner";
+export type { ResourceStoreElementType, TaskStoreElementType, EventStoreElementType, };
+/**
+ * Store class which is used to store all the resources, tasks, middleware and events.
+ */
+export declare class Store {
+    #private;
+    protected readonly eventManager: EventManager;
+    protected readonly logger: Logger;
+    readonly onUnhandledError: OnUnhandledError;
+    root: ResourceStoreElementType;
+    private registry;
+    private overrideManager;
+    private validator;
+    private taskRunner?;
+    private middlewareManager;
+    private readonly initializedResourceIds;
+    mode: RunnerMode;
+    constructor(eventManager: EventManager, logger: Logger, onUnhandledError: OnUnhandledError, mode?: RunnerMode);
+    get tasks(): Map<string, TaskStoreElementType>;
+    get hooks(): Map<string, import("..").HookStoreElementType>;
+    get resources(): Map<string, ResourceStoreElementType>;
+    get events(): Map<string, EventStoreElementType>;
+    get errors(): Map<string, import("..").IErrorHelper<any>>;
+    get asyncContexts(): Map<string, import("..").IAsyncContext<any>>;
+    get taskMiddlewares(): Map<string, import("..").TaskMiddlewareStoreElementType>;
+    get resourceMiddlewares(): Map<string, import("..").ResourceMiddlewareStoreElementType>;
+    get tags(): Map<string, ITag<void, void, void>>;
+    get overrides(): Map<string, IResourceMiddleware<any, void, void, any> | import("..").ITask<any, any, {}, any, import("..").TagType[], import("..").TaskMiddlewareAttachmentType[]> | import("..").IHook<{}, any, any> | IResource<void, Promise<any>, any, any, any, import("..").TagType[], import("..").ResourceMiddlewareAttachmentType[]> | ITaskMiddleware<any, void, void, any> | import("..").IResourceWithConfig<any, Promise<any>, any, any, any, import("..").TagType[], IResourceMiddleware<any, void, void, any>[]>>;
+    get overrideRequests(): Set<{
+        source: string;
+        override: RegisterableItems;
+    }>;
+    getMiddlewareManager(): MiddlewareManager;
+    get isLocked(): boolean;
+    lock(): void;
+    checkLock(): void;
+    private registerGlobalComponents;
+    setTaskRunner(taskRunner: TaskRunner): void;
+    private setupRootResource;
+    validateDependencyGraph(): void;
+    validateEventEmissionGraph(): void;
+    initializeStore(root: IResource<any, any, any, any, any>, config: any): void;
+    dispose(): Promise<void>;
+    recordResourceInitialized(resourceId: string): void;
+    private getResourcesInDisposeOrder;
+    /**
+     * Internal, avoid using this method directly.
+     */
+    processOverrides(): void;
+    /**
+     * Internal, avoid using this method directly.
+     * @param item
+     * @returns
+     */
+    storeGenericItem<C>(item: RegisterableItems): void;
+    /**
+     * Returns all tasks with the given tag.
+     * @param tag - The tag to filter by.
+     * @returns The tasks with the given tag.
+     */
+    getTasksWithTag(tag: string | ITag<any, any, any>): import("..").ITask<any, any, any, any, import("..").TagType[], import("..").TaskMiddlewareAttachmentType[]>[];
+    /**
+     * Returns all resources with the given tag.
+     * @param tag - The tag to filter by.
+     * @returns The resources with the given tag.
+     */
+    getResourcesWithTag(tag: string | ITag<any, any, any>): IResource<any, any, {}, any, any, import("..").TagType[], import("..").ResourceMiddlewareAttachmentType[]>[];
+}

package/dist/types/models/StoreRegistry.d.ts

@@ -0,0 +1,49 @@
+import { IResource, ITask, IResourceWithConfig, RegisterableItems, ITaskMiddleware, IResourceMiddleware, IEvent, ITag, IHook } from "../defs";
+import { TaskStoreElementType, TaskMiddlewareStoreElementType, ResourceMiddlewareStoreElementType, ResourceStoreElementType, EventStoreElementType, HookStoreElementType } from "../defs";
+import { StoreValidator } from "./StoreValidator";
+import { Store } from "./Store";
+import { IDependentNode } from "./utils/findCircularDependencies";
+import { IErrorHelper } from "../types/error";
+import type { IAsyncContext } from "../types/asyncContext";
+type StoringMode = "normal" | "override";
+export declare class StoreRegistry {
+    protected readonly store: Store;
+    tasks: Map<string, TaskStoreElementType>;
+    resources: Map<string, ResourceStoreElementType>;
+    events: Map<string, EventStoreElementType>;
+    taskMiddlewares: Map<string, TaskMiddlewareStoreElementType>;
+    resourceMiddlewares: Map<string, ResourceMiddlewareStoreElementType>;
+    hooks: Map<string, HookStoreElementType>;
+    tags: Map<string, ITag>;
+    asyncContexts: Map<string, IAsyncContext<any>>;
+    errors: Map<string, IErrorHelper<any>>;
+    private validator;
+    constructor(store: Store);
+    getValidator(): StoreValidator;
+    storeGenericItem<_C>(item: RegisterableItems): void;
+    storeError<_C>(item: IErrorHelper<any>): void;
+    storeAsyncContext<_C>(item: IAsyncContext<any>): void;
+    storeTag(item: ITag<any, any, any>): void;
+    storeHook<_C>(item: IHook<any, any>, overrideMode?: StoringMode): void;
+    storeTaskMiddleware<_C>(item: ITaskMiddleware<any>, storingMode?: StoringMode): void;
+    storeResourceMiddleware<_C>(item: IResourceMiddleware<any>, overrideMode?: StoringMode): void;
+    storeEvent<_C>(item: IEvent<void>): void;
+    storeResourceWithConfig<_C>(item: IResourceWithConfig<any, any, any>, storingMode?: StoringMode): IResource<any, any, any, any, any, import("..").TagType[], IResourceMiddleware<any, void, void, any>[]>;
+    computeRegistrationDeeply<_C>(element: IResource<_C>, config?: _C): void;
+    storeResource<_C>(item: IResource<any, any, any>, overrideMode?: StoringMode): IResource<any, any, any, any, any, import("..").TagType[], import("..").ResourceMiddlewareAttachmentType[]>;
+    storeTask<_C>(item: ITask<any, any, {}>, storingMode?: StoringMode): void;
+    getDependentNodes(): IDependentNode[];
+    /**
+     * Builds a directed graph of event emissions based on hooks listening to events
+     * and their dependencies on events (emission capability). Ignores wildcard hooks by default.
+     */
+    buildEventEmissionGraph(): IDependentNode[];
+    private setupBlankNodes;
+    getTasksWithTag(tag: string | ITag): ITask<any, any, any, any, import("..").TagType[], import("..").TaskMiddlewareAttachmentType[]>[];
+    getResourcesWithTag(tag: string | ITag): IResource<any, any, {}, any, any, import("..").TagType[], import("..").ResourceMiddlewareAttachmentType[]>[];
+    /**
+     * Used to fetch the value cloned, and if we're dealing with an override, we need to extend the previous value.
+     */
+    private getFreshValue;
+}
+export {};

package/dist/types/models/StoreValidator.d.ts

@@ -0,0 +1,8 @@
+import { StoreRegistry } from "./StoreRegistry";
+export declare class StoreValidator {
+    private registry;
+    constructor(registry: StoreRegistry);
+    checkIfIDExists(id: string): void | never;
+    runSanityChecks(): void;
+    ensureAllTagsUsedAreRegistered(): void;
+}

package/dist/types/models/TaskRunner.d.ts

@@ -0,0 +1,28 @@
+import { DependencyMapType, ITask } from "../defs";
+import { EventManager } from "./EventManager";
+import { Store } from "./Store";
+import { Logger } from "./Logger";
+import type { ExecutionJournal } from "../types/executionJournal";
+import type { TaskCallOptions } from "../types/utilities";
+export declare class TaskRunner {
+    protected readonly store: Store;
+    protected readonly eventManager: EventManager;
+    protected readonly logger: Logger;
+    protected readonly runnerStore: Map<string | symbol, (input: any, journal?: ExecutionJournal) => Promise<any>>;
+    constructor(store: Store, eventManager: EventManager, logger: Logger);
+    private readonly middlewareManager;
+    /**
+     * Begins the execution of a task. These are registered tasks and all sanity checks have been performed at this stage to ensure consistency of the object.
+     * 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 options optional call options including journal for forwarding
+     */
+    run<TInput, TOutput extends Promise<any>, TDeps extends DependencyMapType>(task: ITask<TInput, TOutput, TDeps>, input?: TInput, options?: TaskCallOptions): Promise<TOutput | undefined>;
+    /**
+     * Creates the function with the chain of middleware.
+     * @param task
+     * @returns
+     */
+    protected createRunnerWithMiddleware<TInput, TOutput extends Promise<any>, TDeps extends DependencyMapType>(task: ITask<TInput, TOutput, TDeps>): (input: TInput, parentJournal?: ExecutionJournal) => Promise<Awaited<TOutput>>;
+}

package/dist/types/models/UnhandledError.d.ts

@@ -0,0 +1,11 @@
+import { Logger } from "./Logger";
+export type UnhandledErrorKind = "process" | "task" | "middleware" | "resourceInit" | "hook" | "run";
+export interface OnUnhandledErrorInfo {
+    error: unknown;
+    kind?: UnhandledErrorKind;
+    source?: string;
+}
+export type OnUnhandledError = (info: OnUnhandledErrorInfo) => void | Promise<void>;
+export declare function createDefaultUnhandledError(logger: Logger): OnUnhandledError;
+export declare function bindProcessErrorHandler(handler: OnUnhandledError): (error: unknown, source: "uncaughtException" | "unhandledRejection") => void | Promise<void>;
+export declare function safeReportUnhandledError(handler: OnUnhandledError, info: OnUnhandledErrorInfo): Promise<void>;

package/dist/types/models/event/CycleContext.d.ts

@@ -0,0 +1,9 @@
+import { IEmissionFrame } from "./types";
+export declare class CycleContext {
+    private readonly emissionStack;
+    private readonly currentHookIdContext;
+    readonly isEnabled: boolean;
+    constructor(runtimeEventCycleDetection: boolean);
+    runEmission<TResult>(frame: IEmissionFrame, source: string, processEmission: () => Promise<TResult>): Promise<TResult>;
+    runHook<T>(hookId: string, execute: () => Promise<T>): Promise<T>;
+}

package/dist/types/models/event/EmissionExecutor.d.ts

@@ -0,0 +1,11 @@
+import { IEventEmission } from "../../defs";
+import { IListenerStorage } from "./types";
+interface ExecuteOptions {
+    listeners: IListenerStorage[];
+    event: IEventEmission<any>;
+    isPropagationStopped: () => boolean;
+}
+export declare function executeSequentially({ listeners, event, isPropagationStopped, }: ExecuteOptions): Promise<void>;
+export declare function executeInParallel({ listeners, event, }: Omit<ExecuteOptions, "isPropagationStopped">): Promise<void>;
+export declare function shouldExecuteListener(listener: IListenerStorage, event: IEventEmission<any>): boolean;
+export {};

package/dist/types/models/event/InterceptorPipeline.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Utility to compose an array of interceptors into a single function.
+ * Last-added interceptor executes first (LIFO).
+ */
+export declare function composeInterceptors<TArgs extends any[], TResult>(interceptors: Array<(next: (...args: TArgs) => Promise<TResult>, ...args: TArgs) => Promise<TResult>>, base: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;

package/dist/types/models/event/ListenerRegistry.d.ts

@@ -0,0 +1,31 @@
+import { IEvent } from "../../defs";
+import { IListenerStorage } from "./types";
+type IsExcludedFromGlobal = (event: IEvent<any>) => boolean;
+/**
+ * Manages event-specific and global listener collections plus caching.
+ * Keeps ordering invariant using binary insertion.
+ */
+export declare class ListenerRegistry {
+    readonly listeners: Map<string, IListenerStorage[]>;
+    readonly globalListeners: IListenerStorage[];
+    readonly cachedMergedListeners: Map<string, IListenerStorage[]>;
+    private _globalListenersCacheValid;
+    private readonly isExcludedFromGlobal;
+    constructor(isExcludedFromGlobal?: IsExcludedFromGlobal);
+    get globalListenersCacheValid(): boolean;
+    addListener(eventId: string, newListener: IListenerStorage): void;
+    addGlobalListener(newListener: IListenerStorage): void;
+    getListenersForEmit(eventDefinition: IEvent<any>): IListenerStorage[];
+    hasListeners(eventDefinition: IEvent<any>): boolean;
+    /**
+     * Cached merge between event-specific and global listeners.
+     * Exposed for backward compatibility with existing tests.
+     */
+    clear(): void;
+    getCachedMergedListeners(eventId: string): IListenerStorage[];
+    private invalidateCache;
+    private mergeSortedListeners;
+    private insertListener;
+}
+export declare function createListener(newListener: Partial<IListenerStorage>): IListenerStorage;
+export {};