Hume.EventOrder (hume v0.0.9)

Provides utilities for working with ordered event sequences.

Events are tuples of {sequence_number, event_data} where sequence numbers are integers used to maintain ordering. This module provides functions to check ordering, ensure ordering, and merge ordered event sequences.

Summary

Types

event()

ordered()

Functions

ensure_ordered(events)

Ensures a list of events is ordered, sorting if necessary.

len(events)

Returns the length of the event list.

merge_ordered(arg1, arg2)

Merges two ordered event sequences into a single ordered sequence.

ordered?(arg1)

Checks if a list of events is ordered by sequence number.

to_list(events)

Converts an {:ordered, events} tuple to a raw event list. If given a raw event list, returns it as-is.

Types

event()

@type event() :: {integer(), term()}

ordered()

@type ordered() :: {:ordered, [event()]}

Functions

ensure_ordered(events)

@spec ensure_ordered([event()]) :: ordered()

Ensures a list of events is ordered, sorting if necessary.

Returns an {:ordered, events} tuple. If the input is already ordered, it returns the events as-is. Otherwise, it sorts them by sequence number.

Examples

iex> Hume.EventOrder.ensure_ordered([{1, :foo}, {2, :bar}])
{:ordered, [{1, :foo}, {2, :bar}]}

iex> Hume.EventOrder.ensure_ordered([{2, :bar}, {1, :foo}])
{:ordered, [{1, :foo}, {2, :bar}]}

iex> Hume.EventOrder.ensure_ordered([])
{:ordered, []}

len(events)

@spec len(ordered() | [event()]) :: non_neg_integer()

Returns the length of the event list.

Works with both raw event lists and {:ordered, events} tuples.

Examples

iex> Hume.EventOrder.len([])
0

iex> Hume.EventOrder.len([{1, :foo}, {2, :bar}])
2

iex> Hume.EventOrder.len({:ordered, [{1, :foo}, {2, :bar}]})
2

merge_ordered(arg1, arg2)

@spec merge_ordered(ordered(), ordered()) :: ordered()

Merges two ordered event sequences into a single ordered sequence.

When events have the same sequence number (conflict), the "later wins" policy is applied - the event from the second list takes precedence.

Examples

iex> Hume.EventOrder.merge_ordered({:ordered, [{1, :a}]}, {:ordered, [{2, :b}]})
{:ordered, [{1, :a}, {2, :b}]}

iex> Hume.EventOrder.merge_ordered({:ordered, [{1, :a}, {3, :c}]}, {:ordered, [{2, :b}]})
{:ordered, [{1, :a}, {2, :b}, {3, :c}]}

iex> Hume.EventOrder.merge_ordered({:ordered, [{1, :old}]}, {:ordered, [{1, :new}]})
{:ordered, [{1, :new}]}

iex> Hume.EventOrder.merge_ordered({:ordered, []}, {:ordered, [{1, :a}]})
{:ordered, [{1, :a}]}

ordered?(arg1)

@spec ordered?([event()] | ordered()) :: boolean()

Checks if a list of events is ordered by sequence number.

Examples

iex> Hume.EventOrder.ordered?([])
true

iex> Hume.EventOrder.ordered?([{1, :foo}])
true

iex> Hume.EventOrder.ordered?([{1, :foo}, {2, :bar}, {3, :baz}])
true

iex> Hume.EventOrder.ordered?([{1, :foo}, {3, :bar}, {2, :baz}])
false

iex> Hume.EventOrder.ordered?([{2, :foo}, {1, :bar}])
false

to_list(events)

@spec to_list(ordered() | [event()]) :: [event()]

Converts an {:ordered, events} tuple to a raw event list. If given a raw event list, returns it as-is.

Examples

iex> Hume.EventOrder.to_list({:ordered, [{1, :foo}, {2, :bar}]})
[{1, :foo}, {2, :bar}]

iex> Hume.EventOrder.to_list([{1, :foo}, {2, :bar}])
[{1, :foo}, {2, :bar}]