@arpabet/vrpc 0.2.0

package/README.md

@@ -0,0 +1,75 @@
+# @arpabet/vrpc
+
+value-rpc protocol core for browsers, Node ≥ 22, and Bun. Zero runtime
+dependencies. See the [repo README](../../README.md) for the full tour.
+
+```ts
+import { createClient } from "@arpabet/vrpc";
+
+const client = createClient({ url: "wss://example.com/rpc" });
+
+await client.call("greet", ["world"]);                    // unary
+for await (const v of client.getStream("count", [10])) {} // server stream
+await client.putStream("upload", null, values);           // client stream
+const chat = client.chat("chat.echo");                    // bidirectional
+
+client.addFunction("notify", (args) => null);             // server calls YOU
+```
+
+## Options (`createClient`)
+
+| Option | Default | Meaning |
+|---|---|---|
+| `url` | — | `ws://` / `wss://` endpoint |
+| `codec` | `"msgpack"` | `"msgpack"` works with every server; `"json"` needs a JSON-codec server (negotiated via the `vrpc.json` subprotocol) |
+| `auth` | — | credential (or async factory) for the handshake `auth` field |
+| `timeoutMs` | `5000` | default unary timeout, sent as the request SLA |
+| `connectTimeoutMs` | `10000` | dial + handshake bound |
+| `metadata` | — | `Metadata` or per-request factory (`traceparent`, …) |
+| `reconnect` | enabled | backoff options or `false` |
+| `resume` | `true` | hash-chain session resumption across reconnects |
+| `maxPending` | `4096` | per-stream receive window (flow-control credit) |
+| `dialect` | standard | wire field names; must match the server's `Dialect` |
+| `webSocket` / `dialer` | global / WS | overrides for tests and custom transports |
+
+## Error model
+
+Every failure is a `VrpcError` with a `code` mirroring `valuerpc.Code`:
+
+```ts
+try {
+  await client.call("user.get", [42]);
+} catch (err) {
+  if (err instanceof VrpcError && err.code === Code.Unavailable) retryLater();
+}
+```
+
+Timeouts map to `Code.DeadlineExceeded`, aborts to `Code.Canceled`,
+connection loss to `Code.Unavailable` — the same branches a Go caller writes
+with `valuerpc.CodeOf`.
+
+## Value model
+
+`null | boolean | number | bigint | string | Uint8Array | Value[] | {…} |
+VrpcDouble | VrpcDecimal | VrpcExt`
+
+- Integer `number`s encode as value LONG; beyond ±2^53 pass a `bigint`
+  (exact int64 over msgpack). `double(x)` forces a DOUBLE encoding.
+- `Uint8Array` is value RAW bytes.
+- Maps are plain objects; keys encode sorted (canonical frames).
+- `VrpcDecimal` (`decimal("1.045")`) and `VrpcExt` round-trip over msgpack.
+
+## Streams & flow control
+
+`getStream` returns an async iterator; **credit is granted to the server as
+you consume**, so a slow consumer backpressures the producer losslessly.
+`break`/`return` sends a `CancelRequest`. `putStream`/`chat.send` honor the
+credit the server grants — a misbehaving peer is cut off with
+`Code.ResourceExhausted`, exactly like the Go client.
+
+## Reverse calls
+
+The server can invoke functions and open streams on this client
+(`addFunction`, `addOutgoingStream`, `addIncomingStream`, `addChat`) — the
+same registrar surface `valueserver.Server` has. Handlers receive
+`(args, ctx)` where `ctx.signal` aborts on cancellation/disconnect.

package/dist/index.d.ts

@@ -0,0 +1,561 @@
+/**
+ * The TypeScript projection of the `go.arpabet.com/value` model.
+ *
+ * | value kind      | TypeScript                          |
+ * |-----------------|-------------------------------------|
+ * | NULL            | null (undefined encodes as null)    |
+ * | BOOL            | boolean                             |
+ * | NUMBER/LONG     | number (safe integers) or bigint    |
+ * | NUMBER/DOUBLE   | number (or VrpcDouble to force)     |
+ * | NUMBER/BIGINT   | bigint beyond int64                 |
+ * | NUMBER/DECIMAL  | VrpcDecimal                         |
+ * | STRING/UTF8     | string                              |
+ * | STRING/RAW      | Uint8Array                          |
+ * | LIST            | Array                               |
+ * | MAP             | plain object (string keys)          |
+ * | UNKNOWN (ext)   | VrpcExt                             |
+ */
+type Value = null | boolean | number | bigint | string | Uint8Array | VrpcDouble | VrpcDecimal | VrpcExt | Value[] | {
+    [key: string]: Value;
+};
+/** A string-keyed map value (the envelope shape). */
+type ValueMap = {
+    [key: string]: Value;
+};
+/**
+ * Forces a JS number to encode as a value DOUBLE (float64) even when it is
+ * integer-valued. Bare integer-valued numbers encode as LONG; use
+ * `double(42)` when the peer's handler verifies a DOUBLE argument.
+ */
+declare class VrpcDouble {
+    readonly value: number;
+    constructor(value: number);
+    valueOf(): number;
+    toString(): string;
+}
+/** Convenience constructor for {@link VrpcDouble}. */
+declare function double(value: number): VrpcDouble;
+/**
+ * An arbitrary-precision decimal: `coefficient * 10^exponent`, mirroring the
+ * shopspring/decimal representation used by value's NUMBER/DECIMAL kind.
+ * Round-trips through the msgpack codec (ext tag 2). The JSON codec cannot
+ * represent it (matching the Go-side asymmetry) and rejects it on encode.
+ */
+declare class VrpcDecimal {
+    readonly coefficient: bigint;
+    readonly exponent: number;
+    constructor(coefficient: bigint, exponent: number);
+    /** Parses "123", "-1.045", "1.2e-5" style decimal strings. */
+    static fromString(s: string): VrpcDecimal;
+    toString(): string;
+    toNumber(): number;
+    equals(other: VrpcDecimal): boolean;
+}
+/** Convenience constructor for {@link VrpcDecimal} from a decimal string. */
+declare function decimal(s: string): VrpcDecimal;
+/**
+ * An opaque msgpack extension value (value kind UNKNOWN): the ext tag plus its
+ * payload bytes. Preserved through both codecs so unrecognized extensions
+ * round-trip unchanged. The JSON form is the value-library convention
+ * `"data:application/x-msgpack-ext;base64,<tag byte + data, base64>"`.
+ */
+declare class VrpcExt {
+    readonly tag: number;
+    readonly data: Uint8Array;
+    constructor(tag: number, data: Uint8Array);
+    equals(other: VrpcExt): boolean;
+}
+
+/**
+ * MessagePack codec producing the canonical byte form of go.arpabet.com/value
+ * (see its CANONICAL.md): minimal integer family, doubles always float64,
+ * str/bin distinct, map keys sorted by UTF-8 byte order, BIGINT as ext tag 1
+ * (big.Int gob framing), DECIMAL as ext tag 2 (shopspring framing). Equal
+ * values therefore produce byte-identical frames on both sides of the wire.
+ */
+
+/** Decode limits mirroring value's limits.go defaults. */
+interface DecodeLimits {
+    maxDepth: number;
+    maxCollectionLen: number;
+    maxByteLen: number;
+}
+declare const DEFAULT_LIMITS: DecodeLimits;
+/** Encodes a single value in value's canonical MessagePack form. */
+declare function msgpackEncode(v: Value): Uint8Array;
+/** Decodes one value; throws on malformed, truncated, or oversized input. */
+declare function msgpackDecode(data: Uint8Array, limits?: DecodeLimits): Value;
+
+type CodecName = "msgpack" | "json";
+/**
+ * The wire codec seam (WEB.md §3.3): one envelope per WebSocket frame,
+ * msgpack in binary frames, JSON in text frames.
+ */
+interface WireCodec {
+    readonly name: CodecName;
+    /**
+     * Subprotocol offered on dial. msgpack offers none: "no subprotocol" IS the
+     * msgpack negotiation, and it keeps compatibility with servers that predate
+     * codec negotiation. JSON offers "vrpc.json" and requires the server to echo
+     * it (a server that does not support JSON fails the connect with a clear
+     * error instead of choking on text frames).
+     */
+    readonly subprotocols: string[];
+    readonly textFrames: boolean;
+    encode(msg: ValueMap): Uint8Array | string;
+    decode(data: Uint8Array | string): ValueMap;
+}
+declare function msgpackCodec(limits?: DecodeLimits): WireCodec;
+declare function jsonCodec(limits?: DecodeLimits): WireCodec;
+declare function codecByName(name: CodecName, limits?: DecodeLimits): WireCodec;
+
+/**
+ * Machine-readable RPC status, mirroring valuerpc.Code (a useful subset of
+ * gRPC status codes). Carried on the wire in ErrorResponse frames.
+ */
+declare enum Code {
+    OK = 0,
+    Unknown = 1,
+    Canceled = 2,
+    InvalidArgument = 3,
+    DeadlineExceeded = 4,
+    NotFound = 5,
+    ResourceExhausted = 6,
+    Unavailable = 7,
+    Unauthenticated = 8,
+    Internal = 9
+}
+declare function codeName(code: Code): string;
+/**
+ * A coded RPC error, mirroring *valuerpc.Error. Server-raised failures arrive
+ * with the server's code; client-local failures (timeout, connection loss,
+ * cancellation) use the matching local code so callers can branch on
+ * `err.code` the way Go callers branch on valuerpc.CodeOf(err).
+ */
+declare class VrpcError extends Error {
+    readonly code: Code;
+    readonly name = "VrpcError";
+    constructor(code: Code, message: string, options?: {
+        cause?: unknown;
+    });
+    /** The message without the "vrpc <Code>: " prefix. */
+    get detail(): string;
+}
+/** The Code carried by err: VrpcError's code, or Unknown for foreign errors. */
+declare function codeOf(err: unknown): Code;
+
+/** vRPC message types (wire numbering; 12/13 reserved). */
+declare enum MessageType {
+    HandshakeRequest = 0,
+    HandshakeResponse = 1,
+    FunctionRequest = 2,
+    FunctionResponse = 3,
+    GetStreamRequest = 4,
+    PutStreamRequest = 5,
+    ChatRequest = 6,
+    ErrorResponse = 7,
+    StreamReady = 8,
+    StreamValue = 9,
+    StreamEnd = 10,
+    CancelRequest = 11,
+    StreamCredit = 14
+}
+/**
+ * Dialect names the wire-level fields and markers of the vRPC envelope,
+ * mirroring valuerpc.Dialect. Both peers MUST share the same dialect.
+ * Override fields only if your Go deployment installed a custom Dialect.
+ */
+interface Dialect {
+    magic: string;
+    version: number;
+    handshakeRequestId: number;
+    messageTypeField: string;
+    magicField: string;
+    versionField: string;
+    requestIdField: string;
+    timeoutField: string;
+    clientIdField: string;
+    sessionTokenField: string;
+    authField: string;
+    functionNameField: string;
+    argumentsField: string;
+    resultField: string;
+    errorField: string;
+    codeField: string;
+    creditField: string;
+    metadataField: string;
+    valueField: string;
+}
+/** The standard vRPC dialect (the default wire format). */
+declare function newDialect(): Dialect;
+type Metadata = Record<string, string>;
+/** Envelope builders and field accessors bound to one dialect. */
+declare class Protocol {
+    readonly d: Dialect;
+    constructor(d: Dialect);
+    handshakeRequest(clientId: number, token: string, auth: Value | undefined): ValueMap;
+    request(mt: MessageType, requestId: number, name: string, args: Value | undefined, timeoutMs: number, metadata: Metadata | undefined): ValueMap;
+    functionResult(requestId: number, result: Value): ValueMap;
+    errorResponse(requestId: number, code: Code, message: string): ValueMap;
+    streamReady(requestId: number): ValueMap;
+    streamValue(requestId: number, value: Value): ValueMap;
+    streamEnd(requestId: number, value?: Value): ValueMap;
+    streamCredit(requestId: number, credit: number): ValueMap;
+    cancelRequest(requestId: number): ValueMap;
+    messageType(msg: ValueMap): MessageType | undefined;
+    requestId(msg: ValueMap): number | undefined;
+    functionName(msg: ValueMap): string | undefined;
+    args(msg: ValueMap): Value;
+    result(msg: ValueMap): Value;
+    streamVal(msg: ValueMap): Value;
+    credit(msg: ValueMap): number | undefined;
+    errorOf(msg: ValueMap): {
+        code: Code;
+        message: string;
+    };
+    metadata(msg: ValueMap): Metadata | undefined;
+}
+
+/**
+ * One established message connection. Deliberately tiny (WEB.md §7): a future
+ * WebTransport implementation slots in without touching the protocol layer.
+ */
+interface Transport {
+    send(data: Uint8Array | string): void;
+    close(): void;
+    onMessage: ((data: Uint8Array | string) => void) | null;
+    /** Fired exactly once, for both clean and failed closes. */
+    onClose: ((err?: Error) => void) | null;
+}
+interface DialOptions {
+    url: string;
+    subprotocols: string[];
+    timeoutMs: number;
+    /** Override the WebSocket constructor (tests, custom agents). */
+    webSocket?: typeof WebSocket;
+}
+type Dialer = (opts: DialOptions) => Promise<Transport>;
+/** Dials a WebSocket and resolves once the connection is open. */
+declare const webSocketDialer: Dialer;
+
+type Status = "idle" | "connecting" | "open" | "resuming" | "closed";
+interface ReconnectOptions {
+    /** Re-establish dropped connections automatically. Default true. */
+    enabled?: boolean;
+    /** First backoff delay. Default 300 ms. */
+    initialDelayMs?: number;
+    /** Backoff cap. Default 10 000 ms. */
+    maxDelayMs?: number;
+    /** Give up after this many consecutive failed attempts. Default Infinity. */
+    maxAttempts?: number;
+    /** Equal jitter (half fixed, half random), like the Go client. Default true. */
+    jitter?: boolean;
+}
+interface ClientOptions {
+    /** WebSocket endpoint, e.g. "wss://example.com/rpc". */
+    url: string;
+    /**
+     * Wire codec. "msgpack" (default) speaks to every value-rpc server —
+     * binary frames, no subprotocol. "json" offers the "vrpc.json" subprotocol
+     * and requires a server with JSON codec support (WEB.md phase 1).
+     */
+    codec?: CodecName | WireCodec;
+    /**
+     * Credential for the handshake `auth` field, validated by the server's
+     * Authenticator. A function is re-evaluated on every (re)connect, so
+     * refreshed tokens are picked up automatically.
+     */
+    auth?: Value | (() => Value | Promise<Value>);
+    /** Default unary timeout / request SLA in ms. Default 5000. */
+    timeoutMs?: number;
+    /** Dial + handshake timeout in ms. Default 10 000. */
+    connectTimeoutMs?: number;
+    /** Metadata attached to every request (static or per-request factory). */
+    metadata?: Metadata | ((name: string) => Metadata | undefined);
+    reconnect?: boolean | ReconnectOptions;
+    /**
+     * Hash-chain session resumption (default true): reconnects present a
+     * one-time token proving continuity, so the server reattaches the session.
+     * When disabled, every connection is a fresh session with a fresh clientId.
+     */
+    resume?: boolean;
+    /** Resumption chain length = max reconnects per session. Default 1024. */
+    chainLength?: number;
+    /** Per-stream receive window (flow-control credit). Default 4096. */
+    maxPending?: number;
+    /** Wire dialect overrides; must match the server's Dialect. */
+    dialect?: Partial<Dialect>;
+    /** WebSocket constructor override (tests, custom agents). */
+    webSocket?: typeof WebSocket;
+    /** Transport override (in-memory tests, future WebTransport). */
+    dialer?: Dialer;
+}
+interface CallOptions {
+    /** Per-call timeout in ms; also sent to the server as the request SLA. */
+    timeoutMs?: number;
+    /** Abort maps to a vRPC CancelRequest toward the server. */
+    signal?: AbortSignal;
+    metadata?: Metadata;
+}
+/** A server->client stream (getStream): pull-based, credit-backed. */
+interface VrpcStream extends AsyncIterableIterator<Value> {
+    readonly requestId: number;
+    /** Resolves when the server acks the stream (StreamReady). */
+    readonly ready: Promise<void>;
+    /** Cancels the stream (sends CancelRequest); the iterator ends. */
+    cancel(): void;
+}
+/** A bidirectional stream (chat). */
+interface VrpcChat extends AsyncIterable<Value> {
+    readonly requestId: number;
+    readonly ready: Promise<void>;
+    readonly incoming: AsyncIterableIterator<Value>;
+    /** Sends one value; awaits flow-control credit from the peer. */
+    send(v: Value): Promise<void>;
+    /** Half-closes our sending side (StreamEnd); receiving continues. */
+    end(): void;
+    /** Tears the whole chat down (CancelRequest). */
+    cancel(): void;
+}
+interface HandlerContext {
+    readonly requestId: number;
+    readonly metadata: Metadata | undefined;
+    /** Aborted when the peer cancels the request or the connection drops. */
+    readonly signal: AbortSignal;
+}
+type UnaryHandler = (args: Value, ctx: HandlerContext) => Value | Promise<Value>;
+type OutgoingStreamHandler = (args: Value, ctx: HandlerContext) => Iterable<Value> | AsyncIterable<Value> | Promise<Iterable<Value> | AsyncIterable<Value>>;
+type IncomingStreamHandler = (args: Value, incoming: AsyncIterableIterator<Value>, ctx: HandlerContext) => void | Promise<void>;
+type ChatHandler = (args: Value, incoming: AsyncIterableIterator<Value>, ctx: HandlerContext) => Iterable<Value> | AsyncIterable<Value> | Promise<Iterable<Value> | AsyncIterable<Value>>;
+interface ClientEvents {
+    status: (status: Status) => void;
+    /** Fired per successful handshake with the server's handshake response. */
+    open: (handshake: ValueMap) => void;
+    close: () => void;
+    /** Non-fatal protocol anomalies (unroutable or malformed frames). */
+    error: (err: Error) => void;
+}
+/**
+ * A value-rpc client over WebSocket. Symmetric peer: it calls the server
+ * (call / getStream / putStream / chat) and serves the server's reverse
+ * calls (addFunction / addOutgoingStream / addIncomingStream / addChat).
+ */
+declare class VrpcClient {
+    readonly protocol: Protocol;
+    private readonly codec;
+    private readonly opts;
+    private readonly reconnect;
+    private readonly timeoutMs;
+    private readonly connectTimeoutMs;
+    private readonly maxPending;
+    private readonly dialer;
+    private _status;
+    private _clientId;
+    private transport;
+    private chain;
+    private established;
+    private nextRequestId;
+    private reconnects;
+    private pending;
+    private serving;
+    private handlers;
+    private listeners;
+    private connectPromise;
+    private resumeAbort;
+    private openWaiters;
+    private handshakeWaiter;
+    private handshakeTransport;
+    private hintsInstalled;
+    constructor(options: ClientOptions);
+    get status(): Status;
+    get connected(): boolean;
+    get clientId(): number;
+    get codecName(): CodecName;
+    stats(): {
+        requests: number;
+        reconnects: number;
+        pending: number;
+        serving: number;
+    };
+    on<E extends keyof ClientEvents>(event: E, fn: ClientEvents[E]): () => void;
+    private emit;
+    private setStatus;
+    /** Connects (idempotent). Calls also auto-connect on first use. */
+    connect(): Promise<void>;
+    private handshakeToken;
+    private doConnect;
+    /** Waits until the client is open, connecting if idle. */
+    private ensureOpen;
+    private onTransportClose;
+    private resumeLoop;
+    /** Browser wake hints: retry immediately when connectivity likely returned. */
+    private installBrowserHints;
+    private failAllInFlight;
+    /** Closes the client permanently. */
+    close(): void;
+    private sendFrame;
+    private trySendFrame;
+    cancelRequest(requestId: number): void;
+    private buildMetadata;
+    /** Calls a unary function on the server. */
+    call(name: string, args?: Value, opts?: CallOptions): Promise<Value>;
+    /**
+     * Opens a server->client stream. Consume with `for await`; breaking out of
+     * the loop cancels the stream. Credit is granted as values are consumed, so
+     * a slow consumer applies real backpressure to the server.
+     */
+    getStream(name: string, args?: Value, opts?: CallOptions): VrpcStream;
+    private openConsumingStream;
+    private establishStream;
+    private retireGetSide;
+    /**
+     * Opens a client->server stream and sends every value from source, honoring
+     * the server's flow-control credit. Resolves once the stream ended cleanly.
+     */
+    putStream(name: string, args: Value | undefined, source: Iterable<Value> | AsyncIterable<Value>, opts?: CallOptions): Promise<void>;
+    /** Opens a bidirectional stream (chat). */
+    chat(name: string, args?: Value, opts?: CallOptions): VrpcChat;
+    /** Registers a unary function the server may call on this client. */
+    addFunction(name: string, fn: UnaryHandler): void;
+    /** Registers a stream the server can consume from this client (GetStream). */
+    addOutgoingStream(name: string, fn: OutgoingStreamHandler): void;
+    /** Registers a stream the server can send to this client (PutStream). */
+    addIncomingStream(name: string, fn: IncomingStreamHandler): void;
+    /** Registers a bidirectional stream the server can open (Chat). */
+    addChat(name: string, fn: ChatHandler): void;
+    removeHandler(name: string): void;
+    private onFrame;
+    private processResponse;
+    private handlerCtx;
+    private serveInboundCall;
+    private serveInboundStream;
+    private serveRunning;
+}
+/** Creates a {@link VrpcClient}. The client connects lazily on first call. */
+declare function createClient(options: ClientOptions): VrpcClient;
+
+/**
+ * JSON codec per WEB.md §3.1 — the value library's existing JSON conventions:
+ *
+ * - raw bytes      <-> "base64,<standard base64, no padding>"
+ * - msgpack ext    <-> "data:application/x-msgpack-ext;base64,<tag+data>"
+ * - NaN / ±Inf     ->  null (decode never produces them)
+ * - map keys       ->  sorted by UTF-8 byte order (canonical, deterministic)
+ * - integers       ->  plain JSON numbers; throws beyond ±2^53 on encode
+ * - bigint         ->  encoded as a number when within ±2^53, else rejected
+ *                      (the wire cannot carry it exactly; use msgpack)
+ * - VrpcDecimal    ->  rejected on encode (does not round-trip through JSON)
+ *
+ * Known hazard inherited from the convention: a *string* that genuinely starts
+ * with "base64," or "data:application/x-msgpack-ext;" is indistinguishable
+ * from encoded bytes/ext and will decode as such.
+ */
+
+/** Serializes a value to canonical JSON text (sorted keys). */
+declare function jsonEncode(v: Value): string;
+/** Parses JSON text into a value, applying the string-prefix conventions. */
+declare function jsonDecode(text: string, limits?: DecodeLimits): Value;
+
+/**
+ * Client-held reverse hash chain (S/KEY style) for replay-resistant session
+ * resumption, mirroring valuerpc.HashChain:
+ *
+ *   seed = h[0],  h[i] = SHA-256(h[i-1]),  anchor = h[N]
+ *
+ * The anchor is presented (hex) in the first handshake's `tok` field; each
+ * reconnect reveals the next pre-image in reverse order. The chain always
+ * advances — even when a handshake is lost — and the server self-heals by
+ * hashing forward (its resync window), so a link is never revealed twice.
+ *
+ * Browser-sized default: 1024 links (~1024 awaited SHA-256 digests at build
+ * time, milliseconds) bounds reconnects per session; an exhausted chain makes
+ * the client start a fresh session (new clientId + new chain).
+ */
+declare class HashChain {
+    private readonly links;
+    private next;
+    private constructor();
+    static readonly DEFAULT_LENGTH = 1024;
+    static create(n?: number): Promise<HashChain>;
+    /** The public commitment h[N], hex-encoded. Resending it consumes nothing. */
+    anchor(): string;
+    /**
+     * Reveals the next one-time resumption token and advances. Returns "" when
+     * the chain is exhausted and a fresh session is required.
+     */
+    nextToken(): string;
+    remaining(): number;
+}
+
+/**
+ * Typed calls without codegen — the TS analogue of valuerpc.Codec[T] /
+ * CallUnary. Describe your API as an interface and get compile-time checked
+ * method names, argument tuples, and result types:
+ *
+ * ```ts
+ * interface Api {
+ *   "user.get":    { args: [id: number]; result: User };
+ *   "events.tail": { args: [topic: string]; stream: OrderEvent };
+ *   "logs.upload": { args: []; put: string };
+ *   "support.chat": { args: [ticket: number]; in: Message; out: string };
+ * }
+ * const api = typedClient<Api>(client);
+ * const user = await api.call("user.get", [42]);
+ * for await (const ev of api.getStream("events.tail", ["orders"])) { ... }
+ * ```
+ */
+
+interface UnaryShape {
+    args: Value[];
+    result: unknown;
+}
+interface GetStreamShape {
+    args: Value[];
+    stream: unknown;
+}
+interface PutStreamShape {
+    args: Value[];
+    put: unknown;
+}
+interface ChatShape {
+    args: Value[];
+    in: unknown;
+    out: unknown;
+}
+type ApiShape = Record<string, UnaryShape | GetStreamShape | PutStreamShape | ChatShape>;
+type UnaryNames<A extends ApiShape> = {
+    [K in keyof A]: A[K] extends UnaryShape ? K : never;
+}[keyof A];
+type GetNames<A extends ApiShape> = {
+    [K in keyof A]: A[K] extends GetStreamShape ? K : never;
+}[keyof A];
+type PutNames<A extends ApiShape> = {
+    [K in keyof A]: A[K] extends PutStreamShape ? K : never;
+}[keyof A];
+type ChatNames<A extends ApiShape> = {
+    [K in keyof A]: A[K] extends ChatShape ? K : never;
+}[keyof A];
+interface TypedStream<T> extends AsyncIterableIterator<T> {
+    readonly requestId: number;
+    readonly ready: Promise<void>;
+    cancel(): void;
+}
+interface TypedChat<TIn, TOut> extends AsyncIterable<TIn> {
+    readonly requestId: number;
+    readonly ready: Promise<void>;
+    readonly incoming: AsyncIterableIterator<TIn>;
+    send(v: TOut): Promise<void>;
+    end(): void;
+    cancel(): void;
+}
+interface TypedClient<A extends ApiShape> {
+    call<K extends UnaryNames<A>>(name: K, args: A[K] extends UnaryShape ? A[K]["args"] : never, opts?: CallOptions): Promise<A[K] extends UnaryShape ? A[K]["result"] : never>;
+    getStream<K extends GetNames<A>>(name: K, args: A[K] extends GetStreamShape ? A[K]["args"] : never, opts?: CallOptions): TypedStream<A[K] extends GetStreamShape ? A[K]["stream"] : never>;
+    putStream<K extends PutNames<A>>(name: K, args: A[K] extends PutStreamShape ? A[K]["args"] : never, source: A[K] extends PutStreamShape ? Iterable<A[K]["put"]> | AsyncIterable<A[K]["put"]> : never, opts?: CallOptions): Promise<void>;
+    chat<K extends ChatNames<A>>(name: K, args: A[K] extends ChatShape ? A[K]["args"] : never, opts?: CallOptions): TypedChat<A[K] extends ChatShape ? A[K]["in"] : never, A[K] extends ChatShape ? A[K]["out"] : never>;
+    readonly client: VrpcClient;
+}
+/** Wraps a client with a compile-time-typed API surface (zero runtime cost). */
+declare function typedClient<A extends ApiShape>(client: VrpcClient): TypedClient<A>;
+
+export { type ApiShape, type CallOptions, type ChatHandler, type ClientEvents, type ClientOptions, Code, type CodecName, DEFAULT_LIMITS, type DecodeLimits, type DialOptions, type Dialect, type Dialer, type HandlerContext, HashChain, type IncomingStreamHandler, MessageType, type Metadata, type OutgoingStreamHandler, Protocol, type ReconnectOptions, type Status, type Transport, type TypedChat, type TypedClient, type TypedStream, type UnaryHandler, type Value, type ValueMap, type VrpcChat, VrpcClient, VrpcDecimal, VrpcDouble, VrpcError, VrpcExt, type VrpcStream, type WireCodec, codeName, codeOf, codecByName, createClient, decimal, double, jsonCodec, jsonDecode, jsonEncode, msgpackCodec, msgpackDecode, msgpackEncode, newDialect, typedClient, webSocketDialer };