@trevrpc/effect 1.5.0 → 1.7.0

package/README.md

@@ -1,9 +1,13 @@
 # @trevrpc/effect
 
-[Effect](https://effect.website) adapter for the TrevRPC browser client, [`@trevrpc/trevrpc-js`](https://www.npmjs.com/package/@trevrpc/trevrpc-js): it wraps a generated client so that its calls are effects and streams.
+[Effect](https://effect.website) adapter for the TrevRPC browser client, [`@trevrpc/trevrpc-js`](https://www.npmjs.com/package/@trevrpc/trevrpc-js): it makes clients whose calls are effects and streams.
+
+> **Compatibility:** every TrevRPC package shares one version, and packages of the same version are compatible
+> with each other: `trevrpc-rust` 1.7.0 works with `trevrpc-go` 1.7.0, `trevrpc-js` 1.7.0, and `trevrpc-kotlin`
+> 1.7.0. Compatibility across different versions isn't guaranteed yet; that's a milestone for 2.0.
 
 ```sh
-npm install @trevrpc/effect @trevrpc/trevrpc-js effect
+npm install @trevrpc/effect @trevrpc/trevrpc-js @bufbuild/protobuf effect
 ```
 
 ```ts
@@ -11,10 +15,10 @@ import { createChannel } from "@trevrpc/trevrpc-js";
 import { createEffectClient } from "@trevrpc/effect";
 import { Stream } from "effect";
 
-import { GreeterClient, GreeterService } from "./gen/greeter/v1/greeter.trevrpc.js";
+import { Greeter } from "./gen/greeter/v1/greeter_pb.js";
 
 const channel = createChannel("https://example.com/trevrpc");
-const greeter = createEffectClient(GreeterService, new GreeterClient(channel));
+const greeter = createEffectClient(Greeter, channel);
 
 // Effect<HelloReply, TrevRpcError>
 const reply = greeter.sayHello({ name: "Ada" });
@@ -28,7 +32,7 @@ const replies = greeter.chat(
 );
 ```
 
-`createEffectClient(service, client)` takes the generated descriptor and client, and returns a client with the same method names:
+`createEffectClient(service, transport, options?)` takes what `createClient` of `@trevrpc/trevrpc-js` takes: a service descriptor that [protobuf-es](https://github.com/bufbuild/protobuf-es)'s `protoc-gen-es` generates, a transport such as a channel, and default call options and interceptors. It returns a client with one method per RPC, named by its `localName`:
 
 | RPC kind                | Effect method                                                                           |
 | ----------------------- | --------------------------------------------------------------------------------------- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevrpc/effect",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Effect adapter for TrevRPC browser clients",
   "homepage": "https://trev.zip/llc/TrevRPC",
   "bugs": {
@@ -39,16 +39,19 @@
     "check": "npm run format:check && npm run lint && npm run typecheck && npm test"
   },
   "devDependencies": {
+    "@bufbuild/protobuf": "^2.17.0",
+    "@bufbuild/protoc-gen-es": "^2.17.0",
     "@trevrpc/trevrpc-js": "file:..",
     "effect": "^4.1.2",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "@trevrpc/trevrpc-js": "^1.5.0",
+    "@bufbuild/protobuf": "^2.17.0",
+    "@trevrpc/trevrpc-js": "^1.7.0",
     "effect": "^4.1.2"
   },
   "engines": {
     "node": ">=24"
   },
-  "packageManager": "npm@12.2.1"
+  "packageManager": "npm@12.2.2"
 }

package/src/index.d.ts

@@ -1,56 +1,55 @@
-import type {
-  BidirectionalStreamingCall,
-  CallOptions,
-  ClientStreamingCall,
-  ResponseStream,
-  RpcServiceDescriptor,
-  TrevRpcError,
-} from "@trevrpc/trevrpc-js";
+import type { DescMessage, DescService, MessageInitShape, MessageShape } from "@bufbuild/protobuf";
+import type { CallOptions, ClientOptions, Transport, TrevRpcError } from "@trevrpc/trevrpc-js";
 import type { Effect, Stream } from "effect";
 
 /**
- * The Effect form of a generated client method:
+ * The Effect form of a method of a protobuf-es service descriptor:
  *
  * - unary: `(request, options?) => Effect<Response, TrevRpcError>`
  * - server streaming: `(request, options?) => Stream<Response, TrevRpcError>`
  * - client streaming: `(requests, options?) => Effect<Response, TrevRpcError | E, R>`
  * - bidirectional streaming: `(requests, options?) => Stream<Response, TrevRpcError | E, R>`
  *
- * where `requests` is a `Stream<Request, E, R>`. `never` for anything else.
+ * where a request is a message or the init object `create()` takes, `requests` is a
+ * `Stream<Request, E, R>`, and a response is a message.
  */
-export type EffectMethod<Method> = Method extends (
-  options?: CallOptions,
-) => Promise<BidirectionalStreamingCall<infer Request, infer Response>>
-  ? <E = never, R = never>(
-      requests: Stream.Stream<Request, E, R>,
-      options?: CallOptions,
-    ) => Stream.Stream<Response, TrevRpcError | E, R>
-  : Method extends (
+export type EffectMethod<Method> = Method extends {
+  methodKind: infer Kind;
+  input: infer I extends DescMessage;
+  output: infer O extends DescMessage;
+}
+  ? Kind extends "unary"
+    ? (
+        request: MessageInitShape<I>,
         options?: CallOptions,
-      ) => Promise<ClientStreamingCall<infer Request, infer Response>>
-    ? <E = never, R = never>(
-        requests: Stream.Stream<Request, E, R>,
-        options?: CallOptions,
-      ) => Effect.Effect<Response, TrevRpcError | E, R>
-    : Method extends (
-          request: infer Request,
+      ) => Effect.Effect<MessageShape<O>, TrevRpcError>
+    : Kind extends "server_streaming"
+      ? (
+          request: MessageInitShape<I>,
           options?: CallOptions,
-        ) => Promise<ResponseStream<infer Response>>
-      ? (request: Request, options?: CallOptions) => Stream.Stream<Response, TrevRpcError>
-      : Method extends (request: infer Request, options?: CallOptions) => Promise<infer Response>
-        ? (request: Request, options?: CallOptions) => Effect.Effect<Response, TrevRpcError>
-        : never;
+        ) => Stream.Stream<MessageShape<O>, TrevRpcError>
+      : Kind extends "client_streaming"
+        ? <E = never, R = never>(
+            requests: Stream.Stream<MessageInitShape<I>, E, R>,
+            options?: CallOptions,
+          ) => Effect.Effect<MessageShape<O>, TrevRpcError | E, R>
+        : Kind extends "bidi_streaming"
+          ? <E = never, R = never>(
+              requests: Stream.Stream<MessageInitShape<I>, E, R>,
+              options?: CallOptions,
+            ) => Stream.Stream<MessageShape<O>, TrevRpcError | E, R>
+          : never
+  : never;
 
-/** A generated client with its RPC methods in Effect form; other members are left out. */
-export type EffectClient<Client> = {
-  [Name in keyof Client as EffectMethod<Client[Name]> extends never ? never : Name]: EffectMethod<
-    Client[Name]
-  >;
+/** The Effect client of a service: one method per RPC, named by its `localName`. */
+export type EffectClient<S extends DescService> = {
+  [Name in keyof S["method"]]: EffectMethod<S["method"][Name]>;
 };
 
 /**
- * Wraps a generated client's methods in Effect. `service` is the client's generated descriptor,
- * such as `GreeterService` for a `GreeterClient`.
+ * Creates a client for `service`, a service descriptor that protoc-gen-es generates (such as
+ * `Greeter` from `greeter_pb.js`), whose calls are Effect values. `transport` and `options` are
+ * those of `createClient` in `@trevrpc/trevrpc-js`.
  *
  * Interrupting an effect or stream cancels its call, which the server sees as `Code.Cancelled`.
  * A `signal` in the call options cancels it too. Client-streaming and bidirectional calls pull
@@ -62,12 +61,13 @@ export type EffectClient<Client> = {
  * Calls fail with a `TrevRpcError`; anything else a call rejects with becomes one with
  * `Code.Unknown`, and with the original as `cause`.
  *
- * @throws TypeError if `client` lacks a method of `service`.
+ * @throws TrevRpcError with `Code.InvalidArgument` where `createClient` throws it.
  */
-export function createEffectClient<Client extends object>(
-  service: RpcServiceDescriptor,
-  client: Client,
-): EffectClient<Client>;
+export function createEffectClient<S extends DescService>(
+  service: S,
+  transport: Transport,
+  options?: ClientOptions,
+): EffectClient<S>;
 
 /** Returns a `TrevRpcError` as is, and wraps anything else in one with `Code.Unknown`. */
 export function toTrevRpcError(error: unknown): TrevRpcError;

package/src/index.js

@@ -1,4 +1,4 @@
-import { Code, TrevRpcError } from "@trevrpc/trevrpc-js";
+import { Code, TrevRpcError, createClient } from "@trevrpc/trevrpc-js";
 import { Effect, Stream } from "effect";
 
 /** Returns a `TrevRpcError` as is, and wraps anything else in one with `Code.Unknown`. */
@@ -11,39 +11,30 @@ export function toTrevRpcError(error) {
 }
 
 /**
- * Wraps a generated client's methods in Effect: unary calls return an `Effect`, server-streaming
- * calls a `Stream`, and client-streaming and bidirectional calls take their requests as a
- * `Stream`. Interrupting the effect or stream cancels the call.
+ * Creates a client for `service`, a service descriptor that protoc-gen-es generates, whose calls
+ * are Effect values: unary calls return an `Effect`, server-streaming calls a `Stream`, and
+ * client-streaming and bidirectional calls take their requests as a `Stream`. Interrupting the
+ * effect or stream cancels the call. `transport` and `options` are those of `createClient`.
  */
-export function createEffectClient(service, client) {
+export function createEffectClient(service, transport, options) {
+  const client = createClient(service, transport, options);
   const result = {};
-  for (const [name, method] of Object.entries(service.methods)) {
-    if (typeof client[name] !== "function") {
-      throw new TypeError(`client has no ${name} method for ${service.fullName}/${method.name}`);
-    }
-    const call = client[name].bind(client);
-    switch (method.kind) {
-      case "unary":
-        result[name] = liftUnary(call);
-        break;
-      case "serverStreaming":
-        result[name] = liftServerStreaming(call);
-        break;
-      case "clientStreaming":
-        result[name] = liftClientStreaming(call);
-        break;
-      case "bidirectionalStreaming":
-        result[name] = liftBidirectionalStreaming(call);
-        break;
-      default:
-        throw new TypeError(
-          `unknown kind ${String(method.kind)} of ${service.fullName}/${method.name}`,
-        );
-    }
+  for (const method of service.methods) {
+    const call = client[method.localName];
+    result[method.localName] = Lifts[method.methodKind](call);
   }
   return result;
 }
 
+/** How each protobuf-es method kind's calls become Effect values. */
+const Lifts = Object.freeze({
+  __proto__: null,
+  unary: liftUnary,
+  server_streaming: liftServerStreaming,
+  client_streaming: liftClientStreaming,
+  bidi_streaming: liftBidirectionalStreaming,
+});
+
 function liftUnary(call) {
   return (request, options) =>
     Effect.tryPromise({