@bluelibs/runner 5.2.1 → 5.4.0

package/dist/types/platform/types.d.ts

@@ -23,9 +23,15 @@ export interface IAsyncLocalStorage<T> {
     run<R>(store: T, callback: () => R): R;
 }
 /**
- * Utility functions for environment detection
+ * Backward-compatible utility functions retained for consumers
+ * importing environment guards from `platform/types`.
  */
 export declare function isNode(): boolean;
 export declare function isBrowser(): boolean;
+/**
+ * Legacy alias kept for compatibility.
+ * Worker-like runtimes are now modeled under the "edge" platform id.
+ */
 export declare function isWebWorker(): boolean;
+export declare function isEdge(): boolean;
 export declare function isUniversal(): boolean;

package/dist/types/public.d.ts

@@ -193,7 +193,9 @@ export declare const r: Readonly<{
     tag: typeof import("./definers/builders/tag").tagBuilder;
     override: typeof overrideBuilder;
     asyncContext: typeof import("./definers/builders/asyncContext").asyncContextBuilder;
-    error: typeof import("./definers/builders/error").errorBuilder;
+    error: typeof import("./definers/builders/error").errorBuilder & {
+        is: (error: unknown) => error is import("./public").RunnerError;
+    };
     middleware: Readonly<{
         task: typeof import("./definers/builders/middleware").taskMiddlewareBuilder;
         resource: typeof import("./definers/builders/middleware").resourceMiddlewareBuilder;
@@ -203,7 +205,10 @@ export * as definitions from "./defs";
 export * from "./models";
 export * from "./globals/types";
 export * as Errors from "./errors";
+export { cancellationError } from "./errors";
 export { PlatformAdapter, setPlatform } from "./platform";
+export { RunnerError } from "./definers/defineError";
+export { LockableMap } from "./tools/LockableMap";
 export * from "./http-client";
 export * from "./http-fetch-tunnel.resource";
 export { Serializer, SymbolPolicy, SymbolPolicyErrorMessage, } from "./serializer";

package/dist/types/testing.d.ts

@@ -12,7 +12,6 @@ export interface TestFacade {
  * 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>;

package/dist/types/tools/LockableMap.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A Map that can be permanently locked to prevent further mutations.
+ *
+ * Before locking it behaves exactly like a regular `Map`.
+ * After `lock()` is called, any call to `set`, `delete` or `clear`
+ * throws immediately — enforcing immutability at the data-structure level.
+ */
+export declare class LockableMap<K, V> extends Map<K, V> {
+    #private;
+    constructor(name?: string);
+    /** Whether the map is currently locked. */
+    get locked(): boolean;
+    /** Permanently lock the map — no further mutations allowed. */
+    lock(): void;
+    /** @throws if the map is locked */
+    private throwIfLocked;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    clear(): void;
+}

package/dist/types/types/error.d.ts

@@ -6,9 +6,16 @@ export type ErrorReference = string | IErrorHelper<any>;
 export type ThrowsList = ReadonlyArray<ErrorReference>;
 export interface IErrorDefinition<TData extends DefaultErrorType = DefaultErrorType> {
     id: string;
+    httpCode?: number;
     serialize?: (data: TData) => string;
     parse?: (data: string) => TData;
     format?: (data: TData) => string;
+    /**
+     * Optional advice on how to fix the error. Appears in the stringified
+     * error message after the main message. Can be a static string or a
+     * function that receives the error data and returns a string.
+     */
+    remediation?: string | ((data: TData) => string);
     /**
      * Validate error data on throw(). If provided, data is parsed first.
      */
@@ -17,8 +24,20 @@ export interface IErrorDefinition<TData extends DefaultErrorType = DefaultErrorT
 }
 export interface IErrorDefinitionFinal<TData extends DefaultErrorType> extends IErrorDefinition<TData> {
     format: (data: TData) => string;
+    httpCode?: number;
+    remediation?: string | ((data: TData) => string);
 }
 export type DefaultErrorType = Record<string, unknown>;
+/**
+ * Runtime error shape thrown by r.error()/defineError() helpers.
+ * Consumers can use helper.is(error) to narrow unknown values to this type.
+ */
+export interface IRunnerError<TData extends DefaultErrorType = DefaultErrorType> extends Error {
+    id: string;
+    httpCode?: number;
+    data: TData;
+    remediation?: string;
+}
 /**
  * Runtime helper returned by defineError()/r.error().
  * Contains helpers to throw typed errors and perform type-safe checks.
@@ -26,10 +45,12 @@ export type DefaultErrorType = Record<string, unknown>;
 export interface IErrorHelper<TData extends DefaultErrorType = DefaultErrorType> {
     /** Unique id for registration and DI */
     id: string;
+    /** Optional HTTP status code associated with this error helper */
+    httpCode?: number;
     /** 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;
+    is(error: unknown): error is IRunnerError<TData>;
     /** Brand symbol for runtime detection */
     [symbolError]: true;
     /** Return an optional dependency wrapper for this error */

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

@@ -3,7 +3,7 @@ import { IResourceMiddleware, ResourceMiddlewareAttachmentType } from "./resourc
 import { TagType } from "./tag";
 import { IResourceMeta } from "./meta";
 import type { ThrowsList } from "./error";
-import { symbolFilePath, symbolResource, symbolResourceWithConfig, symbolResourceForkedFrom } from "./symbols";
+import { symbolFilePath, symbolForkedFrom, symbolResource, symbolResourceWithConfig } 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";
@@ -27,8 +27,6 @@ export interface ResourceForkOptions {
 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;
@@ -109,7 +107,7 @@ export interface IResource<TConfig = void, TValue extends Promise<any> = Promise
     [symbolFilePath]: string;
     [symbolResource]: true;
     /** Present only on forked resources. */
-    [symbolResourceForkedFrom]?: ResourceForkInfo;
+    [symbolForkedFrom]?: ResourceForkInfo;
     /** Normalized list of error ids declared via `throws`. */
     throws?: readonly string[];
     /** Return an optional dependency wrapper for this resource. */

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

@@ -5,11 +5,11 @@
  * @internal
  */
 export declare const symbolTask: unique symbol;
-/** Marks a task as a phantom task (no-op run; meant to be tunneled/routed). */
+/** Marks a task as a phantom task (throws when unrouted; 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;
+/** @internal Generic fork provenance metadata for definitions that support `.fork()` */
+export declare const symbolForkedFrom: unique symbol;
 export declare const symbolResourceWithConfig: unique symbol;
 export declare const symbolEvent: unique symbol;
 /** @internal Marks an error helper definition */

package/dist/types/types/tagged.d.ts

@@ -0,0 +1,18 @@
+import type { HasInputContracts, HasOutputContracts, InferInputOrViolationFromContracts, InferOutputOrViolationFromContracts } from "./contracts";
+import type { IResource } from "./resource";
+import type { ITask } from "./task";
+import type { ITag } from "./tag";
+type TagInputContract<TTag extends ITag<any, any, any>> = HasInputContracts<[TTag]> extends true ? InferInputOrViolationFromContracts<[TTag]> : any;
+type TagOutputContract<TTag extends ITag<any, any, any>> = HasOutputContracts<[TTag]> extends true ? InferOutputOrViolationFromContracts<[TTag]> : any;
+export type AnyResource = IResource<any, any, any, any, any, any, any>;
+/**
+ * A task discovered by a concrete tag. If the tag carries contracts,
+ * its input/output contracts are reflected in the task signature.
+ */
+export type TaggedTask<TTag extends ITag<any, any, any>> = ITask<TagInputContract<TTag>, Promise<TagOutputContract<TTag>>, any, any, any, any>;
+/**
+ * A resource discovered by a concrete tag. If the tag carries contracts,
+ * its config/value contracts are reflected in the resource signature.
+ */
+export type TaggedResource<TTag extends ITag<any, any, any>> = IResource<TagInputContract<TTag>, Promise<TagOutputContract<TTag>>, any, any, any, any, any>;
+export {};

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

@@ -70,7 +70,7 @@ export interface ITask<TInput = any, TOutput extends Promise<any> = any, TDepend
     tags: TTags;
 }
 export type AnyTask = ITask<any, any, any, any, any, any>;
-/** Narrowed type for phantom tasks (no-op run by default). */
+/** Narrowed type for phantom tasks (throws unless routed through a tunnel). */
 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;
 };