Msgpack.StreamEncoder (msgpack_elixir v2.0.0)

Lazily encodes a stream of Elixir terms into a stream of MessagePack binaries.

This module is the counterpart to Msgpack.StreamDecoder. It processes an enumerable item by item, making it memory-efficient for encoding large collections or infinite streams without loading the entire dataset into memory.

Each item in the output stream is a result tuple, either {:ok, binary} for a successful encoding or {:error, reason} if an individual term could not be encoded.

Summary

Types

opts_t()

Options passed to the encoder for each term.

result_t()

The result of attempting to encode a single term.

t()

A stream that yields result tuples from an encoding operation.

Functions

encode(enumerable, opts \\ [])

Lazily encodes an enumerable of Elixir terms into a stream of result tuples.

Types

opts_t()

@type opts_t() :: keyword()

Options passed to the encoder for each term.

result_t()

@type result_t() :: {:ok, binary()} | {:error, any()}

The result of attempting to encode a single term.

t()

@type t() :: Stream.t(result_t())

A stream that yields result tuples from an encoding operation.

Each element is either {:ok, binary} or {:error, reason}.

Functions

encode(enumerable, opts \\ [])

@spec encode(Enumerable.t(any()), opts_t()) :: t()

Lazily encodes an enumerable of Elixir terms into a stream of result tuples.

Parameters

enumerable: An Enumerable that yields Elixir terms to be encoded.
opts: A keyword list of options passed to the underlying encoder for each term.

Return Value

Returns a lazy Stream that emits result tuples. For each term in the input enumerable, the stream will contain either:

{:ok, binary} - On successful encoding.
{:error, reason} - If the term cannot be encoded.

Options

This function accepts the same options as Msgpack.encode/2. See the documentation for Msgpack.encode/2 for a full list.

Examples

Standard Usage

iex> terms = [1, "elixir"]
iex> Msgpack.StreamEncoder.encode(terms) |> Enum.to_list()
[
  {:ok, <<1>>},
  {:ok, <<166, 101, 108, 105, 120, 105, 114>>}
]

Handling Unencodable Terms

iex> terms = [1, :elixir, 4]
iex> Msgpack.StreamEncoder.encode(terms, atoms: :error) |> Enum.to_list()
[
  {:ok, <<1>>},
  {:error, {:unsupported_atom, :elixir}},
  {:ok, <<4>>}
]