RpcClient
Runs typed RPC calls from the client side.
This module turns RPC definitions from an RpcGroup into callable client
methods. Each call encodes its payload, sends a message through the active
Protocol, decodes exits or stream chunks from the server, and routes the
response back to the waiting Effect, Stream, or queue. It also defines
the protocol service and includes protocol layers for HTTP, sockets, and
workers.
Constructors
Creates a schema-aware RPC client for a group using the current client
Protocol, encoding requests and decoding server responses.
Signature
declare const make: <Rpcs extends Rpc.Any, Flatten extends boolean = false>(group: RpcGroup.RpcGroup<Rpcs>, options?: { readonly disableTracing?: boolean; readonly flatten?: Flatten; readonly generateRequestId?: () => RequestId; readonly spanAttributes?: Record<string, unknown>; readonly spanPrefix?: string;}) => Effect.Effect<Flatten extends true ? RpcClient.Flat<Rpcs, RpcClientError> : RpcClient<Rpcs, RpcClientError>, never, Protocol | Rpc.MiddlewareClient<Rpcs> | Scope.Scope>makeNoSerialization
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.
Signature
declare const makeNoSerialization: <Rpcs extends Rpc.Any, E, Flatten extends boolean = false>(group: RpcGroup.RpcGroup<Rpcs>, options: { readonly disableTracing?: boolean; readonly flatten?: Flatten; readonly generateRequestId?: () => RequestId; readonly onFromClient: (options: { readonly context: Context.Context<never>; readonly discard: boolean; readonly message: FromClient<Rpcs>; }) => Effect.Effect<void, E>; readonly spanAttributes?: Record<string, unknown>; readonly spanPrefix?: string; readonly supportsAck?: boolean;}) => Effect.Effect<{ readonly client: Flatten extends true ? RpcClient.Flat<Rpcs, E> : RpcClient<Rpcs, E>; readonly write: (message: FromServer<Rpcs>) => Effect.Effect<void>;}, never, Scope.Scope | Rpc.MiddlewareClient<Rpcs>>Headers
withHeaders
Runs an effect with additional RPC client headers, merging them with the
current CurrentHeaders value for outgoing requests.
Signature
declare const withHeaders: { (headers: Input): <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>; <A, E, R>(effect: Effect<A, E, R>, headers: Input): Effect<A, E, R>;}Layers
layerProtocolHttp
Provides a client Protocol backed by HttpClient, targeting the configured
URL and optionally transforming the client before use.
Signature
declare function layerProtocolHttp(options: { readonly transformClient?: <E, R>(client: With<E, R>) => With<E, R>; readonly url: string;}): Layer<Protocol, never, RpcSerialization | HttpClient>layerProtocolSocket
Provides a client Protocol backed by the current Socket and
RpcSerialization services.
Signature
declare function layerProtocolSocket(options?: { readonly onTransientError?: (error: RpcClientError) => Effect<void>; readonly retryTransientErrors?: boolean;}): Layer<Protocol, never, RpcSerialization | Socket>layerProtocolWorker
Provides a client Protocol backed by a worker pool using the current worker
platform and spawner services.
Signature
declare const layerProtocolWorker: (options: { readonly concurrency?: number; readonly size: number; readonly targetUtilization?: number;} | { readonly concurrency?: number; readonly maxSize: number; readonly minSize: number; readonly targetUtilization?: number; readonly timeToLive: Duration.Input;}) => Layer.Layer<Protocol, WorkerError, Worker.WorkerPlatform | Worker.Spawner>Other
Protocols
makeProtocolHttp
Creates a client Protocol that sends each RPC request through the supplied
HttpClient and decodes responses with the current RpcSerialization.
Signature
declare function makeProtocolHttp(client: HttpClient): Effect<{ readonly codecFor: CodecFor; readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>; readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>; readonly supportsAck: boolean; readonly supportsTransferables: boolean;}, never, RpcSerialization>makeProtocolSocket
Creates a client Protocol over the current Socket, using the current
RpcSerialization, connection hooks, ping timeouts, and the configured retry
policy.
Signature
declare function makeProtocolSocket(options?: { readonly onTransientError?: (error: RpcClientError) => Effect<void>; readonly retryPolicy?: Schedule<any, SocketError, never, never>; readonly retryTransientErrors?: boolean;}): Effect<{ readonly codecFor: CodecFor; readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>; readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>; readonly supportsAck: boolean; readonly supportsTransferables: boolean;}, never, Scope | RpcSerialization | Socket>makeProtocolWorker
Creates a client Protocol backed by a pool of workers, routing RPC requests
to workers and supporting transferable values when the platform does.
Signature
declare function makeProtocolWorker(options: { readonly concurrency?: number; readonly size: number; readonly targetUtilization?: number;} | { readonly concurrency?: number; readonly maxSize: number; readonly minSize: number; readonly targetUtilization?: number; readonly timeToLive: Input;}): Effect<{ readonly codecFor: CodecFor; readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>; readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>; readonly supportsAck: boolean; readonly supportsTransferables: boolean;}, WorkerError, Scope | WorkerPlatform | Spawner>Services
ConnectionHooks
Represents optional client protocol hooks that run when a transport connects and disconnects.
When to use
Use to run setup or cleanup effects when an RPC client transport opens or closes.
Signature
declare class ConnectionHooks extends Shape<"effect/rpc/RpcClient/ConnectionHooks", { readonly onConnect: Effect<void>; readonly onDisconnect: Effect<void>;}, this> { constructor(_: never);}CurrentHeaders
Fiber reference containing headers that are merged into outgoing RPC client requests.
When to use
Use to set request headers that should be automatically merged into outgoing RPC client messages.
Signature
declare const CurrentHeaders: Reference<Headers>Defines the service interface for an RPC client transport, responsible for running the receive loop and sending encoded client messages.
When to use
Use to provide the transport boundary for RPC clients over HTTP, WebSocket, workers, sockets, or custom protocols.
Signature
declare class Protocol extends Shape<"effect/rpc/RpcClient/Protocol", { readonly codecFor: CodecFor; readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>; readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>; readonly supportsAck: boolean; readonly supportsTransferables: boolean;}, this> { constructor(_: never); static make: <EX, RX>(f: (write: (clientId: number, response: FromServerEncoded) => Effect<void>, clientIds: ReadonlySet<number>) => Effect<Omit<{ readonly codecFor: CodecFor; readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>; readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>; readonly supportsAck: boolean; readonly supportsTransferables: boolean; }, "run">, EX, RX>) => Effect<{ readonly codecFor: CodecFor; readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>; readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>; readonly supportsAck: boolean; readonly supportsTransferables: boolean; }, EX, RX>;}Utility Types
Derives the object-shaped RPC client type for all RPCs contained in an
RpcGroup.
Signature
type FromGroup<Group, E = never> = RpcClient<RpcGroup.Rpcs<Group>, E>The object-shaped client generated from a union of RPC definitions, with one method per RPC tag.
Signature
type RpcClient<Rpcs extends Rpc.Any, E = never> = Struct.Simplify<RpcClient.From<Rpcs, E>>