@bluelibs/runner 4.7.0 → 4.8.0

package/dist/types/asyncContext.d.ts

@@ -0,0 +1,39 @@
+import type { ITaskMiddlewareConfigured } from "defs";
+export declare const ASYNC_CONTEXT_TYPES_LOADED: true;
+import { symbolAsyncContext } from "./symbols";
+import type { IValidationSchema, IOptionalDependency } from "./utilities";
+export interface IAsyncContextDefinition<T> {
+    id: string;
+    serialize?(data: T): string;
+    parse?(data: string): T;
+    /**
+     * When provided, context values will be validated when provide() is called.
+     */
+    configSchema?: IValidationSchema<T>;
+}
+/**
+ * The generic AsyncContext object returned by `defineAsyncContext`.
+ */
+export interface IAsyncContext<T> {
+    /** unique symbol used as key in the AsyncLocalStorage map */
+    readonly id: string;
+    /** Brand marker for registration and runtime checks */
+    [symbolAsyncContext]: true;
+    /** Retrieve the current context value or throw */
+    use(): T;
+    /**
+     * Provide a value for this context during the lifetime of `fn()`
+     */
+    provide<R>(value: T, fn: () => Promise<R> | R): Promise<R> | R;
+    /**
+     * Generates a middleware that guarantees the context exists (and optionally
+     * enforces that certain keys are present on the context object).
+     */
+    require<K extends keyof T = never>(keys?: K[]): ITaskMiddlewareConfigured<{
+        context: IAsyncContext<T>;
+    }>;
+    serialize(data: T): string;
+    parse(data: string): T;
+    /** Return an optional dependency wrapper for this context */
+    optional(): IOptionalDependency<IAsyncContext<T>>;
+}

package/dist/types/error.d.ts

@@ -0,0 +1,34 @@
+import { symbolError } from "./symbols";
+import type { IOptionalDependency } from "./utilities";
+import type { IValidationSchema } from "./utilities";
+export declare const ERROR_TYPES_LOADED: true;
+export interface IErrorDefinition<TData extends DefaultErrorType = DefaultErrorType> {
+    id: string;
+    serialize?: (data: TData) => string;
+    parse?: (data: string) => TData;
+    format?: (data: TData) => string;
+    /**
+     * Validate error data on throw(). If provided, data is parsed first.
+     */
+    dataSchema?: IValidationSchema<TData>;
+}
+export interface IErrorDefinitionFinal<TData extends DefaultErrorType> extends IErrorDefinition<TData> {
+    format: (data: TData) => string;
+}
+export type DefaultErrorType = Record<string, unknown>;
+/**
+ * Runtime helper returned by defineError()/r.error().
+ * Contains helpers to throw typed errors and perform type-safe checks.
+ */
+export interface IErrorHelper<TData extends DefaultErrorType = DefaultErrorType> {
+    /** Unique id for registration and DI */
+    id: string;
+    /** Throw a typed error with the given data */
+    throw(data: TData): never;
+    /** Type guard for checking if an unknown error is this error */
+    is(error: unknown): boolean;
+    /** Brand symbol for runtime detection */
+    [symbolError]: true;
+    /** Return an optional dependency wrapper for this error */
+    optional(): IOptionalDependency<IErrorHelper<TData>>;
+}

package/dist/types/runner.d.ts

@@ -52,4 +52,17 @@ export type RunOptions = {
      * you don't have event deadlocks to improve event emission performance.
      */
     runtimeCycleDetection?: 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/symbols.d.ts

@@ -10,6 +10,8 @@ export declare const symbolPhantomTask: unique symbol;
 export declare const symbolResource: 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;
@@ -17,6 +19,8 @@ export declare const symbolResourceMiddleware: unique symbol;
 export declare const symbolMiddlewareConfigured: unique symbol;
 /** Marks a task that has been patched by a tunnel. Value is the local side mode. */
 export declare const symbolTunneledTask: 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 */
@@ -26,3 +30,5 @@ export declare const symbolTagConfigured: unique symbol;
 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/utilities.d.ts

@@ -6,6 +6,8 @@ import { IHook } from "./hook";
 import { IEvent, IEventDefinition } from "./event";
 import { ITag } from "./tag";
 import { symbolOptionalDependency } from "./symbols";
+import { IErrorHelper } from "./error";
+import type { IAsyncContext } from "./asyncContext";
 export * from "./symbols";
 /**
  * Generic validation schema interface that can be implemented by any validation library.
@@ -49,7 +51,7 @@ export type OverridableElements = IResource<any, any, any, any, any> | ITask<any
  * for tasks and resources. Values are later transformed into the actual
  * callable/value shape by `DependencyValuesType`.
  */
-export type DependencyMapType = Record<string, ITask<any, any, any, any, any, any> | IResource<any, any, any, any, any, any, any> | IEvent<any> | IOptionalDependency<ITask<any, any, any, any, any, any>> | IOptionalDependency<IResource<any, any, any, any, any, any, any>> | IOptionalDependency<IEvent<any>>>;
+export type DependencyMapType = Record<string, ITask<any, any, any, any, any, any> | IResource<any, any, any, any, any, any, any> | IEvent<any> | IErrorHelper<any> | IAsyncContext<any> | IOptionalDependency<ITask<any, any, any, any, any, any>> | IOptionalDependency<IResource<any, any, any, any, any, any, any>> | IOptionalDependency<IEvent<any>> | IOptionalDependency<IErrorHelper<any>> | IOptionalDependency<IAsyncContext<any>>>;
 /** Wrapper type marking a dependency as optional at wiring time */
 export interface IOptionalDependency<T> {
     /** The wrapped dependency definition */
@@ -86,7 +88,7 @@ type EventDependency<P> = P extends void ? (() => Promise<void>) & ((input?: Rec
  * - Resource -> resolved value
  * - Event -> emit function
  */
-export type DependencyValueType<T> = T extends ITask<any, any, any> ? TaskDependency<ExtractTaskInput<T>, ExtractTaskOutput<T>> : T extends IResource<any, any> ? ResourceDependency<ExtractResourceValue<T>> : T extends IEventDefinition<any> ? EventDependency<ExtractEventPayload<T>> : T extends IOptionalDependency<infer U> ? DependencyValueType<U> | undefined : never;
+export type DependencyValueType<T> = T extends ITask<any, any, any> ? TaskDependency<ExtractTaskInput<T>, ExtractTaskOutput<T>> : T extends IResource<any, any> ? ResourceDependency<ExtractResourceValue<T>> : T extends IEventDefinition<any> ? EventDependency<ExtractEventPayload<T>> : T extends IErrorHelper<any> ? T : T extends IAsyncContext<any> ? T : T extends IOptionalDependency<infer U> ? DependencyValueType<U> | undefined : never;
 export type DependencyValuesType<T extends DependencyMapType> = {
     [K in keyof T]: DependencyValueType<T[K]>;
 };
@@ -95,7 +97,7 @@ export type TaskDependencyWithIntercept<TInput, TOutput> = TaskDependency<TInput
     intercept: (middleware: TaskLocalInterceptor<TInput, TOutput>) => void;
 };
 /** Resource-context dependency typing where tasks expose intercept() */
-export type ResourceDependencyValueType<T> = T extends ITask<any, any, any> ? TaskDependencyWithIntercept<ExtractTaskInput<T>, ExtractTaskOutput<T>> : T extends IResource<any, any> ? ResourceDependency<ExtractResourceValue<T>> : T extends IEventDefinition<any> ? EventDependency<ExtractEventPayload<T>> : T extends IOptionalDependency<infer U> ? ResourceDependencyValueType<U> | undefined : never;
+export type ResourceDependencyValueType<T> = T extends ITask<any, any, any> ? TaskDependencyWithIntercept<ExtractTaskInput<T>, ExtractTaskOutput<T>> : T extends IResource<any, any> ? ResourceDependency<ExtractResourceValue<T>> : T extends IEventDefinition<any> ? EventDependency<ExtractEventPayload<T>> : T extends IErrorHelper<any> ? T : T extends IAsyncContext<any> ? T : T extends IOptionalDependency<infer U> ? ResourceDependencyValueType<U> | undefined : never;
 export type ResourceDependencyValuesType<T extends DependencyMapType> = {
     [K in keyof T]: ResourceDependencyValueType<T[K]>;
 };
@@ -108,4 +110,4 @@ export type ResourceDependencyValuesType<T extends DependencyMapType> = {
  */
 export type RegisterableItems = IResourceWithConfig<any, any, any, any, any, any, any> | IResource<void, any, any, any, any, any, any> | IResource<{
     [K in any]?: any;
-}, any, any, any, any, any, any> | ITask<any, any, any, any, any, any> | IHook<any, any> | ITaskMiddleware<any, any, any, any> | IResourceMiddleware<any, any, any, any> | IEvent<any> | ITag<any, any, any>;
+}, any, any, any, any, any, any> | ITask<any, any, any, any, any, any> | IHook<any, any> | ITaskMiddleware<any, any, any, any> | IResourceMiddleware<any, any, any, any> | IEvent<any> | IAsyncContext<any> | IErrorHelper<any> | ITag<any, any, any>;