SyntropyWeb.Api.Listing (syntropy v0.3.0)

Copy Markdown

Shared helpers for paginated, filterable list endpoints.

List endpoints accept limit, cursor, q, and resource-specific filter params. When persistence is enabled the controllers page through Postgres; otherwise these helpers paginate the bounded in-memory rings with the same opaque-cursor contract.

Summary

Types

page()

Functions

filter_agents(agents, opts)

Filters agent exports by :perspective and :q (id, name, or perspective).

filter_recommendations(recommendations, opts)

Filters in-memory recommendations by :status, :kind, and :q.

filter_runs(runs, opts)

Filters in-memory run envelopes by :status, :kind, and :q.

filter_snapshots(snapshots, opts)

Filters in-memory snapshots by :kind (trigger kind) and :q.

meta(page)

Builds the meta object appended to paginated list responses.

paginate(entries, opts, timestamp_key)

Applies cursor + limit pagination to an already-filtered in-memory list.

parse_opts(params, allowed_filters)

Parses shared list params (limit, cursor, plus the allowed filters).

Types

page()

@type page() :: Syntropy.Persistence.page()

Functions

filter_agents(agents, opts)

@spec filter_agents(
  [map()],
  keyword()
) :: [map()]

Filters agent exports by :perspective and :q (id, name, or perspective).

filter_recommendations(recommendations, opts)

@spec filter_recommendations(
  [map()],
  keyword()
) :: [map()]

Filters in-memory recommendations by :status, :kind, and :q.

filter_runs(runs, opts)

@spec filter_runs(
  [map()],
  keyword()
) :: [map()]

Filters in-memory run envelopes by :status, :kind, and :q.

filter_snapshots(snapshots, opts)

@spec filter_snapshots(
  [map()],
  keyword()
) :: [map()]

Filters in-memory snapshots by :kind (trigger kind) and :q.

meta(page)

@spec meta(page()) :: map()

Builds the meta object appended to paginated list responses.

paginate(entries, opts, timestamp_key)

@spec paginate([map()], keyword(), atom()) :: page()

Applies cursor + limit pagination to an already-filtered in-memory list.

Entries must be sorted newest-first. timestamp_key selects the field used for cursor ordering; the entry :id (a string) breaks ties.

parse_opts(params, allowed_filters)

@spec parse_opts(map(), [atom()]) :: {:ok, keyword()} | {:error, :invalid_cursor}

Parses shared list params (limit, cursor, plus the allowed filters).

Returns {:error, :invalid_cursor} when a cursor is present but malformed.