Skip to content

Msgpack

Encodes and decodes MessagePack frames in Effect channels.

MessagePack is a compact binary serialization format for protocols and storage layers that expect bytes instead of JSON text, such as RPC transports, socket streams, caches, or database columns. This module includes raw channel helpers for values whose shape is already agreed on, and schema-based helpers for validating and transforming values at the boundary.

10 exports Added in v4.0.0 Source

Combinators

duplex

Added in v4.0.0 Source

Wraps a bidirectional byte channel with MessagePack encoding and decoding.

Details

Outgoing values are packed as MessagePack bytes before reaching the wrapped channel, and incoming bytes are unpacked into values.

Signature

declare function duplex<R, IE, OE, OutDone, InDone>(
  self: Channel<
    readonly [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>],
    OE,
    OutDone,
    readonly [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>],
    MsgPackError | IE,
    InDone,
    R
  >,
): Channel<
  readonly [unknown, unknown],
  MsgPackError | OE,
  OutDone,
  readonly [unknown, unknown],
  IE,
  InDone,
  R
>;

duplexSchema

Added in v4.0.0 Source

Wraps a bidirectional byte channel with schema-aware MessagePack encoding and decoding.

Details

Values sent to the wrapped channel are encoded with inputSchema and packed as MessagePack bytes; bytes received from it are unpacked and decoded with outputSchema.

Signature

declare const duplexSchema: {
  <In extends Constraint, Out extends Constraint>(options: {
    readonly inputSchema: In;
    readonly outputSchema: Out;
  }): <OutErr, OutDone, InErr, InDone, R>(
    self: Channel<
      readonly [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>],
      OutErr,
      OutDone,
      readonly [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>],
      SchemaError | MsgPackError | InErr,
      InDone,
      R
    >,
  ) => Channel<
    readonly [Out["Type"], Out["Type"]],
    SchemaError | MsgPackError | OutErr,
    OutDone,
    readonly [In["Type"], In["Type"]],
    InErr,
    InDone,
    R | In["EncodingServices"] | Out["DecodingServices"]
  >;
  <Out extends Constraint, In extends Constraint, OutErr, OutDone, InErr, InDone, R>(
    self: Channel<
      readonly [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>],
      OutErr,
      OutDone,
      readonly [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>],
      SchemaError | MsgPackError | InErr,
      InDone,
      R
    >,
    options: {
      readonly inputSchema: In;
      readonly outputSchema: Out;
    },
  ): Channel<
    readonly [Out["Type"], Out["Type"]],
    SchemaError | MsgPackError | OutErr,
    OutDone,
    readonly [In["Type"], In["Type"]],
    InErr,
    InDone,
    R | In["EncodingServices"] | Out["DecodingServices"]
  >;
};

Constructors

decode

Added in v4.0.0 Source

Creates a channel that decodes MessagePack byte chunks into values.

Details

Incomplete frames are buffered across chunks, and invalid MessagePack data fails with MsgPackError.

Signature

declare function decode<IE = never, Done = unknown>(): Channel<
  readonly [unknown, unknown],
  MsgPackError | IE,
  Done,
  readonly [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>],
  IE,
  Done
>;

decodeSchema

Added in v4.0.0 Source

Creates a MessagePack decoder channel for values of a schema.

Details

The channel unpacks bytes into unknown values and then decodes each value with the schema.

Signature

declare function decodeSchema<S extends Constraint>(
  schema: S,
): <IE = never, Done = unknown>() => Channel<
  readonly [S["Type"], S["Type"]],
  SchemaError | MsgPackError | IE,
  Done,
  readonly [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>],
  IE,
  Done,
  S["DecodingServices"]
>;

encode

Added in v4.0.0 Source

Creates a channel that encodes non-empty chunks of values as MessagePack byte arrays.

Details

The channel fails with MsgPackError when any value cannot be packed.

Signature

declare function encode<IE = never, Done = unknown>(): Channel<
  readonly [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>],
  MsgPackError | IE,
  Done,
  readonly [unknown, unknown],
  IE,
  Done
>;

encodeSchema

Added in v4.0.0 Source

Creates a MessagePack encoder channel for values of a schema.

Details

Values are first encoded with the schema and then packed as MessagePack bytes, so the channel can fail with either schema errors or MsgPackError.

Signature

declare function encodeSchema<S extends Constraint>(
  schema: S,
): <IE = never, Done = unknown>() => Channel<
  readonly [Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>],
  SchemaError | MsgPackError | IE,
  Done,
  readonly [S["Type"], S["Type"]],
  IE,
  Done,
  S["EncodingServices"]
>;

Errors

MsgPackError

Added in v4.0.0 Source

Error raised when MessagePack encoding or decoding fails.

Details

The kind field identifies whether the failure happened while packing or unpacking, and cause preserves the original error.

Signature

declare class MsgPackError extends YieldableError<this> & {
  readonly _tag: "MsgPackError";
} & Readonly<{
  readonly cause: unknown;
  readonly kind: "Pack" | "Unpack";
}> {
  constructor(args: {
    readonly cause: unknown;
    readonly kind: "Pack" | "Unpack";
  });
  readonly "~effect/encoding/MsgPack/MsgPackError": "~effect/encoding/MsgPack/MsgPackError";
  message: "Pack" | "Unpack";
}

Schemas

schema

Added in v4.0.0 Source

Builds a schema that stores values as MessagePack bytes.

Details

The resulting schema decodes Uint8Array payloads with MessagePack and the provided schema, and encodes values back to MessagePack bytes.

Signature

declare const schema: <S extends Constraint>(schema: S) => schema<S>;

schema interface

Added in v4.0.0 Source

Schema type for values encoded as MessagePack bytes.

Details

It decodes a Uint8Array MessagePack payload to the target schema type and encodes the target type back to bytes.

Signature

interface schema<S extends Schema.Constraint> extends decodeTo<
  S,
  Schema.instanceOf<Uint8Array<ArrayBuffer>>
> {
  constructor(_: never);
}

transformation

Added in v4.0.0 Source

Schema for decoding MessagePack bytes into values and encoding values back to MessagePack bytes.

Details

MessagePack codec failures are converted to InvalidValue schema issues.

Signature

declare const transformation: SchemaTransformation.Transformation<unknown, Uint8Array<ArrayBuffer>>;