refactor(query-db-collection): extract query ownership helpers #1664
main fromrefs/pull/1664/head·merged by KyleAMathews(GitHub profile, opens in a new tab) Extracts the internal row/query ownership bookkeeping in @tanstack/query-db-collection into small private helpers. There is no intended public API or user-visible behavior change; this is lifecycle groundwork for future cancellation/lease-manager work.
Related#
Approach#
This keeps the existing maps and lifecycle flow intact while centralizing the direct mutations of query ownership state:
addRowOwnerupdatesrowToQueriesandqueryToRowsfor one query/row relationship.addRowOwnershydrates ownership for persisted rows with multiple owners.removeRowOwnerremoves one query/row relationship while preserving existing empty-set behavior.removeQueryOwnershipcomputes the remaining owners for all rows associated with a query during cleanup.
The extraction is intentionally local to query.ts and does not change observer refcounting, invalidation handling, or persisted retention semantics.
Key invariants#
rowToQueriesandqueryToRowsremain inverse ownership indexes.- Shared rows stay materialized while at least one query still owns them.
- Cleanup removes only rows whose owner set becomes empty.
- Existing invalidation and remount behavior remains unchanged.
- Persisted retention metadata continues to be updated by the existing call sites.
Non-goals#
- No public API changes.
- No observer lifecycle rewrite.
- No new cancellation or lease state machine yet.
- No behavior-adjacent cleanup of empty ownership sets; that can be handled separately with focused characterization tests.
Trade-offs#
A full lease manager would make lifecycle ownership more explicit, but would be higher risk. This PR takes a smaller step: it reduces duplicated map mutation code and creates clearer seams for future work while preserving current behavior.
Verification#
pnpm --filter @tanstack/db-ivm build
pnpm --filter @tanstack/electric-db-collection build
pnpm --filter @tanstack/db build
pnpm --filter @tanstack/query-db-collection test tests/query.test.ts -t "lifecycle|GC|invalidation|on-demand|late|cleanup"
pnpm --filter @tanstack/query-db-collection test tests/query.test.ts
pnpm --filter @tanstack/query-db-collection build
pnpm --filter @tanstack/query-db-collection test -- --runInBand
Files changed#
packages/query-db-collection/src/query.ts— extracts private row/query ownership helpers and routes existing ownership call sites through them..changeset/extract-query-ownership-helpers.md— patch changeset for the internal refactor.
Summary by CodeRabbit#
Bug Fixes
- Improved internal cleanup and ownership tracking for persisted query data.
- Preserved existing behavior while making row removal and metadata updates more reliable during query reconciliation and lifecycle cleanup.
Release
- Patch release prepared for
@tanstack/query-db-collection.
- Patch release prepared for
- 1
📝 Walkthrough
Walkthrough#
Internal query row ownership tracking is refactored into explicit helpers. Baseline hydration, placeholder cleanup, result reconciliation, and query cleanup now use these helpers without changing public APIs.
Changes#
Query ownership lifecycle
Layer / File(s) Summary Ownership helper API
packages/query-db-collection/src/query.ts,.changeset/extract-query-ownership-helpers.mdRow ownership is managed through helpers that add owners, remove individual owners, and remove query ownership across rows; a patch Changesets entry documents the refactor. Baseline ownership hydration
packages/query-db-collection/src/query.tsHydrated and scanned persisted baselines register row owners through the shared helper API, and placeholder cleanup uses remaining-owner results. Reconciliation and query cleanup
packages/query-db-collection/src/query.tsSuccessful-result reconciliation and query cleanup use owner-aware removal and addition helpers to drive row deletion and persisted metadata updates. Estimated code review effort: 3 (Moderate) | ~20 minutes
Possibly related issues
- TanStack/db#1488 — Concerns the same row ownership registration and cleanup paths in
query.ts.
Possibly related PRs
- TanStack/db#1655 — Adds rematerialization tests for behavior affected by the ownership bookkeeping refactor.
Suggested reviewers:
kevin-dp🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request. Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request. Title check ✅ Passed The title clearly summarizes the main change: extracting query ownership helpers in query-db-collection. Description check ✅ Passed The description is detailed and covers changes, rationale, approach, invariants, verification, and related context. ✨ Finishing Touches
📝 Generate docstrings
- Create stacked PR
- Commit on current branch
🧪 Generate unit tests (beta)
- Create PR with unit tests
- Commit unit tests in branch `query-lease-manager-groundwork`
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.
Comment `@coderabbitai help` to get the list of available commands.- TanStack/db#1488 — Concerns the same row ownership registration and cleanup paths in
Size 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.js767 B packages/db/dist/esm/indexes/basic-index.js2.06 kB packages/db/dist/esm/indexes/btree-index.js2.19 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.11 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 kevin-dp(GitHub profile, opens in a new tab) approved these changes
Should we rename
removeQueryOwnershiptoremoveQueryOwnersin order to be consistent withaddRowOwnersnaming?KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
More templates
@tanstack/angular-db
@tanstack/browser-db-sqlite-persistence
@tanstack/capacitor-db-sqlite-persistence
@tanstack/cloudflare-durable-objects-db-sqlite-persistence
@tanstack/db
@tanstack/db-ivm
@tanstack/db-sqlite-persistence-core
@tanstack/electric-db-collection
@tanstack/electron-db-sqlite-persistence
@tanstack/expo-db-sqlite-persistence
@tanstack/node-db-sqlite-persistence
@tanstack/offline-transactions
@tanstack/powersync-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/react-native-db-sqlite-persistence
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/tauri-db-sqlite-persistence
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit:
298c392