@trevrpc/effect 0.0.0-stage → 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 trev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @trevrpc/effect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[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.
+
+```sh
+npm install @trevrpc/effect @trevrpc/trevrpc-js @bufbuild/protobuf effect
+```
+
+```ts
+import { createChannel } from "@trevrpc/trevrpc-js";
+import { createEffectClient } from "@trevrpc/effect";
+import { Stream } from "effect";
+
+import { Greeter } from "./gen/greeter/v1/greeter_pb.js";
+
+const channel = createChannel("https://example.com/trevrpc");
+const greeter = createEffectClient(Greeter, channel);
+
+// Effect<HelloReply, TrevRpcError>
+const reply = greeter.sayHello({ name: "Ada" });
+// Stream<Update, TrevRpcError>
+const updates = greeter.watch({ name: "Ada" });
+// Effect<UploadReply, TrevRpcError>
+const upload = greeter.upload(Stream.make({ chunk: "a" }, { chunk: "b" }));
+// Stream<ChatReply, TrevRpcError>
+const replies = greeter.chat(
+  Stream.fromIterable(["hi", "bye"]).pipe(Stream.map((text) => ({ text }))),
+);
+```
+
+`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                                                                           |
+| ----------------------- | --------------------------------------------------------------------------------------- |
+| unary                   | `(request, options?) => Effect<Response, TrevRpcError>`                                 |
+| server streaming        | `(request, options?) => Stream<Response, TrevRpcError>`                                 |
+| client streaming        | `(requests: Stream<Request, E, R>, options?) => Effect<Response, TrevRpcError \| E, R>` |
+| bidirectional streaming | `(requests: Stream<Request, E, R>, options?) => Stream<Response, TrevRpcError \| E, R>` |
+
+`options` are the usual [call options](https://trev.zip/llc/TrevRPC/wiki/JavaScript-Guide#call-options).
+
+- **Cancellation.** Interrupting an effect or stream cancels its call, which the server sees as `CANCELLED`; so does taking part of a response stream (`Stream.take`) or a failure elsewhere in the program. A `signal` in the call options also cancels the call.
+- **Request streams.** Client-streaming and bidirectional calls pull their requests from the stream as the transport accepts them, so a request stream is only consumed as fast as the server reads it. When the server ends the call first, the rest of the stream is not pulled, and the server's outcome is the result: its response or response stream if it succeeded, or its `TrevRpcError`. A request stream that fails cancels the call, and the call fails with the request stream's error.
+- **Errors.** Calls fail with the `TrevRpcError` of the [client](https://trev.zip/llc/TrevRPC/wiki/JavaScript-Guide#errors-cancellation-and-streams), whose `_tag` is `"TrevRpcError"`, so `Effect.catchTag("TrevRpcError", ...)` handles it. Anything else a call rejects with becomes a `TrevRpcError` with `Code.Unknown` and the original as `cause`, as `toTrevRpcError(error)` does.
+- **Rendering.** Response streams deliver buffered messages without returning to the event loop, as the client does; see [Rendering long streams](https://trev.zip/llc/TrevRPC/wiki/JavaScript-Guide#rendering-long-streams) before rendering a long stream message by message.
+
+## Development
+
+The package is developed against the trevrpc-js of this checkout, which it links as `file:..`, so install that first:
+
+```sh
+npm ci --prefix ..
+npm ci
+npm run check      # format check, lint, typecheck, tests
+```
+
+The tests run the real client against the in-memory server of trevrpc-js's own tests. `nix build .#trevrpc-js-effect` runs them against the built trevrpc-js, and checks the published files.

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@trevrpc/effect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.6.0",
+  "description": "Effect adapter for TrevRPC browser clients",
+  "homepage": "https://trev.zip/llc/TrevRPC",
+  "bugs": {
+    "url": "https://trev.zip/llc/TrevRPC/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://trev.zip/llc/TrevRPC.git",
+    "directory": "trevrpc-js/effect"
+  },
+  "files": [
+    "src/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node test/generate.js",
+    "format": "oxfmt --write",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint --deny-warnings src test",
+    "typecheck": "npm run build && tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.js",
+    "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": {
+    "@bufbuild/protobuf": "^2.17.0",
+    "@trevrpc/trevrpc-js": "^1.6.0",
+    "effect": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "npm@12.2.2"
+}

package/src/index.d.ts

@@ -0,0 +1,73 @@
+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 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 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 {
+  methodKind: infer Kind;
+  input: infer I extends DescMessage;
+  output: infer O extends DescMessage;
+}
+  ? Kind extends "unary"
+    ? (
+        request: MessageInitShape<I>,
+        options?: CallOptions,
+      ) => Effect.Effect<MessageShape<O>, TrevRpcError>
+    : Kind extends "server_streaming"
+      ? (
+          request: MessageInitShape<I>,
+          options?: CallOptions,
+        ) => 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;
+
+/** 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]>;
+};
+
+/**
+ * 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
+ * their requests from the stream as the transport accepts them. When the server ends the call
+ * first, the rest of the stream is not pulled, and the server's outcome is the result. A request
+ * stream that fails cancels the call, and the effect or stream fails with the request stream's
+ * error.
+ *
+ * Calls fail with a `TrevRpcError`; anything else a call rejects with becomes one with
+ * `Code.Unknown`, and with the original as `cause`.
+ *
+ * @throws TrevRpcError with `Code.InvalidArgument` where `createClient` throws it.
+ */
+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

@@ -0,0 +1,137 @@
+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`. */
+export function toTrevRpcError(error) {
+  if (error instanceof TrevRpcError) {
+    return error;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return new TrevRpcError(Code.Unknown, message, undefined, { cause: error });
+}
+
+/**
+ * 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, transport, options) {
+  const client = createClient(service, transport, options);
+  const result = {};
+  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({
+      try: (signal) => call(request, withSignal(options, signal)),
+      catch: toTrevRpcError,
+    });
+}
+
+function liftServerStreaming(call) {
+  return (request, options) =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const signal = yield* abortOnClose;
+        const responses = yield* open(() => call(request, withSignal(options, signal)));
+        return Stream.fromAsyncIterable(responses, toTrevRpcError);
+      }),
+    );
+}
+
+function liftClientStreaming(call) {
+  return (requests, options) =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const signal = yield* abortOnClose;
+        const stream = yield* open(() => call(withSignal(options, signal)));
+        // The server may answer before the upload is done; its status ends the upload, and
+        // closeAndRecv() reports the outcome.
+        yield* Effect.raceFirst(upload(stream, requests), settled(stream.status));
+        return yield* Effect.tryPromise({
+          try: () => stream.closeAndRecv(),
+          catch: toTrevRpcError,
+        });
+      }),
+    );
+}
+
+function liftBidirectionalStreaming(call) {
+  return (requests, options) =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const signal = yield* abortOnClose;
+        const stream = yield* open(() => call(withSignal(options, signal)));
+        const sending = upload(stream, requests).pipe(
+          // closeSend() resolves when the server already ended the call; any other failure is
+          // the response's to report.
+          Effect.andThen(Effect.promise(() => stream.closeSend().catch(ignore))),
+        );
+        // The responses decide when the stream ends: their end stops an unfinished upload,
+        // while a failed request stream fails the whole stream.
+        return Stream.merge(
+          Stream.fromAsyncIterable(stream, toTrevRpcError),
+          Stream.drain(Stream.fromEffect(sending)),
+          { haltStrategy: "left" },
+        );
+      }),
+    );
+}
+
+/**
+ * A signal that aborts when the scope closes, cancelling a call that has not finished: on
+ * interruption, on failure, and after the call ended, when aborting has no effect.
+ */
+const abortOnClose = Effect.map(
+  Effect.acquireRelease(
+    Effect.sync(() => new AbortController()),
+    (controller) => Effect.sync(() => controller.abort()),
+  ),
+  (controller) => controller.signal,
+);
+
+/** Starts a call, whose promise settles once the call is open. */
+function open(start) {
+  return Effect.tryPromise({ try: start, catch: toTrevRpcError });
+}
+
+/** The call options with `signal` added to the caller's own, either of which cancels the call. */
+function withSignal(options, signal) {
+  const own = options?.signal;
+  return { ...options, signal: own ? AbortSignal.any([own, signal]) : signal };
+}
+
+/**
+ * Sends each request of `requests`, waiting for the transport to accept it. Stops without an error
+ * at the first rejected send, which means the call has ended; the call reports its outcome. A
+ * failing request stream fails with its error, and the caller's scope then cancels the call.
+ */
+function upload(stream, requests) {
+  return Stream.runForEachWhile(requests, (request) =>
+    Effect.promise(() => stream.send(request).then(accepted, rejected)),
+  );
+}
+
+/** Succeeds once `promise` settles, whatever its outcome. */
+function settled(promise) {
+  return Effect.promise(() => promise.then(ignore, ignore));
+}
+
+const accepted = () => true;
+const rejected = () => false;
+const ignore = () => {};