pagination

func Empty ¶

func Empty() *empty

Empty returns a pagination instance that will force a query an empty page

func EmptyFromRaw ¶

func EmptyFromRaw(raw []byte) (*empty, error)

func Keyset ¶

func Keyset[I comparable](offset, pageSize int, sqlIdName common.FieldName, idGetter func(any) I) (*keyset[I], error)

Keyset creates a keyset (cursor) pagination over the SQL column sqlIdName, where idGetter extracts that id from a row returned by the query.

Constraints, which the caller is responsible for satisfying:

• the generated SQL always orders by sqlIdName ascending and walks forward with `sqlIdName > cursor`. There is no descending variant and no secondary tiebreaker column, so sqlIdName must be unique; a non-unique column would silently skip rows that share the cursor value.
• only int and string ids are supported; anything else is rejected here rather than panicking later while the query is being built.

func KeysetFromRaw ¶

func KeysetFromRaw[I comparable](raw []byte, idFieldName PropertyName[I]) (*keyset[I], error)

KeysetFromRaw initializes a Keyset pagination struct from a buffer. It also needs to get the field name of the id in the struct returned by the database. This is used in a member function and is not serializable.

func KeysetWithField ¶

func KeysetWithField[I comparable](offset, pageSize int, sqlIdName common.FieldName, idFieldName PropertyName[I]) (*keyset[I], error)

KeysetWithField creates a keyset pagination where the id is read from the exported struct field idFieldName of each returned row. See Keyset for the ordering constraints that keyset pagination imposes.

func KeysetWithId ¶

func KeysetWithId[I comparable, V id[I]](offset, pageSize int, sqlIdName common.FieldName) (*keyset[I], error)

KeysetWithId creates a keyset pagination where each row returned by the query reports its own id through Id().

It returns the same *keyset[I] as every other constructor here. It used to be parameterised on the row type as well, which made it a distinct generic instantiation that neither the pagination interpreter nor NewPage could match, so every call panicked (#2044). See Keyset for the ordering constraints that keyset pagination imposes.

func NewDefaultInterpreter ¶

func NewDefaultInterpreter() *interpreter

func NewPage ¶

func NewPage[V any](results collections.Iterator[*V], pagination driver.Pagination) (*driver.PageIterator[*V], error)

NewPage creates a new page where the id is a string

func None ¶

func None() *none

None returns a pagination instance that will force a query to return everything in one shot

func NoneFromRaw ¶

func NoneFromRaw(raw []byte) (*none, error)

func Offset ¶

func Offset(os, pageSize int) (*offset, error)

Offset creates a pagination using LIMIT/OFFSET.

Note that `OFFSET n` makes the database scan and discard n rows on every page, so the cost of fetching a page grows with its distance from the start. It is the right choice for random access into a small number of pages; for walking a large result set from beginning to end, prefer Keyset.

func OffsetFromRaw ¶

func OffsetFromRaw(raw []byte) (*offset, error)

func ValidateLimited ¶ added in v0.21.0

func ValidateLimited(p driver.Pagination, maxPageSize int) error

ValidateLimited rejects pagination that would run an unlimited scan: nil, None(), or a page (offset or keyset) whose page size is non-positive or exceeds maxPageSize (limited only when maxPageSize > 0). Empty pagination (an always-empty page) is allowed. Any pagination type that does not expose a page-size limit is rejected (fail closed): the guard cannot prove it is bounded, so it must not be allowed to run a possibly unlimited scan.