# `Threadline.Query`
[🔗](https://github.com/szTheory/threadline/blob/v0.2.0/lib/threadline/query.ex#L1)

Ecto query implementations for the Threadline public API.

All functions require an explicit `:repo` option and return plain lists of
Ecto structs. DB errors propagate as exceptions, consistent with `Ecto.Repo.all/2`.

## Timeline filters

`timeline/2`, `timeline_query/1`, and `Threadline.Export` accept the same
filter keyword list. Only these keys are allowed: `:repo`, `:table`, `:actor_ref`,
`:from`, `:to`. Unknown keys raise `ArgumentError` (breaking vs pre-1.0 callers
that relied on silent ignores — see CHANGELOG when upgrading).

Use `timeline_repo!/2` to resolve `:repo` from filters and opts with the same
messages as export entrypoints.

## See also

- `Threadline.Export` — CSV / JSON export using the same filter vocabulary.

# `actor_history`

Returns `AuditTransaction` records for a given actor, ordered by
`occurred_at` descending.

For anonymous actors, returns all anonymous transactions (no actor_id
distinction — all anonymous transactions are equivalent by design, per ACTR-03).

## Options

- `:repo` — required `Ecto.Repo` module

## Example

    Threadline.actor_history(actor_ref, repo: MyApp.Repo)

# `export_changes_query`

```elixir
@spec export_changes_query(keyword()) :: Ecto.Query.t()
```

Query returning one row per matching change with change + transaction columns
for export (`Threadline.Export`).

Validates filters, then reuses `timeline_query/1` and extends with `select`.

# `history`

Returns `AuditChange` records for a given schema record, ordered by
`captured_at` descending.

## Options

- `:repo` — required `Ecto.Repo` module

## Example

    Threadline.history(MyApp.User, user.id, repo: MyApp.Repo)

Each `AuditChange` loads all table columns mapped on the schema, including
`changed_from` when the database column is populated (no narrowing `select`).

# `timeline`

Returns `AuditChange` records across tables, filtered by the given options,
ordered by `captured_at` descending, then `id` descending.

## Options

- `:table` — string or atom; filters by `table_name`
- `:actor_ref` — `%ActorRef{}`; filters by actor via joined `audit_transactions`
- `:from` — `DateTime`; inclusive lower bound on `captured_at`
- `:to` — `DateTime`; inclusive upper bound on `captured_at`
- `:repo` — required `Ecto.Repo` module (in `filters` or `opts`; see `Threadline.Export`)

## Example

    Threadline.timeline(table: "users", from: ~U[2026-01-01 00:00:00Z], repo: MyApp.Repo)

## See also

- `Threadline.Export` — CSV / JSON export using the same filter vocabulary.
- `Threadline.export_csv/2` and `Threadline.export_json/2` — top-level delegators.

# `timeline_query`

```elixir
@spec timeline_query(keyword()) :: Ecto.Query.t()
```

Builds the shared `AuditChange` query used by `timeline/2` and export.

Does **not** call `validate_timeline_filters!/1` — callers must validate first
when accepting external filter lists.

# `timeline_repo!`

```elixir
@spec timeline_repo!(keyword(), keyword()) :: module()
```

Resolves `Ecto.Repo` for `timeline/2`, export, and related APIs.

Checks `opts` first, then `filters`. Raises `ArgumentError` if missing or not an atom module.

# `validate_timeline_filters!`

```elixir
@spec validate_timeline_filters!(keyword()) :: :ok
```

Validates that `filters` contains only timeline filter keys.

Allowed keys: `:repo`, `:table`, `:actor_ref`, `:from`, `:to`.

Returns `:ok` or raises `ArgumentError`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*