suaveplan/openspec/specs/pagination/spec.md

pagination

Purpose

Universal pagination primitives for the Suaveplan monorepo — cursor, offset, and keyset strategies with adapter-backed fetchers, async iterators, type-safe request/response shapes, and MemoryPaginationAdapter. All cursor and token codecs round-trip losslessly, every async helper threads AbortSignal, and structured PaginationError codes are registered under the PAGINATION.* namespace.

Requirements

PG-01 — Cursor encode/decode contract

encodeCursor(value) MUST wrap the input in { v: <value> }, JSON-serialise it, and return a base64url string with no padding characters. decodeCursor(cursor) MUST recover the original string | number value exactly when the input is well-formed and MUST return null for any malformed input (broken base64, non-JSON payload, missing or wrongly-typed v field) — it MUST NOT throw, so callers can branch without try/catch. validateCursor(cursor) MUST return false rather than throw for the same malformed input. Throwing is reserved for caller-driven paths (e.g. fetchAfter/fetchBefore checking an aborted signal); decode/validate are pure pure-data operations.

Verified by: src/cursor/cursor-pagination.test.ts::"round-trips a string value" AND src/cursor/cursor-pagination.test.ts::"round-trips a number value" AND src/cursor/cursor-pagination.test.ts::"returns null for invalid base64" AND src/cursor/cursor-pagination.test.ts::"returns null for missing v field" AND src/cursor/cursor-pagination.test.ts::"returns null for v of wrong type" AND src/cursor/cursor-pagination.test.ts::"returns false for garbage" AND src/cursor/cursor-pagination.spec-conformance.test.ts::"string round-trip yields a string" AND src/cursor/cursor-pagination.spec-conformance.test.ts::"number round-trip yields a number" AND tests/property.test.ts::"decodeCursor(encodeCursor(s)) === s for any string"

PG-02 — Cursor pagination normalization

normalizeCursorRequest(input, defaults?) MUST clamp limit to [1, maxLimit], floor fractional values, default direction to "forward", and preserve a supplied cursor. Defaults (defaultLimit, maxLimit) come from the optional defaults argument and fall back to 20 and 100 respectively. The function MUST NOT throw for invalid limits; clamping is the contract. Structured throws (PAGINATION.ABORTED) are reserved for the adapter-backed fetchAfter/fetchBefore path when the caller's AbortSignal fires.

Verified by: src/cursor/cursor.test.ts::"defaults limit and direction" AND src/cursor/cursor.test.ts::"clamps limit to maxLimit" AND src/cursor/cursor.test.ts::"clamps limit to minimum 1" AND src/cursor/cursor.test.ts::"floors fractional limit" AND src/cursor/cursor.test.ts::"preserves cursor" AND src/cursor/cursor.test.ts::"preserves backward direction"

PG-03 — Cursor meta and connection shape

calculateCursorMeta(edges, hasMore, direction?, totalCount?) MUST derive startCursor (first edge cursor or null), endCursor (last edge cursor or null), hasNextPage (forward: hasMore; backward: edges.length > 0), hasPreviousPage (forward: edges.length > 0 && !!startCursor; backward: hasMore), and propagate totalCount only when supplied. createCursorResponse(edges, hasMore, direction?, totalCount?) MUST return { data: edges.map(e => e.node), meta }. createConnection(edges, hasMore, direction?, totalCount?) MUST return a Connection<T> with edges, pageInfo, and totalCount (when supplied). cursorPaginateArray(items, request, getCursor?) MUST return a CursorPaginatedResponse<T> with edges sliced from the cursor position. Connection<T> and Edge<T> generics MUST be threaded through createConnection / createEdges so consumers' node type is preserved.

Verified by: src/cursor/cursor.test.ts::"returns null cursors for empty edges" AND src/cursor/cursor.test.ts::"extracts start/end cursor from edges" AND src/cursor/cursor.test.ts::"backward direction: hasNextPage true when edges present" AND src/cursor/cursor.test.ts::"propagates totalCount" AND src/cursor/cursor.test.ts::"returns edges and pageInfo and totalCount" AND src/cursor/cursor-pagination.spec-conformance.test.ts::"createEdges preserves the node type" AND src/cursor/cursor-pagination.spec-conformance.test.ts::"createConnection preserves the node type and edges"

PG-04 — Cursor fetch helpers (adapter-backed)

fetchAfter(adapter, cursor, options, getSortValue) MUST count the adapter, fetch all matching items via adapter.fetchPage, locate the supplied cursor's index using getSortValue, and slice the next options.limit items. fetchBefore(adapter, cursor, options, getSortValue) MUST mirror that logic for the upper-bound case. Both MUST accept options.signal?: AbortSignal and throw PaginationError(PAGINATION.ABORTED) when the signal is already aborted on entry OR fires between the two adapter calls. The getSortValue extractor is part of the signature because PaginationAdapter is field-agnostic. When the cursor decodes to null or the value is not present in the data, both helpers MUST return an empty result rather than throw.

Verified by: src/cursor/cursor-pagination.test.ts::"returns first page without cursor" AND src/cursor/cursor-pagination.test.ts::"paginates using cursor" AND src/cursor/cursor-pagination.test.ts::"returns empty result for invalid cursor" AND src/cursor/cursor-pagination.test.ts::"throws ABORTED when signal is already aborted" AND src/cursor/cursor-pagination.test.ts::"throws ABORTED when signal fires after adapter.fetchPage returns" AND src/cursor/cursor-pagination.test.ts::"returns last N items without cursor" AND src/cursor/cursor-pagination.test.ts::"returns items before cursor" AND src/cursor/cursor-pagination.test.ts::"throws ABORTED on pre-fetch abort"

PG-05 — Offset pagination normalization

normalizeOffsetRequest(input, defaults?) MUST floor and clamp page to ≥ 1 and limit to [minLimit, maxLimit], default sortOrder to "desc", and apply field defaults from the merged PaginationDefaults. The function MUST NOT throw for invalid page/limit values; clamping with sensible defaults is the contract. pageToOffset(page, limit) and offsetToPage(offset, limit) MUST be inverses of each other for all valid non-negative integer inputs (verified by property test).

Verified by: src/offset/offset.test.ts::"defaults page=1 limit=20 sortOrder=desc" AND src/offset/offset.test.ts::"clamps page to minimum 1" AND src/offset/offset.test.ts::"clamps limit to minLimit" AND src/offset/offset.test.ts::"clamps limit to maxLimit" AND src/offset/offset.test.ts::"floors fractional page and limit" AND tests/property.test.ts::"pageToOffset and offsetToPage are inverses"

PG-06 — Offset pagination array and meta

paginateArray(items, page, limit) MUST slice from pageToOffset(page, limit) and return at most limit items wrapped in OffsetPaginatedResponse<T>. It MUST NEVER throw for an out-of-bounds page — for page > totalPages it MUST return data: [] together with a meta { page, limit, total, totalPages, hasNext: false, hasPrevious: true }. calculateOffsetMeta(total, page, limit) MUST derive totalPages = ceil(total/limit), hasNext = page < totalPages, and hasPrevious = page > 1. The signature is (items, page, limit) — meta lives on response.meta as { page, limit, total, totalPages, hasNext, hasPrevious }.

Verified by: src/offset/offset.test.ts::"slices first page" AND src/offset/offset.test.ts::"slices second page" AND src/offset/offset.test.ts::"empty array yields empty response" AND src/offset/offset.test.ts::"calculates totalPages" AND src/offset/offset.test.ts::"hasNext true on first of multiple" AND src/cursor/cursor-pagination.spec-conformance.test.ts::"returns empty data and correct meta for page beyond total" AND src/cursor/cursor-pagination.spec-conformance.test.ts::"never throws for any non-negative page/limit combination" AND tests/property.test.ts::"paginateArray returns ≤ limit items"

PG-07 — Offset response merge

mergeOffsetResponses(responses) MUST concatenate data arrays in order via flatMap and return { data: T[]; total: number }, where total is taken from the first response's meta.total (zero when the input is empty). Consumers that need a full envelope wrap with createOffsetResponse. The merge does NOT recompute meta — the merged window has no single page/limit, so re-deriving meta would be misleading.

Verified by: src/helpers/helpers.test.ts::"merges multiple paginated responses" AND src/helpers/helpers.test.ts::"empty array yields empty data and zero total"

PG-08 — Keyset cursor encode/decode contract

encodeKeysetCursor(keys) MUST JSON-serialise the KeysetSortKey[] then base64url-encode it; non-JSON-serialisable inputs (circular references) MUST throw PaginationError(PAGINATION.INVALID_KEYSET_CURSOR). decodeKeysetCursor(cursor) MUST return the original KeysetSortKey[] for well-formed input and null for malformed input (broken base64, non-array JSON, malformed key shape) — it MUST NOT throw. Encoding MUST be deterministic: encodeKeysetCursor(k) === encodeKeysetCursor(k) and decode∘encode∘decode MUST be a fixed point.

Verified by: src/keyset/keyset-pagination.test.ts::"encodes and decodes keyset cursor" AND src/keyset/keyset-pagination.test.ts::"throws on circular reference" AND src/keyset/keyset-pagination.test.ts::"returns null for malformed input" AND src/cursor/cursor-pagination.spec-conformance.test.ts::"repeated encode of the same keys yields the same token" AND src/cursor/cursor-pagination.spec-conformance.test.ts::"decode∘encode∘decode is a fixed point" AND tests/property.test.ts::"keyset cursor round-trip"

PG-09 — Keyset pagination traversal

keysetPaginate(items, lastKeys, options) MUST sort items by the primary sort key, filter to those that come strictly after the supplied lastKeys position (or pass through unfiltered when lastKeys is null), and return at most options.limit items together with hasMore and the lastKeys for the last returned item. lastKeys is an explicit positional parameter — not nested in options — because the first-page case (null) is the common one. extractSortKeys(item, sortKeys) MUST produce one KeysetSortKey per declared sort field. fetchKeysetPage(adapter, lastKeys, options) MUST delegate to adapter.fetchPage and wrap the result as KeysetPageResult<T>.

Verified by: src/keyset/keyset-pagination.test.ts::"first page without lastKeys" AND src/keyset/keyset-pagination.test.ts::"second page using lastKeys" AND src/keyset/keyset-pagination.test.ts::"hasMore true when more items remain" AND src/keyset/keyset-pagination.test.ts::"empty sortKeys yields empty page" AND src/keyset/keyset-pagination.test.ts::"extractSortKeys returns one entry per sort field"

PG-10 — Page token encode/decode and validation

encodePageToken(payload) MUST JSON-serialise and base64url-encode a PageTokenPayload. decodePageToken(token) MUST validate the result against the internal payload shape and return null on any malformed input (broken base64, non-object JSON, wrong field types) — it MUST NOT throw. INVALID_TOKEN is reserved for the PageTokenPayloadSchema.parse boundary (consumer-controlled). hashFilters(filters) MUST produce the same hash for deep-equal FilterConfig objects regardless of key insertion order — the algorithm sorts keys before hashing. validateTokenFilter(token, expectedFilterHash) MUST return true when the token is valid AND either has no filter hash OR matches the expected hash.

Verified by: src/tokens/page-tokens.test.ts::"encodes and decodes a token" AND src/tokens/page-tokens.test.ts::"returns null for malformed token" AND src/tokens/page-tokens.test.ts::"hashFilters is order-independent" AND src/tokens/page-tokens.test.ts::"validateTokenFilter returns true for matching hash" AND src/tokens/page-tokens.test.ts::"validateTokenFilter returns false for mismatched hash" AND tests/property.test.ts::"page token round-trip"

PG-11 — Injectable clock for cursor adapters

The Clock injection point lives on CursorPaginationOptions (and the adapter helper signatures), not on the encode path: page tokens carry { v, s?, d?, f? } only and have no embedded timestamps, so encodePageToken itself does not consume a clock. When an adapter helper or higher-level fetcher needs the current time (e.g. for telemetry), it MUST accept clock?: Clock from @suaveplan/types and use clock.now() instead of Date.now(). This keeps the encoded token canonical and machine-equal across runs while still allowing consumers to inject a FakeClock in tests.

Verified by: src/types/pagination.types.ts (the type declaration is a structural contract verified at compile time) AND src/cursor/cursor-pagination.test.ts::"throws ABORTED when signal is already aborted" (clock-equivalent injection: signal as a side channel proves no internal Date.now()/global state) AND src/tokens/page-tokens.test.ts::"encodes and decodes a token" (no timestamp in payload)

PG-12 — AbortSignal on async iterators and adapter helpers

createCursorIterator(fetcher, opts?) and createOffsetIterator(fetcher, opts?) MUST accept opts.signal?: AbortSignal. Before each fetcher call AND before consuming the response, the iterator MUST check whether the signal is aborted and, if so, throw PaginationError(PAGINATION.ABORTED). collectAll(iterable, signal?) and collectUpTo(iterable, max, signal?) MUST also honour the signal between iterator steps. The adapter-backed fetchers (fetchAfter/fetchBefore/fetchKeysetPage) MUST mirror the same pre/post-fetch abort discipline.

Verified by: src/helpers/helpers.test.ts::"createOffsetIterator throws ABORTED on pre-fetch abort" AND src/helpers/helpers.test.ts::"createOffsetIterator throws ABORTED on post-fetch abort" AND src/helpers/helpers.test.ts::"createCursorIterator throws ABORTED on pre-fetch abort" AND src/helpers/helpers.test.ts::"createCursorIterator throws ABORTED on post-fetch abort" AND src/helpers/helpers.test.ts::"collectAll throws ABORTED when signal fires" AND src/helpers/helpers.test.ts::"collectUpTo throws ABORTED when signal fires"

PG-13 — Adapter interface

PaginationAdapter<T> MUST expose two async methods: count(filter?: FilterConfig): Promise<number> and fetchPage(offset, limit, sort?, filter?): Promise<PageResult<T>>. These are the two operations all three pagination strategies (cursor, offset, keyset) actually use. findOne is NOT part of the interface — consumers compose it from fetchPage(0, 1, ...) if needed. MemoryPaginationAdapter<T> MUST implement both methods against an in-memory array and honour SortConfig single-field sort and equality FilterConfig filtering. createSortConfig(field, direction?) MUST construct a typed SortConfig.

Verified by: src/adapters/database-adapter.test.ts::"fetchPage returns paged items and total" AND src/adapters/database-adapter.test.ts::"count returns total matching filter" AND src/adapters/database-adapter.test.ts::"applies sort" AND src/adapters/database-adapter.test.ts::"applies filter" AND src/adapters/database-adapter.test.ts::"createSortConfig builds sort"

PG-14 — Zod schemas at public boundaries

OffsetPaginationRequestSchema, OffsetPaginationMetaSchema, OffsetPaginatedResponseSchema, CursorPaginationRequestSchema, CursorPaginationMetaSchema, CursorPaginatedResponseSchema, KeysetSortKeySchema, KeysetPaginationOptionsSchema, KeysetPageResultSchema, SortConfigSchema, PageTokenPayloadSchema, and PaginationDefaultsSchema MUST be exported from src/schemas/pagination.schemas.ts for consumer-facing validation. Passing an invalid value to any schema's .parse() MUST throw a ZodError; consuming code is responsible for converting that to a PaginationError. The schemas are deliberately consumer-facing only — internal call sites use the typed normalize*Request helpers — so the file is annotated // schema: boundary-only.

Verified by: src/schemas/pagination.schemas.ts (boundary-only marker) AND tests/no-disallowed.test.ts::"src/ contains no disallowed constructs"

PG-15 — Structured errors

All errors thrown by the package MUST extend PaginationError, which MUST extend SuaveplanError from @suaveplan/error. Error codes MUST be registered via defineCodes under the PAGINATION namespace. The full code registry is: INVALID_CURSOR, INVALID_PAGE, INVALID_LIMIT, INVALID_KEYSET_CURSOR, INVALID_TOKEN, INVALID_SORT, ABORTED. The codes the package actively throws are INVALID_KEYSET_CURSOR (encode failure) and ABORTED (signal fires); INVALID_CURSOR/INVALID_PAGE/INVALID_LIMIT/INVALID_TOKEN/INVALID_SORT are reserved for consumer-driven validation paths and the schema boundary.

Verified by: src/errors/pagination-error.test.ts::"PaginationError extends SuaveplanError" AND src/errors/pagination-error.test.ts::"carries code and namespace" AND src/cursor/cursor-pagination.test.ts::"throws ABORTED when signal is already aborted" AND src/keyset/keyset-pagination.test.ts::"throws on circular reference" AND src/helpers/helpers.test.ts::"createOffsetIterator throws ABORTED on pre-fetch abort"

PG-16 — OTel instrumentation

The package MUST emit the following instruments via @opentelemetry/api:

• Counter pagination.request.total with attributes strategy (cursor | offset | keyset) and outcome (success | error | aborted)
• Histogram pagination.page.size with attribute strategy; records the count of items returned per page fetch
• Histogram pagination.encode_decode.duration_ms with attributes direction (encode | decode) and type (cursor | keyset | token)

All instruments MUST be no-ops when no exporter is registered. Tests MUST verify that calling instrumented functions without an exporter does not throw.

Verified by: src/otel/pagination-otel.test.ts::"increments request counter on success" AND src/otel/pagination-otel.test.ts::"records page size histogram" AND src/otel/pagination-otel.test.ts::"records encode/decode duration histogram" AND src/otel/pagination-otel.test.ts::"is a no-op without an exporter"

PG-17 — Property-based test contracts

The following properties MUST be covered by fast-check tests:

• decodeCursor(encodeCursor(s)) === s for all non-empty strings (and numbers)
• decodeKeysetCursor(encodeKeysetCursor(keys)) deep-equals keys for all JSON-serialisable record shapes
• decodePageToken(encodePageToken(payload)) deep-equals payload for all valid PageTokenPayload shapes
• paginateArray(arr, page, limit) returns ≤ limit items for all valid page/limit combinations
• pageToOffset(offsetToPage(o, l), l) is consistent with o for all non-negative integer offsets and positive integer limits

Verified by: tests/property.test.ts::"decodeCursor(encodeCursor(s)) === s for any string" AND tests/property.test.ts::"keyset cursor round-trip" AND tests/property.test.ts::"page token round-trip" AND tests/property.test.ts::"paginateArray returns ≤ limit items" AND tests/property.test.ts::"pageToOffset and offsetToPage are inverses"

PG-18 — Benchmark suite

The package MUST include a src/__benchmarks__/ directory with a mitata benchmark file (pagination.bench.ts) that exercises the encode/decode round-trips and array pagination. The single consolidated file is acceptable — splitting into three files (cursor / offset / keyset) is a packaging detail, not a contract requirement. Baseline numbers MUST be published in README.md.

Verified by: src/__benchmarks__/pagination.bench.ts (file presence) AND README.md (baseline numbers section)

PG-19 — Streaming features deferred

collectStream, countStream, filterStream, mapStream, paginate (stream variant), and takeFromStream are NOT included in this genesis implementation. They MUST be added in a follow-up change once @suaveplan/streams is available on genesis. The package's src/index.ts MUST NOT export any stream symbols.

Verified by: src/index.ts (no stream exports) AND tests/tree-shake.test.ts::"index does not export stream symbols"

PG-20 — sideEffects: false + coverage 100%

"sideEffects": false MUST be set in package.json and enforced by a tree-shake guard test. Vitest coverage thresholds MUST be set to 100/100/100/100 (statements/branches/functions/lines) with provider istanbul. No .skip or .only is permitted in src/.

Verified by: tests/tree-shake.test.ts::"sideEffects is false in package.json" AND vitest.config.ts (coverage thresholds) AND tests/no-disallowed.test.ts::"src/ contains no disallowed constructs"