feat: offset / page / orderByID / orderDirection on selectByQuery and siblings (v1.11.0)

[gmpassos]

Context

selectByQuery and its siblings already accepted limit, but there was no way to paginate: no OFFSET, and no ordering support of any kind anywhere in the query machinery (the only ORDER BY in lib/ was inside a Postgres pg_constraint introspection query). Without a stable order a LIMIT alone returns an arbitrary subset, so page-by-page reads were impossible to write correctly. The one place that did order results — APIDBModule.select — worked around it by selecting every row and sorting by ID in Dart.

What this adds

Four optional parameters across the whole select surface:

• offset — the return offset.
• page — 1-based page, the ergonomic form of offset: resolves to (page - 1) * limit.
• orderByID — orders by the table's ID column, resolved automatically from the machinery that already existed (TableScheme.idFieldName → EncodingContext.tableFieldID, or EntityHandler.idFieldName). No new resolution code.
• orderDirection — new OrderDirection enum: ascending (default) / descending.

Semantics

Rule	Behavior
Effective ordering	orderByID ?? (offset != null) — an offset implies the ordering, so pagination is stable by default
Opt-out	orderByID: false with an offset emits a bare OFFSET, no ORDER BY
orderDirection alone	Ignored while the ordering is not active
page → offset	(page - 1) * limit. page: 1 → offset: 0, which still activates the ordering, so even the first page is stable
Existing callers	All four unset → generated SQL is character-identical to 1.10.0

// Page 3, 20 per page. Stable, and no ordering to spell out:
await accountRepo.selectByQuery(' state == ? ', parameters: ['NY'],
    limit: 20, page: 3);
// -> SELECT "ac".* FROM "account" as "ac" WHERE ( ... )
//    ORDER BY "ac"."id" ASC LIMIT 20 OFFSET 40

// The 10 newest:
await accountRepo.selectAll(limit: 10,
    orderByID: true, orderDirection: OrderDirection.descending);

page validation

page is a public convenience resolved to an offset at the repository layer by the shared resolveSelectOffset. The adapter contract, SQL, SQLDialect, the SQL generation and every DB adapter still take offset alone — so no second source-breaking widening of the abstract adapter methods.

It throws an ArgumentError rather than silently returning the wrong rows when:

Case	Why
page + offset	Two spellings of one concept — passing both is a bug, not a precedence question
page without a positive limit	A page has no meaning without a page size, and limit: 0 already means "no limit" here. Includes page: 1, so the rule stays predictable
page < 1	Pages are numbered from 1; a 0-based caller silently getting page 1 is an off-by-one that never surfaces

selectFirstByQuery forces limit: 1, so page: n there is the Nth entity.

Dialects

All dialect-specific SELECT tail syntax now lives in SQLDialect.orderBySQL / limitOffsetSQL, with two new capabilities: offsetRequiresLimit and offsetMaxLimitValue.

MySQL can't parse an OFFSET that is not preceded by a LIMIT, so an offset-only select there emits LIMIT 18446744073709551615 OFFSET n. PostgreSQL and the generic (in-memory) dialect emit a bare OFFSET n. This is asserted per-dialect and exercised against real containers.

⚠️ Behavior change: limit starts working where it was ignored

limit was accepted and silently discarded by DBEntityRepository.select's ConditionID/ConditionIdIN/ConditionANY/KeyConditionEQ fast paths, by DBAdapter.doSelectAll/doSelectByIDs, and by every DBObject* adapter. Those are all fixed here, so e.g. selectAll(limit: 2) on an object adapter returned every row before this PR and now returns 2. There is an explicit regression test pinning this.

⚠️ Source-breaking for external subclasses

New named parameters were added to abstract members (EntitySource.select/selectIDsBy/selectAll, DBAdapter.doSelectAll/doSelectByIDs, DBRelationalAdapter.doSelect/doSelectIDsBy). Dart requires an override to accept every named parameter of the supertype, so third-party EntityRepository/DBAdapter implementations must widen their overrides. Hence the minor bump (1.10.0 → 1.11.0), not a patch.

APIDBModule.select

/db/select/<table> gains LIMIT=<n>, OFFSET=<n>, PAGE=<n> and ORDER=asc|desc query directives, parsed alongside the pre-existing EAGER=true and stripped before the remainder is parsed as the entity condition query. The ad-hoc EAGER=true string surgery is replaced by a general directive extractor. The manual Dart-side sort is gone — the ordering is resolved by the DB. Output order for existing calls is unchanged (this endpoint defaults to orderByID: true, not to the offset != null rule). An invalid PAGE returns an error response rather than an uncaught ArgumentError.

/db/select/user/json?email == "a@b.c"&LIMIT=10&PAGE=3&ORDER=desc

Commits (each independently compilable and tested)

ac67146	OrderDirection + the shared ordering/pagination primitives + SQLDialect clause builders
238663a	offset/orderByID/orderDirection threaded through the SQL path and the public API
602bb6c	The DBAdapter object path — closes the limit dead ends
1241b3a	APIDBModule.select query directives
b9fe0b0	v1.11.0 chores
47eb8c7	The page parameter + PAGE directive
a581922	CI: upgrade GitHub Actions versions
1256462	reflection_factory ^2.8.1 + regenerate
93ed7fc	Close the gaps in the pagination/ordering test suite

(Commits 493f801..edafbc9 are a pin/CI experiment that nets to zero — git diff 47eb8c7 edafbc9 is empty. Squash-merge, or say the word and I'll drop them.)

Testing

719 VM tests + 447 Chrome tests pass, with the Docker daemon running so the PostgreSQL and MySQL suites actually executed rather than self-skipping.

• 3 new test files: bones_api_entity_select_order_test.dart (enum, comparator, shared applier, resolveSelectOffset incl. all three error paths, dialect clause builders), bones_api_entity_db_sql_select_test.dart (exact generated SQL per case + end-to-end paging by offset and by page), and bones_api_db_module_test.dart — the first test coverage APIDBModule has ever had.
• 3 new tests in the shared runAdapterTests template, so the generated SQL and real page-by-page reads are asserted for the in-memory, PostgreSQL, MySQL, object-memory and object-directory adapters at once.
• Photo (String IDs) is used for the object-adapter test, covering the non-numeric branch of compareEntityIDs.

dart format, dart analyze --fatal-infos --fatal-warnings, dart pub publish --dry-run and ensure_build_test are all clean.

Toolchain fixes pulled in along the way

CI went red on ensure_build_test for a reason unrelated to this feature: reflection_factory 2.8.0 was published after the last master build, and ^2.7.5 let CI's dart pub upgrade take it. 2.8.0 requires dart_style: ^3.1.9 → resolves 3.1.12, whose output differs from the dart_style 3.1.6 vendored in Dart SDK 3.12.2 — making dart format --set-exit-if-changed and ensure_build_test mutually exclusive.

Resolved upstream rather than worked around here:

• reflection_factory 2.8.1 (published) caps dart_style below 3.1.10, with a regression test that compares DartFormatter against the SDK's dart format on the generated-proxy shape.
• This PR now requires reflection_factory: ^2.8.1 — deliberately not ^2.7.5, which would let consumers of the released 1.11.0 resolve the broken 2.8.0. The regenerated *.g.dart change only the builder version stamp; there is no formatting change.
• Reported to the formatter: dart-lang/dart_style#1882 — the 3.1.10 style change is not language-versioned, so no SDK constraint avoids it (verified at language versions 3.7, 3.10, 3.11 and 3.12).
• GitHub Actions versions upgraded: checkout v4→v7, setup-dart v1→v1.7.2, codecov-action v3→v7 (token moved to an input, as v4+ requires). No workflow logic changed.

Test coverage added after review

Gaps where the original assertions would have passed even with a broken implementation:

• Non-id ID column — every test entity uses id, so orderByID would have passed even if the column were hardcoded. A legacy_item table with idFieldName: 'item_code' now asserts the emitted SQL orders by item_code and contains no .id at all.
• ORDER BY across a JOIN — must target the main table's alias. All 5 campaigns share one config row, so ordering by the joined table's ID would give arbitrary paging and fail.
• Ordering survives eager resolution — paging with EntityResolutionRules(allEager: true).
• Stability — the same page requested repeatedly returns the same rows, which is the point of offset ⇒ orderByID.
• Empty results — a query matching nothing stays empty under offset/limit.

Not covered

DBObjectGCSAdapter has no test suite in this repo (it had none before either), so its symmetrical change is compile-checked and review-only.

Known limitation (pre-existing, documented not fixed)

A query over a to-many relationship generates a JOIN without a DISTINCT, so it can already return the same entity more than once. Layering LIMIT/OFFSET on top means such a page can contain duplicates — paginating those queries is best-effort. Noted in the dartdoc and the CHANGELOG.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 92.59259% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.49%. Comparing base (3bd35fb) to head (93ed7fc).

Files with missing lines	Patch %	Lines
lib/src/bones_api_entity_db.dart	57.89%	8 Missing ⚠️
lib/src/bones_api_entity.dart	91.11%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #145      +/-   ##
==========================================
+ Coverage   66.47%   67.49%   +1.02%     
==========================================
  Files          63       63              
  Lines       21222    21347     +125     
==========================================
+ Hits        14107    14409     +302     
+ Misses       7115     6938     -177     

Flag	Coverage Δ
unittests	67.49% <92.59%> (+1.02%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.