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
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 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 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 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 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 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 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>>;
Creates a schema-aware RPC client for a group using the current client
Protocol, encoding requests and decoding server responses.