@trevrpc/trevrpc-js 0.1.8 → 0.1.9

package/README.md

@@ -1,202 +1,96 @@
 # trevrpc-js
 
-`trevrpc-js` is the ESM-only JavaScript runtime and protobuf.js generator for TrevRPC.
+TrevRPC is an RPC framework like gRPC, but uses QUIC (and HTTP/3 / WebTransport) instead of HTTP/2. Define services in protobuf, generate typed clients and servers, and run them over QUIC.
 
-## Generated files
+Full documentation: https://trev.zip/llc/TrevRPC/wiki
 
-For every protobuf file containing services, `protoc-gen-trevrpc-js` emits an ordinary browser-safe client module and a separate Node server module:
+## Protobuf
 
-```text
-greeter.trevrpc.js
-greeter.trevrpc.d.ts
-greeter.node.trevrpc.js
-greeter.node.trevrpc.d.ts
-```
-
-The ordinary module contains the protobuf root, service descriptors, typed clients, and client factories. The Node companion contains typed handler interfaces and registration helpers backed by `@trevrpc/trevrpc-js/node/generated`.
-
-```sh
-protoc \
-  --plugin=protoc-gen-trevrpc-js=./node_modules/.bin/protoc-gen-trevrpc-js \
-  --trevrpc-js_out=. \
-  greeter.proto
-```
+```proto
+syntax = "proto3";
 
-Generator options are `runtime_import`, `runtime_type_import`, `node_runtime_import`, `node_runtime_type_import`, and `file_suffix`. Runtime type imports default to their matching runtime import for bare and relative specifiers. URL specifiers such as `file:` require an explicit type import because TypeScript NodeNext does not resolve them in declarations. A Node import is never inferred by appending `/node` to another specifier.
+package example.greeter;
 
-## Browser clients
-
-Browser declarations accept only `BrowserChannelOptions`.
-
-```js
-import { connect } from "@trevrpc/trevrpc-js";
-import { GreeterClient } from "./greeter.trevrpc.js";
-
-const channel = await connect("https://localhost:50051/trevrpc", {
-  timeoutMs: 10_000,
-  congestionControl: "low-latency",
-  serverCertificateHashes: [{ algorithm: "sha-256", value: certificateHash }],
-});
-try {
-  const client = new GreeterClient(channel, { timeoutMs: 5_000 });
-  const reply = await client.sayHello({ name: "TrevRPC" });
-  console.log(reply.message);
-} finally {
-  channel.close({ closeCode: 0, reason: "client shutdown" });
+service Greeter {
+  rpc SayHello(HelloRequest) returns (HelloReply);
+  rpc LotsOfReplies(HelloRequest) returns (stream HelloReply);
+  rpc LotsOfGreetings(stream HelloRequest) returns (HelloReply);
+  rpc BidiHello(stream HelloRequest) returns (stream HelloReply);
 }
-```
 
-Native TLS bypass, certificate validation, MsQuic buffering, and native stream options are intentionally unavailable under browser or Bundler resolution.
+message HelloRequest { string name = 1; }
+message HelloReply { string message = 1; }
+```
 
-## Node clients
+Generate with `protoc-gen-trevrpc-js` (`--trevrpc-js_out`).
 
-Under Node conditions, the root package uses the native channel. The explicit `@trevrpc/trevrpc-js/node` subpath also exports `Channel`, `NodeServer`, and `NodeServerCall`.
+## Client
 
 ```js
 import { connect } from "@trevrpc/trevrpc-js";
 import { GreeterClient } from "./greeter.trevrpc.js";
 
-const channel = await connect("https://localhost:50051", {
-  timeoutMs: 10_000,
-  caCertFile: "localhost-cert.pem",
-});
-try {
-  console.log(channel.endpoint); // frozen { host, port }
-  console.log(channel.options); // frozen effective NodeChannelOptions
-  const client = new GreeterClient(channel, { timeoutMs: 5_000 });
-  console.log((await client.sayHello({ name: "TrevRPC" })).message);
-} finally {
-  channel.close();
-}
-```
-
-URL and `{ host, port, ...options }` forms normalize to the same public state. Channels reconnect for future calls after native transport loss, but never replay or resume an operation that already failed.
-
-## Streaming clients
-
-Server-streaming methods resolve to `ResponseAsyncIterable<T>`:
+const channel = await connect("https://127.0.0.1:50051/trevrpc");
+const client = new GreeterClient(channel);
 
-```js
-const replies = await client.lotsOfReplies({ name: "TrevRPC" });
-try {
-  for await (const reply of replies) {
-    console.log(reply.message);
-  }
-  const terminal = await replies.status;
-  console.log(terminal.code, terminal.message, terminal.metadata);
-} finally {
-  await replies.close();
-}
-```
+// Unary
+const reply = await client.sayHello({ name: "TrevRPC" });
 
-Full clean consumption resolves `status`. A non-OK terminal status rejects iteration and `status` with the same `TrevRpcError`. `close()`, iterator `return()`, and breaking a `for await` loop cancel the stream and reject `status` with `Code.Cancelled`. Consuming a valid terminal frame claims terminal precedence and cancels the absolute deadline, but `status` settles only after trailing EOF is validated; merely buffering a status frame is not completion.
+// Server streaming
+const stream = await client.lotsOfReplies({ name: "TrevRPC" });
+for await (const r of stream) console.log(r.message);
 
-The status/error text distinction is deliberate:
+// Client streaming
+const cs = await client.lotsOfGreetings();
+await cs.send({ name: "Alice" });
+await cs.send({ name: "Bob" });
+const summary = await cs.closeAndRecv();
 
-- `StreamStatus.message` is the unmodified peer terminal message.
-- `TrevRpcError.statusMessage` is the unmodified peer error message.
-- `TrevRpcError.message` is formatted JavaScript text such as `"Unavailable: down"`.
+// Bidirectional streaming
+const bidi = await client.bidiHello();
+await bidi.send({ name: "Alice" });
+console.log(await bidi.recv());
+await bidi.closeSend();
+for await (const r of bidi) console.log(r.message);
 
-Unary and client-streaming terminal metadata is available through `sayHelloWithResponse()` and `closeAndRecvWithResponse()`.
-
-Client streaming:
-
-```js
-const call = await client.lotsOfGreetings();
-await call.send({ name: "Alice" });
-await call.send({ name: "Bob" });
-const { message, metadata } = await call.closeAndRecvWithResponse();
+channel.close();
 ```
 
-Bidirectional streaming:
+Node uses the same API via `@trevrpc/trevrpc-js/node` (native MsQuic).
 
-```js
-const call = await client.bidiHello();
-try {
-  await call.send({ name: "Alice" });
-  console.log(await call.recv());
-  await call.closeSend();
-  while ((await call.recv()) != null) {}
-  console.log(await call.status);
-} finally {
-  await call.close();
-}
-```
-
-`timeoutMs` is one absolute RPC deadline that begins before transport setup and covers upload, send, receive, and cleanup. The same `DeadlineExceeded` object wins signal and rejection settlement. `streamIdleTimeoutMs` remains an independent per-read inactivity bound.
-
-## Typed Node servers
-
-Import the generated registration helper from the Node companion. Direct protobuf responses are never confused with metadata envelopes, even when they have `message` or `messages` properties.
+## Server (Node)
 
 ```js
-import { Code, createStreamingResponse, createUnaryResponse } from "@trevrpc/trevrpc-js";
 import { NodeServer } from "@trevrpc/trevrpc-js/node";
 import { registerGreeterServer } from "./greeter.node.trevrpc.js";
+import { createUnaryResponse, createStreamingResponse } from "@trevrpc/trevrpc-js";
 
 const server = await NodeServer.listen({
   host: "127.0.0.1",
   port: 50051,
-  certFile: "localhost-cert.pem",
-  keyFile: "localhost-key.pem",
+  certFile: "cert.pem",
+  keyFile: "key.pem",
 });
 
 registerGreeterServer(server, {
-  sayHello(request, call) {
-    console.log(call.deadline, call.signal.aborted);
-    return createUnaryResponse(
-      { message: `Hello, ${request.name || "world"}` },
-      { trailer: "unary" },
-    );
+  sayHello(req) {
+    return createUnaryResponse({ message: `hello, ${req.name}` });
   },
-
-  async lotsOfGreetings(requests) {
-    const names = [];
-    for await (const request of requests) names.push(request.name);
-    return createUnaryResponse({ message: names.join(", ") }, { trailer: "client-stream" });
+  lotsOfReplies(req) {
+    return createStreamingResponse([
+      { message: `hello, ${req.name}` },
+      { message: `goodbye, ${req.name}` },
+    ]);
   },
-
-  lotsOfReplies(request) {
-    return createStreamingResponse([{ message: request.name }], {
-      code: Code.Ok,
-      message: "complete",
-      metadata: { trailer: "server-stream" },
-    });
+  async lotsOfGreetings(reqs) {
+    const names = [];
+    for await (const r of reqs) names.push(r.name);
+    return createUnaryResponse({ message: names.join(", ") });
   },
-
-  async *bidiHello(requests) {
-    for await (const request of requests) yield { message: request.name };
+  async *bidiHello(reqs) {
+    for await (const r of reqs) yield { message: `hello, ${r.name}` };
   },
 });
 
 await server.serve();
 ```
-
-Client-streaming completion uses streaming wire semantics: exactly one response message followed by exactly one terminal status; it never uses unary `respond()`.
-
-`NodeServerCall.signal` covers effective deadlines, server shutdown, local close, and cancellation observed by native I/O. The current native bridge cannot promptly report remote peer cancellation while a handler is idle and performs no call I/O; cancellation becomes observable when the handler next enters native call I/O.
-
-## Native package support
-
-The core tarball is platform-neutral. Native code is supplied by the exact optional package `@trevrpc/trevrpc-js-native-linux-x64-gnu@0.1.8`.
-
-Initial support is Linux x86-64, glibc 2.42 or newer, and Node 24. Browser usage still installs and runs on Darwin, ARM, and musl. Requesting a native Node channel on an unsupported or incomplete installation throws `TrevRpcError(Code.Unavailable)` with the detected target, supported targets, expected optional package, whether loading was missing or failed, and the original loader error as `cause`.
-
-All addon errors crossing public Node transport and server boundaries become `TrevRpcError` unless already normalized. `nativeCode` and `cause` preserve native provenance.
-
-## Package resolution
-
-Conditional ESM exports are authoritative; the package has no legacy top-level `main` or `types`. Use TypeScript NodeNext resolution for Node consumers and Bundler resolution with browser conditions for browser consumers.
-
-## Native development
-
-Installation never builds native code. In a source checkout:
-
-```sh
-npm run build:native:test
-npm test
-npm run build:native
-npm run verify:native:production
-```
-
-The development fallback is only `build/native/trevrpc_native.node` in a source checkout.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevrpc/trevrpc-js",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "JavaScript WebTransport runtime and protobuf.js code generator for TrevRPC",
   "homepage": "https://trev.zip/llc/TrevRPC",
   "bugs": {
@@ -79,7 +79,7 @@
     "typescript": "^7.0.2"
   },
   "optionalDependencies": {
-    "@trevrpc/trevrpc-js-native-linux-x64-gnu": "0.1.8"
+    "@trevrpc/trevrpc-js-native-linux-x64-gnu": "0.1.9"
   },
   "engines": {
     "node": ">=24 <25"