> ## Documentation Index
> Fetch the complete documentation index at: https://abxbus.archivebox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# EventHistory

> EventHistory ordered store API for lookup, retention, and trimming.

`EventHistory` is the ordered event store owned by each `EventBus` as `bus.event_history`.
Rust stores the same history inside `EventBus` runtime state and exposes it through `EventBus` history methods rather than a standalone public `EventHistory` type.

It is the canonical history backend in each runtime and exposes ordered access, lookup (`find`), and retention controls.

## Common fields

* `max_history_size`: max retained events (`None`/`null` means unbounded, `0` keeps only in-flight visibility)
* `max_history_drop`: whether to trim oldest entries when over limit
* Ordered mapping keyed by `event_id`

## Mapping interface

`EventHistory` behaves like an ordered mapping in Python/TypeScript; Go exposes equivalent explicit methods.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from abxbus import EventHistory

    history = EventHistory(max_history_size=100, max_history_drop=True)
    history[event.event_id] = event

    exists = event.event_id in history
    loaded = history.get(event.event_id)
    count = len(history)

    for event_id, item in history.items():
        print(event_id, item.event_type)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    import { EventHistory } from 'abxbus'

    const history = new EventHistory({ max_history_size: 100, max_history_drop: true })
    history.set(event.event_id, event)

    const exists = history.has(event.event_id)
    const loaded = history.get(event.event_id)
    const count = history.size

    for (const [event_id, item] of history) {
      console.log(event_id, item.event_type)
    }
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    maxSize := 100
    history := abxbus.NewEventHistory(&maxSize, true)
    history.AddEvent(event)

    exists := history.Has(event.EventID)
    loaded := history.GetEvent(event.EventID)
    count := history.Size()

    for _, item := range history.Values() {
    	fmt.Println(item.EventID, item.EventType)
    }
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let bus = EventBus::new_with_history(Some("HistoryBus".to_string()), Some(100), true);
    let event = bus.emit(SomeEvent {
        ..Default::default()
    });
    block_on(event.now());

    let count = bus.event_history_size();
    let ids = bus.event_history_ids();
    let loaded = bus.runtime_payload_for_test().get(&ids[0]).cloned();
    ```
  </Tab>
</Tabs>

## Accessor methods

All runtimes expose explicit accessors in addition to mapping methods where the language supports them.

<Tabs>
  <Tab title="Python">
    * `add_event(event)`
    * `get_event(event_id)`
    * `remove_event(event_id)`
    * `has_event(event_id)`
    * `find(...)`
    * `filter(...)`
    * `trim_event_history(...)`
  </Tab>

  <Tab title="TypeScript">
    * `addEvent(event)`
    * `getEvent(event_id)`
    * `removeEvent(event_id)`
    * `hasEvent(event_id)`
    * `find(...)`
    * `filter(...)`
    * `trimEventHistory(...)`
  </Tab>

  <Tab title="Go">
    * `AddEvent(event)`
    * `GetEvent(event_id)`
    * `RemoveEvent(event_id)`
    * `Has(event_id)`
    * `Find(...)`
    * `Filter(...)`
    * `TrimEventHistory(...)`
  </Tab>

  <Tab title="Rust">
    * `event_history_size()`
    * `event_history_ids()`
    * `find(...)`
    * `filter(...)`
    * `max_history_size()`
    * `max_history_drop()`
  </Tab>
</Tabs>

## `find(...)`

`EventHistory.find(...)` supports:

* event pattern (`'EventType'`, class, or `'*'`)
* `where` predicate filtering
* field equality filters (`**event_fields` in Python, options object fields in TypeScript)
* `past` / `future` windows
* `child_of` constraints

`EventBus.find(...)` delegates to `event_history.find(...)`. Future waiter ownership remains on `EventBus`; the bus injects the callback used for future waits.

## `filter(...)`

Same as `find(...)` but returns the list of all matching events (newest to oldest)
instead of just the first match. Accepts an additional `limit` argument to cap the
result count. `find(...)` is implemented as `filter(..., limit=1)` returning the first
result or `None` / `null`.

## Retention and trim methods

* `trim_event_history` / `trimEventHistory` applies configured retention policy.
* `on_remove` callbacks let the caller run cleanup side effects when history entries are removed.

## Constructor options

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    history = EventHistory(max_history_size=100, max_history_drop=False)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={null}
    const history = new EventHistory({ max_history_size: 100, max_history_drop: false })
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    maxSize := 100
    history := abxbus.NewEventHistory(&maxSize, false)
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let bus = EventBus::new_with_history(Some("HistoryBus".to_string()), Some(100), false);
    ```
  </Tab>
</Tabs>