listquery

type Bounds struct {
	// DefaultSize is the page size used when the request omits one (a final floor of 10
	// applies).
	DefaultSize int
	// MaxSize, when > 0, is the ceiling a client-supplied page size is clamped to.
	MaxSize int
	// CountCap bounds the offset arm's total_count: rows are counted only up to the cap,
	// so a per-page count never pays a full-table COUNT. ≤ 0 falls back to
	// DefaultCountCap, so a count is always bounded. A tally over the cap is reported as
	// the cap with an estimate flag.
	CountCap int
}

type ColumnFn func(field string) string

type DerivedFn func(field string) *types.DerivedSort

type Field struct {
	// Join, when non-nil, resolves this field to a correlated-EXISTS predicate on a
	// joined table instead of the same-table Column. Filter-only.
	Join *types.JoinTarget
	// Name is the DTO field name a client uses in the filter JSON.
	Name string
	// Column is the storage column the filter compiles against (defaults to Name).
	Column string
	// Ordinal, when non-empty, is the Column's DB values in ascending sort order: sorting
	// the field orders by this value ordinal (a CASE) instead of lexically. Sort-only
	// (does not affect filtering).
	Ordinal []string
	// Aggregates are the aggregations an analytics query may apply to a RoleMeasure field.
	Aggregates []types.Aggregate
	// Type is the field's value type, gating value/element compatibility.
	Type FieldType
	// Role is how an analytics query may use the field (dimension by default).
	Role FieldRole
}

type FieldRole int

type FieldSchema struct {
	// ValueSource is the decoded value-provisioning strategy for the field.
	ValueSource ValueSource
	// Join, when non-nil, marks this field as filtering a JOINED table's column; the
	// index-obligation gate reads Join.Table + Join.Columns so it checks the TARGET
	// table, not the resource's own. Populated from schema.json's `join` descriptor; nil
	// for a same-table field.
	Join *JoinTarget
	// Name is the DTO/proto field name — the filter/sort key clients use.
	Name string
	// AccessSensitivity is the field's declared access-sensitivity classification.
	AccessSensitivity string
	// Column is the backing storage column name.
	Column string
	// IndexKind is the declared index kind backing this field (checked by the
	// index-obligation gate); empty when the field declares no index.
	IndexKind string
	// Operators are the filter operators permitted on this field.
	Operators []string
	// Type is the field's value type (string, int, time, id, …).
	Type FieldType
	// CaseInsensitive reports whether string comparisons on this field are case-insensitive.
	CaseInsensitive bool
	// Sortable reports whether the field may be used in an ORDER BY.
	Sortable bool
	// Keysettable reports whether the field is the keyset-ordering (pagination
	// tiebreaker) column.
	Keysettable bool
}

type FieldType int

type JoinFn func(field string) *types.JoinTarget

type JoinTarget = types.JoinTarget

type Keyset[T any] struct {
	// RowValue returns a row's value for a resolved keyset column (the id column as its
	// string form), and false when the column is not one this store can extract — a guard
	// against a silently corrupt cursor if a sortable column is added without updating
	// the extractor. A timestamp column is returned as its time.Time; Run encodes it into
	// the token.
	RowValue func(row T, column string) (any, bool)

	// ParseID converts the token's id string to the value the seek binds against the id
	// column (e.g. uuid.Parse). Nil keeps the id a string. Kept here so foundation stays
	// uuid-free while the seek binds the id's native type.
	ParseID func(id string) (any, error)

	// TimestampCols names the keyset columns carried as time.Time, so the token encodes
	// them as a unix-microsecond int64 and restores them before the seek. Sourced from
	// the generated schema (ResourceSchema.TimeColumns), never hand-listed.
	TimestampCols map[string]bool
}

type KeysetColumn struct {
	// Column is the resolved storage column (empty when Join is set — a joined sort has
	// no base column).
	Column string
	// Join, when non-nil, is a joined-table sort target: the ORDER BY is a correlated
	// subquery, not a base column. Only the caller's sort fields can be joined; the
	// appended tiebreaker + id are always same-table. A joined column never participates
	// in the keyset seek (a joined sort is always a custom sort → the offset pager), so
	// this is consumed only by the ORDER BY path.
	Join *types.JoinTarget
	// Derived, when non-nil, is a COMPUTED / CORRELATED sort — a correlated aggregate or
	// a timestamp-plus-interval — with no base column (Column is empty). Like Join, only
	// a caller sort field carries it (never a tiebreaker), and it rides the offset pager
	// (never the keyset seek).
	Derived *types.DerivedSort
	// Ordinal, when non-empty, sorts Column by a value ordinal instead of lexically — the
	// column's DB values in ascending order. Like Join, only a caller sort field carries
	// it (never a tiebreaker), and it rides the offset pager (never the keyset seek).
	Ordinal []string
	// Desc is true for a descending column, false for ascending.
	Desc bool
}

type Map struct {
	// contains filtered or unexported fields
}

type OrdinalFn func(field string) []string

type Reader[T, D any] struct {
	// Runner is the datastore ListRunner: the store's scoped base query + typed execution.
	Runner interfaces.ListRunner[T]
	// Filter is the user's (unresolved) filter; Run resolves its columns via Resolve
	// before use.
	Filter types.Filter
	// ToDomain maps one datastore row to its domain entity.
	ToDomain func(T) (D, error)
	// Resolve maps a field name to its resolved storage column (the allow-list gate).
	Resolve ColumnFn
	// ResolveJoin maps a field name to its joined-table target, or nil for a same-table
	// field. Optional: a resource with no joined filter fields leaves it nil (no joins).
	// Build it from the resource's allow-list with (*Map).Join.
	ResolveJoin JoinFn
	// ResolveOrdinal maps a field name to its value-ordinal sort order, or nil for a
	// field with no ordinal. Optional: a resource with no ordinal-sorted fields leaves it
	// nil. Build it from the resource's allow-list with (*Map).Ordinal.
	ResolveOrdinal OrdinalFn
	// ResolveDerived maps a sort field name to a COMPUTED / CORRELATED sort spec — a
	// correlated aggregate (a Documents/Members count) or a timestamp-plus-interval (a
	// connector's Next Sync) — or nil for a plain/joined/ordinal field. Optional: a
	// resource with no derived sort fields leaves it nil. Supplied by the STORE (a
	// derived sort's correlation is repos-tier knowledge, not a proto-declared column),
	// unlike ResolveJoin/ResolveOrdinal which come from the generated allow-list.
	ResolveDerived DerivedFn
	// MapErr maps a datastore error to a domain error (nil ⇒ pass through unchanged).
	MapErr func(error) error
	// Keyset is the optional keyset spec; nil means this reader is offset-only (a keyset
	// token is rejected).
	Keyset *Keyset[T]
	// Tiebreaker is the resource's final ordering column (after Sort), before the id column.
	Tiebreaker string
	// Sort is the caller's ordering; empty ⇒ the default order (Tiebreaker, id), the only
	// keyset-eligible order.
	Sort []types.OrderField
	// Bounds carries the page-size limits and the total_count cap.
	Bounds Bounds
	// Count requests total_count on the offset arm (bounded by Bounds.CountCap; ignored
	// under skip-count).
	Count bool
}

type ResourceSchema struct {
	// Resource is the resource's Go/message name (e.g. "Document").
	Resource string
	// Fields are the resource's filterable/sortable fields, ordered by field name.
	Fields []FieldSchema
}

type Set struct {
	// contains filtered or unexported fields
}

type ValueSource struct {
	// Kind is one of "enum", "suggest", "entityRef", "freetext".
	Kind string
	// EnumType is the fully-qualified proto enum type when Kind == "enum".
	EnumType string
	// EntityRef is the dimension name when Kind == "entityRef".
	EntityRef string
}