test(db): extract reusable trace runner #1718
main fromrefs/pull/1718/head·merged by tannerlinsley Extract the includes recompute-oracle loop into a reusable trace runner, then validate the driver/projection boundary with structural histories, scalar materialization, and full-row sync batches. This is test-only, and the expanded scalar driver has already exposed a new deterministic incremental-materialization bug.
Reviewer guidance#
Root cause#
The includes oracle had two hand-written execution loops. That made each new mutation or lifecycle domain repeat setup, checkpoint, and cleanup behavior instead of sharing one contract.
The first extracted runner also awaited every hook unconditionally. Awaiting a synchronous apply yields to the microtask queue before the checkpoint, which could hide stale state repaired by a queued microtask. Its cleanup path could replace the useful trace failure, and assertEqual: () => void allowed an async assertion whose promise the runner ignored.
Approach#
- A driver owns setup, startup, step application, and cleanup.
- A projection observes live state, recomputes expected state independently, and compares the two.
- The runner checks after startup and every step. Drivers can request extra checkpoints within a step.
- The runner awaits only promise-like hook results, so synchronous mutations and checkpoints stay in the same turn.
- If both the trace and cleanup fail, the trace error remains primary and the cleanup error is attached as suppressed diagnostic data.
- Projection assertions must return
undefined; a type test rejects async assertions. - A deterministic full-row driver sends multi-change sync batches through the structural projection. Its trace covers inserts, updates, reparenting, deletion, and insertion.
- The scalar-materialization driver can update a nested reference. A reduced five-step expected-failure seed records the new bug it found: changing
middle.sharedIdupdates the visible key but leaves the old nested shared row materialized.
Key invariants#
- Synchronous mutations and their checkpoints occur in the same turn.
- Async lifecycle hooks finish before the runner advances.
- Every trace checks its initial post-start state and the state after each step.
- Explicit checkpoints can verify intermediate optimistic states within a step.
- Cleanup runs after startup, step, or assertion failures.
- A trace failure stays primary if cleanup also fails; cleanup alone still fails the run.
- Observed state and recomputed state remain independent.
- Known and discovered runtime failures must reject with the oracle assertion, not an unrelated harness error.
Non-goals#
- No production query fix for the newly discovered nested-reference bug; that belongs in a separate small PR.
- No broad generators yet for full-row batches, timing, lifecycle, publication, rekeying, or deeper guaranteed paths.
- No changes to existing known-failure seeds.
- No replay system or multiple-projection orchestration.
Trade-offs#
Assertions remain synchronous to preserve exact checkpoint timing. The batch driver uses a short deterministic trace: it is enough to test the abstraction with a distinct mutation model while leaving the larger fuzz-domain expansion for later RFC slices. The new bug stays as an assertion-specific expected failure so this test-infrastructure PR remains green without hiding unrelated failures.
Verification#
From packages/db:
pnpm exec vitest run tests/query/includes-oracle.property.test.ts tests/trace-runner.test.ts tests/trace-runner.test-d.ts
pnpm test
- Oracle file: 12 tests passed; no type errors.
- Full DB suite: 110 files, 2,541 tests passed, 5 skipped; no type errors.
- ESLint, Prettier, and
git diff --checkpass.
Files changed#
packages/db/tests/trace-runner.ts: adds the shared runner and its timing and error-handling guarantees.packages/db/tests/trace-runner.test.ts: tests checkpoints, same-turn timing, and cleanup failure precedence.packages/db/tests/trace-runner.test-d.ts: proves async projection assertions are rejected.packages/db/tests/query/includes-oracle.property.test.ts: migrates the existing oracle drivers, adds the full-row batch driver, and records the nested-reference failure.
Release impact#
- This change is docs/CI/dev-only (no release).
Related work: RFC #1658, #1716, #1717.
Summary by CodeRabbit#
- Tests
- Added comprehensive trace-based coverage for structural, full-row batch, and materialization scenarios.
- Added validation for checkpoints during startup, after each step, and at explicit checkpoints.
- Ensured cleanup runs reliably after assertion failures and preserves the original error.
- Added coverage for batched partial and full-row updates.
- Added materialization checks for leaf updates following inserts.
- 1
🧹 Nitpick comments (4)
packages/db/tests/query/includes-oracle.property.test.ts (2)
945-960: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueOptional: build the increment steps with
filterand spread.The second loop repeats the
leaf-1/leaf-2test and the id mapping. An array-method form states the intent in one pass.♻️ Proposed refactor
function createMaterializeTraceSteps( insertOrder: Array<MaterializeInsert>, ): Array<MaterializeTraceStep> { - const steps: Array<MaterializeTraceStep> = insertOrder.map((insert) => ({ - type: `insert`, - insert, - })) - - for (const insert of insertOrder) { - if (insert === `leaf-1` || insert === `leaf-2`) { - steps.push({ type: `incrementLeaf`, id: insert === `leaf-1` ? 1 : 2 }) - } - } - - return steps + const leafId = (insert: MaterializeInsert): number => + insert === `leaf-1` ? 1 : 2 + + return [ + ...insertOrder.map( + (insert): MaterializeTraceStep => ({ type: `insert`, insert }), + ), + ...insertOrder + .filter((insert) => insert === `leaf-1` || insert === `leaf-2`) + .map((insert): MaterializeTraceStep => ({ + type: `incrementLeaf`, + id: leafId(insert), + })), + ] }As per coding guidelines: "Use array methods like
filter()instead of manual loops for array transformations" and "Use the spread operator for combining arrays instead of manual loops with push".🤖 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 945 - 960, Refactor createMaterializeTraceSteps to build incrementLeaf steps with filter/map and combine them with the initial insert steps using spread, removing the manual loop and push while preserving the existing leaf-to-ID mapping.Source: Coding guidelines
777-787: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winBoth projections type the observed value as
unknown.assertEqualthen compares an untyped value against a precisely typed expectation, so a shape drift between the live query result and the oracle result no longer fails type checking. IfstripVirtualPropertiesreturns a typed value, pass that type instead ofunknown. If it returns a loose type, add a small typed wrapper for the observed shape.packages/db/tests/query/includes-oracle.property.test.ts#L777-L787: replace theunknowntype argument ofstructuralProjectionwith the observed structural shape, for exampleArray<OracleNode>.packages/db/tests/query/includes-oracle.property.test.ts#L1000-L1016: replace theunknowntype argument ofmaterializeProjectionwith the observed materialization shape, for exampleArray<MaterializeTree>.
As per coding guidelines: "Always provide the most precise return type annotation; avoid
unknownoranyreturn types unless truly necessary".🤖 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 777 - 787, Replace the unknown observed-type arguments in both projections with their precise observed shapes: use Array<OracleNode> for structuralProjection at packages/db/tests/query/includes-oracle.property.test.ts:777-787 and Array<MaterializeTree> for materializeProjection at packages/db/tests/query/includes-oracle.property.test.ts:1000-1016, preserving the existing observation and equality logic.Source: Coding guidelines
packages/db/tests/trace-runner.ts (1)
44-54: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winConsider preserving the original failure if
cleanupalso throws.If a checkpoint assertion fails and
driver.cleanupthen rejects, the cleanup error replaces the assertion error. The oracle drivers callincremental.cleanup()andcleanupSources(sources), which can reject after a failed step. The property test then reports a teardown error instead of the mismatch that caused it.♻️ Proposed change to keep the primary error
try { await driver.start?.(context) checkpoint() for (const step of steps) { await driver.apply(step, context, checkpoint) checkpoint() } + } catch (error) { + try { + await driver.cleanup(context) + } catch { + // Keep the original trace failure as the reported error. + } + throw error } finally { - await driver.cleanup(context) + // cleanup already ran on the error path }A simpler variant is a
let failed = falseflag, orPromise.allSettled-style handling, if you prefer to keep a singlefinally.🤖 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/trace-runner.ts` around lines 44 - 54, Update the trace runner’s try/finally flow around driver.start, step execution, and checkpoint so cleanup failures do not replace the original execution or assertion error. Preserve the primary failure, while still awaiting driver.cleanup(context) and surfacing its error when no earlier failure occurred.packages/db/tests/trace-runner.test.ts (1)
45-67: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd corner-case tests for the runner lifecycle.
The current suite covers the happy path and a failing checkpoint. Three cases remain untested, and all three are reachable through the oracle drivers:
steps: []. The runner must still check after startup and callcleanuponce.- An async driver.
setup,start,apply, andcleanupeach may return a promise. Assert that the runner awaits them in order. driver.applythrowing. Assert thatcleanupstill runs.
Note also that
applyon Line 53 never executes in this test, because the startup checkpoint throws first.💚 Proposed additional tests
it(`cleans up when a checkpoint fails`, async () => {it(`checks after startup and cleans up for an empty trace`, async () => { const checkpoints: Array<number> = [] const cleanup = vi.fn() await runTrace({ steps: [], driver: { setup: () => ({ observed: 0, expected: 0 }), apply: () => undefined, cleanup, }, projection: { observe: (context) => context.observed, recompute: (context) => context.expected, assertEqual: (observed, expected) => { expect(observed).toBe(expected) checkpoints.push(observed) }, }, }) expect(checkpoints).toEqual([0]) expect(cleanup).toHaveBeenCalledOnce() }) it(`awaits an asynchronous driver in order`, async () => { const calls: Array<string> = [] const tick = async () => { await Promise.resolve() } await runTrace({ steps: [1], driver: { setup: async () => { await tick() calls.push(`setup`) return { observed: 0, expected: 0 } }, start: async () => { await tick() calls.push(`start`) }, apply: async (step, context) => { await tick() context.observed += step context.expected += step calls.push(`apply`) }, cleanup: async () => { await tick() calls.push(`cleanup`) }, }, projection: { observe: (context) => context.observed, recompute: (context) => context.expected, assertEqual: (observed, expected) => { expect(observed).toBe(expected) calls.push(`check`) }, }, }) expect(calls).toEqual([`setup`, `start`, `check`, `apply`, `check`, `cleanup`]) }) it(`cleans up when apply throws`, async () => { const cleanup = vi.fn() await expect( runTrace({ steps: [1], driver: { setup: () => ({ observed: 0, expected: 0 }), apply: () => { throw new Error(`apply failed`) }, cleanup, }, projection: { observe: (context) => context.observed, recompute: (context) => context.expected, assertEqual: (observed, expected) => { expect(observed).toBe(expected) }, }, }), ).rejects.toThrow(`apply failed`) expect(cleanup).toHaveBeenCalledOnce() })As per coding guidelines: "Test corner cases including: empty arrays/sets, single-element collections, undefined vs null values, resolved promises, async race conditions, and limit/offset edge cases".
🤖 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/trace-runner.test.ts` around lines 45 - 67, Add the three missing lifecycle tests alongside the existing trace-runner tests: verify empty steps perform the startup checkpoint and call cleanup once, verify async setup/start/apply/cleanup methods are awaited in the order setup, start, check, apply, check, cleanup, and verify cleanup runs when driver.apply throws while preserving the original error. Use the existing runTrace, driver, and projection symbols and assert the specified checkpoint, call-order, and cleanup behavior.Sources: Coding guidelines, Learnings
🤖 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. Nitpick comments: In `@packages/db/tests/query/includes-oracle.property.test.ts`: - Around line 945-960: Refactor createMaterializeTraceSteps to build incrementLeaf steps with filter/map and combine them with the initial insert steps using spread, removing the manual loop and push while preserving the existing leaf-to-ID mapping. - Around line 777-787: Replace the unknown observed-type arguments in both projections with their precise observed shapes: use Array<OracleNode> for structuralProjection at packages/db/tests/query/includes-oracle.property.test.ts:777-787 and Array<MaterializeTree> for materializeProjection at packages/db/tests/query/includes-oracle.property.test.ts:1000-1016, preserving the existing observation and equality logic. In `@packages/db/tests/trace-runner.test.ts`: - Around line 45-67: Add the three missing lifecycle tests alongside the existing trace-runner tests: verify empty steps perform the startup checkpoint and call cleanup once, verify async setup/start/apply/cleanup methods are awaited in the order setup, start, check, apply, check, cleanup, and verify cleanup runs when driver.apply throws while preserving the original error. Use the existing runTrace, driver, and projection symbols and assert the specified checkpoint, call-order, and cleanup behavior. In `@packages/db/tests/trace-runner.ts`: - Around line 44-54: Update the trace runner’s try/finally flow around driver.start, step execution, and checkpoint so cleanup failures do not replace the original execution or assertion error. Preserve the primary failure, while still awaiting driver.cleanup(context) and surfacing its error when no earlier failure occurred.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
2723ea87-aec6-4372-8a73-8a03f2c8f117📥 Commits
Reviewing files that changed from the base of the PR and between 2985e0b67ab9e0bd91fe9af0cb3ee6e77713486d and de67bd4a6ff4437d614977e36674ae5ed2734708.
📒 Files selected for processing (3)
packages/db/tests/query/includes-oracle.property.test.tspackages/db/tests/trace-runner.test.tspackages/db/tests/trace-runner.ts
More templates
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1718@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1718@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1718@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1718@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1718@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1718@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1718@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1718@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1718@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1718@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1718@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1718@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1718@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1718@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1718@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1718@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1718@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1718@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1718@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1718@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1718@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1718commit:
210ad3cSize Change: 0 B
Total Size: 128 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size packages/db/dist/esm/collection/change-events.js1.44 kB packages/db/dist/esm/collection/changes.js1.43 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.83 kB packages/db/dist/esm/collection/indexes.js1.99 kB packages/db/dist/esm/collection/lifecycle.js1.7 kB packages/db/dist/esm/collection/mutations.js2.47 kB packages/db/dist/esm/collection/state.js5.51 kB packages/db/dist/esm/collection/subscription.js3.82 kB packages/db/dist/esm/collection/sync.js2.94 kB packages/db/dist/esm/collection/transaction-metadata.js144 B packages/db/dist/esm/deferred.js207 B packages/db/dist/esm/errors.js5.13 kB packages/db/dist/esm/event-emitter.js748 B packages/db/dist/esm/index.js3.21 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/live-query-observer.js2.29 kB 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.24 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: 3.81 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.js920 B packages/react-db/dist/esm/useLiveQueryEffect.js355 B packages/react-db/dist/esm/useLiveSuspenseQuery.js567 B packages/react-db/dist/esm/usePacedMutations.js401 B 🧹 Nitpick comments (3)
packages/db/tests/query/includes-oracle.property.test.ts (2)
1143-1149: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider
itinstead offcTestfor this fixed trace.fullRowBatchTraceis a fixed literal array. This case takes no fast-check arbitraries, so it is an example-based test, not a property test. Usingitstates the intent more precisely and avoids the fast-check runner overhead.🤖 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 1143 - 1149, Change the test declaration for the fixed fullRowBatchTrace case from fcTest to it. Keep the existing runTrace call, driver, projection, and assertions unchanged.
776-782: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winGuarantee source cleanup when the live query cleanup fails.
cleanupStructuralTraceawaitsincremental.cleanup()first. If that call rejects,cleanupSources(sources)never runs and the five source collections stay alive. A property test executes this path many times, so the leak accumulates.♻️ Proposed fix
async function cleanupStructuralTrace({ incremental, sources, }: StructuralTraceContext): Promise<void> { - await incremental.cleanup() - await cleanupSources(sources) + try { + await incremental.cleanup() + } finally { + await cleanupSources(sources) + } }🤖 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 776 - 782, Update cleanupStructuralTrace so cleanupSources(sources) always runs even when incremental.cleanup() rejects, using guaranteed cleanup control flow such as a finally block. Preserve the existing cleanup order by attempting incremental.cleanup() first, then source cleanup, while allowing the original failure to propagate.packages/db/tests/trace-runner.test.ts (1)
122-144: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd coverage for asynchronous driver results.
All drivers in this file return synchronously. The
isPromiseLikebranches inrunTraceforsetup,start,apply, andcleanupare never exercised. Add one test with a rejected asynccleanupand one test with a non-Promisethenablesetup. This pins the thenable detection that the runner advertises.Based on learnings, tests should cover corner cases including "resolved promises" and "async race conditions".
🧪 Proposed additional tests
it(`rejects with an asynchronous cleanup failure`, async () => { const cleanupError = new Error(`cleanup failed`) await expect( runTrace({ steps: [], driver: { setup: () => ({ observed: 0, expected: 0 }), apply: () => undefined, cleanup: () => Promise.reject(cleanupError), }, projection: { observe: (context) => context.observed, recompute: (context) => context.expected, assertEqual: (observed, expected) => { expect(observed).toBe(expected) }, }, }), ).rejects.toBe(cleanupError) }) it(`awaits a thenable setup result`, async () => { const context = { observed: 1, expected: 1 } await expect( runTrace({ steps: [], driver: { setup: () => ({ then: (resolve: (value: typeof context) => void) => resolve(context), }), apply: () => undefined, cleanup: () => undefined, }, projection: { observe: (value) => value.observed, recompute: (value) => value.expected, assertEqual: (observed, expected) => { expect(observed).toBe(expected) }, }, }), ).resolves.toBeUndefined() })🤖 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/trace-runner.test.ts` around lines 122 - 144, Add coverage in the trace-runner tests for asynchronous driver results: add a test where cleanup returns a rejected Promise and assert runTrace rejects with that error, then add a test where setup returns a non-Promise thenable resolving to a valid context and assert runTrace resolves successfully. Keep the existing synchronous cleanup-failure test and exercise the isPromiseLike handling in runTrace.Source: Learnings
🤖 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. Nitpick comments: In `@packages/db/tests/query/includes-oracle.property.test.ts`: - Around line 1143-1149: Change the test declaration for the fixed fullRowBatchTrace case from fcTest to it. Keep the existing runTrace call, driver, projection, and assertions unchanged. - Around line 776-782: Update cleanupStructuralTrace so cleanupSources(sources) always runs even when incremental.cleanup() rejects, using guaranteed cleanup control flow such as a finally block. Preserve the existing cleanup order by attempting incremental.cleanup() first, then source cleanup, while allowing the original failure to propagate. In `@packages/db/tests/trace-runner.test.ts`: - Around line 122-144: Add coverage in the trace-runner tests for asynchronous driver results: add a test where cleanup returns a rejected Promise and assert runTrace rejects with that error, then add a test where setup returns a non-Promise thenable resolving to a valid context and assert runTrace resolves successfully. Keep the existing synchronous cleanup-failure test and exercise the isPromiseLike handling in runTrace.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
7b4d57f3-e19d-4a85-8cb3-caf5b7c19ece📥 Commits
Reviewing files that changed from the base of the PR and between de67bd4a6ff4437d614977e36674ae5ed2734708 and 5ece238068761e0d17f0d99c20ab5b566f851a14.
📒 Files selected for processing (4)
packages/db/tests/query/includes-oracle.property.test.tspackages/db/tests/trace-runner.test-d.tspackages/db/tests/trace-runner.test.tspackages/db/tests/trace-runner.ts
🧹 Nitpick comments (2)
packages/db/tests/query/includes-oracle.property.test.ts (2)
892-901: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse precise observed types for both projections.
structuralProjectionandmaterializeProjectionuseunknownforTObserved. This removes compile-time checking between the live query shape and the oracle shape. UseArray<OracleNode>andArray<MaterializeTree>, and type or narrowstripVirtualPropertiesat the observation boundary. (raw.githubusercontent.com)Proposed type refinement
const structuralProjection: TraceProjection< StructuralTraceContext, - unknown, + Array<OracleNode>, Array<OracleNode> > = { const materializeProjection: TraceProjection< MaterializeTraceContext, - unknown, + Array<MaterializeTree>, Array<MaterializeTree> > = {As per coding guidelines: “Always provide the most precise return type annotation; avoid
unknownoranyreturn types unless truly necessary.”Also applies to: 1122-1139
🤖 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 892 - 901, Replace the unknown observed types in both structuralProjection and materializeProjection with Array<OracleNode> and Array<MaterializeTree>, respectively. Update or narrow stripVirtualProperties at the observation boundary so its result conforms to the precise projection type while preserving the existing observation behavior and type checking.Source: Coding guidelines
1059-1075: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winReplace the manual loop and
pushwith array methods.createMaterializeTraceStepsmaps insert steps, then scansinsertOrderagain and mutatesstepswithpush. Build the leaf steps withfilter().map()and combine both arrays with spread. (raw.githubusercontent.com)Proposed refactor
function createMaterializeTraceSteps( insertOrder: Array<MaterializeInsert>, ): Array<MaterializeTraceStep> { - const steps: Array<MaterializeTraceStep> = insertOrder.map((insert) => ({ - type: `insert`, - insert, - })) + const leafId = (insert: MaterializeInsert): number => + insert === `leaf-1` ? 1 : 2 - for (const insert of insertOrder) { - if (insert === `leaf-1` || insert === `leaf-2`) { - steps.push({ type: `incrementLeaf`, id: insert === `leaf-1` ? 1 : 2 }) - } - } - - return steps + return [ + ...insertOrder.map( + (insert): MaterializeTraceStep => ({ type: `insert`, insert }), + ), + ...insertOrder + .filter((insert) => insert === `leaf-1` || insert === `leaf-2`) + .map((insert): MaterializeTraceStep => ({ + type: `incrementLeaf`, + id: leafId(insert), + })), + ] }As per coding guidelines: “Use array methods like
filter()instead of manual loops for array transformations” and “Use the spread operator for combining arrays instead of manual loops with push.”🤖 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 1059 - 1075, Refactor createMaterializeTraceSteps to avoid the manual loop and mutation: keep the existing insert-step map, derive incrementLeaf steps from insertOrder with filter().map(), and return the two arrays combined via spread while preserving the current leaf-1/leaf-2 IDs and ordering.Source: Coding guidelines
🤖 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. Nitpick comments: In `@packages/db/tests/query/includes-oracle.property.test.ts`: - Around line 892-901: Replace the unknown observed types in both structuralProjection and materializeProjection with Array<OracleNode> and Array<MaterializeTree>, respectively. Update or narrow stripVirtualProperties at the observation boundary so its result conforms to the precise projection type while preserving the existing observation behavior and type checking. - Around line 1059-1075: Refactor createMaterializeTraceSteps to avoid the manual loop and mutation: keep the existing insert-step map, derive incrementLeaf steps from insertOrder with filter().map(), and return the two arrays combined via spread while preserving the current leaf-1/leaf-2 IDs and ordering.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
ea388cbb-542e-400b-80e0-9b5bf0a54a94📥 Commits
Reviewing files that changed from the base of the PR and between 5ece238068761e0d17f0d99c20ab5b566f851a14 and 210ad3cf2f75fba4e4e311c1250c1aba83d561b3.
📒 Files selected for processing (1)
packages/db/tests/query/includes-oracle.property.test.ts
tannerlinsley merged thise4940a4
tannerlinsley closed this
Sign in to join this conversation.
📝 Walkthrough
Walkthrough#
The PR adds a typed asynchronous trace runner with checkpoint and cleanup handling. Structural and materialization property-test scenarios now use trace drivers and projections. Tests cover lifecycle ordering, synchronous checkpoints, type constraints, and cleanup failures.
Changes#
Trace runner property tests
packages/db/tests/trace-runner.ts,packages/db/tests/trace-runner.test.ts,packages/db/tests/trace-runner.test-d.tsrunTrace, typed driver and projection contracts, lifecycle handling, checkpoint assertions, cleanup error handling, runtime tests, and a compile-time assertion for synchronousassertEqual.packages/db/tests/query/includes-oracle.property.test.tspackages/db/tests/query/includes-oracle.property.test.tsEstimated code review effort: 4 (Complex) | ~45 minutes
Sequence Diagram(s)#
Possibly related PRs
includes-oracle.property.test.ts.Suggested reviewers:
kevin-dp🚥 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