@trevrpc/trevrpc-js 1.3.2 → 1.5.0

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;
+}

package/src/interceptor.js

@@ -0,0 +1,102 @@
+import { normalizeMetadata } from "./metadata.js";
+import { Code, TrevRpcError, invalidArgument } from "./status.js";
+
+/**
+ * Checks a list of call interceptors from the options of a channel or client, and returns it as a
+ * frozen array; undefined or null is no interceptors. Throws InvalidArgument otherwise.
+ */
+export function interceptorList(interceptors, what) {
+  if (interceptors == null) {
+    return Object.freeze([]);
+  }
+  if (typeof interceptors[Symbol.iterator] !== "function" || typeof interceptors === "string") {
+    throw invalidArgument(`${what} must be a list of functions`);
+  }
+  const list = [...interceptors];
+  if (!list.every((interceptor) => typeof interceptor === "function")) {
+    throw invalidArgument(`${what} must be a list of functions`);
+  }
+  return Object.freeze(list);
+}
+
+/**
+ * Runs `interceptors` in order, then starts the call with `start(options)`, passing the options
+ * with the metadata the interceptors left, and returns what `start` returns. The finish functions
+ * the interceptors returned run once, innermost first, with `{ code, error }` when the call ends:
+ * when an interceptor or `start` fails, when `start` settles if `ended` is undefined, and when
+ * `ended(result)` settles otherwise, such as a streaming call's final status.
+ */
+export async function interceptCall(interceptors, info, options, start, ended) {
+  const finishes = [];
+  let result;
+  try {
+    const call = new InterceptedCall(info, options);
+    for (const interceptor of interceptors) {
+      const finish = await interceptor(call);
+      if (finish != null) {
+        if (typeof finish !== "function") {
+          throw new TypeError("a call interceptor must return a function or nothing");
+        }
+        finishes.push(finish);
+      }
+    }
+    result = await start({ ...options, metadata: normalizeMetadata(call.metadata) });
+  } catch (error) {
+    runFinishes(finishes, error);
+    throw error;
+  }
+  if (ended === undefined) {
+    runFinishes(finishes, undefined);
+  } else if (finishes.length > 0) {
+    ended(result).then(
+      () => runFinishes(finishes, undefined),
+      (error) => runFinishes(finishes, error),
+    );
+  }
+  return result;
+}
+
+/** What an interceptor sees of a call before it starts, and may change. */
+class InterceptedCall {
+  constructor({ method, service, name, kind }, { metadata, timeoutMs, signal }) {
+    this.method = method;
+    this.service = service;
+    this.name = name;
+    this.kind = kind;
+    /** The request metadata; interceptors may add, replace and delete entries. */
+    this.metadata = { ...metadata };
+    this.timeoutMs = timeoutMs;
+    this.signal = signal;
+    Object.seal(this);
+  }
+}
+
+/**
+ * Calls each finish function, innermost first, with how the call ended. A finish function that
+ * throws does not stop the others; its error is reported as uncaught.
+ */
+function runFinishes(finishes, error) {
+  if (finishes.length === 0) {
+    return;
+  }
+  const end = Object.freeze(
+    error === undefined
+      ? { code: Code.Ok, error: undefined }
+      : { code: error instanceof TrevRpcError ? error.code : Code.Unknown, error },
+  );
+  for (let index = finishes.length - 1; index >= 0; index -= 1) {
+    try {
+      finishes[index](end);
+    } catch (failure) {
+      reportUncaught(failure);
+    }
+  }
+}
+
+function reportUncaught(error) {
+  if (typeof globalThis.reportError === "function") {
+    globalThis.reportError(error);
+  } else {
+    console.error(error);
+  }
+}

package/src/status.js

@@ -37,6 +37,10 @@ export class TrevRpcError extends Error {
   }
 }
 
+// A discriminant for libraries that match errors by tag, such as Effect's `catchTag`. It is on the
+// prototype, so errors carry no extra own property.
+Object.defineProperty(TrevRpcError.prototype, "_tag", { value: "TrevRpcError" });
+
 /** Converts a number into a known status code, defaulting unknown values to Unknown. */
 export function codeFromNumber(code) {
   return Number.isInteger(code) && code >= 0 && code < CodeNames.length ? code : Code.Unknown;

package/src/stream-compression.js

@@ -17,9 +17,6 @@ const StreamCompressionStart = 3;
 /** The default memory budget of one channel's stream contexts, in bytes. */
 export const DefaultStreamCompressionMemory = 64 * 1024 * 1024;
 
-/** The key of a transport's StreamBudget; a Channel sets it from its connect options. */
-export const StreamBudgetKey = Symbol("trevrpc.streamBudget");
-
 /** The memory stream contexts may hold, shared by the calls of one channel. */
 export class StreamBudget {
   #available;
@@ -54,9 +51,12 @@ export class StreamBudget {
 
 const defaultBudgets = new WeakMap();
 
-/** The stream budget of a transport: a Channel's own, or a default one per other transport. */
+/**
+ * The stream budget of a transport: a Channel's own, which a transport that wraps one forwards, or
+ * a default one per other transport.
+ */
 export function streamBudget(transport) {
-  const budget = transport[StreamBudgetKey];
+  const budget = transport.streamCompressionBudget;
   if (budget !== undefined) {
     return budget;
   }

package/src/wire.js

@@ -1,6 +1,7 @@
 import protobuf from "protobufjs";
 
 import { byteView } from "./bytes.js";
+import { setInt64Representation } from "./int64.js";
 
 export { protobuf };
 
@@ -102,9 +103,16 @@ export function preflightWireMessage(messageType, body) {
   scanMessage(messageType, byteView(body), 0);
 }
 
-/** Creates a protobuf root from a JSON namespace definition. */
-export function createRoot(json) {
-  return protobuf.Root.fromJSON(json);
+/**
+ * Creates a protobuf root from a JSON namespace definition. `options.int64` sets how calls decode
+ * its messages' 64-bit integers (see `setInt64Representation`); without it they stay Long objects.
+ */
+export function createRoot(json, options = {}) {
+  const root = protobuf.Root.fromJSON(json);
+  if (options.int64 !== undefined) {
+    setInt64Representation(root, options.int64);
+  }
+  return root;
 }
 
 function scanMessage(messageType, bytes, depth) {
@@ -183,15 +191,25 @@ function scanMapEntry(field, bytes, depth) {
     if (fieldNumber === 1) {
       scanSyntheticField(field.keyType, `${field.name}.key`, bytes, cursor, wireType, depth);
     } else if (fieldNumber === 2) {
-      scanSyntheticField(field.type, `${field.name}.value`, bytes, cursor, wireType, depth);
+      const messageType = field.resolvedType?.fieldsById != null ? field.resolvedType : undefined;
+      scanSyntheticField(
+        field.type,
+        `${field.name}.value`,
+        bytes,
+        cursor,
+        wireType,
+        depth,
+        messageType,
+      );
     } else {
       skipUnknownField(bytes, cursor, fieldNumber, wireType, depth);
     }
   }
 }
 
-function scanSyntheticField(type, name, bytes, cursor, wireType, depth) {
-  const expected = scalarWireType(type);
+/** Scans a map key or value: a scalar of `type`, or a message of `messageType` when it is set. */
+function scanSyntheticField(type, name, bytes, cursor, wireType, depth, messageType) {
+  const expected = messageType === undefined ? scalarWireType(type) : 2;
   if (wireType !== expected) {
     throw malformedWire(`field ${name} used incompatible protobuf wire type ${wireType}`);
   }
@@ -206,7 +224,9 @@ function scanSyntheticField(type, name, bytes, cursor, wireType, depth) {
     skipFixed(bytes, cursor, 4, name);
   } else if (wireType === 2) {
     const value = readLengthDelimited(bytes, cursor, `truncated protobuf field ${name}`);
-    if (type === "string") {
+    if (messageType !== undefined) {
+      scanMessage(messageType, value, depth + 1);
+    } else if (type === "string") {
       validateUtf8(value, name);
     }
   } else {
@@ -234,6 +254,10 @@ function scanPackedField(field, bytes) {
 }
 
 function acceptedWireTypes(field) {
+  // A map entry is a length-delimited message, whatever its value type.
+  if (field.map) {
+    return [2];
+  }
   const expected = field.resolvedType?.fieldsById != null ? 2 : scalarWireType(field.type);
   return field.repeated && isPackableField(field) ? [expected, 2] : [expected];
 }

package/src/wkt.js

@@ -0,0 +1,137 @@
+// Helpers for the well-known types google.protobuf.Timestamp, Duration, Struct, Value and
+// ListValue, whose declarations generated code imports from the runtime.
+import { int64ToBigInt } from "./int64.js";
+import { invalidArgument } from "./status.js";
+
+/** google.protobuf.NullValue. */
+export const NullValue = Object.freeze({ NULL_VALUE: 0 });
+
+const MsPerSecond = 1000n;
+const NanosPerMs = 1_000_000;
+
+/** Returns the Timestamp of a Date. */
+export function timestampFromDate(date) {
+  return timestampFromMs(date.getTime());
+}
+
+/** Returns the Timestamp of milliseconds since the Unix epoch. */
+export function timestampFromMs(ms) {
+  checkFinite(ms, "timestamp");
+  const whole = Math.floor(ms);
+  const seconds = Math.floor(whole / 1000);
+  return { seconds: BigInt(seconds), nanos: (whole - seconds * 1000) * NanosPerMs };
+}
+
+/** Returns the Date of a Timestamp. */
+export function timestampDate(timestamp) {
+  return new Date(timestampMs(timestamp));
+}
+
+/** Returns the milliseconds since the Unix epoch of a Timestamp, rounded down. */
+export function timestampMs(timestamp) {
+  return toMs(timestamp, Math.floor);
+}
+
+/** Returns the Duration of a number of milliseconds. */
+export function durationFromMs(ms) {
+  checkFinite(ms, "duration");
+  const whole = Math.trunc(ms);
+  const seconds = Math.trunc(whole / 1000);
+  // Seconds and nanos share the duration's sign; `+ 0` turns -0 into 0.
+  return { seconds: BigInt(seconds), nanos: (whole - seconds * 1000) * NanosPerMs + 0 };
+}
+
+/** Returns the milliseconds of a Duration, rounded towards zero. */
+export function durationMs(duration) {
+  return toMs(duration, Math.trunc);
+}
+
+/** Returns the Struct of a JSON object. */
+export function structFromJson(json) {
+  if (json === null || typeof json !== "object" || Array.isArray(json)) {
+    throw invalidArgument("a Struct is made from a JSON object");
+  }
+  const fields = {};
+  for (const [key, value] of Object.entries(json)) {
+    fields[key] = valueFromJson(value);
+  }
+  return { fields };
+}
+
+/** Returns the JSON object of a Struct. */
+export function structToJson(struct) {
+  const json = {};
+  for (const [key, value] of Object.entries(struct?.fields ?? {})) {
+    json[key] = valueToJson(value);
+  }
+  return json;
+}
+
+/** Returns the Value of a JSON value. */
+export function valueFromJson(json) {
+  if (json === null) {
+    return { nullValue: NullValue.NULL_VALUE };
+  }
+  switch (typeof json) {
+    case "number":
+      return { numberValue: json };
+    case "string":
+      return { stringValue: json };
+    case "boolean":
+      return { boolValue: json };
+    case "object":
+      return Array.isArray(json)
+        ? { listValue: { values: json.map(valueFromJson) } }
+        : { structValue: structFromJson(json) };
+    default:
+      throw invalidArgument(`a Value cannot hold a ${typeof json}`);
+  }
+}
+
+/** Returns the JSON value of a Value; a Value with no kind set is null. */
+export function valueToJson(value) {
+  switch (valueKind(value)) {
+    case "numberValue":
+      return value.numberValue;
+    case "stringValue":
+      return value.stringValue;
+    case "boolValue":
+      return value.boolValue;
+    case "structValue":
+      return structToJson(value.structValue);
+    case "listValue":
+      return (value.listValue.values ?? []).map(valueToJson);
+    default:
+      return null;
+  }
+}
+
+const ValueKinds = [
+  "nullValue",
+  "numberValue",
+  "stringValue",
+  "boolValue",
+  "structValue",
+  "listValue",
+];
+
+/**
+ * The member of a Value's `kind` oneof that is set. A decoded Value reads the defaults of the
+ * other members from its prototype, so only own properties count.
+ */
+function valueKind(value) {
+  return ValueKinds.find(
+    (kind) => value != null && Object.hasOwn(value, kind) && value[kind] != null,
+  );
+}
+
+/** The milliseconds of a Timestamp or Duration, with sub-millisecond nanos rounded by `round`. */
+function toMs({ seconds, nanos } = {}, round) {
+  return Number(int64ToBigInt(seconds) * MsPerSecond) + round((nanos ?? 0) / NanosPerMs);
+}
+
+function checkFinite(ms, what) {
+  if (!Number.isFinite(ms)) {
+    throw invalidArgument(`a ${what} needs a finite number of milliseconds, not ${ms}`);
+  }
+}