@trevrpc/trevrpc-js 1.3.1 → 1.4.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;
@@ -65,6 +195,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 +266,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 +277,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 +304,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
@@ -211,6 +428,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. */
@@ -276,12 +495,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 +511,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 +564,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 +596,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 +622,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 +650,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";

package/src/int64.js

@@ -0,0 +1,288 @@
+import protobuf from "protobufjs";
+
+import { invalidArgument } from "./status.js";
+
+/**
+ * How decoded 64-bit integer fields are represented: `bigint`, `number` (exact up to 2^53),
+ * decimal `string`, or protobuf.js's `long` (a Long object, as protobuf.js decodes them).
+ */
+export const Int64Representations = Object.freeze(["bigint", "number", "string", "long"]);
+
+/** The representation of each root's 64-bit fields, for roots made with createRoot(). */
+const rootRepresentations = new WeakMap();
+/** The conversion plan of each message type, or null when its messages need none. */
+const plans = new WeakMap();
+
+const Int64Types = new Set(["int64", "uint64", "sint64", "fixed64", "sfixed64"]);
+const UnsignedTypes = new Set(["uint64", "fixed64"]);
+
+/**
+ * Sets how the decoded messages of `root`'s types represent 64-bit integers. Without it they keep
+ * protobuf.js's Long objects. A field's `jstype` option (`JS_STRING` or `JS_NUMBER`) overrides it.
+ */
+export function setInt64Representation(root, representation) {
+  if (!Int64Representations.includes(representation)) {
+    throw invalidArgument(
+      `int64 must be one of ${Int64Representations.join(", ")}, not ${JSON.stringify(representation)}`,
+    );
+  }
+  rootRepresentations.set(root, representation);
+}
+
+/**
+ * Returns a function that converts, in place, the 64-bit integers of a message of `type` that
+ * protobuf.js decoded, as its root's representation says, and returns the message; or undefined
+ * when its messages need no conversion. 64-bit map keys, which protobuf.js decodes as 8-byte hash
+ * strings, become decimal strings in every representation.
+ */
+export function int64Converter(type) {
+  const plan = planFor(type);
+  return plan === null ? undefined : (message) => applyPlan(plan, message);
+}
+
+/**
+ * Converts a 64-bit integer, as a bigint, a number, a decimal string, or a Long-like object with
+ * `low`, `high` and `unsigned`, to a bigint. Null and undefined are zero.
+ */
+export function int64ToBigInt(value, unsigned = value?.unsigned === true) {
+  switch (typeof value) {
+    case "bigint":
+      return value;
+    case "number":
+      return BigInt(Math.trunc(value));
+    case "string":
+      return BigInt(value);
+    default: {
+      if (value == null) {
+        return 0n;
+      }
+      const bits = (BigInt(value.high >>> 0) << 32n) | BigInt(value.low >>> 0);
+      return unsigned ? bits : BigInt.asIntN(64, bits);
+    }
+  }
+}
+
+function planFor(type) {
+  const cached = plans.get(type);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const representation = rootRepresentations.get(type.root);
+  if (representation === undefined) {
+    plans.set(type, null);
+    return null;
+  }
+  buildPlans(type, representation);
+  return plans.get(type);
+}
+
+/**
+ * Builds the plans of `start` and every message type reachable from it. A type needs a plan when
+ * it has a 64-bit field to convert, or a message field whose type needs one; that is settled for
+ * every reachable type at once, so recursive types are handled.
+ */
+function buildPlans(start, representation) {
+  const steps = new Map();
+  const pending = [start];
+  steps.set(start, undefined);
+  while (pending.length > 0) {
+    const type = pending.pop();
+    const typeSteps = [];
+    for (const field of type.fieldsArray) {
+      field.resolve();
+      const step = fieldStep(type, field, representation);
+      if (step !== undefined) {
+        typeSteps.push(step);
+      }
+      if (field.resolvedType instanceof protobuf.Type && !steps.has(field.resolvedType)) {
+        steps.set(field.resolvedType, undefined);
+        pending.push(field.resolvedType);
+      }
+    }
+    steps.set(type, typeSteps);
+  }
+
+  // A type needs a plan when it converts a value itself or holds a type that needs one.
+  const needed = new Set();
+  for (let changed = true; changed;) {
+    changed = false;
+    for (const [type, typeSteps] of steps) {
+      if (
+        !needed.has(type) &&
+        typeSteps.some((step) => convertsItself(step) || needed.has(step.type))
+      ) {
+        needed.add(type);
+        changed = true;
+      }
+    }
+  }
+
+  const built = new Map();
+  for (const type of steps.keys()) {
+    if (!plans.has(type)) {
+      built.set(type, needed.has(type) ? [] : null);
+      restoreNullDefaults(type);
+    }
+  }
+  for (const [type, plan] of built) {
+    plans.set(type, plan);
+  }
+  for (const [type, plan] of built) {
+    if (plan === null) {
+      continue;
+    }
+    for (const step of steps.get(type)) {
+      const nested = step.type === undefined ? undefined : plans.get(step.type);
+      if (!convertsItself(step) && nested == null) {
+        continue;
+      }
+      plan.push({ ...step, nested: nested ?? undefined });
+    }
+    patchDefaults(type, plan);
+  }
+}
+
+/** Reports whether a step converts values or keys of its own, not only nested messages. */
+function convertsItself(step) {
+  return step.convert !== undefined || step.convertKey !== undefined;
+}
+
+/**
+ * The conversion step of one field of `type`, or undefined when it holds neither a 64-bit integer
+ * nor a message. `convert` converts its 64-bit values, `convertKey` its 64-bit map keys, and
+ * `type` is the message type of its values.
+ */
+function fieldStep(type, field, representation) {
+  const messageType = field.resolvedType instanceof protobuf.Type ? field.resolvedType : undefined;
+  const convert = Int64Types.has(field.type)
+    ? valueConverter(fieldRepresentation(field, representation), UnsignedTypes.has(field.type))
+    : undefined;
+  if (field.map) {
+    const convertKey = Int64Types.has(field.keyType)
+      ? keyConverter(UnsignedTypes.has(field.keyType))
+      : undefined;
+    if (convert === undefined && convertKey === undefined && messageType === undefined) {
+      return undefined;
+    }
+    return { name: field.name, shape: "map", convert, convertKey, type: messageType };
+  }
+  if (convert === undefined && messageType === undefined) {
+    return undefined;
+  }
+  const shape = field.repeated ? "repeated" : "single";
+  return { name: field.name, shape, convert, type: messageType };
+}
+
+/** The representation of a 64-bit field: its `jstype` option's, or the root's. */
+function fieldRepresentation(field, representation) {
+  switch (field.options?.jstype) {
+    case "JS_STRING":
+      return "string";
+    case "JS_NUMBER":
+      return "number";
+    default:
+      return representation;
+  }
+}
+
+/** Returns a function converting a decoded 64-bit value, or undefined for Long objects. */
+function valueConverter(representation, unsigned) {
+  switch (representation) {
+    case "bigint":
+      return (value) => int64ToBigInt(value, unsigned);
+    case "number":
+      return (value) => Number(int64ToBigInt(value, unsigned));
+    case "string":
+      return (value) => int64ToBigInt(value, unsigned).toString();
+    default:
+      return undefined;
+  }
+}
+
+/** Returns a function converting a decoded 64-bit map key, an 8-byte hash, to decimal. */
+function keyConverter(unsigned) {
+  return (key) => int64ToBigInt(protobuf.util.longFromHash(key, unsigned), unsigned).toString();
+}
+
+/**
+ * Makes unset proto3 `optional` 64-bit fields of `type`'s messages read null, as other fields with
+ * presence do: protobuf.js turns their null default into a Long zero.
+ */
+function restoreNullDefaults(type) {
+  for (const field of type.fieldsArray) {
+    if (Int64Types.has(field.type) && field.options?.proto3_optional && !field.repeated) {
+      type.ctor.prototype[field.name] = null;
+    }
+  }
+}
+
+/**
+ * Converts the defaults that `type`'s messages read from their prototype for unset singular 64-bit
+ * fields, so that an unset field reads like a set one.
+ */
+function patchDefaults(type, plan) {
+  const prototype = type.ctor.prototype;
+  for (const step of plan) {
+    // A field with presence, such as a proto3 optional one, reads null when unset.
+    if (step.shape === "single" && step.convert !== undefined && prototype[step.name] != null) {
+      prototype[step.name] = step.convert(prototype[step.name]);
+    }
+  }
+}
+
+function applyPlan(plan, message) {
+  for (const step of plan) {
+    if (!Object.hasOwn(message, step.name)) {
+      continue;
+    }
+    const value = message[step.name];
+    if (value == null) {
+      continue;
+    }
+    switch (step.shape) {
+      case "single":
+        message[step.name] =
+          step.convert === undefined ? applyPlan(step.nested, value) : step.convert(value);
+        break;
+      case "repeated":
+        for (let index = 0; index < value.length; index += 1) {
+          value[index] =
+            step.convert === undefined
+              ? applyPlan(step.nested, value[index])
+              : step.convert(value[index]);
+        }
+        break;
+      case "map":
+        if (step.convertKey === undefined) {
+          convertMapValues(step, value);
+        } else {
+          message[step.name] = convertMap(step, value);
+        }
+        break;
+    }
+  }
+  return message;
+}
+
+/** Returns a copy of a decoded map with converted keys and values. */
+function convertMap(step, map) {
+  const converted = {};
+  for (const [key, value] of Object.entries(map)) {
+    converted[step.convertKey(key)] = convertMapValue(step, value);
+  }
+  return converted;
+}
+
+/** Converts the values of a decoded map in place. */
+function convertMapValues(step, map) {
+  for (const [key, value] of Object.entries(map)) {
+    map[key] = convertMapValue(step, value);
+  }
+}
+
+function convertMapValue(step, value) {
+  if (step.convert !== undefined) {
+    return step.convert(value);
+  }
+  return step.nested !== undefined && value != null ? applyPlan(step.nested, value) : value;
+}