Docket.EventPage (docket v0.1.0-dev)

Copy Markdown View Source

One page of retained run events with the retention bounds observed alongside it.

A page carries the committed events whose sequence is greater than the requested cursor, in ascending sequence order and bounded by the requested limit. It also carries the retention bounds and the owning run's latest committed event sequence, all read from one consistent snapshot so a caller can reason about progress and pruning without a second query.

Sequence gaps are legal: persistence filtering and retention pruning both leave holes, so consecutive pages and the bounds are not promised contiguous.

latest_seq is the run's committed event counter and is present even when history is fully pruned. A fully pruned history is therefore detectable as latest_seq > 0 with latest_available_seq == nil.

Summary

Types

t()

Fields

Functions

new(events, after_seq, oldest, latest, latest_seq)

Builds a page from a decoded event list and the bounds observed with it.

Types

t()

@type t() :: %Docket.EventPage{
  events: [Docket.Event.t()],
  has_more?: boolean(),
  latest_available_seq: pos_integer() | nil,
  latest_seq: non_neg_integer(),
  next_after_seq: non_neg_integer(),
  oldest_available_seq: pos_integer() | nil
}

Fields:

  • events — retained events with sequence greater than the requested cursor, ascending by sequence, at most the requested limit.
  • next_after_seq — the sequence to pass as the next cursor: the last returned event's sequence, or the supplied cursor when the page is empty.
  • has_more? — whether a retained event exists beyond next_after_seq, computed from the same snapshot as latest_available_seq.
  • oldest_available_seq — the lowest retained sequence, or nil when no events are retained.
  • latest_available_seq — the highest retained sequence, or nil when no events are retained.
  • latest_seq — the owning run's latest committed event sequence, independent of retention.

Functions

new(events, after_seq, oldest, latest, latest_seq)

@spec new(
  [Docket.Event.t()],
  non_neg_integer(),
  pos_integer() | nil,
  pos_integer() | nil,
  non_neg_integer()
) :: t()

Builds a page from a decoded event list and the bounds observed with it.

Derivation rules, shared by every backend so pagination cannot drift:

  • next_after_seq is the last event's sequence, or after_seq when the page is empty.
  • has_more? is true when a retained event exists beyond next_after_seq, i.e. latest is present and greater than next_after_seq.

oldest, latest, and latest_seq are recorded verbatim from the same snapshot that produced events.