@trevrpc/effect 0.0.0-stage → 1.5.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 wraps a generated client so that its calls are effects and streams.
+
+```sh
+npm install @trevrpc/effect @trevrpc/trevrpc-js effect
+```
+
+```ts
+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";
+
+const channel = createChannel("https://example.com/trevrpc");
+const greeter = createEffectClient(GreeterService, new GreeterClient(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, client)` takes the generated descriptor and client, and returns a client with the same method names:
+
+| 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,54 @@
 {
   "name": "@trevrpc/effect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.5.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": {
+    "@trevrpc/trevrpc-js": "file:..",
+    "effect": "^4.1.2",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "@trevrpc/trevrpc-js": "^1.5.0",
+    "effect": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "npm@12.2.1"
+}

package/src/index.d.ts

@@ -0,0 +1,73 @@
+import type {
+  BidirectionalStreamingCall,
+  CallOptions,
+  ClientStreamingCall,
+  ResponseStream,
+  RpcServiceDescriptor,
+  TrevRpcError,
+} from "@trevrpc/trevrpc-js";
+import type { Effect, Stream } from "effect";
+
+/**
+ * The Effect form of a generated client method:
+ *
+ * - 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.
+ */
+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 (
+        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,
+          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;
+
+/** 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]
+  >;
+};
+
+/**
+ * Wraps a generated client's methods in Effect. `service` is the client's generated descriptor,
+ * such as `GreeterService` for a `GreeterClient`.
+ *
+ * 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 TypeError if `client` lacks a method of `service`.
+ */
+export function createEffectClient<Client extends object>(
+  service: RpcServiceDescriptor,
+  client: Client,
+): EffectClient<Client>;
+
+/** 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,146 @@
+import { Code, TrevRpcError } 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 });
+}
+
+/**
+ * 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.
+ */
+export function createEffectClient(service, client) {
+  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}`,
+        );
+    }
+  }
+  return result;
+}
+
+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 = () => {};