@riebeckite/runtime 0.0.0-stage → 0.0.37

package/dist/src/client/worker.d.ts

@@ -0,0 +1,31 @@
+import type { RuntimeCapability, RuntimeDefinition, RuntimeKind, RuntimeLimits } from "../core/types.js";
+export declare const MAX_ACTIVE_WORKERS = 8;
+export type WorkerMessageEvent = {
+    readonly data: unknown;
+};
+export type WorkerErrorEvent = {
+    readonly error?: unknown;
+    readonly message?: string;
+};
+export type WorkerLike = {
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+    addEventListener(type: "message", listener: (event: WorkerMessageEvent) => void): void;
+    addEventListener(type: "error", listener: (event: WorkerErrorEvent) => void): void;
+    addEventListener(type: "messageerror", listener: (event: WorkerMessageEvent) => void): void;
+    removeEventListener(type: "message", listener: (event: WorkerMessageEvent) => void): void;
+    removeEventListener(type: "error", listener: (event: WorkerErrorEvent) => void): void;
+    removeEventListener(type: "messageerror", listener: (event: WorkerMessageEvent) => void): void;
+    terminate(): void;
+};
+export type WorkerRuntimeOptions<TInput, TOutput> = {
+    readonly id: string;
+    readonly kind?: RuntimeKind;
+    readonly capabilities?: readonly RuntimeCapability[];
+    readonly limits?: RuntimeLimits;
+    readonly createWorker: () => WorkerLike;
+    readonly init?: unknown;
+    readonly initTransfer?: readonly Transferable[];
+    readonly invokePayload?: (input: TInput) => unknown;
+    readonly mapResult?: (payload: unknown) => TOutput;
+};
+export declare function createWorkerRuntime<TInput, TOutput>(options: WorkerRuntimeOptions<TInput, TOutput>): RuntimeDefinition<TInput, TOutput>;

package/dist/src/core/abort.d.ts

@@ -0,0 +1 @@
+export declare function abortReasonToError(signal: AbortSignal): Error;

package/dist/src/core/errors.d.ts

@@ -0,0 +1,44 @@
+export declare class RuntimeError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class RuntimeStateError extends RuntimeError {
+    constructor(message: string);
+}
+export declare class RuntimeFailureError extends RuntimeStateError {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class RuntimeAbortError extends RuntimeError {
+    constructor(message?: string);
+}
+export declare class RuntimeTimeoutError extends RuntimeError {
+    constructor(message?: string);
+}
+export declare class RuntimePayloadError extends RuntimeError {
+    constructor(message: string);
+}
+export declare class RuntimeConcurrencyError extends RuntimeError {
+    constructor(message: string);
+}
+export declare class RuntimeWorkerError extends RuntimeError {
+    readonly remoteName: string | undefined;
+    readonly remoteKind: string | undefined;
+    constructor(message: string, options?: ErrorOptions & {
+        remoteName?: string;
+        remoteKind?: string;
+    });
+}
+export declare class RuntimeWasmError extends RuntimeError {
+    readonly trap: boolean;
+    constructor(message: string, options?: ErrorOptions & {
+        trap?: boolean;
+    });
+}
+export declare class RuntimeIframeError extends RuntimeError {
+    readonly remoteKind: string | undefined;
+    constructor(message: string, options?: ErrorOptions & {
+        remoteKind?: string;
+    });
+}
+export declare class RuntimeUnsupportedError extends RuntimeError {
+    constructor(message: string);
+}

package/dist/src/core/instance.d.ts

@@ -0,0 +1,32 @@
+import type { InteractiveRuntime, InvokeOptions, RuntimeCapability, RuntimeDefinition, RuntimeInstanceOptions, RuntimeKind, RuntimeState, RuntimeStateChange } from "./types.js";
+export declare class RuntimeInstance<TInput, TOutput> implements InteractiveRuntime<TInput, TOutput> {
+    readonly id: string;
+    readonly instanceId: string;
+    readonly kind: RuntimeKind;
+    readonly capabilities: readonly RuntimeCapability[];
+    private readonly driver;
+    private readonly controller;
+    private readonly listeners;
+    private readonly active;
+    private readonly limits;
+    private readonly onError;
+    private currentState;
+    private requestCount;
+    private mountPromise;
+    private disposePromise;
+    private stopPromise;
+    private failure;
+    constructor(definition: RuntimeDefinition<TInput, TOutput>, options: RuntimeInstanceOptions);
+    get state(): RuntimeState;
+    get signal(): AbortSignal;
+    onStateChange(listener: (change: RuntimeStateChange) => void): () => void;
+    mount(): Promise<void>;
+    invoke(input: TInput, options?: InvokeOptions): Promise<TOutput>;
+    dispose(): Promise<void>;
+    private runStart;
+    private runStop;
+    private stopDriver;
+    private disposedError;
+    private transition;
+    private report;
+}

package/dist/src/core/outcome.d.ts

@@ -0,0 +1,7 @@
+export declare class RuntimeTransfer<TOutput> {
+    readonly value: TOutput;
+    readonly transfer: readonly unknown[];
+    constructor(value: TOutput, transfer?: readonly unknown[]);
+}
+export declare function transferOutput<TOutput>(value: TOutput, transfer?: readonly unknown[]): RuntimeTransfer<TOutput>;
+export declare function isRuntimeTransfer<TOutput>(value: unknown): value is RuntimeTransfer<TOutput>;

package/dist/src/core/payload.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Estimates the structured-clone payload size in bytes. It intentionally
+ * rejects graphs that are too deep or too large instead of walking forever.
+ */
+export declare function estimatePayloadSize(value: unknown): number;
+export declare function assertPayloadSize(value: unknown, limit: number, label: string): void;

package/dist/src/core/protocol.d.ts

@@ -0,0 +1,26 @@
+import type { RuntimeCapability, RuntimeLimits } from "./types.js";
+export declare const RUNTIME_PROTOCOL = "riebeckite:runtime";
+export declare const RUNTIME_PROTOCOL_VERSION = 1;
+export declare const RUNTIME_MESSAGE_KINDS: readonly ["init", "invoke", "cancel", "ready", "result", "error", "fatal", "dispose"];
+export type RuntimeMessageKind = (typeof RUNTIME_MESSAGE_KINDS)[number];
+export type RuntimeErrorWire = {
+    readonly name: string;
+    readonly message: string;
+    readonly kind?: string;
+    readonly trap?: boolean;
+    readonly stack?: string;
+};
+export type RuntimeMessage = {
+    readonly protocol: typeof RUNTIME_PROTOCOL;
+    readonly version: number;
+    readonly instanceId: string;
+    readonly kind: RuntimeMessageKind;
+    readonly requestId?: number;
+    readonly capability?: RuntimeCapability;
+    readonly payload?: unknown;
+    readonly transfer?: readonly unknown[];
+    readonly limits?: RuntimeLimits;
+    readonly error?: RuntimeErrorWire;
+};
+export declare function isRuntimeMessage(value: unknown): value is RuntimeMessage;
+export declare function serializeRuntimeError(error: unknown): RuntimeErrorWire;

package/dist/src/core/registry.d.ts

@@ -0,0 +1,17 @@
+import type { InteractiveRuntime, RuntimeCapability, RuntimeDefinition, RuntimeInstanceOptions, RuntimeKind, RuntimeLimits } from "./types.js";
+export declare class InteractiveRuntimeRegistry {
+    private readonly definitions;
+    register<TInput, TOutput>(definition: RuntimeDefinition<TInput, TOutput>): void;
+    has(id: string): boolean;
+    get<TInput = unknown, TOutput = unknown>(id: string): RuntimeDefinition<TInput, TOutput>;
+    get ids(): readonly string[];
+    create<TInput = unknown, TOutput = unknown>(id: string, options?: RuntimeInstanceOptions): InteractiveRuntime<TInput, TOutput>;
+}
+export declare function defineInteractiveRuntime<TInput, TOutput>(definition: {
+    readonly id: string;
+    readonly kind: RuntimeKind;
+    readonly capabilities?: readonly RuntimeCapability[];
+    readonly limits?: RuntimeLimits;
+    readonly create: RuntimeDefinition<TInput, TOutput>["create"];
+}): RuntimeDefinition<TInput, TOutput>;
+export declare function createInteractiveRuntime<TInput, TOutput>(definition: RuntimeDefinition<TInput, TOutput>, options?: RuntimeInstanceOptions): InteractiveRuntime<TInput, TOutput>;

package/dist/src/core/types.d.ts

@@ -0,0 +1,77 @@
+export declare const RUNTIME_KINDS: readonly ["main", "worker", "wasm-worker", "iframe"];
+export type RuntimeKind = (typeof RUNTIME_KINDS)[number];
+export declare const RUNTIME_STATES: readonly ["created", "starting", "ready", "running", "stopping", "disposed", "failed"];
+export type RuntimeState = (typeof RUNTIME_STATES)[number];
+export declare const RUNTIME_CAPABILITIES: readonly ["dom", "worker", "wasm", "network", "message"];
+export type RuntimeCapability = (typeof RUNTIME_CAPABILITIES)[number];
+export type RuntimeLimits = {
+    readonly maxInputBytes?: number;
+    readonly maxOutputBytes?: number;
+    readonly maxConcurrent?: number;
+    readonly invokeTimeoutMs?: number;
+    readonly startTimeoutMs?: number;
+};
+export type ResolvedRuntimeLimits = {
+    readonly maxInputBytes: number;
+    readonly maxOutputBytes: number;
+    readonly maxConcurrent: number;
+    readonly invokeTimeoutMs: number;
+    readonly startTimeoutMs: number;
+};
+export type RuntimeInvokeContext = {
+    readonly signal: AbortSignal;
+    readonly requestId: number;
+    readonly capability?: RuntimeCapability;
+    readonly transfer?: readonly unknown[];
+};
+export type RuntimeDriverResult<TOutput> = {
+    readonly value: TOutput;
+    readonly transfer: readonly unknown[];
+};
+export type RuntimeDriver<TInput, TOutput> = {
+    start(): void | Promise<void>;
+    invoke(input: TInput, context: RuntimeInvokeContext): TOutput | RuntimeDriverResult<TOutput> | Promise<TOutput | RuntimeDriverResult<TOutput>>;
+    stop(): void | Promise<void>;
+};
+export type RuntimeCreateContext = {
+    readonly instanceId: string;
+    readonly signal: AbortSignal;
+    readonly limits: ResolvedRuntimeLimits;
+    /** DOM mount target. Core never reads it; adapters interpret it. */
+    readonly root?: unknown;
+};
+export type RuntimeDefinition<TInput, TOutput> = {
+    readonly id: string;
+    readonly kind: RuntimeKind;
+    readonly capabilities: readonly RuntimeCapability[];
+    readonly limits: RuntimeLimits;
+    create(context: RuntimeCreateContext): RuntimeDriver<TInput, TOutput>;
+};
+export type InvokeOptions = {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly capability?: RuntimeCapability;
+    readonly transfer?: readonly unknown[];
+};
+export type RuntimeInstanceOptions = {
+    readonly signal?: AbortSignal;
+    readonly root?: unknown;
+    readonly onError?: (error: unknown, phase: RuntimeErrorPhase) => void;
+};
+export type RuntimeErrorPhase = "start" | "invoke" | "stop" | "state-change";
+export type RuntimeStateChange = {
+    readonly previous: RuntimeState;
+    readonly state: RuntimeState;
+};
+export type InteractiveRuntime<TInput, TOutput> = {
+    readonly id: string;
+    readonly instanceId: string;
+    readonly kind: RuntimeKind;
+    readonly capabilities: readonly RuntimeCapability[];
+    readonly state: RuntimeState;
+    readonly signal: AbortSignal;
+    onStateChange(listener: (change: RuntimeStateChange) => void): () => void;
+    mount(): Promise<void>;
+    invoke(input: TInput, options?: InvokeOptions): Promise<TOutput>;
+    dispose(): Promise<void>;
+};

package/dist/worker.d.ts

@@ -0,0 +1,37 @@
+import { type RuntimeTransfer } from "./src/core/outcome.js";
+import type { RuntimeCapability } from "./src/core/types.js";
+export type RuntimeMessageScope = {
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+    addEventListener(type: "message", listener: (event: {
+        readonly data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (event: {
+        readonly data: unknown;
+    }) => void): void;
+    close?(): void;
+};
+export type WorkerRuntimeHandler<TInput, TOutput> = {
+    initialize?(init: unknown, context: {
+        readonly instanceId: string;
+        readonly signal: AbortSignal;
+    }): void | Promise<void>;
+    invoke(input: TInput, context: {
+        readonly instanceId: string;
+        readonly requestId: number;
+        readonly signal: AbortSignal;
+        readonly capability?: RuntimeCapability;
+    }): TOutput | RuntimeTransfer<TOutput> | Promise<TOutput | RuntimeTransfer<TOutput>>;
+    dispose?(): void | Promise<void>;
+};
+export declare function serveWorkerRuntime<TInput, TOutput>(scope: RuntimeMessageScope, handler: WorkerRuntimeHandler<TInput, TOutput>): () => void;
+export type WasmWorkerInit = {
+    readonly wasmUrl: string;
+    readonly exportName: string;
+};
+export type WasmWorkerHostOptions = {
+    readonly imports?: WebAssembly.Imports;
+    readonly fetch?: (input: RequestInfo | URL) => Promise<Response>;
+    readonly allowCrossOrigin?: boolean;
+    readonly streaming?: boolean;
+};
+export declare function serveWasmWorkerRuntime(scope: RuntimeMessageScope, options?: WasmWorkerHostOptions): () => void;