@trevrpc/trevrpc-js 1.4.0 → 1.5.0

package/README.md

@@ -142,6 +142,48 @@ call.
 
 - To find the final status while the caller only sends, a client-streaming or bidirectional call reads the response ahead of `recv()` while its request side is open: at most 32 frames or 1 MiB (plus one frame of at most `maxFrameSize`) are held; beyond that reading pauses and flow control applies until `recv()` takes messages. Responses read ahead are delivered in order, including before an error that ended the stream.
 
+### Rendering long streams
+
+Once response messages are buffered, `for await` hands them over without returning to the event loop: each `next()` resolves as a microtask, as with any async iterator over a `fetch` body. When the network delivers faster than the page consumes, which is always the case on localhost, a loop over a long stream runs to its end before the browser renders anything, timers fire, or input is handled. The client does not yield on its own, because a timer-based yield would slow streams in hidden tabs and add latency for consumers that do not render.
+
+A page that renders a stream should batch messages per animation frame and, after a time budget, yield with a timer so that frame can render:
+
+```js
+let batch = [];
+let frame;
+const flush = () => {
+  frame = undefined;
+  store.append(batch);
+  batch = [];
+};
+
+let sliceStart = performance.now();
+try {
+  for await (const row of stream) {
+    batch.push(row);
+    frame ??= requestAnimationFrame(flush);
+    if (performance.now() - sliceStart > 8) {
+      if (document.hidden) {
+        cancelAnimationFrame(frame);
+        flush();
+      } else {
+        await new Promise((resolve) => setTimeout(resolve));
+      }
+      sliceStart = performance.now();
+    }
+  }
+} finally {
+  if (frame !== undefined) {
+    cancelAnimationFrame(frame);
+    flush();
+  }
+}
+```
+
+- `scheduler.yield()` does not help: Chromium resumes its continuation before rendering, so every message still lands in one frame.
+- Hidden tabs run no animation frames and throttle timers to about one per second, so while `document.hidden` the loop applies the batch itself after each time budget instead of yielding. It holds at most one budget's worth of messages, and a stream in a background tab keeps its speed.
+- If the stream fails or the loop is left early, which cancels the call, the `finally` still applies the messages received before.
+
 ### Connections
 
 `connect()` opens a session and resolves when it is ready; it rejects if no transport can establish one. After that the `Channel` re-establishes the session in the background with exponential backoff whenever it is lost. Calls fail fast with `Unavailable` while `channel.state` is `"reconnecting"` and are never replayed; use `await channel.waitUntilReady()` or the `onStateChange` option to follow the state. `channel.close()` stops reconnecting.
@@ -202,6 +244,10 @@ const client = new GreeterClient(channel, { interceptors: [logCalls] });
 - An interceptor that throws fails the call with what it threw before it starts; the finish functions of earlier interceptors still run.
 - A client-streaming call has a `status` promise too, like the other streaming calls.
 
+### Effect
+
+The separate package [`@trevrpc/effect`](effect) wraps a generated client for [Effect](https://effect.website): `createEffectClient(GreeterService, new GreeterClient(channel))` returns a client whose unary calls are effects, whose server-streaming calls are streams, and whose client-streaming and bidirectional calls take their requests as a stream. Interrupting an effect or stream cancels its call. `TrevRpcError` has a `_tag` of `"TrevRpcError"`, so `Effect.catchTag` matches it.
+
 ### Compression
 
 Messages can travel compressed with zstd and a dictionary trained on them (see [Compression](https://trev.zip/llc/TrevRPC/wiki/Compression)). The codec lives in a separate entry point, `@trevrpc/trevrpc-js/zstd`, which loads libzstd as WebAssembly (about 85 KB gzipped), so applications without compression never load it:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevrpc/trevrpc-js",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Browser WebTransport client and protobuf.js code generator for TrevRPC",
   "homepage": "https://trev.zip/llc/TrevRPC",
   "bugs": {

package/src/index.d.ts

@@ -166,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;
@@ -391,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. */
@@ -443,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. */

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;