RpcGroup

Collects typed RPC definitions and server handlers.

An RpcGroup stores RPC definitions by tag and keeps annotations shared by the group. This module provides helpers for composing groups, applying middleware or annotations, deriving handler types, and turning handler objects into Context or Layer values used by RPC servers.

8 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Creates an RpcGroup from one or more RPC definitions.

Signature

declare function make<Rpcs extends readonly Array<Any>>(...rpcs: Rpcs): RpcGroup<Rpcs[number]>

Models

RpcGroup interface

Added in v4.0.0 Source

A collection of RPC definitions that can be composed, annotated, and converted into server handlers or layers.

Signature

interface RpcGroup<in out R extends Rpc.Any> extends Pipeable {
  constructor(_: never);
  readonly "~effect/rpc/RpcGroup": "~effect/rpc/RpcGroup";
  readonly annotations: Context<never>;
  readonly requests: ReadonlyMap<string, R>;
  accessHandler<Tag extends string>(tag: Tag): Effect<(payload: Payload<Extract<R, {
    readonly _tag: Tag;
  }>>, options: {
    readonly client: ServerClient;
    readonly headers: Headers;
    readonly requestId: RequestId;
  }) => ResultFrom<Extract<R, {
    readonly _tag: Tag;
  }>, never>, never, Handler<Tag>>;
  add<Rpcs2 extends readonly Array<Any>>(...rpcs: Rpcs2): RpcGroup<R | Rpcs2[number]>;
  annotate<I, S>(service: Key<I, S>, value: S): RpcGroup<R>;
  annotateMerge<S>(annotations: Context<S>): RpcGroup<R>;
  annotateRpcs<I, S>(service: Key<I, S>, value: S): RpcGroup<R>;
  annotateRpcsMerge<S>(annotations: Context<S>): RpcGroup<R>;
  merge<Groups extends readonly Array<Any>>(...groups: Groups): RpcGroup<R | Rpcs<Groups[number]>>;
  middleware<M extends AnyService>(middleware: M): RpcGroup<AddMiddleware<R, M>>;
  of<Handlers extends HandlersFrom<R>>(handlers: Handlers): Handlers;
  omit<Tags extends readonly Array<R["_tag"]>>(...tags: Tags): RpcGroup<Exclude<R, {
    readonly _tag: Tags[number];
  }>>;
  prefix<Prefix extends string>(prefix: Prefix): RpcGroup<Prefixed<R, Prefix>>;
  toHandlers<Handlers extends HandlersFrom<R>, EX = never, RX = never>(build: Handlers | Effect<Handlers, EX, RX>): Effect<Context<ToHandler<R>>, EX, RX | HandlersServices<R, Handlers>>;
  toLayer<Handlers extends HandlersFrom<R>, EX = never, RX = never>(build: Handlers | Effect<Handlers, EX, RX>): Layer<ToHandler<R>, EX, Exclude<RX, Scope> | HandlersServices<R, Handlers>>;
  toLayerHandler<Tag extends string, Handler extends never, EX = never, RX = never>(tag: Tag, build: Handler | Effect<Handler, EX, RX>): Layer<Handler<Tag>, EX, Exclude<RX, Scope> | HandlerServices<R, Tag, Handler>>;
}

Utility Types

Any interface

Added in v4.0.0 Source

An erased RpcGroup type for APIs that only need to know that a value is an RPC group.

Signature

interface Any {
  readonly "~effect/rpc/RpcGroup": "~effect/rpc/RpcGroup";
}

HandlerFrom type

Added in v4.0.0 Source

Extracts the server handler function type for a specific RPC tag from an RPC union.

Signature

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

HandlerServices type

Added in v4.0.0 Source

Computes the services required by a single RPC handler, excluding services provided by middleware and Scope where the server supplies it.

Signature

type HandlerServices<Rpcs extends Rpc.Any, K extends Rpcs["_tag"], Handler> = true extends Rpc.IsStream<Rpcs, K> ? Handler extends (...args: any) => Stream.Stream<infer _A, infer _E, infer _R> | Rpc.Wrapper<Stream.Stream<infer _A, infer _E, infer _R>> | Effect.Effect<Queue.Dequeue<infer _A, infer _E | Cause.Done>, infer _EX, infer _R> | Rpc.Wrapper<Effect.Effect<Queue.Dequeue<infer _A, infer _E | Cause.Done>, infer _EX, infer _R>> ? Exclude<Rpc.ExcludeProvides<_R, Rpcs, K>, Scope> | Rpc.ExtractRequires<Rpcs, K> : never : Handler extends (...args: any) => Effect.Effect<infer _A, infer _E, infer _R> | Rpc.Wrapper<Effect.Effect<infer _A, infer _E, infer _R>> ? Exclude<Rpc.ExcludeProvides<_R, Rpcs, K>, Scope> | Rpc.ExtractRequires<Rpcs, K> : never

HandlersFrom type

Added in v4.0.0 Source

Builds the object type of server handler functions required to implement each RPC in a union.

Signature

type HandlersFrom<Rpc extends Rpc.Any> = { [Current in Rpc]: Rpc.ToHandlerFn<Current> }

HandlersServices type

Added in v4.0.0 Source

Computes the services required by all handlers in a handler object for an RPC union.

Signature

type HandlersServices<Rpcs extends Rpc.Any, Handlers> = keyof Handlers extends infer K ? K extends keyof Handlers & string ? HandlerServices<Rpcs, K, Handlers[K]> : never : never

Rpcs type

Added in v4.0.0 Source

Extracts the union of RPC definitions from an RpcGroup.

Signature

type Rpcs<Group> = Group extends RpcGroup<infer R> ? string extends R["_tag"] ? never : R : never