effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/unstable/rpc/RpcClient.ts

@@ -1,4 +1,30 @@
 /**
+ * Client-side support for calling RPCs defined in an `RpcGroup`.
+ *
+ * This module derives typed client APIs from RPC definitions, turns method
+ * calls into request messages, and routes server responses back to the waiting
+ * `Effect` or `Stream`. Use it to construct schema-aware clients over the
+ * provided HTTP, socket, and worker transports, or use `makeNoSerialization`
+ * when an already-decoded message channel should participate in the same
+ * request, interruption, acknowledgement, and streaming lifecycle.
+ *
+ * The `make` constructor requires a `Protocol`, which owns the encoded
+ * transport. HTTP sends one request per call and does not support client
+ * acknowledgements, while socket and worker protocols keep receive loops alive,
+ * support streaming acknowledgements, and can fail in-flight requests with
+ * protocol errors. Streaming RPCs return `Stream`s by default, or scoped
+ * queues when `asQueue` is enabled, so `streamBufferSize` controls the client
+ * side of streaming back pressure.
+ *
+ * Payloads, exits, and stream chunks are encoded and decoded through the RPC
+ * schemas with the active `RpcSerialization`; any schema services required by
+ * those codecs remain part of the generated client method environments.
+ * Client middleware declared on an RPC is looked up from
+ * `Rpc.MiddlewareClient`, can rewrite or short-circuit outgoing requests, and
+ * contributes its client error type to the call signature. Outgoing request
+ * headers combine `CurrentHeaders` with per-call headers before the request is
+ * passed through middleware and then to the transport.
+ *
  * @since 4.0.0
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
@@ -42,19 +68,28 @@ import * as RpcWorker from "./RpcWorker.ts"
 import { withRunClient } from "./Utils.ts"
 
 /**
- * @since 4.0.0
+ * The object-shaped client generated from a union of RPC definitions, with one
+ * method per RPC tag.
+ *
  * @category client
+ * @since 4.0.0
  */
 export type RpcClient<Rpcs extends Rpc.Any, E = never> = Struct.Simplify<RpcClient.From<Rpcs, E>>
 
 /**
+ * Type-level helpers for deriving RPC client call signatures from RPC
+ * definitions.
+ *
  * @since 4.0.0
- * @category client
  */
 export declare namespace RpcClient {
   /**
-   * @since 4.0.0
+   * Builds an object client type from an RPC union, mapping each RPC tag to a
+   * method that accepts the RPC payload and returns either an `Effect` or
+   * `Stream` based on the RPC success schema.
+   *
    * @category client
+   * @since 4.0.0
    */
   export type From<Rpcs extends Rpc.Any, E = never> = {
     readonly [Current in Rpcs as Current["_tag"]]: <
@@ -115,8 +150,11 @@ export declare namespace RpcClient {
   }
 
   /**
-   * @since 4.0.0
+   * Builds a flattened RPC client function that accepts an RPC tag and payload,
+   * returning the corresponding `Effect` or `Stream` for that RPC.
+   *
    * @category client
+   * @since 4.0.0
    */
   export type Flat<Rpcs extends Rpc.Any, E = never> = <
     const Tag extends Rpcs["_tag"],
@@ -175,16 +213,23 @@ export declare namespace RpcClient {
 }
 
 /**
- * @since 4.0.0
+ * Derives the object-shaped RPC client type for all RPCs contained in an
+ * `RpcGroup`.
+ *
  * @category client
+ * @since 4.0.0
  */
 export type FromGroup<Group, E = never> = RpcClient<RpcGroup.Rpcs<Group>, E>
 
 let requestIdCounter = BigInt(0)
 
 /**
- * @since 4.0.0
+ * Creates an RPC client for an already-decoded message channel, returning the
+ * client API together with a `write` function for delivering server messages
+ * back to the client.
+ *
  * @category client
+ * @since 4.0.0
  */
 export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extends boolean = false>(
   group: RpcGroup.RpcGroup<Rpcs>,
@@ -590,8 +635,11 @@ export const makeNoSerialization: <Rpcs extends Rpc.Any, E, const Flatten extend
 let clientIdCounter = 0
 
 /**
- * @since 4.0.0
+ * Creates a schema-aware RPC client for a group using the current client
+ * `Protocol`, encoding requests and decoding server responses.
+ *
  * @category client
+ * @since 4.0.0
  */
 export const make: <Rpcs extends Rpc.Any, const Flatten extends boolean = false>(
   group: RpcGroup.RpcGroup<Rpcs>,
@@ -767,26 +815,38 @@ const rpcSchemas = (rpc: Rpc.AnyWithProps) => {
 }
 
 /**
- * @since 4.0.0
+ * A fiber-local reference containing headers that are merged into outgoing RPC
+ * client requests.
+ *
  * @category headers
+ * @since 4.0.0
  */
 export const CurrentHeaders = Context.Reference<Headers.Headers>("effect/rpc/RpcClient/CurrentHeaders", {
   defaultValue: () => Headers.empty
 })
 
 /**
- * @since 4.0.0
+ * Runs an effect with additional RPC client headers, merging them with the
+ * current `CurrentHeaders` value for outgoing requests.
+ *
  * @category headers
+ * @since 4.0.0
  */
 export const withHeaders: {
   /**
-   * @since 4.0.0
+   * Runs an effect with additional RPC client headers, merging them with the
+   * current `CurrentHeaders` value for outgoing requests.
+   *
    * @category headers
+   * @since 4.0.0
    */
   (headers: Headers.Input): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * @since 4.0.0
+   * Runs an effect with additional RPC client headers, merging them with the
+   * current `CurrentHeaders` value for outgoing requests.
+   *
    * @category headers
+   * @since 4.0.0
    */
   <A, E, R>(effect: Effect.Effect<A, E, R>, headers: Headers.Input): Effect.Effect<A, E, R>
 } = dual(
@@ -796,8 +856,11 @@ export const withHeaders: {
 )
 
 /**
- * @since 4.0.0
+ * Service interface for an RPC client transport, responsible for running the
+ * receive loop and sending encoded client messages.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export class Protocol extends Context.Service<Protocol, {
   readonly run: (
@@ -813,14 +876,19 @@ export class Protocol extends Context.Service<Protocol, {
   readonly supportsTransferables: boolean
 }>()("effect/rpc/RpcClient/Protocol") {
   /**
+   * Creates a client protocol service from the supplied RPC request runner.
+   *
    * @since 4.0.0
    */
   static make = withRunClient
 }
 
 /**
- * @since 4.0.0
+ * Creates a client `Protocol` that sends each RPC request through the supplied
+ * `HttpClient` and decodes responses with the current `RpcSerialization`.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const makeProtocolHttp = (client: HttpClient.HttpClient): Effect.Effect<
   Protocol["Service"],
@@ -907,8 +975,11 @@ export const makeProtocolHttp = (client: HttpClient.HttpClient): Effect.Effect<
   }))
 
 /**
- * @since 4.0.0
+ * Provides a client `Protocol` backed by `HttpClient`, targeting the configured
+ * URL and optionally transforming the client before use.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const layerProtocolHttp = (options: {
   readonly url: string
@@ -925,8 +996,12 @@ export const layerProtocolHttp = (options: {
   )
 
 /**
- * @since 4.0.0
+ * Creates a client `Protocol` over the current `Socket`, using the current
+ * `RpcSerialization`, connection hooks, ping timeouts, and the configured retry
+ * policy.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const makeProtocolSocket = (options?: {
   readonly retryTransientErrors?: boolean | undefined
@@ -1089,8 +1164,11 @@ const makePinger = Effect.fnUntraced(function*<A, E, R>(writePing: Effect.Effect
 })
 
 /**
- * @since 4.0.0
+ * Provides a client `Protocol` backed by the current `Socket` and
+ * `RpcSerialization` services.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const layerProtocolSocket = (options?: {
   readonly retryTransientErrors?: boolean | undefined
@@ -1101,8 +1179,11 @@ export const layerProtocolSocket = (options?: {
 > => Layer.effect(Protocol)(makeProtocolSocket(options))
 
 /**
- * @since 4.0.0
+ * Creates a client `Protocol` backed by a pool of workers, routing RPC requests
+ * to workers and supporting transferable values when the platform does.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const makeProtocolWorker = (
   options: {
@@ -1264,8 +1345,11 @@ export const makeProtocolWorker = (
   }))
 
 /**
- * @since 4.0.0
+ * Provides a client `Protocol` backed by a worker pool using the current worker
+ * platform and spawner services.
+ *
  * @category protocol
+ * @since 4.0.0
  */
 export const layerProtocolWorker: (
   options: {
@@ -1286,8 +1370,11 @@ export const layerProtocolWorker: (
 > = flow(makeProtocolWorker, Layer.effect(Protocol))
 
 /**
- * @since 4.0.0
+ * Optional client protocol hooks that run when a transport connects and
+ * disconnects.
+ *
  * @category ConnectionHooks
+ * @since 4.0.0
  */
 export class ConnectionHooks extends Context.Service<ConnectionHooks, {
   readonly onConnect: Effect.Effect<void>

package/src/unstable/rpc/RpcClientError.ts

@@ -1,4 +1,20 @@
 /**
+ * Shared error types for the RPC client protocol layer.
+ *
+ * This module defines the client-side failures added to schema-aware RPC
+ * clients. `RpcClientError` wraps transport failures from the built-in HTTP,
+ * socket, and worker protocols, while `RpcClientDefect` records protocol
+ * problems such as empty HTTP responses, malformed response batches, failed
+ * transport decoding, or unexpected connection failures.
+ *
+ * These errors are separate from a remote handler's typed error. Remote
+ * failures that match an RPC's error schema are decoded from the RPC exit and
+ * remain part of the procedure's domain error channel. Server defects and
+ * schema mismatches are not normal remote errors: they surface as defects or
+ * protocol failures, so handlers commonly inspect `RpcClientError.reason` to
+ * decide whether a failure is retryable transport trouble or an incompatible
+ * client/server schema or serialization boundary.
+ *
  * @since 4.0.0
  */
 import * as Schema from "../../Schema.ts"
@@ -9,8 +25,11 @@ import { WorkerErrorReason } from "../workers/WorkerError.ts"
 const TypeId = "~effect/rpc/RpcClientError"
 
 /**
+ * Represents a client-side RPC defect, such as a protocol violation or
+ * decoding failure, with a message and original cause.
+ *
+ * @category errors
  * @since 4.0.0
- * @category Errors
  */
 export class RpcClientDefect extends Schema.ErrorClass<RpcClientDefect>("effect/rpc/RpcClientError/RpcClientDefect")({
   _tag: Schema.tag("RpcClientDefect"),
@@ -19,8 +38,11 @@ export class RpcClientDefect extends Schema.ErrorClass<RpcClientDefect>("effect/
 }) {}
 
 /**
+ * The public RPC client error type, wrapping worker, socket, HTTP client, and
+ * client protocol defect failures.
+ *
+ * @category errors
  * @since 4.0.0
- * @category Errors
  */
 export class RpcClientError extends Schema.ErrorClass<RpcClientError>(TypeId)({
   _tag: Schema.tag("RpcClientError"),
@@ -32,6 +54,8 @@ export class RpcClientError extends Schema.ErrorClass<RpcClientError>(TypeId)({
   ])
 }) {
   /**
+   * Marks this value as an RPC client error for runtime guards.
+   *
    * @since 4.0.0
    */
   readonly [TypeId] = TypeId

package/src/unstable/rpc/RpcGroup.ts

@@ -1,4 +1,25 @@
 /**
+ * Groups typed `Rpc` definitions into a protocol that can be shared by
+ * clients, servers, tests, cluster entities, workflows, and other RPC
+ * integrations.
+ *
+ * An `RpcGroup` keeps RPC definitions keyed by their tags while preserving the
+ * payload, success, error, defect, middleware, and annotation metadata carried
+ * by each `Rpc`. Build groups with `make`, extend them with `add`, combine them
+ * with `merge`, remove calls with `omit`, and turn the final protocol into
+ * handler contexts or layers with `toHandlers`, `toLayer`, or `toLayerHandler`.
+ *
+ * Common uses include defining a service surface once and deriving both client
+ * and server implementations from it, splitting a large protocol into feature
+ * groups that are merged later, prefixing generated or proxied RPC names, and
+ * attaching metadata for higher-level runtimes. Composition order matters:
+ * `middleware` and `annotateRpcs` update only the RPCs currently in the group,
+ * duplicate tags from `add` or `merge` replace the existing definition, and
+ * handlers are keyed by the tags after any prefixing. Schema requirements still
+ * come from each RPC's payload, success, error, defect, and middleware schemas;
+ * grouping preserves those requirements but does not provide the services
+ * needed to encode, decode, or handle them.
+ *
  * @since 4.0.0
  */
 import type * as Cause from "../../Cause.ts"
@@ -19,8 +40,11 @@ import type * as RpcMiddleware from "./RpcMiddleware.ts"
 const TypeId = "~effect/rpc/RpcGroup"
 
 /**
- * @since 4.0.0
+ * A collection of RPC definitions that can be composed, annotated, and
+ * converted into server handlers or layers.
+ *
  * @category groups
+ * @since 4.0.0
  */
 export interface RpcGroup<in out R extends Rpc.Any> extends Pipeable {
   new(_: never): {}
@@ -157,39 +181,54 @@ export interface RpcGroup<in out R extends Rpc.Any> extends Pipeable {
 }
 
 /**
- * @since 4.0.0
+ * An erased `RpcGroup` type for APIs that only need to know that a value is an
+ * RPC group.
+ *
  * @category groups
+ * @since 4.0.0
  */
 export interface Any {
   readonly [TypeId]: typeof TypeId
 }
 
 /**
- * @since 4.0.0
+ * Builds the object type of server handler functions required to implement each
+ * RPC in a union.
+ *
  * @category groups
+ * @since 4.0.0
  */
 export type HandlersFrom<Rpc extends Rpc.Any> = {
   readonly [Current in Rpc as Current["_tag"]]: Rpc.ToHandlerFn<Current>
 }
 
 /**
- * @since 4.0.0
+ * Extracts the server handler function type for a specific RPC tag from an RPC
+ * union.
+ *
  * @category groups
+ * @since 4.0.0
  */
 export type HandlerFrom<Rpc extends Rpc.Any, Tag extends Rpc["_tag"]> = Extract<Rpc, { readonly _tag: Tag }> extends
   infer Current ? Current extends Rpc.Any ? Rpc.ToHandlerFn<Current> : never : never
 
 /**
- * @since 4.0.0
+ * Computes the services required by all handlers in a handler object for an RPC
+ * union.
+ *
  * @category groups
+ * @since 4.0.0
  */
 export type HandlersServices<Rpcs extends Rpc.Any, Handlers> = keyof Handlers extends infer K ?
   K extends keyof Handlers & string ? HandlerServices<Rpcs, K, Handlers[K]> : never :
   never
 
 /**
- * @since 4.0.0
+ * Computes the services required by a single RPC handler, excluding services
+ * provided by middleware and `Scope` where the server supplies it.
+ *
  * @category groups
+ * @since 4.0.0
  */
 export type HandlerServices<Rpcs extends Rpc.Any, K extends Rpcs["_tag"], Handler> = true extends
   Rpc.IsStream<Rpcs, K> ? Handler extends (...args: any) =>
@@ -215,8 +254,10 @@ export type HandlerServices<Rpcs extends Rpc.Any, K extends Rpcs["_tag"], Handle
   : never
 
 /**
- * @since 4.0.0
+ * Extracts the union of RPC definitions from an `RpcGroup`.
+ *
  * @category groups
+ * @since 4.0.0
  */
 export type Rpcs<Group> = Group extends RpcGroup<infer R> ? string extends R["_tag"] ? never : R : never
 
@@ -368,8 +409,10 @@ const makeProto = <Rpcs extends Rpc.Any>(options: {
   }) as any
 
 /**
- * @since 4.0.0
+ * Creates an `RpcGroup` from one or more RPC definitions.
+ *
  * @category groups
+ * @since 4.0.0
  */
 export const make = <const Rpcs extends ReadonlyArray<Rpc.Any>>(
   ...rpcs: Rpcs