docs(rest): pagination total count (`Prefer: count=`) and exactCount option by cb1kenobi · Pull Request #623 · HarperFast/documentation

cb1kenobi · 2026-08-11T23:20:39Z

Documents the REST pagination total-count feature — companion to harper HarperFast/harper#2147.

Changes

reference/rest/querying.md — new "Pagination and Total Count" section: Prefer: count=exact|estimated, the Content-Range / Range-Unit / Preference-Applied response headers, the unavailable-total (.../*) case, HEAD pre-flight, CORS exposure, and disabling exact counts per mount.
reference/rest/overview.md — adds the exactCount option to the rest: config block.
reference/rest/headers.md — adds the Prefer request header and notes the count response headers.

Version

Version badges assume v5.3.0 (next minor after 5.2). If the feature lands in a different release, it's a find/replace of v5.3.0 across the three files.

Verification

npm run format:write + format:check — clean.
npm run build — passes (onBrokenLinks: throw); new cross-links/anchors resolve. The only broken-anchor warnings are pre-existing pages, not these.

🤖 Generated with Claude Code

gemini-code-assist

Code Review

This pull request documents the new pagination and total count feature introduced in version 5.3.0, including updates to headers, configuration options, and querying guides. The review feedback focuses on improving technical accuracy and consistency, specifically by clarifying the description of the Prefer header, using the correct =ct= operator notation, and correcting references to global configuration rather than per-mount settings.

github-actions · 2026-08-11T23:23:40Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-623

This preview will update automatically when you push new commits.

github-actions · 2026-08-11T23:37:12Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-623

This preview will update automatically when you push new commits.

Addresses review feedback on #623: - Drop the confusing/inaccurate "per REST mount" / "on a given mount" scope wording for exactCount. It is not a global setting — it is read only from a component's `rest:` config (server/REST.ts), so describe it as configured "in an application's REST configuration" rather than a mount or a global option. - Refer to the header as the `Prefer` request header (`Prefer: count=exact`). - Use the `=ct=` operator spelling for the contains example, matching the operators table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-08-12T03:01:38Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-623

This preview will update automatically when you push new commits.

github-actions · 2026-08-13T16:46:51Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-623

This preview will update automatically when you push new commits.

github-actions · 2026-08-19T15:31:32Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-623

This preview will update automatically when you push new commits.

Ethan-Arrowood · 2026-09-02T18:33:29Z

Now that the companion merged, @cb1kenobi can you fix the merge conflicts?

kriszyp

Cool, a few minor comments, but looks good.
_{🤖 Reviewed with Codex}

…tion Documents the REST pagination total-count feature shipping in Harper v5.3.0: - reference/rest/querying.md: new "Pagination and Total Count" section covering Prefer: count=exact|estimated, the Content-Range / Range-Unit / Preference-Applied response headers, the unavailable-total (.../*) case, HEAD pre-flight, CORS exposure, and disabling exact counts per mount. - reference/rest/overview.md: adds the `exactCount` rest-mount option. - reference/rest/headers.md: adds the Prefer request header and notes the count response headers. Version badges assume v5.3.0 (next minor after 5.2) — adjust if the feature lands in a different release. Pairs with the harper core branch feat/rest-pagination-total-count. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

A count request without a limit() is served normally with no count headers (the core feature falls through to streaming rather than counting the whole collection). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Addresses review feedback on #623: - Drop the confusing/inaccurate "per REST mount" / "on a given mount" scope wording for exactCount. It is not a global setting — it is read only from a component's `rest:` config (server/REST.ts), so describe it as configured "in an application's REST configuration" rather than a mount or a global option. - Refer to the header as the `Prefer` request header (`Prefer: count=exact`). - Use the `=ct=` operator spelling for the contains example, matching the operators table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…d limit Follows the harper #2147 review outcome: exact counting is now off by default and enabled per mount with `rest: { exactCount: true }`; count=exact is otherwise served as an estimate. Also note that counting applies to GET/HEAD only and requires a limit() within a supported page size. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-authored-by: Dawson Toth <dawson@harperdb.io>

- Document the count page-size bounds (limit ≤ 10,000, window ≤ 1,000,000) and name the exact-scan guardrail (1M-row / ~1s budget) that yields an unavailable total. - Frame HEAD + count=exact as bandwidth-saving, not a low-cost counting shortcut (still scans the matched set). - Clarify estimated counts don't require exactCount, and their total can still be unavailable (*). - Scope exactCount to the REST interface rather than a per-mount setting. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

cb1kenobi · 2026-09-02T22:26:55Z

Rebased on main (the companion feat(rest): total-count pagination via Prefer: count= (Content-Range) #2147 is now merged), resolved the conflicts, and folded in the review feedback. Thanks all for the careful reads! 🙏

Conflicts — three files, all keep-both:

headers.md — kept main's new Cache-Control section and added the count-headers note after the response-headers table.
overview.md — kept main's Tables and Their Automatic Endpoints section and placed the exactCount note under the config block.
querying.md — auto-merged.

Review feedback addressed:

@kriszyp (page-size bounds) — now documented explicitly: limit() must be a non-negative integer ≤ 10,000, and the window (offset + limit) ≤ 1,000,000; anything outside falls through to a normal response with no count headers.
@kriszyp (HEAD "cheap") — reframed as a bandwidth-saving pre-flight, not a low-cost counting shortcut: count=exact still scans the matched set. Also named the exact-scan guardrail (1M-row / ~1s budget) that produces an unavailable total.
@kriszyp + Barber AI ("Estimated counts are always available") — corrected to: estimated counts don't require exactCount, and when no estimate exists the total is *. No longer contradicts the unavailable-total contract.
@dawsontoth (count=estimated in the main headers.md example) — applied.
@gemini-code-assist — dropped the "per mount" framing (exactCount is per REST interface, not per mount) in both querying.md and overview.md; =ct= (contains) notation already in place.

Verification: prettier clean, npm run build passes (onBrokenLinks: throw) with all new cross-links/anchors resolving.

_{🤖 Generated by Claude (Opus 4.8)}

github-actions · 2026-09-02T22:29:19Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-623

This preview will update automatically when you push new commits.

github-actions · 2026-09-02T22:35:44Z

🧹 Preview Cleanup

The preview deployment for this PR has been removed.

cb1kenobi requested a review from a team as a code owner August 11, 2026 23:20

cb1kenobi mentioned this pull request Aug 11, 2026

feat(rest): total-count pagination via Prefer: count= (Content-Range) HarperFast/harper#2147

Merged

gemini-code-assist Bot reviewed Aug 11, 2026

View reviewed changes

Comment thread reference/rest/querying.md Outdated

Comment thread reference/rest/querying.md Outdated

Comment thread reference/rest/querying.md Outdated

Comment thread reference/rest/overview.md Outdated

github-actions Bot temporarily deployed to pr-623 August 11, 2026 23:23 Inactive

github-actions Bot temporarily deployed to pr-623 August 11, 2026 23:37 Inactive

github-actions Bot temporarily deployed to pr-623 August 12, 2026 03:01 Inactive

cb1kenobi mentioned this pull request Aug 13, 2026

REST pagination total count (Prefer: count=) HarperFast/harper#2162

Closed

github-actions Bot temporarily deployed to pr-623 August 13, 2026 16:46 Inactive

dawsontoth approved these changes Aug 13, 2026

View reviewed changes

Comment thread reference/rest/headers.md Outdated

kriszyp mentioned this pull request Aug 15, 2026

Add companion-check workflow: docs PRs auto-merge once their companion code PR lands #629

Merged

github-actions Bot temporarily deployed to pr-623 August 19, 2026 15:31 Inactive

Ethan-Arrowood added the waiting-for-companion PR is generally ready to go as soon as companion (usually implementation) PR merges. label Aug 27, 2026

cb1kenobi commented Sep 1, 2026

View reviewed changes

Comment thread reference/rest/querying.md

kriszyp approved these changes Sep 2, 2026

View reviewed changes

Comment thread reference/rest/querying.md Outdated

Comment thread reference/rest/querying.md Outdated

Comment thread reference/rest/querying.md Outdated

cb1kenobi and others added 6 commits September 2, 2026 17:22

Update reference/rest/headers.md

a145b69

Co-authored-by: Dawson Toth <dawson@harperdb.io>

cb1kenobi force-pushed the docs/rest-pagination-total-count branch from 0cc334f to 28bd76e Compare September 2, 2026 22:26

github-actions Bot temporarily deployed to pr-623 September 2, 2026 22:29 Inactive

cb1kenobi merged commit 7ca851f into main Sep 2, 2026
10 checks passed

cb1kenobi deleted the docs/rest-pagination-total-count branch September 2, 2026 22:35

Uh oh!

Conversation

cb1kenobi commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Version

Verification

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Aug 11, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Aug 11, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Aug 12, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Aug 13, 2026

🚀 Preview Deployment

Uh oh!

Uh oh!

github-actions Bot commented Aug 19, 2026

🚀 Preview Deployment

Uh oh!

Uh oh!

Ethan-Arrowood commented Sep 2, 2026

Uh oh!

kriszyp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cb1kenobi commented Sep 2, 2026

Uh oh!

github-actions Bot commented Sep 2, 2026

🚀 Preview Deployment

Uh oh!

Uh oh!

github-actions Bot commented Sep 2, 2026

🧹 Preview Cleanup

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cb1kenobi commented Aug 11, 2026 •

edited

Loading