pagination

type Cursor struct {
	SortField   string      `json:"sort_field"`
	SortValue   interface{} `json:"sort_value"`
	UniqueField string      `json:"unique_field"`
	UniqueValue interface{} `json:"unique_value"`
	Direction   string      `json:"direction,omitempty"`
}

type CursorRequest struct {
	Limit        int    `json:"limit"`
	Cursor       string `json:"cursor"`
	Sort         string `json:"sort,omitempty"`
	IncludeCount bool   `json:"include_count,omitempty"`

	// Filter is server-side only: Field and Comparison are interpolated into SQL and must never come from client input.
	Filter []query.Filter `json:"-" xml:"-"`
}

type CursorResponse struct {
	NextCursor  string `json:"next_cursor,omitempty"`
	HasNextPage bool   `json:"has_next_page"`
	TotalCount  *int   `json:"total_count,omitempty"`
}

type Options struct {
	// Direction is the default order, used when the request has no Sort. A Direction other than ASC or DESC,
	// the zero value included, is ez.EINTERNAL, even under a client sort.
	Direction OrderDirection
	// SortFields is the allowlist of client sorts: sort name to a column of the model's table,
	// e.g. {"name": "name"}, rendered as ?TableAlias."name" from the model's bun schema. Empty means the
	// client cannot choose the sort. A client-sortable column must be NOT NULL and selected by the query: the
	// keyset comparison skips rows whose sort value is NULL, and a column the query does not select pages from
	// a zero value. Give each sortable column an index on (column, unique column) for large tables. A Go float
	// field sorts correctly only on a column no wider than its type, holding finite values: a float32 only on
	// real, a float64 on real or double precision. A wider column, double precision under a float32 or numeric
	// with more digits than the field holds, is rounded in the cursor, so pages repeat or skip rows and may
	// never end, and NaN or ±Infinity cannot be stored in a cursor, so the page fails with ez.EINTERNAL. Map a
	// numeric column to a string or decimal type implementing driver.Valuer instead.
	SortFields map[string]string
	// AllowCount lets the client ask for a count with IncludeCount. False means the client cannot ask for a
	// count. The count is a count(*) over the whole filtered query on every request that asks for it, so
	// enable it only on lists whose filtered set is bounded. The count does not run the model's BeforeSelect
	// hook, so rows that hook filters out of the page are still counted: filter on the query passed to
	// Paginate instead. A count renders the query twice, and bun runs the apply function of a has-one or
	// belongs-to relation on every render. What an apply function adds to the query it is given (conditions,
	// joins, columns) is not repeated in the page query. Two things can still change the page query when a
	// count is asked for, so the page can fail or disagree with the total: an apply function that calls
	// Relation with another apply function, or JoinOn on a join the query already had, and a relation with
	// an apply function inside a With query or a subquery. Do not enable the count on such a list.
	AllowCount bool
}

type OrderDirection string

type Paginatable interface {
	GetSortField() string        // Returns the SQL expression of the default sort, e.g. "?TableAlias.created_at"
	GetSortValue() interface{}   // Returns the value of the default sort field
	GetUniqueField() string      // Returns the SQL expression of the unique tie-breaker, e.g. "?TableAlias.id"
	GetUniqueValue() interface{} // Returns the value for the unique field
}