feat: count typed query scopes for pagination

[medz]

Problem and behavior

Typed user search could return a page, but obtaining its filtered total required loading every model or duplicating the predicates in raw SQL. Add count() to the immutable query scope and generated table facade: one parameterized SELECT returns one integer without selecting or decoding model fields.

Count includes the scope's limit/offset. An unpaged scope uses direct COUNT; a paged scope counts a SELECT 1 derived table, with existing SQLite/PostgreSQL pagination binding shared by reads. Sorting is omitted because it does not change cardinality. No aggregate framework or pagination class is added.

The complete searchUsers example now returns (users: ..., total: ...), validates offset/limit and reuses one typed AND/OR filter scope for total + selected page in one read-only transaction. Empty or later pages retain the filtered total. Direct page.users.first.username remains typed.

Refs #516

Validation and upgrade

• 51 query/business checks passed against real SQLite and PostgreSQL 18 with native postgres 3.5.20; analyzer clean; generated output check and complete shop executable passed.
• Both engines cover escaped text prefixes, nullable filters, immutable reuse, one-cell count without model decoding, parameter limits, limit zero, limit+offset, offset-only, offsets past the end, and omission of unnecessary sorting.
• Business checks assert exactly two SELECTs in the same transaction, engine-enforced read-only settings, direct typed page fields and invalid pagination rejection before SQL. SQLite read-only PRAGMA events stay observable and are not miscounted as business SELECTs.
• The actual-archive consumer is updated to independently regenerate count delegates and verify selected-page totals and an empty page with a nonzero total.
• A Git archive of this exact candidate commit passed the fresh consumer, both engines' generation/migration drafting, analysis, native AOT build and complete business checks. This is prepublication evidence; the actual pub.dev archive will be downloaded and verified after the batch release.
• Existing generated clients remain usable. Regenerate to expose the new count method. Code copied from the shop's searchUsers example now reads .users and .total; no compatibility wrapper is introduced. Frozen schemas, reviewed migration definitions and fingerprints are unchanged.
• Full real-database CI and exact final-head automated review are required before merge. This PR joins the PostgreSQL failure-recovery batch rather than triggering a version by itself.

Summary by CodeRabbit

• New Features
  • Added count() to query APIs, returning the number of rows in the current scope, including any limit and offset.
  • User search now supports configurable paging and returns both the matching users on the requested page and the total number of matches. Invalid offsets and limits are rejected.
• Documentation
  • Added guidance and an example for retrieving a total and a page of results separately. An empty page can still report a nonzero total.

[netlify]

✅ Deploy Preview for prisma-dart canceled.

Name	Link
🔨 Latest commit	b199384
🔍 Latest deploy log	https://app.netlify.com/projects/prisma-dart/deploys/6ac8864a2827f80008792035

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-09T06:16:29.006322Z	b199384	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0f6f135f-b6b5-4c4a-9a35-3d700f25b579

📥 Commits

Reviewing files that changed from the base of the PR and between d73fe50 and b199384.

📒 Files selected for processing (9)

• doc/README.md
• example/main.dart
• example/models.db.dart
• example/shop.dart
• lib/src/dev/emit.dart
• lib/src/query/query.dart
• test/business_test.dart
• test/query_test.dart
• tool/check_package.dart

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The query API adds count() for filtered and paginated scopes. The user-search example now validates pagination and returns both matching users and their total. Tests and documentation cover count behavior and paged search results.

Changes

Scoped Counts and Search Pages

Layer / File(s)	Summary
Implement and expose scoped counts lib/src/query/query.dart, lib/src/dev/emit.dart, example/models.db.dart, test/query_test.dart, doc/README.md	TableQuery.count() counts the current scope, including limit and offset, without applying sorting. Generated table APIs expose the method. Tests and documentation cover filtering, pagination, and count behavior.
Return counted user-search pages example/shop.dart, example/main.dart, test/business_test.dart, tool/check_package.dart	searchUsers validates pagination and returns matching users with their total from a read-only transaction. Examples and tests cover page results, totals, and invalid pagination.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant searchUsers
  participant TableQuery
  participant Database
  searchUsers->>TableQuery: count matching users
  TableQuery->>Database: execute COUNT(*) SELECT
  Database-->>TableQuery: return total
  searchUsers->>TableQuery: select ordered page with offset and limit
  TableQuery->>Database: execute page SELECT
  Database-->>searchUsers: return page rows

Loading

Merge Risk: ⚪ Minimal · up to b1993

No actionable merge blocker is identified; complete the planned final-head checks before merging.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: adding count support for typed query scopes used in pagination.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit counts each row with care
Then pages users from the query there
The first page hops, the next can wait
A total stays beside each state
Two quiet reads complete the tale}

_{Comment @coderabbitai help to get the list of available commands.}