RpcSerialization
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.
Errors
MaxBufferSizeExceeded
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
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
RPC serialization layer that uses JSON-RPC for serialization.
Signature
declare function layerJsonRpc(options?: { readonly contentType?: string;}): Layer<RpcSerialization>layerNdjson
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
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
RPC serialization layer that uses NDJSON with custom streaming options.
Signature
declare function layerNdjsonWith(options?: StreamOptions): Layer<RpcSerialization>layerSchemaBinary
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
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 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"]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
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;}Default newline-delimited JSON RPC serialization.
Signature
declare const ndjson: RpcSerialization["Service"]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;}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
Options shared by streaming RPC serialization formats.
Signature
interface StreamOptions { readonly maxBufferSize?: number | "unbounded";}Services
RpcSerialization
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);}