@runic-artifex/views

A failure or terminal event the Views runtime observed.

type BridgeDiagnosticListener = (diagnostic: BridgeDiagnostic) => void;

No documentation.

A Bridge call that .NET or the transport did not complete.

type BridgeErrorKind = "rejected" | "cancelled" | "failed" | "disconnected" | "timeout" | "unavailable";

Why a Bridge call did not complete. unavailable means no host installed window.__runicBridge; timeout means a Bridge exists but did not connect in time.

function bridgeFailure<TFailure>(failure: TFailure): BridgeOutcome<never, TFailure>;

An outcome with the declared failure.

Local failure detail that .NET adds to an error reply only in development (host environment Development, or BridgeDiagnostics.IncludeFailureDetail).

A recoverable .NET command execution identified by its request id.

type BridgeOperationCancelKind = "cancellation-requested" | "not-running" | "unknown" | "expired";

No documentation.

Why a completed operation's result or failure could not be delivered.

type BridgeOperationDeliveryKind = "result-too-large" | "result-encoding-failed" | "stream-overflow" | "stream-retention-too-large";

No documentation.

type BridgeOperationStatus<TResult = void, TFailure = never> = [
    TFailure
] extends [
    never
] ? Exclude<BridgeOperationStatusOf<TResult, never>, {
    readonly kind: "domain-failed";
}> : BridgeOperationStatusOf<TResult, TFailure>;

The status of an operation, discriminated by kind. An operation that declares no failure type never reports domain-failed.

type BridgeOperationStatusKind = "running" | "succeeded" | "domain-failed" | "failed" | "cancelled" | "expired" | "unknown" | "timedOut";

domain-failed means the command failed with its declared failure type. timedOut is a client-side terminal state: wait({ timeout }) passed its deadline and sent a cancellation request. .NET never reports it.

type BridgeOperationStatusOf<TResult, TFailure> = BridgeOperationIdentity & {
    readonly kind: "running";
} | BridgeOperationIdentity & {
    readonly kind: "succeeded";
    readonly result?: TResult;
    readonly delivery?: BridgeOperationDelivery;
    readonly stream?: true;
} | BridgeOperationIdentity & {
    readonly kind: "domain-failed";
    readonly failure?: TFailure;
    readonly delivery?: BridgeOperationDelivery;
    readonly stream?: true;
} | BridgeOperationIdentity & {
    readonly kind: "failed";
    readonly error: {
        readonly kind: "failed";
        readonly message: string;
        readonly detail?: BridgeFailureDetail;
    };
    readonly stream?: true;
} | BridgeOperationIdentity & {
    readonly kind: "cancelled" | "expired" | "unknown";
    readonly stream?: true;
} | BridgeOperationIdentity & {
    readonly kind: "timedOut";
    readonly cancellation: BridgeOperationCancelKind | "unobserved";
};

Every operation status, including domain-failed. Generic code that builds statuses uses this type; applications read BridgeOperationStatus.

The client could not observe whether .NET admitted or completed an operation.

type BridgeOutcome<TValue, TFailure> = {
    readonly ok: true;
    readonly value: TValue;
    readonly [outcomeBrand]: true;
} | {
    readonly ok: false;
    readonly failure: TFailure;
    readonly [outcomeBrand]: true;
};

How a command or operation that declares a failure type ended: ok with its value, or not ok with the declared failure. Unexpected failures still reject with BridgeError.

type BridgeOutcomeFailure<T> = [
    OutcomeOf<T>
] extends [
    never
] ? never : OutcomeOf<T> extends {
    readonly failure: infer F;
} ? F : never;

The declared failure type of a command result: F for a BridgeOutcome<_, F>, otherwise never.

An operation whose command yields a stream of TItem values, read through stream(). Its status and outcome() carry no value, so it is a BridgeOperation<void, TFailure>.

function bridgeSuccess<TValue>(value: TValue): BridgeOutcome<TValue, never>;

A successful outcome with value.

function collectionViewport(options: {
    readonly totalCount: number;
    readonly scrollTop: number;
    readonly height: number;
    readonly rowHeight: number;
    readonly overscan?: number;
}): CollectionViewport;

Computes a bounded viewport for fixed-height rows in any web framework.

Follows a scroll container and publishes its CollectionViewport. Framework bindings attach their element and pass the current row count.

The list a viewport controller measures: its row count, fixed row height and overscan.

Runs a command and tracks whether it is pending and why it last failed.

One consistent reading of a CommandController.

function createCollectionViewportController(options: CollectionViewportOptions): CollectionViewportController;

Creates the framework-neutral viewport tracker behind each binding's useCollectionViewport. Scroll events are coalesced to one measurement per animation frame, and a ResizeObserver follows the container's height. current only changes when the requested range or sizes change.

function createCommandController<TArgs extends readonly unknown[], TReturn>(command: (...args: TArgs) => TReturn): CommandController<TArgs, Awaited<TReturn>, BridgeOutcomeFailure<Awaited<TReturn>>>;

Creates the framework-neutral command runner behind useCommand and injectCommand. The command may return a plain value or undefined, for example () => client?.increment() while the client is still connecting. It may also return one of several commands' promises, such as name => name === "save" ? client.save() : client.discard(); the result is then their union and failure the union of their declared failures.

function createViewController<TClient extends ViewClient>(options?: ViewControllerOptions<TClient>): ViewController<TClient>;

Creates the framework-neutral controller behind useView and injectView.

type FieldBaseline<T> = {
    readonly value: T;
    readonly version: number;
};

No documentation.

type FieldWriteOptions<T> = {
    readonly requestId: string;
    readonly baseline: FieldBaseline<T>;
};

No documentation.

type FieldWriteReceipt<T> = {
    readonly kind: "applied";
    readonly snapshot: FieldBaseline<T>;
    readonly validation?: string;
} | {
    readonly kind: "committed-with-error";
    readonly snapshot: FieldBaseline<T>;
    readonly message: string;
} | {
    readonly kind: "rejected";
    readonly message: string;
} | {
    readonly kind: "conflict";
    readonly incoming: FieldBaseline<T>;
    readonly message: string;
};

No documentation.

function isBridgeOutcome(value: unknown): value is BridgeOutcome<unknown, unknown>;

True for an outcome created by bridgeSuccess or bridgeFailure, including by another copy of this package.

function isViewClient<TClient extends ViewClient>(source: ViewConnector<TClient> | TClient): source is TClient;

True for a connected client; false for a connector.

function matchCase<F extends {
    readonly $case: string;
}, H extends {
    readonly [K in F["$case"]]: (value: Extract<F, {
        readonly $case: K;
    }>) => unknown;
}>(value: F, cases: H): ReturnType<H[F["$case"]]>;

Handles every case of a $case union, such as a declared failure:

const message = matchCase(outcome.failure, {
  titleRequired: () => "A note needs a title.",
  titleTaken: failure => `"${failure.existingTitle}" exists.`,
});

A missing handler is a type error. The result is the union of the handlers' return types.

function onBridgeDiagnostic(listener: BridgeDiagnosticListener): () => void;

Observes Views runtime failures: failed routes (with their .NET detail in development), a missing or unconnected Bridge, operation timeouts and errors the runtime caught from listeners. The Vite plugin forwards these to the Runic DevTools dock. Returns a function that stops observing.

The host-neutral Bridge a host script installs as window.__runicBridge.

The framework-neutral surface every generated client shares.

Anything that connects a client: a generated page reference or { connect: connect<Name> }.

The connect, observe and release state machine that every framework binding shares. A binding feeds it the current source and renders current.

One consistent reading of a ViewController. A new object is published for every change.

A generated content reference: a logical .NET View presented in a ViewModel slot.

type ViewSource<TClient extends ViewClient> = ViewConnector<TClient> | TClient | null | undefined;

What a framework binding follows. A connector is connected and released by the binding; an already connected client is only observed, and its owner disposes it.

function viewSourceIdentity<TClient extends ViewClient>(source: ViewSource<TClient>): object | undefined;

The identity a binding compares to decide whether a source changed: the client itself or the connect function.

function waitForBridge(timeoutMilliseconds?: number): Promise<RunicBridgeClient>;
function waitForBridge(options?: WaitForBridgeOptions): Promise<RunicBridgeClient>;

Waits for the installed host Bridge to report a connection to .NET. Rejects with an unavailable BridgeError when no host installed window.__runicBridge, and with a timeout BridgeError when it did not connect in time.

Generated item codecs and stable keys for an incremental state collection.

The keyed collections of one generated client, passed to connectView as collections. A View without keyed collections does not bundle this code.

type BridgeInteractions = (scope: InteractionScope) => InteractionSession;

The interactions of one generated client, passed to connectView as interactions. A View without interactions does not bundle this code.

type BridgeOperationRuntimeHandle<TResult, TFailure> = BridgeOperation<TResult, TFailure> & BridgeStreamOperation<TResult, TFailure>;

What the runtime returns for a started or recovered operation: either handle shape.

const bridgeOperations: BridgeOperations;

No documentation.

The operation protocol, passed to connectView as operations by a generated client with operations. A View without operations does not bundle it. decodeFailure is given for an operation that declares a failure type.

function connectView<TState>(options: ViewConnectOptions<TState>): Promise<ViewConnection<TState>>;

Connects one generated client lease to its route. Leases of one route share a single snapshot, push callback and revision; each lease has its own listeners, mount token and interaction handlers.

function decodeBridgeValidation(value: unknown): BridgeValidationState;

Decodes the validation state of a ViewModel with validation.

function defineCollection<T>(decode: (wire: unknown) => T, key: (item: T) => string): BridgeCollectionDefinition;

Keeps collection codecs typed in generated clients.

function defineCollections(definitions: Readonly<Record<string, BridgeCollectionDefinition>>): BridgeCollections;

Binds the collection codecs of a generated client to the code that applies their changes.

function defineInteractions(definitions: Readonly<Record<string, InteractionDefinition>>): BridgeInteractions;

Binds the interaction codecs of a generated client to the interaction protocol.

Generated codec and contract of one ReactiveUI interaction.

The connection one presentation's interaction handlers run in.

The interaction handlers of one connected presentation.

The connection an operation starts on.

The runtime half of a generated client. Generated code is its only intended caller.

How a generated module connects one ViewModel route.

function viewReferences<R extends object>(create: (id: string) => R): (id: string) => R;

Returns a per-module cache of content references. A reference stays the same object while it is reachable, so frameworks can key Views by identity.

function array<T>(value: unknown, decode: (item: unknown) => T): readonly T[];

No documentation.

function decodeBigInt(value: unknown, minimum?: string, maximum?: string): bigint;

No documentation.

function decodeBoolean(value: unknown): boolean;

No documentation.

function dateOnly(value: unknown): string;

No documentation.

function dateTime(value: unknown): string;

No documentation.

function dateTimeOffset(value: unknown): string;

No documentation.

function decimal(value: unknown): string;

No documentation.

function duration(value: unknown): string;

No documentation.

function encodeUnion(value: unknown): Record<string, unknown>;

No documentation.

function enumName<T extends string = string>(value: unknown, names?: readonly T[]): T;

No documentation.

function finiteNumber(value: unknown): number;

No documentation.

function guid(value: unknown): string;

No documentation.

function int64String(value: unknown): string;

No documentation.

function integer(value: unknown, minimum: number, maximum: number): number;

No documentation.

function decodeObject<T>(value: unknown, decode: (item: Record<string, unknown>) => T): T;

No documentation.

function decodeString(value: unknown): string;

No documentation.

function stringRecord<T>(value: unknown, decode: (item: unknown) => T): Readonly<Record<string, T>>;

No documentation.

function timeOnly(value: unknown): string;

No documentation.

function union(value: unknown): any;

No documentation.

function createMockBridge(options?: MockBridgeOptions): MockBridge;

No documentation.

function installMockBridge(bridge?: MockBridge): MockBridge;

Installs a mock as window.__runicBridge, so generated clients connect to it instead of waiting for a .NET host. Call it before the first connect*().

An in-memory __runicBridge that answers generated-client routes without .NET.

function mockBridgeInternals(bridge: MockBridge): MockBridgeInternals;

No documentation.

Internal hooks the generated typed mocks use. Not part of the public API.

Edits one keyed collection of a mock View and pushes each edit as a delta frame, like a .NET [RunicCollection]. Inside MockView.batch the edits share one frame.

One keyed collection edit of a delta frame, as .NET writes it.

type MockCommandHandler<TState, TArgs extends readonly unknown[] = [
]> = (state: TState, ...args: TArgs) => Awaitable<Patch<TState> | void>;

Runs a command and returns the state changes it makes. A thrown error becomes the client's BridgeError; throw mockFailure(failure) resolves the client's outcome with the declared failure.

A declared failure (domain-failed) the mock answers instead of running a handler. A command replies with it; a Start{Command} admits an operation that has already failed with it.

An unexpected failure the mock answers instead of running a handler.

function mockFailure<TFailure>(failure: TFailure, message?: string): Error;

An error that a mock command or operation handler throws to fail with its declared failure: throw mockFailure({ $case: "titleRequired" }).

type MockFailure = MockErrorFailure | MockDomainFailure;

A failure the mock answers instead of running a handler.

function mockFailureOf(error: unknown): {
    readonly failure: unknown;
} | undefined;

No documentation.

type MockFailureOf<TMethod> = TMethod extends (...args: never[]) => Promise<infer R> ? R extends {
    outcome(...args: never[]): Promise<infer O>;
} ? BridgeOutcomeFailure<O> : BridgeOutcomeFailure<R> : never;

The declared failure type of a client method: F for a command that resolves BridgeOutcome<_, F> or a start{Command} whose operation declares F.

type MockInteractionReply = {
    readonly kind: "answered";
    readonly output: unknown;
} | {
    readonly kind: "cancelled";
} | {
    readonly kind: "failed";
} | {
    readonly kind: "unhandled";
};

How the browser answered an interaction request.

type MockMethodName<TClient> = Exclude<keyof TClient & string, "snapshot" | "subscribe" | "dispose" | "interactions" | "fieldBaseline" | `recover${string}` | `${string}WithRequestId`>;

A client method name a failure can target, such as save, startSave, setTitle or canSetViewport.

An operation a client started with start{Command}().

type MockOperationHandler = (state: MockState, input: unknown, operation: MockOperation) => MockOperationOutcome | void | Promise<MockOperationOutcome | void>;

Runs a started operation. When the returned promise resolves, a still running operation succeeds with its outcome; a throw fails it, or cancels it after the client asked to cancel, and throw mockFailure(failure) ends it domain-failed. Cancellation is cooperative, as in .NET: a cancel request aborts operation.signal, and the operation keeps running until its handler stops. "manual" leaves every operation running until the test settles it through MockView.operations().

type MockOperationKind = "running" | "succeeded" | "domain-failed" | "failed" | "cancelled";

No documentation.

What an operation handler's completion means.

The wire form of a content reference in a mock state, such as { kind: "editor", id: "1" }.

The mock's internal state of one View route.

type MockRoute = (state: MockState, ...args: unknown[]) => MockState | boolean | string | void | Promise<MockState | boolean | string | void>;

Answers one route suffix of a mock View. A returned object is merged into the state, a boolean answers a Can{Command} query, and a string is the raw reply. A thrown error becomes a failed reply with its type, message and stack as detail; an error with a kind keeps that kind. throw mockFailure(failure) replies with a declared failure (domain-failed).

type MockScheduling = "immediate" | "manual";

When the mock delivers replies and pushed states. immediate (the default) answers each call as soon as its handler returns and pushes synchronously. manual queues calls and pushes until flush(), flushUntil() or advance(), so a test decides exactly when the client observes each one.

type MockSetterHandler<TState, TValue> = (state: TState, value: TValue) => Awaitable<Patch<TState> | void>;

Runs before a setter or checked write applies value. Return more state changes, such as a dirty flag; throw to reject the value.

type MockState = Record<string, unknown>;

A wire state as .NET serializes it, without revision.

A keyed collection of a typed mock. Each edit pushes a delta frame.

An interaction that .NET asks the browser to handle.

An operation that a client started with start{Command}(), with typed input and results.

type MockTypedOperationHandler<TState, TInput, TResult, TFailure = never> = (state: TState, input: TInput, operation: MockTypedOperation<TInput, TResult, TFailure>) => Awaitable<MockTypedOperationOutcome<TState, TResult> | void>;

Runs a started operation. When it returns, a still running operation succeeds with the outcome; a throw fails it, and throw mockFailure(failure) ends it with its declared failure. Return a promise that waits on the operation's signal, or use "manual", to settle it from the test.

function mockTypedView(bridge: MockBridge, spec: MockTypedViewSpec, definition: MockTypedViewDefinition): unknown;

Registers a typed mock View. Generated mock{Name}() helpers call this with their client's codecs; applications call the generated helper.

The typed mock of one generated client, created by a generated mock{Name}().

The loose shape of a generated mock definition.

What a generated mock{Name}() knows about its client. Generated code is its only intended caller.