@bluelibs/runner 4.6.0 → 4.7.0-alpha

package/dist/node/platform/createFile.d.ts

@@ -0,0 +1,9 @@
+import type { Readable } from "stream";
+import type { InputFileMeta, EjsonFileSentinel } from "../../types/inputFile";
+export interface NodeFileSource {
+    stream?: Readable;
+    buffer?: Buffer;
+}
+export declare function createFile(meta: InputFileMeta, source: NodeFileSource, id?: string): EjsonFileSentinel & {
+    _node: NodeFileSource;
+};

package/dist/node/tunnel.allowlist.d.ts

@@ -0,0 +1,7 @@
+import type { Store } from "../models/Store";
+export interface TunnelAllowList {
+    enabled: boolean;
+    taskIds: Set<string>;
+    eventIds: Set<string>;
+}
+export declare function computeAllowList(store: Store): TunnelAllowList;

package/dist/node/upload/manifest.d.ts

@@ -0,0 +1,22 @@
+import type { Readable } from "stream";
+import type { InputFileMeta } from "../../types/inputFile";
+export interface NodeFileSource {
+    id: string;
+    meta: InputFileMeta;
+    source: {
+        type: "buffer";
+        buffer: Buffer;
+    } | {
+        type: "stream";
+        stream: Readable;
+    };
+}
+export interface BuiltManifest<T = any> {
+    input: T;
+    files: NodeFileSource[];
+}
+/**
+ * Walk an input object and collect File sentinels having local Node sources.
+ * It returns a shallow-cloned structure where any internal _node fields are removed.
+ */
+export declare function buildNodeManifest<T = any>(input: T): BuiltManifest<T>;

package/dist/platform/adapters/browser.d.ts

@@ -0,0 +1,14 @@
+import type { IAsyncLocalStorage, IPlatformAdapter, PlatformId } from "../types";
+export declare class BrowserPlatformAdapter implements IPlatformAdapter {
+    readonly id: PlatformId;
+    init(): Promise<void>;
+    onUncaughtException(handler: (error: any) => void): () => any;
+    onUnhandledRejection(handler: (reason: any) => void): () => any;
+    onShutdownSignal(handler: () => void): () => void;
+    exit(): void;
+    getEnv(key: string): any;
+    hasAsyncLocalStorage(): boolean;
+    createAsyncLocalStorage<T>(): IAsyncLocalStorage<T>;
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+}

package/dist/platform/adapters/edge.d.ts

@@ -0,0 +1,5 @@
+import { BrowserPlatformAdapter } from "./browser";
+export declare class EdgePlatformAdapter extends BrowserPlatformAdapter {
+    readonly id: "edge";
+    onShutdownSignal(handler: () => void): () => void;
+}

package/dist/platform/adapters/node-als.d.ts

@@ -0,0 +1 @@
+export declare function loadAsyncLocalStorageClass(): Promise<any>;

package/dist/platform/adapters/node.d.ts

@@ -0,0 +1,15 @@
+import type { IAsyncLocalStorage, IPlatformAdapter } from "../types";
+export declare class NodePlatformAdapter implements IPlatformAdapter {
+    readonly id: "node";
+    private alsClass;
+    init(): Promise<void>;
+    onUncaughtException(handler: (error: any) => void): () => NodeJS.Process;
+    onUnhandledRejection(handler: (reason: any) => void): () => NodeJS.Process;
+    onShutdownSignal(handler: () => void): () => void;
+    exit(code: number): void;
+    getEnv(key: string): string | undefined;
+    hasAsyncLocalStorage(): boolean;
+    createAsyncLocalStorage<T>(): IAsyncLocalStorage<T>;
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+}

package/dist/platform/adapters/universal-generic.d.ts

@@ -0,0 +1,14 @@
+import type { IAsyncLocalStorage, IPlatformAdapter } from "../types";
+export declare class GenericUniversalPlatformAdapter implements IPlatformAdapter {
+    readonly id: "universal";
+    init(): Promise<void>;
+    onUncaughtException(handler: (error: any) => void): () => any;
+    onUnhandledRejection(handler: (reason: any) => void): () => any;
+    onShutdownSignal(handler: () => void): () => void;
+    exit(): void;
+    getEnv(key: string): string | undefined;
+    hasAsyncLocalStorage(): boolean;
+    createAsyncLocalStorage<T>(): IAsyncLocalStorage<T>;
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+}

package/dist/platform/adapters/universal.d.ts

@@ -0,0 +1,17 @@
+import type { IPlatformAdapter, PlatformId } from "../types";
+export declare function detectEnvironment(): PlatformId;
+export declare class UniversalPlatformAdapter implements IPlatformAdapter {
+    readonly id: PlatformId;
+    private inner;
+    init(): Promise<void>;
+    private get;
+    onUncaughtException(handler: (error: Error) => void): () => void;
+    onUnhandledRejection(handler: (reason: unknown) => void): () => void;
+    onShutdownSignal(handler: () => void): () => void;
+    exit(code: number): void;
+    getEnv(key: string): string | undefined;
+    hasAsyncLocalStorage(): boolean;
+    createAsyncLocalStorage<T>(): import("..").IAsyncLocalStorage<T>;
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+}

package/dist/platform/createFile.d.ts

@@ -0,0 +1,10 @@
+import type { InputFileMeta, EjsonFileSentinel } from "../types/inputFile";
+/**
+ * Universal/browser `createFile` helper. For Node, import from `@bluelibs/runner/node`.
+ */
+export declare function createFile(meta: InputFileMeta, blob: Blob, id?: string): EjsonFileSentinel & {
+    _web: {
+        blob: Blob;
+    };
+};
+export type { EjsonFileSentinel };

package/dist/platform/createWebFile.d.ts

@@ -0,0 +1,11 @@
+import type { InputFileMeta, EjsonFileSentinel } from "../types/inputFile";
+/**
+ * Browser/edge-friendly File sentinel creator.
+ * Produces the same public EJSON File shape with a browser sidecar `_web`.
+ * The sidecar will be stripped out by the universal manifest walker before upload.
+ */
+export declare function createWebFile(meta: InputFileMeta, blob: Blob, id?: string): EjsonFileSentinel & {
+    _web: {
+        blob: Blob;
+    };
+};

package/dist/platform/factory.d.ts

@@ -0,0 +1,2 @@
+import type { IPlatformAdapter } from "./types";
+export declare function createPlatformAdapter(): IPlatformAdapter;

package/dist/platform/index.d.ts

@@ -0,0 +1,27 @@
+import type { IPlatformAdapter, IAsyncLocalStorage, PlatformId } from "./types";
+import { detectEnvironment } from "./adapters/universal";
+export { detectEnvironment };
+export declare function getPlatform(): IPlatformAdapter;
+export declare function setPlatform(adapter: IPlatformAdapter): void;
+export declare function resetPlatform(): void;
+export declare function getDetectedEnvironment(): PlatformId;
+export declare function isNode(): boolean;
+export declare function isBrowser(): boolean;
+export declare function isUniversal(): boolean;
+export type { IPlatformAdapter, IAsyncLocalStorage } from "./types";
+export declare class PlatformAdapter implements IPlatformAdapter {
+    private inner;
+    readonly env: PlatformId;
+    readonly id: PlatformId;
+    constructor(env?: PlatformId);
+    init(): Promise<void>;
+    onUncaughtException(handler: (error: any) => void): () => void;
+    onUnhandledRejection(handler: (reason: any) => void): () => void;
+    onShutdownSignal(handler: () => void): () => void;
+    exit(code: number): void;
+    getEnv(key: string): string | undefined;
+    hasAsyncLocalStorage(): boolean;
+    createAsyncLocalStorage<T>(): IAsyncLocalStorage<T>;
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+}

package/dist/platform/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Platform abstraction interface for universal compatibility
+ * Inspired by Remix's approach to Web APIs and runtime-agnostic design
+ */
+export type PlatformId = "node" | "browser" | "edge" | "universal";
+export interface IPlatformAdapter {
+    readonly id: PlatformId;
+    onUncaughtException(handler: (error: Error) => void): () => void;
+    onUnhandledRejection(handler: (reason: unknown) => void): () => void;
+    onShutdownSignal(handler: () => void): () => void;
+    exit(code: number): void;
+    getEnv(key: string): string | undefined;
+    hasAsyncLocalStorage(): boolean;
+    createAsyncLocalStorage<T>(): IAsyncLocalStorage<T>;
+    setTimeout: typeof globalThis.setTimeout;
+    clearTimeout: typeof globalThis.clearTimeout;
+    init: () => Promise<void>;
+}
+export interface IAsyncLocalStorage<T> {
+    getStore(): T | undefined;
+    run<R>(store: T, callback: () => R): R;
+}
+/**
+ * Utility functions for environment detection
+ */
+export declare function isNode(): boolean;
+export declare function isBrowser(): boolean;
+export declare function isWebWorker(): boolean;
+export declare function isUniversal(): boolean;

package/dist/processHooks.d.ts

@@ -0,0 +1,2 @@
+export declare function registerProcessLevelSafetyNets(handler: (error: unknown, source: "uncaughtException" | "unhandledRejection") => void | Promise<void>): () => void;
+export declare function registerShutdownHook(disposeOnce: () => Promise<void>): () => void;

package/dist/run.d.ts

@@ -0,0 +1,14 @@
+import { IResource, IResourceWithConfig } from "./defs";
+import { RunResult } from "./models/RunResult";
+import { RunOptions } from "./types/runner";
+/**
+ * This is the central function that kicks off you runner. You can run as many resources as you want in a single process, they will run in complete isolation.
+ *
+ * @param resourceOrResourceWithConfig - The resource or resource with config to run.
+ * @param options - The options for the run.
+ * @returns A promise that resolves to the result of the run.
+ */
+export declare function run<C, V extends Promise<any>>(resourceOrResourceWithConfig: IResourceWithConfig<C, V> | IResource<void, V, any, any> | IResource<{
+    [K in any]?: any;
+}, V, any, any>, // For optional config
+options?: RunOptions): Promise<RunResult<V extends Promise<infer U> ? U : V>>;

package/dist/testing.d.ts

@@ -0,0 +1,25 @@
+import { IResource, IResourceWithConfig, ITaskMiddleware, IResourceMiddleware, ITask, RegisterableItems, DependencyMapType } from "./defs";
+import { EventManager, Logger, Store, TaskRunner } from "./models";
+/**
+ * Helper to create a minimal test harness resource that wraps a root app (or any registerable)
+ * and exposes convenient testing utilities while running the full ecosystem
+ * (registration, overrides, middleware, events) without modifying the core API.
+ * @deprecated Use `run` instead with your testResource, as it provides the necessary toolkit.
+ */
+export declare function createTestResource(root: RegisterableItems, options?: {
+    overrides?: Array<IResource | ITask | ITaskMiddleware | IResourceMiddleware | IResourceWithConfig>;
+}): IResource<void, Promise<ReturnType<typeof buildTestFacade>>>;
+declare function buildTestFacade(deps: {
+    taskRunner: TaskRunner;
+    store: Store;
+    logger: Logger;
+    eventManager: EventManager;
+}): {
+    runTask: <I, O extends Promise<any>, D extends DependencyMapType>(task: ITask<I, O, D>, ...args: I extends undefined ? [] : [I]) => Promise<Awaited<O> | undefined>;
+    getResource: (id: string) => any;
+    taskRunner: TaskRunner;
+    store: Store;
+    logger: Logger;
+    eventManager: EventManager;
+};
+export {};

package/dist/tools/getCallerFile.d.ts

@@ -0,0 +1 @@
+export declare function getCallerFile(): string;

package/dist/tunnels/buildUniversalManifest.d.ts

@@ -0,0 +1,24 @@
+import type { Readable } from "stream";
+import type { InputFileMeta } from "../types/inputFile";
+export interface NodeCollectedFile {
+    id: string;
+    meta: InputFileMeta;
+    source: {
+        type: "buffer";
+        buffer: Buffer;
+    } | {
+        type: "stream";
+        stream: Readable;
+    };
+}
+export interface WebCollectedFile {
+    id: string;
+    meta: InputFileMeta;
+    blob: Blob;
+}
+export interface BuiltUniversalManifest<T = any> {
+    input: T;
+    nodeFiles: NodeCollectedFile[];
+    webFiles: WebCollectedFile[];
+}
+export declare function buildUniversalManifest<T = any>(input: T): BuiltUniversalManifest<T>;

package/dist/types/contracts.d.ts

@@ -0,0 +1,63 @@
+import { TagType } from "./tag";
+export declare const CONTRACT: unique symbol;
+export type CONTRACT = typeof CONTRACT;
+export interface IContractable<TConfig = any, TInput = void, TOutput = void> {
+    readonly __containsContract: true;
+    readonly [CONTRACT]: {
+        config: TConfig;
+        input: TInput;
+        output: TOutput;
+    };
+}
+type NonVoid<T> = [T] extends [void] ? never : T;
+type IsTuple<T extends readonly unknown[]> = number extends T["length"] ? false : true;
+type UnionToIntersection<U> = (U extends any ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type IsUnknown<T> = unknown extends T ? [T] extends [unknown] ? true : false : false;
+type UnknownToNever<T> = IsUnknown<T> extends true ? never : T;
+type ExtractContractOf<T, Kind extends "input" | "output"> = T extends IContractable<any, infer I, infer O> ? UnknownToNever<Kind extends "input" ? NonVoid<I> : NonVoid<O>> : never;
+type FilterContractsKind<TItems extends readonly unknown[], Kind extends "input" | "output", Acc extends readonly unknown[] = []> = TItems extends readonly [infer H, ...infer R] ? ExtractContractOf<H, Kind> extends never ? FilterContractsKind<R, Kind, Acc> : FilterContractsKind<R, Kind, [...Acc, ExtractContractOf<H, Kind>]> : Acc;
+type ExtractContractsFromCollection<TItems extends readonly unknown[], Kind extends "input" | "output"> = IsTuple<TItems> extends true ? FilterContractsKind<TItems, Kind> : Array<ExtractContractOf<TItems[number], Kind>>;
+export type ExtractInputTypeFromContracts<TItems extends readonly unknown[]> = ExtractContractsFromCollection<TItems, "input">;
+export type ExtractOutputTypeFromContracts<TItems extends readonly unknown[]> = ExtractContractsFromCollection<TItems, "output">;
+type ContractsUnionInputs<TItems extends readonly unknown[]> = ExtractInputTypeFromContracts<TItems> extends readonly (infer U)[] ? U : never;
+type ContractsUnionOutputs<TItems extends readonly unknown[]> = ExtractOutputTypeFromContracts<TItems> extends readonly (infer U)[] ? U : never;
+type ContractsIntersectionInputs<TItems extends readonly unknown[]> = UnionToIntersection<ContractsUnionInputs<TItems>>;
+type ContractsIntersectionOutputs<TItems extends readonly unknown[]> = UnionToIntersection<ContractsUnionOutputs<TItems>>;
+export type HasInputContracts<TItems extends readonly unknown[]> = [
+    ContractsUnionInputs<TItems>
+] extends [never] ? false : true;
+export type HasOutputContracts<TItems extends readonly unknown[]> = [
+    ContractsUnionOutputs<TItems>
+] extends [never] ? false : true;
+type IsNever<T> = [T] extends [never] ? true : false;
+type KeysWithNever<T> = T extends object ? {
+    [K in keyof T]-?: [T[K]] extends [never] ? K : never;
+}[keyof T] : never;
+type HasNeverProperty<T> = KeysWithNever<T> extends never ? false : true;
+type IsImpossibleIntersection<T> = IsNever<T> extends true ? true : HasNeverProperty<T> extends true ? true : false;
+export type InputContractViolationError<TItems extends readonly unknown[], TActual> = {
+    message: "Value does not satisfy all input contracts";
+    expected: Simplify<ContractsIntersectionInputs<TItems>>;
+    received: TActual;
+};
+export type OutputContractViolationError<TItems extends readonly unknown[], TActual> = {
+    message: "Value does not satisfy all output contracts";
+    expected: Simplify<ContractsIntersectionOutputs<TItems>>;
+    received: TActual;
+};
+export type EnsureInputSatisfiesContracts<TItems extends readonly unknown[], TValue> = [ContractsUnionInputs<TItems>] extends [never] ? TValue : TValue extends Promise<infer U> ? Promise<U extends ContractsIntersectionInputs<TItems> ? U : InputContractViolationError<TItems, U>> : TValue extends ContractsIntersectionInputs<TItems> ? TValue : InputContractViolationError<TItems, TValue>;
+export type EnsureOutputSatisfiesContracts<TItems extends readonly unknown[], TResponse> = [ContractsUnionOutputs<TItems>] extends [never] ? TResponse : TResponse extends Promise<infer U> ? Promise<U extends ContractsIntersectionOutputs<TItems> ? U : OutputContractViolationError<TItems, U>> : TResponse extends ContractsIntersectionOutputs<TItems> ? TResponse : OutputContractViolationError<TItems, TResponse>;
+export type InferInputOrViolationFromContracts<TItems extends readonly unknown[]> = HasInputContracts<TItems> extends false ? void : ContractsIntersectionInputs<TItems> extends infer I ? IsImpossibleIntersection<I> extends true ? InputContractViolationError<TItems, Simplify<I extends never ? never : I>> : Simplify<I> : never;
+export type InputArg<TItems extends readonly unknown[]> = [
+    InferInputOrViolationFromContracts<TItems>
+] extends [void] ? [] : [InferInputOrViolationFromContracts<TItems>];
+export type InputCollisionGuard<TItems extends readonly unknown[]> = IsImpossibleIntersection<ContractsIntersectionInputs<TItems>> extends true ? InputContractViolationError<TItems, Simplify<ContractsIntersectionInputs<TItems>>> : unknown;
+export type InferOutputOrViolationFromContracts<TItems extends readonly unknown[]> = HasOutputContracts<TItems> extends false ? unknown : ContractsIntersectionOutputs<TItems> extends infer O ? IsImpossibleIntersection<O> extends true ? OutputContractViolationError<TItems, Simplify<O extends never ? never : O>> : Simplify<O> : never;
+/** @deprecated Use ExtractOutputTypeFromContracts instead */
+export type ExtractTagsWithNonVoidReturnTypeFromTags<TTags extends TagType[]> = ExtractOutputTypeFromContracts<TTags>;
+/** @deprecated Use EnsureOutputSatisfiesContracts instead */
+export type EnsureResponseSatisfiesContracts<TTags extends TagType[], TResponse> = EnsureOutputSatisfiesContracts<TTags, TResponse>;
+export {};

package/dist/types/event.d.ts

@@ -0,0 +1,74 @@
+import { IOptionalDependency, IValidationSchema } from "../defs";
+import { TagType } from "./tag";
+import { IEventMeta } from "./meta";
+import { CommonPayload, symbolEvent, symbolFilePath } from "./utilities";
+export type EventHandlerType<T = any> = (event: IEventEmission<T>) => any | Promise<any>;
+export declare function onAnyOf<T extends readonly IEventDefinition<any>[]>(...defs: T): T;
+/**
+ * Runtime guard that checks if an emission belongs to one of the given event defs.
+ * Narrows payload type to the intersection of the provided events' payloads.
+ */
+export declare function isOneOf<TDefs extends readonly IEventDefinition<any>[]>(emission: IEventEmission<any>, defs: TDefs): emission is IEventEmission<CommonPayload<TDefs>>;
+export interface IEventDefinition<TPayload = void> {
+    id: string;
+    meta?: IEventMeta;
+    /**
+     * Optional validation schema for runtime payload validation.
+     * When provided, event payload will be validated when emitted.
+     */
+    payloadSchema?: IValidationSchema<TPayload>;
+    tags?: TagType[];
+}
+/**
+ * The definioten of the event.
+ * This is different from the event emission.
+ */
+export interface IEvent<TPayload = any> extends IEventDefinition<TPayload> {
+    id: string;
+    /**
+     * We use this event to discriminate between resources with just 'id' and 'events' as they collide. This is a workaround, should be redone using classes and instanceof.
+     */
+    [symbolEvent]: true;
+    [symbolFilePath]: string;
+    /** Return an optional dependency wrapper for this event. */
+    optional: () => IOptionalDependency<IEvent<TPayload>>;
+    tags: TagType[];
+}
+/**
+ * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * The tags that the event carries.
+     */
+    tags: TagType[];
+}

package/dist/types/hook.d.ts

@@ -0,0 +1,23 @@
+import { DependencyMapType, DependencyValuesType, IEventDefinition, IEventEmission, ExtractEventPayload } from "../defs";
+import { TagType } from "./tag";
+import { ITaskMeta } from "./meta";
+import { CommonPayload, symbolFilePath, symbolHook } from "./utilities";
+type OnType = "*" | IEventDefinition<any> | readonly IEventDefinition<any>[];
+export interface IHookDefinition<TDependencies extends DependencyMapType = {}, TOn extends OnType = any, TMeta extends ITaskMeta = any> {
+    id: string;
+    dependencies?: TDependencies | (() => TDependencies);
+    on: TOn;
+    /** Listener execution order. Lower numbers run first. */
+    order?: number;
+    meta?: TMeta;
+    run: (event: IEventEmission<TOn extends "*" ? any : TOn extends readonly IEventDefinition<any>[] ? CommonPayload<TOn> : ExtractEventPayload<TOn>>, dependencies: DependencyValuesType<TDependencies>) => Promise<any>;
+    tags?: TagType[];
+}
+export interface IHook<TDependencies extends DependencyMapType = {}, TOn extends OnType = any, TMeta extends ITaskMeta = any> extends IHookDefinition<TDependencies, TOn, TMeta> {
+    id: string;
+    dependencies: TDependencies | (() => TDependencies);
+    [symbolFilePath]: string;
+    [symbolHook]: true;
+    tags: TagType[];
+}
+export {};

package/dist/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 EjsonFileSentinel {
+    $ejson: "File";
+    id: string;
+    meta: InputFileMeta;
+}

package/dist/types/meta.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 {
+}

package/dist/types/resource.d.ts

@@ -0,0 +1,87 @@
+import { DependencyMapType, IOptionalDependency, IResourceMiddleware, IValidationSchema, OverridableElements, RegisterableItems, ResourceDependencyValuesType, ResourceMiddlewareAttachmentType } from "../defs";
+import { TagType } from "./tag";
+import { IResourceMeta } from "./meta";
+import { symbolFilePath, symbolResource, symbolResourceWithConfig } from "./symbols";
+import { EnsureInputSatisfiesContracts, EnsureOutputSatisfiesContracts, HasInputContracts, HasOutputContracts, InferInputOrViolationFromContracts } from "./contracts";
+type IsAny<T> = 0 extends 1 & T ? true : false;
+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;
+    /**
+     * 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;
+    /** Return an optional dependency wrapper for this resource. */
+    optional: () => IOptionalDependency<IResource<TConfig, TValue, TDependencies, TContext, TMeta, TTags, TMiddleware>>;
+    tags: TTags;
+}
+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;
+}
+export {};

package/dist/types/resourceMiddleware.d.ts

@@ -0,0 +1,47 @@
+import { DependencyMapType, DependencyValuesType, IValidationSchema, IResource } from "../defs";
+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 | (() => 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>;