@bluelibs/runner 5.1.0 → 5.2.1

package/dist/types/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: Error) => void): () => void | undefined;
+    onUnhandledRejection(handler: (reason: unknown) => void): () => void | undefined;
+    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/types/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/types/platform/adapters/node-als.d.ts

@@ -0,0 +1 @@
+export declare function loadAsyncLocalStorageClass(): Promise<typeof import("async_hooks").AsyncLocalStorage>;

package/dist/types/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: Error) => void): () => NodeJS.Process;
+    onUnhandledRejection(handler: (reason: unknown) => 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/types/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/types/platform/adapters/universal.d.ts

@@ -0,0 +1,18 @@
+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 ensureInner;
+    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/types/platform/createFile.d.ts

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

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

@@ -0,0 +1,11 @@
+import type { InputFileMeta, RunnerFileSentinel } from "../types/inputFile";
+/**
+ * Browser/edge-friendly File sentinel creator.
+ * Produces the public File sentinel 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): RunnerFileSentinel & {
+    _web: {
+        blob: Blob;
+    };
+};

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

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

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

@@ -0,0 +1,27 @@
+import type { IPlatformAdapter, IAsyncLocalStorage, PlatformId, PlatformSetTimeout, PlatformClearTimeout } 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, PlatformId, PlatformSetTimeout, PlatformClearTimeout, } from "./types";
+export declare class PlatformAdapter implements IPlatformAdapter {
+    private inner;
+    readonly env: PlatformId;
+    readonly id: PlatformId;
+    readonly setTimeout: PlatformSetTimeout;
+    readonly clearTimeout: PlatformClearTimeout;
+    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>;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * 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 type PlatformSetTimeout = (...args: Parameters<typeof globalThis.setTimeout>) => ReturnType<typeof globalThis.setTimeout>;
+export type PlatformClearTimeout = (timeout: ReturnType<PlatformSetTimeout>) => void;
+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: PlatformSetTimeout;
+    clearTimeout: PlatformClearTimeout;
+    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/types/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/types/public-types.d.ts

@@ -0,0 +1,13 @@
+export type { IPlatformAdapter, IAsyncLocalStorage, PlatformId, PlatformSetTimeout, PlatformClearTimeout, } from "./platform";
+export type { TestFacade } from "./testing";
+export type { TaskBuilderWithPhantom, PhantomTaskFluentBuilder, TaskFluentBuilder, ResolveInput, ShouldReplaceInput, } from "./definers/builders/task";
+export type { AsyncContextFluentBuilder } from "./definers/builders/asyncContext";
+export type { ErrorFluentBuilder } from "./definers/builders/error";
+export type { EventFluentBuilder } from "./definers/builders/event";
+export type { HookFluentBuilder, ValidOnTarget, ResolvedOn, } from "./definers/builders/hook";
+export type { ResourceFluentBuilder, ResolveConfig, ShouldReplaceConfig, } from "./definers/builders/resource";
+export type { TaskMiddlewareFluentBuilder, ResourceMiddlewareFluentBuilder, } from "./definers/builders/middleware";
+export type { TagFluentBuilder } from "./definers/builders/tag";
+export type { HookOverrideBuilder, HookOn, } from "./definers/builders/override/hook";
+export type { TypeDefinition, SerializerOptions, JsonPrimitive, ObjectReference, SerializedTypeRecord, SerializerLike, SerializedNode, SerializedValue, SerializationContext, DeserializationContext, } from "./serializer";
+export type { ExecutionJournal, JournalKey, JournalSetOptions, } from "./types/executionJournal";

package/dist/types/public.d.ts

@@ -0,0 +1,210 @@
+import { defineTask, defineResource, defineEvent, defineTaskMiddleware, defineResourceMiddleware, defineTag, defineOverride, defineHook } from "./define";
+import { defineAsyncContext, createContext as oldCreateContext } from "./definers/defineAsyncContext";
+import { run } from "./run";
+import { createTestResource } from "./testing";
+import { override as overrideBuilder } from "./definers/builders/override";
+declare const globals: {
+    events: {
+        readonly ready: import("./defs").IEvent<void>;
+    };
+    resources: {
+        readonly store: import("./defs").IResource<void, Promise<import("./models").Store>, {}, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly middlewareManager: import("./defs").IResource<void, Promise<import("./models").MiddlewareManager>, {}, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly eventManager: import("./defs").IResource<void, Promise<import("./models").EventManager>, {}, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly taskRunner: import("./defs").IResource<void, Promise<import("./models").TaskRunner>, {}, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly logger: import("./defs").IResource<void, Promise<import("./models").Logger>, {}, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly serializer: import("./defs").IResource<void, Promise<import("./serializer").SerializerLike>, {}, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly cache: import("./defs").IResource<import("./public").CacheResourceConfig, Promise<{
+            map: Map<string, import("./defs").ICacheInstance>;
+            cacheFactoryTask: import("./defs").TaskDependencyWithIntercept<import("lru-cache").LRUCache.Options<any, any, any>, Promise<import("./defs").ICacheInstance>>;
+            defaultOptions: any;
+        }>, {
+            cacheFactoryTask: import("./defs").ITask<import("lru-cache").LRUCache.Options<any, any, any>, Promise<import("./defs").ICacheInstance>, any, any, import("./defs").TagType[], import("./defs").TaskMiddlewareAttachmentType[]>;
+        }, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly queue: import("./defs").IResource<void, Promise<{
+            map: Map<string, import("./models").Queue>;
+            run: <T>(id: string, task: (signal: AbortSignal) => Promise<T>) => Promise<T>;
+        }>, {}, {
+            map: Map<string, import("./models").Queue>;
+        }, {
+            title: string;
+            description: string;
+        }, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly httpClientFactory: import("./defs").IResource<void, Promise<import("./public").HttpClientFactory>, {
+            serializer: import("./defs").IResource<void, Promise<import("./serializer").SerializerLike>, {}, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+            store: import("./defs").IResource<void, Promise<import("./models").Store>, {}, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        }, any, {
+            title: string;
+            description: string;
+        }, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly rateLimit: import("./defs").IResource<void, Promise<{
+            states: WeakMap<import("./public").RateLimitMiddlewareConfig, import("./public").RateLimitState>;
+        }>, {}, any, any, import("./defs").ITag<{
+            metadata?: Record<string, any>;
+        }, void, void>[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly circuitBreaker: import("./defs").IResource<void, Promise<{
+            statusMap: Map<string, import("./public").CircuitBreakerStatus>;
+        }>, {}, any, any, import("./defs").ITag<{
+            metadata?: Record<string, any>;
+        }, void, void>[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly temporal: import("./defs").IResource<void, Promise<{
+            debounceStates: WeakMap<import("./public").TemporalMiddlewareConfig, import("./public").DebounceState>;
+            throttleStates: WeakMap<import("./public").TemporalMiddlewareConfig, import("./public").ThrottleState>;
+        }>, {}, any, any, import("./defs").ITag<{
+            metadata?: Record<string, any>;
+        }, void, void>[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+        readonly concurrency: import("./defs").IResource<void, Promise<{
+            semaphoresByConfig: WeakMap<import("./public").ConcurrencyMiddlewareConfig, import("./models").Semaphore>;
+            semaphoresByKey: Map<string, {
+                semaphore: import("./models").Semaphore;
+                limit: number;
+            }>;
+        }>, {}, any, any, import("./defs").ITag<{
+            metadata?: Record<string, any>;
+        }, void, void>[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+    };
+    middleware: {
+        requireContext: import("./defs").ITaskMiddleware<import("./public").RequireContextMiddlewareConfig, void, void, any>;
+        task: {
+            requireContext: import("./defs").ITaskMiddleware<import("./public").RequireContextMiddlewareConfig, void, void, any>;
+            cache: import("./defs").ITaskMiddleware<any, void, void, {
+                cache: import("./defs").IResource<import("./public").CacheResourceConfig, Promise<{
+                    map: Map<string, import("./defs").ICacheInstance>;
+                    cacheFactoryTask: import("./defs").TaskDependencyWithIntercept<import("lru-cache").LRUCache.Options<any, any, any>, Promise<import("./defs").ICacheInstance>>;
+                    defaultOptions: any;
+                }>, {
+                    cacheFactoryTask: import("./defs").ITask<import("lru-cache").LRUCache.Options<any, any, any>, Promise<import("./defs").ICacheInstance>, any, any, import("./defs").TagType[], import("./defs").TaskMiddlewareAttachmentType[]>;
+                }, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+            }> & {
+                journalKeys: {
+                    readonly hit: import("./public-types").JournalKey<boolean>;
+                };
+            };
+            concurrency: import("./defs").ITaskMiddleware<import("./public").ConcurrencyMiddlewareConfig, void, void, {
+                state: import("./defs").IResource<void, Promise<{
+                    semaphoresByConfig: WeakMap<import("./public").ConcurrencyMiddlewareConfig, import("./models").Semaphore>;
+                    semaphoresByKey: Map<string, {
+                        semaphore: import("./models").Semaphore;
+                        limit: number;
+                    }>;
+                }>, {}, any, any, import("./defs").ITag<{
+                    metadata?: Record<string, any>;
+                }, void, void>[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+            }>;
+            debounce: import("./defs").ITaskMiddleware<import("./public").TemporalMiddlewareConfig, void, void, {
+                state: import("./defs").IResource<void, Promise<{
+                    debounceStates: WeakMap<import("./public").TemporalMiddlewareConfig, import("./public").DebounceState>;
+                    throttleStates: WeakMap<import("./public").TemporalMiddlewareConfig, import("./public").ThrottleState>;
+                }>, {}, any, any, import("./defs").ITag<{
+                    metadata?: Record<string, any>;
+                }, void, void>[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+            }>;
+            throttle: import("./defs").ITaskMiddleware<import("./public").TemporalMiddlewareConfig, void, void, {
+                state: import("./defs").IResource<void, Promise<{
+                    debounceStates: WeakMap<import("./public").TemporalMiddlewareConfig, import("./public").DebounceState>;
+                    throttleStates: WeakMap<import("./public").TemporalMiddlewareConfig, import("./public").ThrottleState>;
+                }>, {}, any, any, import("./defs").ITag<{
+                    metadata?: Record<string, any>;
+                }, void, void>[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+            }>;
+            fallback: import("./defs").ITaskMiddleware<import("./public").FallbackMiddlewareConfig, void, void, {
+                taskRunner: import("./defs").IResource<void, Promise<import("./models").TaskRunner>, {}, any, any, import("./defs").TagType[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+            }> & {
+                journalKeys: {
+                    readonly active: import("./public-types").JournalKey<boolean>;
+                    readonly error: import("./public-types").JournalKey<Error>;
+                };
+            };
+            rateLimit: import("./defs").ITaskMiddleware<import("./public").RateLimitMiddlewareConfig, void, void, {
+                state: import("./defs").IResource<void, Promise<{
+                    states: WeakMap<import("./public").RateLimitMiddlewareConfig, import("./public").RateLimitState>;
+                }>, {}, any, any, import("./defs").ITag<{
+                    metadata?: Record<string, any>;
+                }, void, void>[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+            }> & {
+                journalKeys: {
+                    readonly remaining: import("./public-types").JournalKey<number>;
+                    readonly resetTime: import("./public-types").JournalKey<number>;
+                    readonly limit: import("./public-types").JournalKey<number>;
+                };
+            };
+            retry: import("./defs").ITaskMiddleware<import("./public").RetryMiddlewareConfig, void, void, any> & {
+                journalKeys: {
+                    readonly attempt: import("./public-types").JournalKey<number>;
+                    readonly lastError: import("./public-types").JournalKey<Error>;
+                };
+            };
+            timeout: import("./defs").ITaskMiddleware<import("./public").TimeoutMiddlewareConfig, void, void, any> & {
+                journalKeys: {
+                    readonly abortController: import("./public-types").JournalKey<AbortController>;
+                };
+            };
+            circuitBreaker: import("./defs").ITaskMiddleware<import("./public").CircuitBreakerMiddlewareConfig, void, void, {
+                state: import("./defs").IResource<void, Promise<{
+                    statusMap: Map<string, import("./public").CircuitBreakerStatus>;
+                }>, {}, any, any, import("./defs").ITag<{
+                    metadata?: Record<string, any>;
+                }, void, void>[], import("./defs").ResourceMiddlewareAttachmentType[]>;
+            }> & {
+                journalKeys: {
+                    readonly state: import("./public-types").JournalKey<import("./public").CircuitBreakerState>;
+                    readonly failures: import("./public-types").JournalKey<number>;
+                };
+            };
+        };
+        resource: {
+            retry: import("./defs").IResourceMiddleware<import("./public").RetryMiddlewareConfig, void, void, any>;
+            timeout: import("./defs").IResourceMiddleware<import("./public").TimeoutMiddlewareConfig, void, void, any>;
+        };
+    };
+    tags: {
+        system: import("./defs").ITag<{
+            metadata?: Record<string, any>;
+        }, void, void>;
+        excludeFromGlobalHooks: import("./defs").ITag<{
+            metadata?: Record<string, any>;
+        }, void, void>;
+        debug: import("./defs").ITag<import("./public").DebugFriendlyConfig, void, void>;
+        tunnel: import("./defs").ITag<void, void, import("./public").TunnelRunner>;
+        tunnelPolicy: import("./defs").ITag<import("./public").TunnelTaskMiddlewarePolicyConfig, void, void>;
+        authValidator: import("./defs").ITag<void, void, void>;
+    };
+    tunnels: Readonly<{
+        http: Readonly<{
+            createClient(cfg: import("./public").HttpCreateClientConfig): import("./http-fetch-tunnel.resource").ExposureFetchClient;
+        }>;
+    }>;
+    debug: {
+        levels: {
+            normal: import("./public").DebugConfig;
+            verbose: import("./public").DebugConfig;
+        };
+    };
+};
+export { globals };
+export { defineTask as task, defineResource as resource, defineEvent as event, defineTaskMiddleware as taskMiddleware, defineResourceMiddleware as resourceMiddleware, defineAsyncContext as asyncContext, defineTag as tag, defineOverride as override, defineHook as hook, run, createTestResource, };
+declare const createContext: typeof oldCreateContext;
+export { createContext };
+export declare const r: Readonly<{
+    resource: typeof import("./definers/builders/resource").resourceBuilder;
+    task: import("./public-types").TaskBuilderWithPhantom;
+    event: typeof import("./definers/builders/event").eventBuilder;
+    hook: typeof import("./definers/builders/hook").hookBuilder;
+    tag: typeof import("./definers/builders/tag").tagBuilder;
+    override: typeof overrideBuilder;
+    asyncContext: typeof import("./definers/builders/asyncContext").asyncContextBuilder;
+    error: typeof import("./definers/builders/error").errorBuilder;
+    middleware: Readonly<{
+        task: typeof import("./definers/builders/middleware").taskMiddlewareBuilder;
+        resource: typeof import("./definers/builders/middleware").resourceMiddlewareBuilder;
+    }>;
+}>;
+export * as definitions from "./defs";
+export * from "./models";
+export * from "./globals/types";
+export * as Errors from "./errors";
+export { PlatformAdapter, setPlatform } from "./platform";
+export * from "./http-client";
+export * from "./http-fetch-tunnel.resource";
+export { Serializer, SymbolPolicy, SymbolPolicyErrorMessage, } from "./serializer";
+export { journal } from "./models/ExecutionJournal";

package/dist/types/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/types/serializer/Serializer.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Graph-aware serializer/deserializer with circular reference
+ * handling and pluggable type support.
+ *
+ * Internal protocol reference: `readmes/SERIALIZER_PROTOCOL.md`.
+ */
+import type { TypeDefinition, SerializationContext, SerializerOptions, DeserializationContext, SerializedValue, SerializedNode } from "./types";
+export declare class Serializer {
+    /** Type registry for managing custom types */
+    private readonly typeRegistry;
+    private readonly runtimeOptions;
+    /** JSON indentation width when pretty printing is enabled */
+    private readonly indent;
+    /** Maximum recursion depth allowed */
+    private readonly maxDepth;
+    /** Maximum allowed RegExp pattern length during deserialization */
+    private readonly maxRegExpPatternLength;
+    /** Allow RegExp patterns that fail the safety heuristic */
+    private readonly allowUnsafeRegExp;
+    /** Disallowed keys that can lead to prototype pollution */
+    private readonly unsafeKeys;
+    constructor(options?: SerializerOptions);
+    /**
+     * Alias of `serialize()` to match the historical tunnel serializer surface.
+     */
+    stringify<T>(value: T): string;
+    /**
+     * Alias of `deserialize()` to match the historical tunnel serializer surface.
+     */
+    parse<T = unknown>(payload: string): T;
+    /**
+     * Serialize an arbitrary value into a JSON string.
+     */
+    serialize<T>(value: T, context?: SerializationContext): string;
+    /**
+     * Deserialize a JSON string back to its original value.
+     */
+    deserialize<T = unknown>(payload: string): T;
+    /**
+     * Register a custom type for serialization/deserialization.
+     */
+    addType<TInstance, TSerialized>(typeDef: TypeDefinition<TInstance, TSerialized>): void;
+    addType<TJson = unknown, TInstance = unknown>(name: string, factory: (json: TJson) => TInstance): void;
+    /**
+     * @internal - Exposed for testing RegExp safety validation
+     */
+    readonly isRegExpPatternSafe: (pattern: string) => boolean;
+    /**
+     * @internal - Exposed for testing quantifier detection
+     */
+    readonly isQuantifierAt: (pattern: string, index: number) => boolean;
+    /**
+     * @internal - Exposed for testing quantifier character detection
+     */
+    readonly isQuantifierChar: (char: string, pattern: string, index: number) => boolean;
+    /**
+     * @internal - Exposed for testing bounded quantifier detection
+     */
+    readonly isBoundedQuantifier: (pattern: string, index: number) => boolean;
+    /**
+     * @internal - Exposed for test compatibility
+     */
+    toNodeRecord(nodes: Record<string, SerializedNode>): Record<string, SerializedNode>;
+    /**
+     * @internal - Exposed for test compatibility
+     */
+    deserializeValue(value: SerializedValue, context: DeserializationContext, depth?: number): unknown;
+    /**
+     * @internal - Exposed for test compatibility
+     */
+    resolveReference(id: string, context: DeserializationContext, depth?: number): unknown;
+    /**
+     * @internal - Exposed for test compatibility
+     */
+    mergePlaceholder(placeholder: unknown, result: unknown): unknown;
+    /**
+     * @internal - Exposed for test compatibility
+     */
+    isSerializedTypeRecord(value: unknown): value is {
+        __type: string;
+        value: unknown;
+    };
+    private jsonStringify;
+}

package/dist/types/serializer/binary-builtins.d.ts

@@ -0,0 +1,5 @@
+import type { TypeDefinition } from "./types";
+export declare const ArrayBufferType: TypeDefinition<ArrayBuffer, readonly number[]>;
+export declare const DataViewType: TypeDefinition<DataView, readonly number[]>;
+export declare const BufferType: TypeDefinition<Uint8Array, readonly number[]>;
+export declare const binaryBuiltInTypes: Array<TypeDefinition<unknown, unknown>>;

package/dist/types/serializer/builtins.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Built-in type definitions for common JavaScript objects
+ */
+import type { TypeDefinition } from "./types";
+import { BigIntPayload, NonFiniteNumberTag } from "./special-values";
+export declare enum SymbolPayloadKind {
+    For = "For",
+    WellKnown = "WellKnown"
+}
+declare const WELL_KNOWN_SYMBOL_KEYS: readonly ["asyncIterator", "hasInstance", "isConcatSpreadable", "iterator", "match", "matchAll", "observable", "replace", "search", "species", "split", "toPrimitive", "toStringTag", "unscopables"];
+type WellKnownSymbolKey = (typeof WELL_KNOWN_SYMBOL_KEYS)[number];
+export type SerializedSymbolPayload = {
+    kind: SymbolPayloadKind.For;
+    key: string;
+} | {
+    kind: SymbolPayloadKind.WellKnown;
+    key: WellKnownSymbolKey;
+};
+export declare const assertSymbolPayload: (payload: unknown) => SerializedSymbolPayload;
+/**
+ * Built-in type handler for Date objects
+ */
+export declare const DateType: TypeDefinition<Date, string>;
+/**
+ * Built-in type handler for RegExp objects
+ */
+export declare const RegExpType: TypeDefinition<RegExp, {
+    pattern: string;
+    flags: string;
+}>;
+/**
+ * Built-in type handler for Map objects
+ */
+export declare const MapType: TypeDefinition<Map<unknown, unknown>, Array<[unknown, unknown]>>;
+/**
+ * Built-in type handler for Set objects
+ */
+export declare const SetType: TypeDefinition<Set<unknown>, unknown[]>;
+export declare const UndefinedType: TypeDefinition<undefined, null>;
+export declare const NonFiniteNumberType: TypeDefinition<number, NonFiniteNumberTag>;
+export declare const BigIntType: TypeDefinition<bigint, BigIntPayload>;
+export declare const SymbolType: TypeDefinition<symbol, SerializedSymbolPayload>;
+/**
+ * Array of all built-in type definitions
+ */
+export declare const builtInTypes: Array<TypeDefinition<unknown, unknown>>;
+export {};

package/dist/types/serializer/deserializer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Deserialization logic for graph and legacy payloads.
+ * Extracted from Serializer.ts as a standalone module.
+ */
+import type { SerializedValue, DeserializationContext } from "./types";
+import type { TypeRegistry } from "./type-registry";
+export interface DeserializerOptions {
+    maxDepth: number;
+    unsafeKeys: ReadonlySet<string>;
+    typeRegistry: TypeRegistry;
+}
+/**
+ * Deserialize a value from its serialized representation.
+ */
+export declare const deserializeValue: (value: SerializedValue, context: DeserializationContext, depth: number, options: DeserializerOptions) => unknown;
+/**
+ * Resolve a reference ID to its deserialized value.
+ */
+export declare const resolveReference: (id: string, context: DeserializationContext, depth: number, options: DeserializerOptions) => unknown;
+/**
+ * Merge a placeholder with the final result for identity preservation.
+ */
+export declare const mergePlaceholder: (placeholder: unknown, result: unknown, unsafeKeys: ReadonlySet<string>) => unknown;
+/**
+ * Deserialize legacy tree-format payloads (pre-graph format).
+ */
+export declare const deserializeLegacy: (value: unknown, depth: number, options: DeserializerOptions) => unknown;

package/dist/types/serializer/error-url-builtins.d.ts

@@ -0,0 +1,13 @@
+import type { TypeDefinition } from "./types";
+interface SerializedErrorPayload {
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: unknown;
+    customFields: Record<string, unknown>;
+}
+export declare const ErrorType: TypeDefinition<Error, SerializedErrorPayload>;
+export declare const URLType: TypeDefinition<URL, string>;
+export declare const URLSearchParamsType: TypeDefinition<URLSearchParams, string>;
+export declare const errorAndUrlBuiltInTypes: Array<TypeDefinition<unknown, unknown>>;
+export {};

package/dist/types/serializer/graph-serializer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Graph-mode serialization with circular reference handling.
+ * Extracted from Serializer.ts as a standalone module.
+ */
+import type { SerializedValue, SerializationContext, SerializedNode } from "./types";
+import type { TypeRegistry } from "./type-registry";
+export interface SerializeState {
+    serializingValueTypes: WeakSet<object>;
+    excludedTypeIds: string[];
+}
+export interface GraphSerializerOptions {
+    maxDepth: number;
+    unsafeKeys: ReadonlySet<string>;
+    typeRegistry: TypeRegistry;
+}
+/**
+ * Create a unique object ID for the serialization context.
+ */
+export declare const createObjectId: (context: SerializationContext) => string;
+/**
+ * Store a node in the serialization context.
+ */
+export declare const storeNode: (context: SerializationContext, id: string, node: SerializedNode) => void;
+/**
+ * Serialize a value in graph mode with reference tracking.
+ */
+export declare const serializeValue: (value: unknown, context: SerializationContext, state: SerializeState, depth: number, options: GraphSerializerOptions) => SerializedValue;

package/dist/types/serializer/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Main export module for the Serializer
+ */
+export type { JsonPrimitive, ObjectReference, SerializedTypeRecord, SerializerOptions, TypeDefinition, SerializedNode, SerializedValue, SerializationContext, DeserializationContext, SerializedGraph, SerializerLike, } from "./types";
+export { SymbolPolicy, SymbolPolicyErrorMessage } from "./types";
+export { Serializer } from "./Serializer";

package/dist/types/serializer/option-normalizers.d.ts

@@ -0,0 +1,2 @@
+export declare const normalizeMaxDepth: (value: number | undefined, fallback: number) => number;
+export declare const normalizeMaxRegExpPatternLength: (value: number | undefined, fallback: number) => number;