feat: add unpaginate util - #53

unpaginate

The lossy counterpart to toPaginated. Takes the result of a find that may or may not be paginated and yields the items:

export function unpaginate<R>(result: R[] | Paginated<R> | undefined | null): R[]

• a plain array is returned as-is (same reference, no copy)
• a paginated result yields its data
• undefined/null yields []

This is the everyday case as soon as a service is consumed without knowing whether pagination is enabled for it or disabled via params.paginate: false. The pattern was already hand-rolled three times inside this repo.

total, limit and skip are dropped, so unpaginate(toPaginated(x)) round-trips but the reverse does not — the JSDoc says so explicitly. The returned array must be treated as read-only, like common/toArray.

changeMany now uses it in place of Array.isArray(found) ? found : (found?.data ?? []).

One thing to review

src/common/ now imports from src/utils/ for the first time — so far common has been a leaf layer. The import targets the file rather than the barrel, and unpaginate itself has only a type import, so a cycle is impossible. If the layering matters more than the single call site, changeMany can keep its ternary.

Drive-by: missing docs pages

replaceData and replaceResult had no .md, so they had no page on the docs site — missed when they were added in #32. Both JSDoc blocks already pointed at utils/replace-data.html and utils/replace-result.html, i.e. the @see links were dead. Frontmatter added for both; the three pagination utils (toPaginated, unpaginate, predicates/isPaginated) are now cross-linked.

Also carries the pagination tag additions to getResultIsArray and mutateResult.

Testing

pnpm test green: 134 files, 1449 passed / 2 skipped, no type errors, no lint errors. pnpm docs:build and pnpm build clean; the three new pages render.

Known, not addressed here

replaceResult writes only .data on a paginated result and leaves total untouched, so a length-changing replacement leaves a stale total (inherited by mutateResult via delegation, and untested — both tests only cover length-preserving cases). Arguably correct, since total is the number of matches in the database rather than the length of this page, but it is currently implicit. Left for a separate change.

🤖 Generated with Claude Code