Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

RpcSerialization unstable

Serializes RPC protocol messages for transports.

RpcSerialization is the boundary between RpcMessage envelopes and the bytes or strings carried by a transport. This module provides built-in serializers for JSON, newline-delimited JSON, JSON-RPC 2.0, and SchemaBinary, including framed formats that can decode multiple messages from streaming chunks.

16 exports Since v4.0.0 Source

Errors

MaxBufferSizeExceeded

unstable
Since v4.0.0

Error raised when a streaming parser retains more data than its configured buffer limit.

Signature

declare class MaxBufferSizeExceeded extends YieldableError<this> & {
  readonly _tag: "MaxBufferSizeExceeded";
} & Readonly<{
  readonly maxBufferSize: number;
}> {
  constructor(args: {
    readonly maxBufferSize: number;
  });
  message: string;
}

Layers

layerJson

unstable
Since v4.0.0

RPC serialization layer that uses JSON for serialization.

When to use

Use when you have a transport protocol that already provides message framing.

See

  • layerNdjson for transports that need newline-delimited framing

Signature

declare const layerJson: Layer.Layer<RpcSerialization>

layerJsonRpc

unstable
Since v4.0.0

RPC serialization layer that uses JSON-RPC for serialization.

Signature

declare function layerJsonRpc(options?: {
  readonly contentType?: string;
}): Layer<RpcSerialization>

layerNdjson

unstable
Since v4.0.0

RPC serialization layer that uses NDJSON for serialization.

When to use

Use when you have a transport protocol that does not provide message framing.

See

  • layerJson for transports that already provide message framing

Signature

declare const layerNdjson: Layer.Layer<RpcSerialization>

layerNdJsonRpc

unstable
Since v4.0.0

RPC serialization layer that uses newline-delimited JSON-RPC for serialization.

Signature

declare function layerNdJsonRpc(options?: {
  readonly contentType?: string;
  readonly maxBufferSize?: number | "unbounded";
}): Layer<RpcSerialization>

layerNdjsonWith

unstable
Since v4.0.0

RPC serialization layer that uses NDJSON with custom streaming options.

Signature

declare function layerNdjsonWith(options?: StreamOptions): Layer<RpcSerialization>

layerSchemaBinary

unstable
Since v4.0.0

RPC serialization layer that uses SchemaBinary with fingerprinted RPC envelopes. Payload fingerprints are disabled by default to support compatible schema evolution. Frames default to a 16 MiB maximum size. Use "unbounded" to disable the frame-size limit.

Signature

declare function layerSchemaBinary(options?: {
  readonly fingerprintPayloads?: boolean;
  readonly maxFrameSize?: number | "unbounded";
}): Layer<RpcSerialization>

Serialization

CodecFor

type unstable
Since v4.0.0

Builds the codec used to fill the unknown holes of RPC protocol messages, such as request payloads, stream chunks, exits, and defects.

Details

The envelope around the hole is framed by Parser, which never sees the schema. JSON based serializations return Schema.toCodecJson, so the encoded hole is JSON. Other serializations may encode the hole as bytes; both fit the unknown hole, so RpcSerialization has no type parameter.

Signature

type CodecFor = <S extends Schema.Top>(schema: S) => Schema.Codec<S["Type"], unknown, S["DecodingServices"], S["EncodingServices"]>

json

unstable
Since v4.0.0

JSON RPC serialization for whole message payloads. It does not include message framing, so it is intended for transports that frame responses themselves.

Signature

declare const json: RpcSerialization["Service"]

jsonRpc

unstable
Since v4.0.0

Creates a JSON-RPC 2.0 serialization for RPC protocol messages without additional message framing.

Signature

declare function jsonRpc(options?: {
  readonly contentType?: string;
}): {
  readonly codecFor: CodecFor;
  readonly contentType: string;
  readonly includesFraming: boolean;
  makeUnsafe(): Parser;
}

makeNdjson

unstable
Since v4.0.0

Serializes RPC protocol messages as newline-delimited JSON, framing each message with a trailing newline.

Signature

declare function makeNdjson(options?: StreamOptions): {
  readonly codecFor: CodecFor;
  readonly contentType: string;
  readonly includesFraming: boolean;
  makeUnsafe(): Parser;
}

ndjson

unstable
Since v4.0.0

Default newline-delimited JSON RPC serialization.

Signature

declare const ndjson: RpcSerialization["Service"]

ndJsonRpc

unstable
Since v4.0.0

Creates a newline-delimited JSON-RPC 2.0 serialization for RPC protocol messages.

Signature

declare function ndJsonRpc(options?: {
  readonly contentType?: string;
  readonly maxBufferSize?: number | "unbounded";
}): {
  readonly codecFor: CodecFor;
  readonly contentType: string;
  readonly includesFraming: boolean;
  makeUnsafe(): Parser;
}

Parser

interface unstable
Since v4.0.0

A stateful parser for an RPC serialization format, able to decode input chunks into protocol messages and encode messages for transport.

Signature

interface Parser {
  readonly decode: (data: string | Uint8Array<ArrayBufferLike>) => readonly Array<unknown>;
  readonly encode: (response: unknown) => string | Uint8Array<ArrayBufferLike> | undefined;
}

StreamOptions

interface unstable
Since v4.0.0

Options shared by streaming RPC serialization formats.

Signature

interface StreamOptions {
  readonly maxBufferSize?: number | "unbounded";
}

Services

RpcSerialization

unstable
Since v4.0.0

Service that describes how RPC protocol messages are encoded and decoded, including the content type and whether the serialization format provides message framing.

When to use

Use to provide the serialization boundary shared by RPC clients and servers for a chosen wire format.

Signature

declare class RpcSerialization extends Shape<"effect/rpc/RpcSerialization", {
  readonly codecFor: CodecFor;
  readonly contentType: string;
  readonly includesFraming: boolean;
  makeUnsafe(): Parser;
}, this> {
  constructor(_: never);
}