Skip to content

Rpc.ts

Rpc.ts overview

Defines schema-backed contracts for individual RPC procedures.

An Rpc describes one remote procedure by recording its tag, payload schema, success schema, error schema, defect schema, middleware, and annotations. Clients and servers read the same declaration, so the procedure contract is independent of the transport used to call it. This module includes constructors, type helpers for deriving client and handler shapes, exit schemas, and handler wrappers for special execution modes.

Since v4.0.0

Exports Grouped by Category

constructors
guards
- isRpc
models
utils
- Custom (namespace)
wrapping

constructors

Custom (interface)

Defines the type-level contract for an RPC custom constructor.

Details

A custom constructor receives the original success, error, and defect schemas and returns transformed output schemas through out.

Signature

export interface Custom {
  readonly out: Custom.OutDefault
  readonly success: Schema.Top
  readonly error: Schema.Top
  readonly defect: DefectSchema
}

Since v4.0.0

custom

Creates a custom Rpc constructor that can transform the output schemas.

Example (Defining a paginated RPC constructor)

import { Schema } from "effect"
import { Rpc } from "effect/unstable/rpc"

// Create a custom Rpc wrapper definition by transforming the success and error
// schemas.
export interface RpcWithPagination extends Rpc.Custom {
  readonly out: Rpc.Custom.Out<Paginated<this["success"]>, this["error"]>
}

// The type definition for the transformed success schema.
export interface Paginated<S extends Schema.Constraint> extends Schema.Struct<{
  readonly offset: Schema.Number
  readonly total: Schema.Number
  readonly results: Schema.$Array<S>
}> {}

// You can then implement the schema transformation using `Rpc.custom`
export const makePaginated = Rpc.custom<RpcWithPagination>((schemas) => ({
  ...schemas,
  success: Schema.Struct({
    offset: Schema.Number,
    total: Schema.Number,
    results: Schema.Array(schemas.success)
  })
}))

// You can then use the custom constructor in the same way `Rpc.make` is used.
export const listAllRpc = makePaginated("listAll", {
  success: Schema.String
})

Signature

declare const custom: <Def extends Custom>(
  f: (options: Custom.OutDefault) => (Def & Custom.OutDefault)["out"]
) => <
  const Tag extends string,
  Payload extends Schema.Top | Schema.Struct.Fields = Schema.Void,
  Success extends Schema.Top = Schema.Void,
  Error extends Schema.Top = Schema.Never,
  const Stream extends boolean = false,
  Out extends Custom.OutDefault = Custom.Kind<Def, Success, Error>
>(
  tag: Tag,
  options?: {
    readonly payload?: Payload
    readonly success?: Success
    readonly error?: Error
    readonly defect?: DefectSchema
    readonly stream?: Stream
    readonly primaryKey?: [Payload] extends [Schema.Struct.Fields]
      ? (
          payload: Payload extends Schema.Struct.Fields
            ? Struct.Simplify<Schema.Struct<Payload>["Type"]>
            : Payload["Type"]
        ) => string
      : never
  }
) => Rpc<
  Tag,
  Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
  Stream extends true ? RpcSchema.Stream<Out["success"], Out["error"]> : Out["success"],
  Stream extends true ? typeof Schema.Never : Out["error"]
>

Since v4.0.0

exitSchema

Builds the Schema.Exit used to encode and decode RPC results.

Details

The failure side includes the RPC error schema, middleware error schemas, and stream error schema for streaming RPCs. Streaming RPCs use Schema.Void for the exit success value. The schema is cached per RPC definition.

Signature

declare const exitSchema: <R extends Any>(
  self: R
) => Schema.Exit<SuccessExitSchema<R>, ErrorExitSchema<R>, DefectSchema>

Since v4.0.0

make

Creates an RPC definition with the supplied tag and optional schemas.

Details

Payload options can be either a schema or struct fields. stream: true wraps the success and error schemas in a stream schema and sets the normal error schema to Schema.Never. primaryKey creates a payload class with a primary key derived from the payload value.

Signature

declare const make: <
  const Tag extends string,
  Payload extends Schema.Top | Schema.Struct.Fields = Schema.Void,
  Success extends Schema.Top = Schema.Void,
  Error extends Schema.Top = Schema.Never,
  const Stream extends boolean = false
>(
  tag: Tag,
  options?: {
    readonly payload?: Payload
    readonly success?: Success
    readonly error?: Error
    readonly defect?: DefectSchema
    readonly stream?: Stream
    readonly primaryKey?: [Payload] extends [Schema.Struct.Fields]
      ? (
          payload: Payload extends Schema.Struct.Fields
            ? Struct.Simplify<Schema.Struct<Payload>["Type"]>
            : Payload["Type"]
        ) => string
      : never
  }
) => Rpc<
  Tag,
  Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
  Stream extends true ? RpcSchema.Stream<Success, Error> : Success,
  Stream extends true ? typeof Schema.Never : Error
>

Since v4.0.0

guards

isRpc

Returns true when the value is an Rpc definition.

Signature

declare const isRpc: (u: unknown) => u is Rpc<any, any, any>

Since v4.0.0

models

AddError (type alias)

Returns an RPC type with an additional error schema unioned into its error channel.

Signature

type AddError<R, Error> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? Rpc<_Tag, _Payload, _Success, _Error | Error, _Middleware, _Requires>
    : never

Since v4.0.0

AddMiddleware (type alias)

Returns an RPC type with additional middleware and the corresponding middleware service requirements applied.

Signature

type AddMiddleware<R, Middleware> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? Rpc<
        _Tag,
        _Payload,
        _Success,
        _Error,
        _Middleware | Middleware,
        RpcMiddleware.ApplyServices<Middleware["Identifier"], _Requires>
      >
    : never

Since v4.0.0

Any (interface)

An erased RPC definition that preserves the common runtime metadata shared by all RPCs.

Signature

export interface Any extends Pipeable {
  readonly [TypeId]: typeof TypeId
  readonly _tag: string
  readonly key: string
  readonly annotations: Context.Context<never>
}

Since v4.0.0

AnyWithProps (interface)

An erased RPC definition with all schema, middleware, annotation, and service metadata available.

Signature

export interface AnyWithProps extends Pipeable {
  readonly [TypeId]: typeof TypeId
  readonly _tag: string
  readonly key: string
  readonly payloadSchema: Schema.Top
  readonly successSchema: Schema.Top
  readonly errorSchema: Schema.Top
  readonly defectSchema: Schema.Top
  readonly annotations: Context.Context<never>
  readonly middlewares: ReadonlySet<RpcMiddleware.AnyServiceWithProps>
  readonly "~requires": any
}

Since v4.0.0

DefectSchema (interface)

Schema for RPC defects.

Details

Defect schemas decode and encode without services and can be constructed from null, undefined, or an object value.

Signature

export interface DefectSchema extends Schema.Top {
  make(input: null, options?: Schema.MakeOptions): unknown
  make(input: undefined, options?: Schema.MakeOptions): unknown
  make(input: {}, options?: Schema.MakeOptions): unknown
  readonly DecodingServices: never
  readonly EncodingServices: never
}

Since v4.0.0

Error (type alias)

Extracts the decoded error value type from an Rpc, including middleware errors.

Signature

type Error<R> = Schema.Schema.Type<ErrorSchema<R>>

Since v4.0.0

ErrorExit (type alias)

Extracts the decoded error type used by an RPC exit.

Details

For streaming RPCs, this includes both stream errors and RPC errors.

Signature

type ErrorExit<R> = Success<R> extends Stream<infer _A, infer _E, infer _Env> ? _E | Error<R> : Error<R>

Since v4.0.0

ErrorExitSchema (type alias)

Extracts the error schema used in an RPC exit.

Details

For streaming RPCs, this includes both the stream error schema and the RPC error schema; otherwise it is the RPC error schema.

Signature

type ErrorExitSchema<R> =
  SuccessSchema<R> extends RpcSchema.Stream<infer _A, infer _E> ? _E | ErrorSchema<R> : ErrorSchema<R>

Since v4.0.0

ErrorSchema (type alias)

Extracts the RPC error schema, including error schemas contributed by middleware.

Signature

type ErrorSchema<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? _Error | _Middleware["error"]
    : never

Since v4.0.0

ExcludeProvides (type alias)

Removes the services provided by middleware for the specified RPC tag from an environment type.

Signature

type ExcludeProvides<Env, R, Tag> = Exclude<Env, ExtractProvides<R, Tag>>

Since v4.0.0

Exit (type alias)

The Exit type produced for an RPC, using the RPC’s exit success and exit error types.

Signature

type Exit<R> = Exit_<SuccessExit<R>, ErrorExit<R>>

Since v4.0.0

ExtractProvides (type alias)

Extracts the services provided by middleware on the RPC with the specified tag.

Signature

type ExtractProvides<R, Tag> =
  R extends Rpc<Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? RpcMiddleware.Provides<_Middleware["Identifier"]>
    : never

Since v4.0.0

ExtractRequires (type alias)

Extracts the service requirements of the RPC with the specified tag.

Signature

type ExtractRequires<R, Tag> =
  R extends Rpc<Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? _Requires
    : never

Since v4.0.0

ExtractTag (type alias)

Extracts the RPC with the specified tag from an RPC union.

Signature

type ExtractTag<R, Tag> =
  R extends Rpc<Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires> ? R : never

Since v4.0.0

Handler (interface)

Represents the server-side implementation of an RPC.

Details

The handler receives the decoded request plus client, request id, headers, and RPC metadata, and returns either an effectful result or a stream result.

Signature

export interface Handler<Tag extends string> {
  readonly _: unique symbol
  readonly tag: Tag
  readonly handler: (
    request: any,
    options: {
      readonly client: ServerClient
      readonly requestId: RequestId
      readonly headers: Headers
      readonly rpc: Any
    }
  ) => Effect<{} | Deferred<any, any>, any> | Stream<any, any>
  readonly context: Context.Context<never>
}

Since v4.0.0

IsStream (type alias)

Returns true when the RPC with the specified tag has a streaming success schema, or never otherwise.

Signature

type IsStream<R, Tag> =
  R extends Rpc<
    Tag,
    infer _Payload,
    RpcSchema.Stream<infer _A, infer _E>,
    infer _Error,
    infer _Middleware,
    infer _Requires
  >
    ? true
    : never

Since v4.0.0

Middleware (type alias)

Extracts the service identifiers for middleware attached to an Rpc.

Signature

type Middleware<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? Context.Service.Identifier<_Middleware>
    : never

Since v4.0.0

MiddlewareClient (type alias)

Extracts client-side middleware service requirements for middleware marked as required on the client.

Signature

type MiddlewareClient<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? _Middleware extends { readonly requiredForClient: true }
      ? RpcMiddleware.ForClient<_Middleware["Identifier"]>
      : never
    : never

Since v4.0.0

Payload (type alias)

Extracts the decoded payload type from an Rpc.

Signature

type Payload<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? _Payload["Type"]
    : never

Since v4.0.0

PayloadConstructor (type alias)

Extracts the payload constructor input type accepted by the RPC payload schema.

Signature

type PayloadConstructor<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? _Payload["~type.make.in"]
    : never

Since v4.0.0

Prefixed (type alias)

Returns an RPC type with the specified string prefix added to its tag while preserving its payload, success, error, middleware, and requirements.

Signature

type Prefixed<Rpcs, Prefix> =
  Rpcs extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? Rpc<`${Prefix}${_Tag}`, _Payload, _Success, _Error, _Middleware, _Requires>
    : never

Since v4.0.0

ResultFrom (type alias)

Computes the allowed handler result type for an RPC.

Details

Streaming RPCs may return a stream or an effect that produces a queue. Other RPCs return an effect that succeeds with the success value or a deferred success value.

Signature

type ResultFrom<R, Services> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? [_Success] extends [RpcSchema.Stream<infer _SA, infer _SE>]
      ?
          | Stream<_SA["Type"], _SE["Type"] | _Error["Type"], Services>
          | Effect<
              Queue.Dequeue<_SA["Type"], _SE["Type"] | _Error["Type"] | Cause.Done>,
              _SE["Type"] | Schema.Schema.Type<_Error>,
              Services
            >
      : Effect<_Success["Type"] | Deferred<_Success["Type"], _Error["Type"]>, _Error["Type"], Services>
    : never

Since v4.0.0

Rpc (interface)

Represents a typed RPC definition.

Details

An RPC is identified by a tag and carries payload, success, error, defect, middleware, and annotation metadata used by RPC clients and servers.

Signature

export interface Rpc<
  in out Tag extends string,
  out Payload extends Schema.Top = Schema.Void,
  out Success extends Schema.Top = Schema.Void,
  out Error extends Schema.Top = Schema.Never,
  out Middleware extends RpcMiddleware.AnyService = never,
  out Requires = never
> extends Pipeable {
  new (_: never): {}

  readonly [TypeId]: typeof TypeId
  readonly _tag: Tag
  readonly key: string
  readonly payloadSchema: Payload
  readonly successSchema: Success
  readonly errorSchema: Error
  readonly defectSchema: Schema.Top
  readonly annotations: Context.Context<never>
  readonly middlewares: ReadonlySet<Middleware>
  readonly "~requires": Requires

  /**
   * Set the schema for the success response of the rpc.
   */
  setSuccess<S extends Schema.Top>(schema: S): Rpc<Tag, Payload, S, Error, Middleware, Requires>

  /**
   * Set the schema for the error response of the rpc.
   */
  setError<E extends Schema.Top>(schema: E): Rpc<Tag, Payload, Success, E, Middleware, Requires>

  /**
   * Set the schema for the payload of the rpc.
   */
  setPayload<P extends Schema.Top | Schema.Struct.Fields>(
    schema: P
  ): Rpc<Tag, P extends Schema.Struct.Fields ? Schema.Struct<P> : P, Success, Error, Middleware, Requires>

  /**
   * Add an `RpcMiddleware` to this procedure.
   */
  middleware<M extends RpcMiddleware.AnyService>(
    middleware: M
  ): Rpc<Tag, Payload, Success, Error, Middleware | M, RpcMiddleware.ApplyServices<M["Identifier"], Requires>>

  /**
   * Set the schema for the error response of the rpc.
   */
  prefix<const Prefix extends string>(
    prefix: Prefix
  ): Rpc<`${Prefix}${Tag}`, Payload, Success, Error, Middleware, Requires>

  /**
   * Add an annotation on the rpc.
   */
  annotate<I, S>(tag: Context.Key<I, S>, value: NoInfer<S>): Rpc<Tag, Payload, Success, Error, Middleware, Requires>

  /**
   * Merge the annotations of the rpc with the provided annotations.
   */
  annotateMerge<I>(annotations: Context.Context<I>): Rpc<Tag, Payload, Success, Error, Middleware, Requires>
}

Since v4.0.0

ServerClient (class)

Represents server-side metadata for the client associated with an RPC request.

When to use

Use to inspect or annotate the connected client while handling an RPC request on the server.

Details

It stores the client id and request annotations that handlers can read or extend.

Signature

declare class ServerClient {
  constructor(id: number)
}

Since v4.0.0

annotate (method)

Signature

declare const annotate: <I, S>(tag: Context.Key<I, S>, value: NoInfer<S>) => ServerClient

id (property)

Signature

readonly id: number

annotations (property)

Signature

annotations: Context.Context<never>

Services (type alias)

Extracts all schema services required to encode or decode an RPC’s payload, success, error, and middleware error schemas.

Signature

type Services<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ?
        | _Payload["DecodingServices"]
        | _Payload["EncodingServices"]
        | _Success["DecodingServices"]
        | _Success["EncodingServices"]
        | _Error["DecodingServices"]
        | _Error["EncodingServices"]
        | _Middleware["error"]["DecodingServices"]
        | _Middleware["error"]["EncodingServices"]
    : never

Since v4.0.0

ServicesClient (type alias)

Extracts the schema services required on the client side of an RPC.

Details

This includes payload encoding services and success, error, and middleware error decoding services.

Signature

type ServicesClient<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ?
        | _Payload["EncodingServices"]
        | _Success["DecodingServices"]
        | _Error["DecodingServices"]
        | _Middleware["error"]["DecodingServices"]
    : never

Since v4.0.0

ServicesServer (type alias)

Extracts the schema services required on the server side of an RPC.

Details

This includes payload decoding services and success, error, and middleware error encoding services.

Signature

type ServicesServer<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ?
        | _Payload["DecodingServices"]
        | _Success["EncodingServices"]
        | _Error["EncodingServices"]
        | _Middleware["error"]["EncodingServices"]
    : never

Since v4.0.0

Success (type alias)

Extracts the decoded success value type from an Rpc.

Signature

type Success<R> = SuccessSchema<R>["Type"]

Since v4.0.0

SuccessChunk (type alias)

Extracts the decoded stream element type from a streaming RPC, or never for non-streaming RPCs.

Signature

type SuccessChunk<R> = Success<R> extends Stream<infer _A, infer _E, infer _Env> ? _A : never

Since v4.0.0

SuccessEncoded (type alias)

Extracts the encoded success value type from an Rpc.

Signature

type SuccessEncoded<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? _Success["Encoded"]
    : never

Since v4.0.0

SuccessExit (type alias)

Extracts the decoded success value carried by an RPC exit.

Details

For streaming RPCs, the immediate exit success is void because stream elements are delivered separately.

Signature

type SuccessExit<R> = Success<R> extends infer T ? (T extends Stream<infer _A, infer _E, infer _Env> ? void : T) : never

Since v4.0.0

SuccessExitSchema (type alias)

Extracts the success schema used in an RPC exit.

Details

For streaming RPCs, this is the stream element schema; otherwise it is the RPC success schema.

Signature

type SuccessExitSchema<R> = SuccessSchema<R> extends RpcSchema.Stream<infer _A, infer _E> ? _A : SuccessSchema<R>

Since v4.0.0

SuccessSchema (type alias)

Extracts the success schema from an Rpc.

Signature

type SuccessSchema<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? _Success
    : never

Since v4.0.0

Tag (type alias)

Extracts the tag string from an Rpc.

Signature

type Tag<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? _Tag
    : never

Since v4.0.0

ToHandler (type alias)

Converts an RPC definition into the corresponding Handler type.

Signature

type ToHandler<R> =
  R extends Rpc<infer _Tag, infer _Payload, infer _Success, infer _Error, infer _Middleware, infer _Requires>
    ? Handler<_Tag>
    : never

Since v4.0.0

ToHandlerFn (type alias)

The function signature for implementing an RPC handler.

Details

The function receives the decoded payload and request metadata, and returns the RPC result shape, optionally wrapped with Wrapper options.

Signature

type ToHandlerFn<Current, R> = (
  payload: Payload<Current>,
  options: {
    readonly client: ServerClient
    readonly requestId: RequestId
    readonly headers: Headers
    readonly rpc: Current
  }
) => WrapperOr<ResultFrom<Current, R>>

Since v4.0.0

utils

Custom (namespace)

Helper types for defining RPC custom constructors.

Since v4.0.0

Out (interface)

The transformed schemas produced by a custom RPC constructor.

Signature

export interface Out<Success extends Schema.Constraint, Error extends Schema.Constraint> {
  readonly success: Success
  readonly error: Error
  readonly defect: DefectSchema
}

Since v4.0.0

OutDefault (type alias)

The default custom-constructor output shape for arbitrary success and error schemas.

Signature

type OutDefault = Out<Schema.Top, Schema.Top>

Since v4.0.0

Kind (type alias)

Applies a custom constructor definition to concrete success and error schemas and returns its transformed output schema type.

Signature

type Kind<Def, Success, Error> = (Def & {
  readonly success: Success
  readonly error: Error
})["out"]

Since v4.0.0

wrapping

Wrapper (interface)

Wraps a handler result with execution options for the RPC server.

Details

fork requests concurrent execution, and uninterruptible requests uninterruptible execution.

Signature

export interface Wrapper<A> {
  readonly [WrapperTypeId]: typeof WrapperTypeId
  readonly value: A
  readonly fork: boolean
  readonly uninterruptible: boolean
}

Since v4.0.0

WrapperOr (type alias)

A value that may be returned directly or wrapped with RPC server execution options.

Signature

type WrapperOr<A> = A | Wrapper<A>

Since v4.0.0

fork

Wraps a response Effect or Stream so the RPC server executes it concurrently regardless of the server concurrency setting.

Signature

declare const fork: <A extends object>(value: A) => Wrapper<A>

Since v4.0.0

isWrapper

Returns true when the value is an RPC Wrapper.

Signature

declare const isWrapper: (u: object) => u is Wrapper<any>

Since v4.0.0

uninterruptible

Wraps a response Effect or Stream so the RPC server runs it in an uninterruptible region.

Signature

declare const uninterruptible: <A extends object>(value: A) => Wrapper<A>

Since v4.0.0

unwrap

Returns the wrapped response value when the input is an RPC Wrapper, or the input itself when it is already unwrapped.

Signature

declare const unwrap: <A extends object>(value: WrapperOr<A>) => A

Since v4.0.0

wrap

Wraps a handler result with RPC server execution options.

Details

When the value is already wrapped, unspecified options are inherited from the existing wrapper.

Signature

declare const wrap: (options: {
  readonly fork?: boolean | undefined
  readonly uninterruptible?: boolean | undefined
}) => <A extends object>(value: A) => Wrapper<A>

Since v4.0.0

wrapMap

Maps the value inside an RPC wrapper, preserving wrapper options such as fork and uninterruptible; unwrapped values are mapped directly.

Signature

declare const wrapMap: <A extends object, B extends object>(self: WrapperOr<A>, f: (value: A) => B) => WrapperOr<B>

Since v4.0.0