test(db): add includes recompute oracle #1716
main fromrefs/pull/1716/head·merged by tannerlinsley Adds a property-based recompute oracle for nested include queries without changing runtime behavior. It gives later include refactors a small, independent test harness that checks incremental results against full recomputation after each change.
Approach#
- Generate
fast-checkhistories across one to four nestedtoArraylevels, including puts, deletes, optimistic confirms, and optimistic rollbacks. - Apply each history to both the live incremental query and a deliberately simple full-recompute model, then compare their normalized result trees after every step.
- Cover nested scalar
materialize(findOne()), optimistic convergence, and metamorphic invariants for alias renaming, sibling order, and unrelated siblings. - Keep stable expected-failure seeds for the known bugs in #1444, #1454, and #1685, plus newly found parent correlation-key update and confirmed child reorder bugs.
Key invariants#
- Every generated incremental state must match the independent recompute model at each checkpoint.
- An expected-failure seed stays red until its bug is fixed. Once it starts passing, Vitest fails the
.failstest so the seed must be promoted to a normal regression test. - Query aliases and unrelated sibling projections must not change the observed result.
- Confirmed optimistic updates must converge to the same state as confirmed-only writes.
Non-goals#
- This PR documents bugs; it does not fix them.
- It does not yet generalize the runner across demand/readiness, publication/revision, ownership/lifecycle, or work-count models. That broader trace-oracle refactor and the remaining RFC cases are deferred in the updated #1658 plan to keep this PR small.
Trade-offs#
The test spells out the depth-specific query shapes so TypeScript checks the real public query API at each depth. This adds some test duplication, but keeps the oracle independent, type-safe, and easy to shrink and replay.
Verification#
All checks pass:
pnpm exec prettier --check packages/db/tests/query/includes-oracle.property.test.ts
pnpm exec eslint packages/db/tests/query/includes-oracle.property.test.ts
cd packages/db
pnpm exec vitest --run tests/query/includes-oracle.property.test.ts --pool-options.threads.maxThreads=2
# 1 file passed, 9 tests passed, no type errors
cd ../..
pnpm --filter @tanstack/db build
Files changed#
packages/db/tests/query/includes-oracle.property.test.ts— adds the recompute model, generated histories, metamorphic checks, scalar materialization coverage, and expected-failure seeds.
Related RFC: #1658
Known bug seeds: #1444, #1454, #1685
Summary by CodeRabbit#
- Tests
- Added comprehensive coverage for nested relationship queries across multiple include depths.
- Tested live-query behavior through inserts, updates, deletes, optimistic confirmations, and rollbacks.
- Added coverage for relationship materialization, arbitrary insertion order, alias changes, sibling ordering, and optimistic update convergence.
- Added regression cases for shared relationships, key updates, duplicate aliases, and child reordering.
- 1
More templates
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1716@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1716@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1716@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1716@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1716@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1716@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1716@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1716@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1716@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1716@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1716@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1716@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1716@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1716@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1716@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1716@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1716@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1716@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1716@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1716@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1716@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1716commit:
dedf116Size Change: 0 B
Total Size: 125 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size packages/db/dist/esm/collection/change-events.js1.43 kB packages/db/dist/esm/collection/changes.js1.38 kB packages/db/dist/esm/collection/cleanup-queue.js810 B packages/db/dist/esm/collection/events.js434 B packages/db/dist/esm/collection/index.js3.62 kB packages/db/dist/esm/collection/indexes.js1.99 kB packages/db/dist/esm/collection/lifecycle.js1.69 kB packages/db/dist/esm/collection/mutations.js2.47 kB packages/db/dist/esm/collection/state.js5.48 kB packages/db/dist/esm/collection/subscription.js3.74 kB packages/db/dist/esm/collection/sync.js2.88 kB packages/db/dist/esm/collection/transaction-metadata.js144 B packages/db/dist/esm/deferred.js207 B packages/db/dist/esm/errors.js5.1 kB packages/db/dist/esm/event-emitter.js748 B packages/db/dist/esm/index.js3.16 kB packages/db/dist/esm/indexes/auto-index.js829 B packages/db/dist/esm/indexes/base-index.js784 B packages/db/dist/esm/indexes/basic-index.js2.17 kB packages/db/dist/esm/indexes/btree-index.js2.29 kB packages/db/dist/esm/indexes/index-registry.js820 B packages/db/dist/esm/indexes/reverse-index.js557 B packages/db/dist/esm/live-query-adapter.js318 B packages/db/dist/esm/local-only.js916 B packages/db/dist/esm/local-storage.js2.12 kB packages/db/dist/esm/optimistic-action.js359 B packages/db/dist/esm/paced-mutations.js496 B packages/db/dist/esm/proxy.js3.75 kB packages/db/dist/esm/query/builder/functions.js1.47 kB packages/db/dist/esm/query/builder/index.js5.84 kB packages/db/dist/esm/query/builder/ref-proxy.js1.24 kB packages/db/dist/esm/query/compiler/evaluators.js1.89 kB packages/db/dist/esm/query/compiler/expressions.js430 B packages/db/dist/esm/query/compiler/group-by.js3.56 kB packages/db/dist/esm/query/compiler/index.js6.67 kB packages/db/dist/esm/query/compiler/joins.js2.5 kB packages/db/dist/esm/query/compiler/lazy-targets.js923 B packages/db/dist/esm/query/compiler/order-by.js1.74 kB packages/db/dist/esm/query/compiler/select.js1.53 kB packages/db/dist/esm/query/effect.js4.77 kB packages/db/dist/esm/query/expression-helpers.js1.43 kB packages/db/dist/esm/query/ir.js1.25 kB packages/db/dist/esm/query/live-query-collection.js360 B packages/db/dist/esm/query/live/collection-config-builder.js9.1 kB packages/db/dist/esm/query/live/collection-registry.js264 B packages/db/dist/esm/query/live/collection-subscriber.js1.93 kB packages/db/dist/esm/query/live/internal.js145 B packages/db/dist/esm/query/live/utils.js1.81 kB packages/db/dist/esm/query/optimizer.js2.92 kB packages/db/dist/esm/query/predicate-utils.js2.97 kB packages/db/dist/esm/query/query-once.js359 B packages/db/dist/esm/query/subset-dedupe.js960 B packages/db/dist/esm/scheduler.js1.3 kB packages/db/dist/esm/SortedMap.js1.3 kB packages/db/dist/esm/strategies/debounceStrategy.js247 B packages/db/dist/esm/strategies/queueStrategy.js428 B packages/db/dist/esm/strategies/throttleStrategy.js246 B packages/db/dist/esm/transactions.js3.04 kB packages/db/dist/esm/utils.js927 B packages/db/dist/esm/utils/array-utils.js273 B packages/db/dist/esm/utils/browser-polyfills.js304 B packages/db/dist/esm/utils/btree.js5.61 kB packages/db/dist/esm/utils/comparison.js1.15 kB packages/db/dist/esm/utils/cursor.js457 B packages/db/dist/esm/utils/index-optimization.js2.39 kB packages/db/dist/esm/utils/type-guards.js157 B packages/db/dist/esm/utils/uuid.js449 B packages/db/dist/esm/virtual-props.js360 B Size Change: 0 B
Total Size: 4.22 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size packages/react-db/dist/esm/index.js249 B packages/react-db/dist/esm/useLiveInfiniteQuery.js1.32 kB packages/react-db/dist/esm/useLiveQuery.js1.33 kB packages/react-db/dist/esm/useLiveQueryEffect.js355 B packages/react-db/dist/esm/useLiveSuspenseQuery.js567 B packages/react-db/dist/esm/usePacedMutations.js401 B Actionable comments posted: 1
🧹 Nitpick comments (6)
packages/db/tests/query/includes-oracle.property.test.ts (6)
891-901: 🚀 Performance & Scalability | 🔵 Trivial | 💤 Low valueGenerate the non-shared scenario directly instead of filtering.
materializeScenarioArbitrarychains fromfc.boolean(). The filter rejects about half of the generated values, so fast-check discards runs to reachnumRuns: 30.Extract the insert-order arbitrary into a function that takes
sharedIntermediate, then call it withfalsehere.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 891 - 901, Update the materialize scenario arbitrary construction by extracting the insert-order arbitrary into a function accepting sharedIntermediate, then build this property’s input with false directly instead of filtering materializeScenarioArbitrary on !sharedIntermediate. Preserve the existing numRuns and expectMaterializeScenarioMatches behavior.
943-956: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winAdd a root-level
orderByto make the comparisons order-independent.None of the four
queryOncecalls order the root rows.toEqualon arrays is order-sensitive. The property then depends on unspecified root iteration order being identical across four separate query executions.Add
.orderBy(({ parent }) => parent.id)to each variant, or sort the results before comparison.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 943 - 956, Add a deterministic root-level order to all four queryOnce variants, using parent.id via orderBy before executing each query, so their array results compare independently of unspecified iteration order. Keep the existing child ordering and query projections unchanged.
291-504: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy liftReduce duplication between the four depth variants.
The four cases repeat the same nested shape. Depth 1 to depth 3 are prefixes of depth 4. The oracle comparison is only meaningful while all four variants stay identical except for depth. Manual duplication lets one variant drift and silently weaken the property.
Extract the repeated child sub-query into a helper, or build the nesting from an array of level collections. If the builder typing blocks a fully generic version, extract at least the deepest three levels into named helpers.
As per coding guidelines: "Extract common logic into utility functions when identical or near-identical code blocks appear in multiple places" and "Extract logical sections from massive functions into separate functions to improve readability and maintainability".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 291 - 504, Reduce duplication in createIncrementalQuery by extracting the repeated nested child-query construction into reusable helpers or by building the nesting from the level collections array. Ensure depths 1–4 remain identical prefixes of the depth-4 shape, preserving each level’s filtering, ordering, and selected fields; if generic typing prevents full extraction, at minimum name and reuse helpers for the deepest three levels.Source: Coding guidelines
1113-1168: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoffConsider asserting the expected failure mode of each red seed.
fcTest.failspasses when the body throws for any reason. A typo, a renamed export, or a cleanup error also makes these tests green. The seeds then stop tracking the specific bugs in#1444,#1454,#1685, and the discovered correlation-key bug.Consider replacing
.failswith a normal test that asserts the current wrong result, plus a comment that names the expected correct result. That form fails loudly when behavior changes in either direction.Also applies to: 1170-1242, 1244-1310
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 1113 - 1168, The red-seed tests using fcTest.fails should explicitly assert their current incorrect results instead of passing on any thrown error. Update the correlation-key test and the analogous seed cases to use normal property tests, assert the observed wrong output, and add comments documenting the expected correct output so regressions, unrelated failures, and fixes in either direction are detected.
568-577: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winCorrelation keys are pinned at row creation in both branches of
applyAction. Both branches reusecurrent?.groupandcurrent?.parentGroupfor every action on an existing row, so the generated histories never change a join key. The main property therefore cannot reach the correlation-key update bug that the seed at lines 1113-1168 documents, and nothing in the code states this exclusion.packages/db/tests/query/includes-oracle.property.test.ts#L568-L577: add a comment above thenextliteral that statesgroupstays fixed on purpose and links the known correlation-key bug.packages/db/tests/query/includes-oracle.property.test.ts#L626-L636: add the same comment forparentGroupandgroup.
As per coding guidelines: "Keep comments that explain non-obvious behavior, such as return value signals or closure captures".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 568 - 577, The generated histories intentionally keep correlation keys unchanged, so document this exclusion with comments above both action-result literals in applyAction: at packages/db/tests/query/includes-oracle.property.test.ts lines 568-577, explain that group remains fixed and reference the known correlation-key bug; at lines 626-636, add the corresponding comment explaining that parentGroup and group remain fixed and reference the same bug.Source: Coding guidelines
1105-1116: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low valueRemove the decorative
seedoptions. These properties usefc.constant(...), so the seed cannot change the generated input. Move issue references to the test names or comments.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 1105 - 1116, Remove the decorative seed options from the two fcTest.fails.prop cases using fc.constant, including the tests for sharedMaterializeSeed and correlation-key-update. Preserve the single-run configuration, and move each issue reference into its test name or an adjacent comment.🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Inline comments: In `@packages/db/tests/query/includes-oracle.property.test.ts`: - Around line 1286-1291: Settle or explicitly catch the optimistic transaction returned by children.collection.update before the test cleanup runs. Follow the existing convergence test pattern by resolving or rejecting the sync promise and awaiting transaction.isPersisted.promise, or attach a catch handler to that promise before finally invokes cleanup(). --- Nitpick comments: In `@packages/db/tests/query/includes-oracle.property.test.ts`: - Around line 891-901: Update the materialize scenario arbitrary construction by extracting the insert-order arbitrary into a function accepting sharedIntermediate, then build this property’s input with false directly instead of filtering materializeScenarioArbitrary on !sharedIntermediate. Preserve the existing numRuns and expectMaterializeScenarioMatches behavior. - Around line 943-956: Add a deterministic root-level order to all four queryOnce variants, using parent.id via orderBy before executing each query, so their array results compare independently of unspecified iteration order. Keep the existing child ordering and query projections unchanged. - Around line 291-504: Reduce duplication in createIncrementalQuery by extracting the repeated nested child-query construction into reusable helpers or by building the nesting from the level collections array. Ensure depths 1–4 remain identical prefixes of the depth-4 shape, preserving each level’s filtering, ordering, and selected fields; if generic typing prevents full extraction, at minimum name and reuse helpers for the deepest three levels. - Around line 1113-1168: The red-seed tests using fcTest.fails should explicitly assert their current incorrect results instead of passing on any thrown error. Update the correlation-key test and the analogous seed cases to use normal property tests, assert the observed wrong output, and add comments documenting the expected correct output so regressions, unrelated failures, and fixes in either direction are detected. - Around line 568-577: The generated histories intentionally keep correlation keys unchanged, so document this exclusion with comments above both action-result literals in applyAction: at packages/db/tests/query/includes-oracle.property.test.ts lines 568-577, explain that group remains fixed and reference the known correlation-key bug; at lines 626-636, add the corresponding comment explaining that parentGroup and group remain fixed and reference the same bug. - Around line 1105-1116: Remove the decorative seed options from the two fcTest.fails.prop cases using fc.constant, including the tests for sharedMaterializeSeed and correlation-key-update. Preserve the single-run configuration, and move each issue reference into its test name or an adjacent comment.🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
0220438a-403c-48d8-85d8-90b0603f0af8📥 Commits
Reviewing files that changed from the base of the PR and between ef0dc8c2a75580582dffb04920c7d2bd2c8107fb and dedf116844a497b2fd77e0af6e8858c99629378d.
📒 Files selected for processing (1)
packages/db/tests/query/includes-oracle.property.test.ts
packages/db/tests/query/includes-oracle.property.test.ts lines 1343 to 1348@@ -0,0 +1271,21 @@1271+ id: root.id,1272+ children: toArray(1273+ q1274+ .from({ child: children.collection })1275+ .where(({ child }) => eq(child.parentGroup, root.group))1276+ .orderBy(({ child }) => child.position)1277+ .select(({ child }) => ({1278+ id: child.id,1279+ position: child.position,1280+ })),1281+ ),1282+ })),1283+ )1284+1285+ try {1286+ await live.preload()1287+ children.collection.update([1, 2], (drafts) => {1288+ drafts[0]!.position = 11289+ drafts[1]!.position = 01290+ })1291+🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
Settle or catch the optimistic transaction before cleanup.
children.collection.update([1, 2], ...)starts an optimistic mutation. The mockonUpdateawaits a sync promise. This test never callsresolveSyncorrejectSync, and never awaits or catchestransaction.isPersisted.promise. Thefinallyblock then callscleanup()while the mutation is still in flight.A rejection raised during cleanup has no handler and surfaces as an unhandled rejection, which can fail unrelated tests in the same run. The convergence test at lines 1073-1088 settles its transaction; follow the same pattern here, or attach
.catch(() => undefined)totransaction.isPersisted.promise.🛡️ Proposed fix
- children.collection.update([1, 2], (drafts) => { - drafts[0]!.position = 1 - drafts[1]!.position = 0 - }) + const transaction = children.collection.update([1, 2], (drafts) => { + drafts[0]!.position = 1 + drafts[1]!.position = 0 + }) + // The sync is never settled here; the assertion below only inspects + // the optimistic state, so the pending promise must not go unhandled. + transaction.isPersisted.promise.catch(() => undefined)📝 Committable suggestion
‼️ IMPORTANT Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
await live.preload() const transaction = children.collection.update([1, 2], (drafts) => { drafts[0]!.position = 1 drafts[1]!.position = 0 }) // The sync is never settled here; the assertion below only inspects // the optimistic state, so the pending promise must not go unhandled. transaction.isPersisted.promise.catch(() => undefined)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/tests/query/includes-oracle.property.test.ts` around lines 1286 - 1291, Settle or explicitly catch the optimistic transaction returned by children.collection.update before the test cleanup runs. Follow the existing convergence test pattern by resolving or rejecting the sync promise and awaiting transaction.isPersisted.promise, or attach a catch handler to that promise before finally invokes cleanup().tannerlinsley merged this91649d7
tannerlinsley closed this
Sign in to join this conversation.
Caution
Review failed#
The pull request is closed.
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
6ce1b1d5-0ad1-4529-bb49-1ee4148d9043📥 Commits
Reviewing files that changed from the base of the PR and between dedf116844a497b2fd77e0af6e8858c99629378d and c2f3cedb8bb07a38703b0e9164995d7b5f2b4b64.
📒 Files selected for processing (1)
packages/db/tests/query/includes-oracle.property.test.ts📝 Walkthrough
Walkthrough#
The PR adds property tests for nested
includesqueries. It covers incremental updates, recomputation, materialization, aliases, ordering, optimistic updates, rollbacks, and regression seeds across include depths one through four.Changes#
Nested includes testing
packages/db/tests/query/includes-oracle.property.test.tspackages/db/tests/query/includes-oracle.property.test.tspackages/db/tests/query/includes-oracle.property.test.tspackages/db/tests/query/includes-oracle.property.test.tsEstimated code review effort: 4 (Complex) | ~45 minutes
Possibly related issues
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
✨ Finishing Touches
📝 Generate docstrings
🧪 Generate unit tests (beta)
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