Command builders for Redis stream operations.

This module provides pure functions that build Redis Stream command lists. Streams are append-only log structures that support fan-out reads, consumer groups with at-least-once delivery, and automatic ID generation. They are well-suited for event sourcing, task queues, and activity feeds.

Every function returns a plain list of strings (a command). To execute a command, pass the result to Redis.command/2; to batch several commands in a single round trip, use Redis.pipeline/2.

Response shapes

These functions build commands; they do not normalize Redis replies. Connections negotiate RESP3 by default and fall back to RESP2 when needed. In particular, XREAD and XREADGROUP return a map keyed by stream under RESP3:

{:ok, %{"events" => [["1234567890123-0", ["type", "click"]]]}}

The same reply under RESP2 is a list of stream/entries pairs:

{:ok, [["events", [["1234567890123-0", ["type", "click"]]]]]}

Both protocols return nil when no stream can be served. XRANGE and XREVRANGE return a list of entries under both protocols.

Examples

Appending entries and reading them back:

iex> Redis.command(conn, Redis.Commands.Stream.xadd("events", "*", [{"type", "click"}, {"url", "/home"}]))
{:ok, "1234567890123-0"}

iex> Redis.command(conn, Redis.Commands.Stream.xread(streams: [{"events", "0"}], count: 10))
{:ok, %{"events" => [["1234567890123-0", ["type", "click", "url", "/home"]]]}}

Consumer group pattern -- read, process, acknowledge:

iex> Redis.command(conn, Redis.Commands.Stream.xgroup_create("events", "workers", "0", mkstream: true))
{:ok, "OK"}

iex> Redis.command(conn, Redis.Commands.Stream.xreadgroup("workers", "worker-1", streams: [{"events", ">"}], count: 5))
{:ok, %{"events" => [["1234567890123-0", ["type", "click", "url", "/home"]]]}}

iex> Redis.command(conn, Redis.Commands.Stream.xack("events", "workers", ["1234567890123-0"]))
{:ok, 1}