perf: O(1) select-by-ID in DBSQLMemoryAdapter; add JSON and DB benchmarks

[gmpassos]

Adds JSON and DB benchmark suites, and one optimization they turned up.

The optimization: O(1) select-by-ID in DBSQLMemoryAdapter

_selectEntries answered every condition by scanning the table Map and evaluating the condition per row — including a ConditionID, even though that Map is keyed by ID and the adapter already has an O(1) lookup helper. So selectByID was O(rows):

rows	before	after
10	7.80 µs	7.13 µs
50	9.73 µs	7.16 µs
400	25.26 µs	7.22 µs

Now flat. A lookup miss falls through to the original scan, so a ConditionID whose value doesn't match a key exactly (a String '7' against an int 7) resolves exactly as before — just as slowly as it always did. Results are unchanged either way.

This mostly speeds up the test suite and development, since the memory adapter is where those run.

A correction

An earlier commit on this branch claimed the cost of a query "is the repository/transaction machinery". That was wrong, and I'd published it before checking. Scaling the row count shows selectByQuery is linear:

rows	selectByQuery
10	10.9 µs
50	20.4 µs
400	105.9 µs

≈ 8.5 µs fixed + ~0.24 µs/row. The number was dominated by the memory adapter's scan, which a real SQL adapter never pays. Only the fixed part is shared framework cost. benchmark/README.md, the CHANGELOG and the in-file comments now say so, and the DB suite takes --rows=N so the two can be separated.

What the suites show otherwise

JSON needs nothing. Json.encodeToSink — the response path — runs close to a bare dart:convert encode (~1.5 µs vs ~1.2 µs, small map) and is faster on larger payloads, since it writes bytes to a sink instead of building a String. Request bodies go through dart:convert directly, so there's no layer to remove.

DB, at 50 rows:

	µs/op
ConditionParseCache.parseQuery (cached)	0.010
Entity.toJson	0.074
generateSelectSQL	0.83
EntityHandler.createFromMap	1.12
ConditionParser.parse (shared parser)	2.74
Transaction.executeBlock (empty)	2.43
repository.selectByID	7.26

The two things a query is assumed to be expensive for are not: parsing is cached at ~300× cheaper than parsing, and SQL generation is under a microsecond.

Two hypotheses that failed

Recorded so they aren't re-tried:

1. Per-response JsonEncoder. Json._buildJsonEncoder returns the cached defaultEncoder only when every argument is defaulted — and the response path always passes toEncodable, so it builds a fresh encoder each time. Memoizing it (safe: autoResetEntityCache defaults to true) moved the small-map encode 1.555 → 1.522 µs and made the 50-map case slightly worse. Noise.
2. Eager Completers. Transaction creates three in its constructor despite the fields being late final. Making them lazy left an empty executeBlock at 2.40 µs, unchanged.

Neither is included.

Another measurement error worth flagging

My first DB run reported ConditionParser.parse at 125 µs, which looked like a major find. It was my benchmark constructing a ConditionParser per iteration — the cost is PetitParser building the grammar lazily. bones_api holds it in a static final, so it's a one-off startup cost and there's no bug. The corrected benchmark reuses the parser (2.74 µs), with a note in the README since a per-query parser would be catastrophic.

Where to look next

Transaction.executeBlock — 2.4 µs for an empty block is the floor under every DB operation and the largest remaining fixed cost. That wants a real profiler (dart run --observe), not more micro-benchmarks.

The DB suite carries a small self-contained BenchUser entity so it doesn't depend on the test fixtures.

Gate	Result
dart test --exclude-tags docker	783 passed
dart analyze --fatal-infos --fatal-warnings .	clean
dart format -o none --set-exit-if-changed .	clean

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.16%. Comparing base (f169496) to head (2be651a).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #151      +/-   ##
==========================================
+ Coverage   68.14%   68.16%   +0.02%     
==========================================
  Files          66       66              
  Lines       22129    22137       +8     
==========================================
+ Hits        15080    15090      +10     
+ Misses       7049     7047       -2     

Flag	Coverage Δ
unittests	68.16% <100.00%> (+0.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.