RpcMiddleware
Middleware services for the unstable RPC runtime.
A middleware service wraps server handler execution and can also install a client-side wrapper for generated clients. Its metadata records the services provided to downstream handlers, the services required by the middleware implementation, the schema for server-visible failures, the client-only error type, and whether generated clients must require the matching client layer.
Constructors
Signature
declare function Service<
Self,
Config extends {
clientError?: any;
provides?: any;
requires?: any;
} = {
clientError: never;
provides: never;
requires: never;
},
>(): <Name extends string, Error extends Top = Never, RequiredForClient extends boolean = false>(
id: Name,
options?: {
readonly error?: Error;
readonly requiredForClient?: RequiredForClient;
},
) => ServiceClass<
Self,
Name,
"provides" extends keyof Config ? Config["provides"] : never,
Error,
"clientError" extends keyof Config ? Config["clientError"] : never,
"requires" extends keyof Config ? Config["requires"] : never,
RequiredForClient
>;Layers
layerClient
Provides the client-side implementation for an RPC middleware service, capturing the layer's environment and merging it into each middleware invocation.
Signature
declare function layerClient<Id extends AnyId, S, R, EX = never, RX = never>(
tag: Key<Id, S>,
service:
| RpcMiddlewareClient<
Id["~effect/rpc/RpcMiddleware"]["error"]["Type"],
Id["~effect/rpc/RpcMiddleware"]["clientError"],
R
>
| Effect<
RpcMiddlewareClient<
Id["~effect/rpc/RpcMiddleware"]["error"]["Type"],
Id["~effect/rpc/RpcMiddleware"]["clientError"],
R
>,
EX,
RX
>,
): Layer<ForClient<Id>, EX, R | Exclude<RX, Scope>>;Models
An erased server-side RPC middleware function, useful when the concrete provided services, errors, and requirements are not needed.
Signature
interface Any {
(
effect: Effect<SuccessValue, any, any>,
options: {
readonly client: ServerClient;
readonly headers: Headers;
readonly payload: unknown;
readonly requestId: RequestId;
readonly rpc: AnyWithProps;
},
): Effect<SuccessValue, any, any>;
}AnyService interface
An erased RPC middleware context key carrying middleware metadata.
Signature
interface AnyService extends Key<any, any> {
readonly "~ClientError": any;
readonly "~effect/rpc/RpcMiddleware": "~effect/rpc/RpcMiddleware";
readonly error: Top;
readonly requiredForClient: boolean;
}AnyServiceWithProps interface
An erased RPC middleware context key whose service value is a server-side middleware function.
Signature
interface AnyServiceWithProps extends Key<any, RpcMiddleware<any, any, any>> {
readonly "~ClientError": any;
readonly "~effect/rpc/RpcMiddleware": "~effect/rpc/RpcMiddleware";
readonly error: Top;
readonly requiredForClient: boolean;
}Marker service requirement indicating that a middleware has a client-side implementation available for an RPC client.
Signature
interface ForClient<Id> {
readonly _: typeof _;
readonly id: Id;
}RpcMiddleware interface
The server-side RPC middleware function shape, wrapping a handler effect with access to request metadata and translating provided services into required services.
Signature
interface RpcMiddleware<Provides, E, Requires> {
(
effect: Effect<SuccessValue, unhandled | E, Provides>,
options: {
readonly client: ServerClient;
readonly headers: Headers;
readonly payload: unknown;
readonly requestId: RequestId;
readonly rpc: AnyWithProps;
},
): Effect<SuccessValue, unhandled | E, Scope | Requires>;
}RpcMiddlewareClient interface
The client-side RPC middleware function shape, allowing outgoing requests to be inspected or modified before calling next.
Signature
interface RpcMiddlewareClient<E, CE, R> {
(options: {
readonly next: (request: Request<Any>) => Effect<SuccessValue, unhandled | E>;
readonly request: Request<Any>;
readonly rpc: AnyWithProps;
}): Effect<SuccessValue, unhandled | E | CE, R>;
}SuccessValue interface
Marker success type used by RPC middleware to represent successful completion without exposing the handler's concrete success value.
Signature
interface SuccessValue {
readonly _: typeof _;
}Services
ServiceClass interface
The Context.Service class shape created for an RPC middleware, including its error schema, service metadata, and client-side requirement marker.
Signature
interface ServiceClass<
Self,
Name extends string,
Provides,
E extends Schema.Constraint,
ClientError,
Requires,
RequiredForClient extends boolean,
> extends Service<Self, RpcMiddleware<Provides, E["Type"], Requires>> {
constructor(_: never);
readonly "~ClientError": ClientError;
readonly "~effect/rpc/RpcMiddleware": "~effect/rpc/RpcMiddleware";
readonly error: E;
readonly requiredForClient: RequiredForClient;
}Type IDs
The runtime type id used to attach and inspect RPC middleware metadata.
Signature
declare const TypeId: "~effect/rpc/RpcMiddleware";The literal type id used to identify RPC middleware service classes.
Signature
type TypeId = "~effect/rpc/RpcMiddleware";Utility Types
A type-level carrier for RPC middleware metadata, including provided services, required services, error schema, and client error type.
Signature
interface AnyId {
readonly "~effect/rpc/RpcMiddleware": {
readonly clientError: any;
readonly error: Top;
readonly provides: any;
readonly requires: any;
};
}ApplyServices type
Applies a middleware's service transformation to an RPC environment by removing services the middleware provides and adding services it requires.
Signature
type ApplyServices<A, R> = Exclude<R, Provides<A>> | Requires<A>;Extracts the decoded error type produced by an RPC middleware.
Signature
type Error<A> = ErrorSchema<A>["Type"];ErrorSchema type
Extracts the error schema associated with an RPC middleware.
Signature
type ErrorSchema<A> = A extends {
readonly "~effect/rpc/RpcMiddleware": {
readonly error: infer E;
};
}
? E extends Schema.Constraint
? E
: never
: never;ErrorServicesDecode type
Extracts the decoding services required by a middleware's error schema.
Signature
type ErrorServicesDecode<A> = ErrorSchema<A>["DecodingServices"];ErrorServicesEncode type
Extracts the encoding services required by a middleware's error schema.
Signature
type ErrorServicesEncode<A> = ErrorSchema<A>["EncodingServices"];Extracts the services provided by an RPC middleware.
Signature
type Provides<A> = A extends {
readonly "~effect/rpc/RpcMiddleware": {
readonly provides: infer P;
};
}
? P
: never;Extracts the services required by an RPC middleware.
Signature
type Requires<A> = A extends {
readonly "~effect/rpc/RpcMiddleware": {
readonly requires: infer R;
};
}
? R
: never;
Creates a typed RPC middleware service class, with optional service requirements, provided services, error schema, and client-side requirement metadata.