@trevrpc/trevrpc-js 1.3.2 → 1.5.0

package/src/index.d.ts

@@ -2,8 +2,138 @@ import type { INamespace, Root } from "protobufjs";
 
 export const protobuf: typeof import("protobufjs");
 
+/**
+ * How decoded messages represent 64-bit integer fields: `bigint`, `number` (exact up to 2^53),
+ * decimal `string`, or protobuf.js's `long` (a Long object). 64-bit map keys are decimal strings
+ * in every representation.
+ */
+export type Int64Representation = "bigint" | "number" | "string" | "long";
+
+export interface CreateRootOptions {
+  /**
+   * How calls decode the 64-bit integers of the root's messages; a field's `jstype` option
+   * (`JS_STRING` or `JS_NUMBER`) overrides it. Without it they stay Long objects. Generated code
+   * passes the generator's `int64` option.
+   */
+  int64?: Int64Representation;
+}
+
 /** Creates a protobuf root from a JSON namespace definition. */
-export function createRoot(json: INamespace): Root;
+export function createRoot(json: INamespace, options?: CreateRootOptions): Root;
+
+/** A 64-bit integer in any representation, including a Long. */
+type Int64Value = bigint | number | string | { low: number; high: number; unsigned?: boolean };
+
+/** A decoded google.protobuf.Timestamp message. */
+export interface Timestamp {
+  seconds: bigint;
+  nanos: number;
+}
+
+/** A google.protobuf.Timestamp message to send. */
+export interface TimestampInit {
+  seconds?: bigint | number | string;
+  nanos?: number;
+}
+
+/** A decoded google.protobuf.Duration message. */
+export interface Duration {
+  seconds: bigint;
+  nanos: number;
+}
+
+/** A google.protobuf.Duration message to send. */
+export interface DurationInit {
+  seconds?: bigint | number | string;
+  nanos?: number;
+}
+
+/** A decoded google.protobuf.Empty message. */
+export interface Empty {}
+
+/** A google.protobuf.Empty message to send. */
+export interface EmptyInit {}
+
+/** Values of the google.protobuf.NullValue enum. */
+export const NullValue: Readonly<{ NULL_VALUE: 0 }>;
+/** A value of the google.protobuf.NullValue enum. */
+export type NullValue = (typeof NullValue)[keyof typeof NullValue];
+
+/** A decoded google.protobuf.Struct message: a JSON object; see `structToJson`. */
+export interface Struct {
+  fields: Record<string, Value>;
+}
+
+/** A google.protobuf.Struct message to send; see `structFromJson`. */
+export interface StructInit {
+  fields?: Record<string, ValueInit>;
+}
+
+/**
+ * A decoded google.protobuf.Value message: a JSON value, which sets one member of the `kind`
+ * oneof; see `valueToJson`.
+ */
+export interface Value {
+  nullValue: NullValue;
+  numberValue: number;
+  stringValue: string;
+  boolValue: boolean;
+  structValue: Struct | null;
+  listValue: ListValue | null;
+}
+
+/** A google.protobuf.Value message to send; see `valueFromJson`. */
+export interface ValueInit {
+  nullValue?: NullValue;
+  numberValue?: number;
+  stringValue?: string;
+  boolValue?: boolean;
+  structValue?: StructInit | null;
+  listValue?: ListValueInit | null;
+}
+
+/** A decoded google.protobuf.ListValue message: a JSON array. */
+export interface ListValue {
+  values: Value[];
+}
+
+/** A google.protobuf.ListValue message to send. */
+export interface ListValueInit {
+  values?: ValueInit[];
+}
+
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export type JsonObject = { [key: string]: JsonValue };
+
+/** Returns the Timestamp of a Date, to the millisecond. */
+export function timestampFromDate(date: Date): Timestamp;
+/** Returns the Timestamp of milliseconds since the Unix epoch. */
+export function timestampFromMs(ms: number): Timestamp;
+/** Returns the Date of a Timestamp, whatever the representation of its seconds. */
+export function timestampDate(timestamp: {
+  seconds?: Int64Value | null;
+  nanos?: number | null;
+}): Date;
+/** Returns the milliseconds since the Unix epoch of a Timestamp, rounded down. */
+export function timestampMs(timestamp: {
+  seconds?: Int64Value | null;
+  nanos?: number | null;
+}): number;
+/** Returns the Duration of a number of milliseconds. */
+export function durationFromMs(ms: number): Duration;
+/** Returns the milliseconds of a Duration, rounded towards zero. */
+export function durationMs(duration: {
+  seconds?: Int64Value | null;
+  nanos?: number | null;
+}): number;
+/** Returns the Struct of a JSON object. */
+export function structFromJson(json: JsonObject): StructInit;
+/** Returns the JSON object of a Struct. */
+export function structToJson(struct: StructInit): JsonObject;
+/** Returns the Value of a JSON value. */
+export function valueFromJson(json: JsonValue): ValueInit;
+/** Returns the JSON value of a Value; one with no member of `kind` set is null. */
+export function valueToJson(value: ValueInit): JsonValue;
 
 export const Code: Readonly<{
   Ok: 0;
@@ -36,6 +166,8 @@ export type Metadata = Record<string, Uint8Array>;
 
 /** Error carrying a TrevRPC status code, message, and metadata. */
 export class TrevRpcError extends Error {
+  /** Always `"TrevRpcError"`, for matching errors by tag, as Effect's `catchTag` does. */
+  readonly _tag: "TrevRpcError";
   readonly code: StatusCode;
   readonly statusMessage: string;
   readonly metadata: Metadata;
@@ -65,6 +197,59 @@ export interface CallOptions {
   onResponseMetadata?(metadata: Metadata): void;
 }
 
+/** The kind of an RPC, as in its generated descriptor. */
+export type CallKind = "unary" | "serverStreaming" | "clientStreaming" | "bidirectionalStreaming";
+
+/** What a call interceptor sees of a call before it starts. */
+export interface InterceptedCall {
+  /** The method's full path, such as `/example.greeter.Greeter/SayHello`. */
+  readonly method: string;
+  /** The service's full name, such as `example.greeter.Greeter`. */
+  readonly service: string;
+  /** The method's name, such as `SayHello`. */
+  readonly name: string;
+  readonly kind: CallKind;
+  /**
+   * The call's request metadata. An interceptor may add, replace and delete entries, such as a
+   * refreshed token; the result is validated after the last interceptor, and invalid metadata
+   * fails the call with InvalidArgument.
+   */
+  metadata: Record<string, MetadataValue>;
+  /** The call's deadline, which starts once the interceptors are done. */
+  readonly timeoutMs: number | undefined;
+  /** The call's abort signal, which an interceptor that waits can watch. */
+  readonly signal: AbortSignal | undefined;
+}
+
+/** How an intercepted call ended. */
+export interface CallEnd {
+  /** `Code.Ok` when the call succeeded; the code of `error` otherwise, or `Code.Unknown`. */
+  readonly code: StatusCode;
+  /** What failed the call, usually a TrevRpcError; undefined when it succeeded. */
+  readonly error: unknown;
+}
+
+/** Called once when an intercepted call ends. A finish function that throws is reported, not rethrown. */
+export type CallFinish = (end: CallEnd) => void;
+
+/**
+ * Runs before each call of a client, in order with the others. It may change the call's metadata,
+ * wait (for example for a token refresh), and return a function that is called once when the call
+ * ends: when a unary call settles, and when a streaming call receives its final status or fails,
+ * including when it is cancelled. Finish functions run innermost first. A streaming call that is
+ * neither read to its end nor closed does not end. An interceptor that throws fails the call with
+ * what it threw, before it starts; the finish functions of earlier interceptors still run.
+ */
+export type CallInterceptor = (
+  call: InterceptedCall,
+) => void | CallFinish | Promise<void | CallFinish>;
+
+/** Options of a service client: defaults for its calls, and interceptors that run around them. */
+export interface ClientOptions extends CallOptions {
+  /** Interceptors for the client's calls, after those of its transport, such as a Channel's. */
+  interceptors?: readonly CallInterceptor[];
+}
+
 export interface TransportStream {
   readable: ReadableStream<Uint8Array>;
   writable: WritableStream<Uint8Array>;
@@ -83,6 +268,8 @@ export interface DatagramTransport {
 }
 
 declare const compressionBrand: unique symbol;
+declare const connectionMetadataBrand: unique symbol;
+declare const streamCompressionBudgetBrand: unique symbol;
 
 /**
  * Compression settings, made by `createCompression()` from `@trevrpc/trevrpc-js/zstd`: the zstd
@@ -92,6 +279,22 @@ export interface Compression {
   readonly [compressionBrand]: true;
 }
 
+/**
+ * A Channel's connection metadata, which `Channel.setConnectionMetadata()` replaces. See
+ * `Transport.connectionMetadata`.
+ */
+export interface ConnectionMetadataSource {
+  readonly [connectionMetadataBrand]: true;
+}
+
+/**
+ * A Channel's stream compression memory budget, from `ConnectOptions.streamCompressionMemory`.
+ * See `Transport.streamCompressionBudget`.
+ */
+export interface StreamCompressionBudget {
+  readonly [streamCompressionBudgetBrand]: true;
+}
+
 /**
  * Anything that opens a bidirectional byte stream per call, such as a Channel or WebTransport.
  * Calls to methods that mark a direction unreliable use the `datagrams` of the session that opens
@@ -103,6 +306,22 @@ export interface Transport {
   readonly datagrams?: DatagramTransport;
   /** Compression settings for calls on this transport; absent without compression. */
   readonly compression?: Compression;
+  /**
+   * The connection metadata calls on this transport carry; a Channel's own. A transport that
+   * wraps a Channel forwards it, or its calls carry no connection metadata.
+   */
+  readonly connectionMetadata?: ConnectionMetadataSource;
+  /**
+   * The memory budget of the stream compression contexts of calls on this transport; a Channel's
+   * own. A transport that wraps a Channel forwards it, or its calls get a default budget of their
+   * own.
+   */
+  readonly streamCompressionBudget?: StreamCompressionBudget;
+  /**
+   * Interceptors that clients created on this transport run around every call, before their own;
+   * a Channel's own. A transport that wraps a Channel forwards them, or its clients skip them.
+   */
+  readonly interceptors?: readonly CallInterceptor[];
   /**
    * Like `createBidirectionalStream()`, but also returns the session that opened the stream.
    * Calls negotiate dictionaries and open datagram flows per session, so transports whose session
@@ -174,6 +393,9 @@ export interface StreamStatus {
 /**
  * Responses of a server-streaming call. Iteration ends after the final OK status and throws a
  * TrevRpcError for any other outcome. Leaving the loop early cancels the call.
+ *
+ * Buffered messages are delivered without returning to the event loop, so a page that renders a
+ * long stream must yield to let the browser render; see "Rendering long streams" in the guide.
  */
 export interface ResponseStream<TResponse> extends AsyncIterable<TResponse> {
   /** Settles with the final status, or rejects with the error that ended the call. */
@@ -211,6 +433,8 @@ export interface ClientStreamingCall<TRequest, TResponse> {
    * the call and reject with what they threw.
    */
   sendAll(requests: Iterable<TRequest> | AsyncIterable<TRequest>): Promise<void>;
+  /** Settles with the final status, or rejects with the error that ended the call. */
+  readonly status: Promise<StreamStatus>;
   /** Closes the request stream and returns the final response. */
   closeAndRecv(): Promise<TResponse>;
   /** Cancels the call unless it already finished. */
@@ -224,6 +448,9 @@ export interface ClientStreamingCall<TRequest, TResponse> {
  * Response datagrams are delivered after the response headers, merged with the stream's messages
  * in arrival order, and dropped when the call's queue is full (32 messages or 1 MiB) or the call
  * has ended. Without datagrams, such as over WebSocket, everything stays on the stream.
+ *
+ * Like a `ResponseStream`, iteration delivers buffered messages without returning to the event
+ * loop.
  */
 export interface BidirectionalStreamingCall<TRequest, TResponse> extends AsyncIterable<TResponse> {
   /** Settles with the final status, or rejects with the error that ended the call. */
@@ -276,12 +503,15 @@ export type ServiceClient = Record<
   (requestOrOptions?: unknown, options?: CallOptions) => Promise<unknown>
 >;
 
-/** Creates a service client from a generated service descriptor. */
+/**
+ * Creates a service client from a generated service descriptor. Its calls run the transport's
+ * interceptors, then those of `options.interceptors`.
+ */
 export function createServiceClient<TClient extends ServiceClient = ServiceClient>(
   transport: Transport,
   service: RpcServiceDescriptor,
   root: Root,
-  options?: CallOptions,
+  options?: ClientOptions,
 ): TClient;
 
 export interface WebTransportCertificateHash {
@@ -289,6 +519,22 @@ export interface WebTransportCertificateHash {
   value: ArrayBuffer | ArrayBufferView;
 }
 
+export interface FetchServerCertificateHashesOptions {
+  signal?: AbortSignal;
+  /** The fetch implementation to use instead of the global one. */
+  fetch?: (input: string | URL, init?: RequestInit) => Promise<Response>;
+}
+
+/**
+ * Fetches the certificate hashes a TrevRPC development server publishes, as JSON such as
+ * `[{"algorithm":"sha-256","value":"<hex>"}]`, for `serverCertificateHashes`. A 404 yields no
+ * hashes; any other failure rejects with Unavailable.
+ */
+export function fetchServerCertificateHashes(
+  url: string | URL,
+  options?: FetchServerCertificateHashesOptions,
+): Promise<WebTransportCertificateHash[]>;
+
 export interface WebTransportSessionLike extends Transport {
   readonly ready: Promise<unknown>;
   /**
@@ -326,6 +572,14 @@ export interface ConnectOptions {
    * only: the WebSocket fallback needs a certificate the browser trusts.
    */
   serverCertificateHashes?: readonly WebTransportCertificateHash[];
+  /**
+   * A URL that publishes the server's development certificate hashes, such as a path that the
+   * development web server proxies to the TrevRPC server's DevelopmentCertificate. Every
+   * WebTransport attempt fetches it, so reconnects follow a rotated certificate, and adds its
+   * hashes to `serverCertificateHashes`; a 404 adds none, so the same build works against a server
+   * with a trusted certificate. A failed fetch fails the WebTransport attempt.
+   */
+  serverCertificateHashesUrl?: string | URL;
   /**
    * WebTransport implementation to use instead of the global one. It is constructed with
    * `protocols: ["trevrpc-1"]`, the wire version, which cannot be changed.
@@ -350,13 +604,18 @@ export interface ConnectOptions {
    * metadata. Replace it with `Channel.setConnectionMetadata()`.
    */
   connectionMetadata?: MetadataInput;
-  /** Cancels the initial connection attempt only. */
+  /**
+   * Interceptors that every client created on the channel runs around its calls, before the
+   * client's own; see `CallInterceptor`.
+   */
+  interceptors?: readonly CallInterceptor[];
+  /** Cancels the initial connection attempt of `connect()` only; `createChannel()` ignores it. */
   signal?: AbortSignal;
   /** Receives channel state transitions. */
   onStateChange?(change: ChannelStateChange): void;
 }
 
-export type ChannelState = "ready" | "reconnecting" | "closed";
+export type ChannelState = "connecting" | "ready" | "reconnecting" | "closed";
 
 export interface ChannelStateChange {
   state: ChannelState;
@@ -371,13 +630,26 @@ export interface ChannelStateChange {
   transport?: TransportKind;
 }
 
-/** Opens a channel to a TrevRPC server and waits for its session to be ready. */
+/**
+ * Opens a channel to a TrevRPC server and waits for its session to be ready. It rejects, leaving
+ * nothing behind, if the first attempt fails.
+ */
 export function connect(url: string | URL, options?: ConnectOptions): Promise<Channel>;
 
+/**
+ * Returns a channel to a TrevRPC server that connects in the background, so that clients can be
+ * created on it right away. Calls started before its first session is ready wait for that attempt
+ * (within their own deadline and signal); a failed attempt fails them, and the channel goes on
+ * reconnecting with backoff. Close the channel to give up; the `signal` option does not apply.
+ * Throws if an option is invalid.
+ */
+export function createChannel(url: string | URL, options?: ConnectOptions): Channel;
+
 /**
  * A session that reconnects in the background after it is lost: WebTransport, or QMux over
- * WebSocket when WebTransport is unavailable or blocked. Calls fail fast with Unavailable while it
- * reconnects and are never replayed.
+ * WebSocket when WebTransport is unavailable or blocked. Calls started while it first connects wait
+ * for that attempt; afterwards they fail fast with Unavailable while it reconnects and are never
+ * replayed.
  */
 export class Channel implements Transport {
   private constructor();
@@ -386,10 +658,16 @@ export class Channel implements Transport {
   static connect(url: string | URL, options?: ConnectOptions): Promise<Channel>;
 
   readonly state: ChannelState;
-  /** The transport of the current or last session. */
-  readonly transport: TransportKind;
+  /** The transport of the current or last session; undefined before the first. */
+  readonly transport: TransportKind | undefined;
   /** The compression settings from the connect options. */
   readonly compression?: Compression;
+  /** The connection metadata of the channel's calls, which a wrapping Transport forwards. */
+  readonly connectionMetadata: ConnectionMetadataSource;
+  /** The stream compression memory budget of the channel's calls, which a wrapping Transport forwards. */
+  readonly streamCompressionBudget: StreamCompressionBudget;
+  /** The interceptors from the connect options, which a wrapping Transport forwards. */
+  readonly interceptors: readonly CallInterceptor[];
   /**
    * Replaces the channel's connection metadata (see `ConnectOptions.connectionMetadata`); empty or
    * missing metadata removes it. Calls started after this use the new metadata, and each

package/src/index.js

@@ -1,4 +1,18 @@
-export { Channel, connect } from "./channel.js";
+export { fetchServerCertificateHashes } from "./certificate-hashes.js";
+export { Channel, connect, createChannel } from "./channel.js";
 export { createServiceClient } from "./client.js";
 export { Code, TrevRpcError, codeName } from "./status.js";
 export { createRoot, protobuf } from "./wire.js";
+export {
+  NullValue,
+  durationFromMs,
+  durationMs,
+  structFromJson,
+  structToJson,
+  timestampDate,
+  timestampFromDate,
+  timestampFromMs,
+  timestampMs,
+  valueFromJson,
+  valueToJson,
+} from "./wkt.js";