refactor(query-db-collection): extract query ownership helpers

[KyleAMathews]

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

• RFC: RFC: roadmap for query-db-collection / TanStack Query integration #1643

Approach

This keeps the existing maps and lifecycle flow intact while centralizing the direct mutations of query ownership state:

• addRowOwner updates rowToQueries and queryToRows for one query/row relationship.
• addRowOwners hydrates ownership for persisted rows with multiple owners.
• removeRowOwner removes one query/row relationship while preserving existing empty-set behavior.
• removeQueryOwnership computes 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

• rowToQueries and queryToRows remain 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.

[pkg-pr-new]

More templates

• todos
• offline-first-electron
• offline-transactions-react-native
• shopping-list-react-native
• tanstack-start-example-basic
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@1664

@tanstack/browser-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1664

@tanstack/capacitor-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1664

@tanstack/cloudflare-durable-objects-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1664

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@1664

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@1664

@tanstack/db-sqlite-persistence-core

npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1664

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@1664

@tanstack/electron-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1664

@tanstack/expo-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1664

@tanstack/node-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1664

@tanstack/offline-transactions

npm i https://pkg.pr.new/@tanstack/offline-transactions@1664

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1664

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@1664

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@1664

@tanstack/react-native-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1664

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1664

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@1664

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@1664

@tanstack/tauri-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1664

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1664

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@1664

commit: 298c392

[coderabbitai]

📝 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.md	Row 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.ts	Hydrated 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.ts	Successful-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

• on-demand store entries are removed while queries still use them when reusing an existing observer #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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Size Change: 0 B

Total Size: 125 kB

ℹ️ View Unchanged

Filename	Size
packages/db/dist/esm/collection/change-events.js	1.43 kB
packages/db/dist/esm/collection/changes.js	1.38 kB
packages/db/dist/esm/collection/cleanup-queue.js	810 B
packages/db/dist/esm/collection/events.js	434 B
packages/db/dist/esm/collection/index.js	3.62 kB
packages/db/dist/esm/collection/indexes.js	1.99 kB
packages/db/dist/esm/collection/lifecycle.js	1.69 kB
packages/db/dist/esm/collection/mutations.js	2.47 kB
packages/db/dist/esm/collection/state.js	5.48 kB
packages/db/dist/esm/collection/subscription.js	3.74 kB
packages/db/dist/esm/collection/sync.js	2.88 kB
packages/db/dist/esm/collection/transaction-metadata.js	144 B
packages/db/dist/esm/deferred.js	207 B
packages/db/dist/esm/errors.js	5.1 kB
packages/db/dist/esm/event-emitter.js	748 B
packages/db/dist/esm/index.js	3.16 kB
packages/db/dist/esm/indexes/auto-index.js	829 B
packages/db/dist/esm/indexes/base-index.js	767 B
packages/db/dist/esm/indexes/basic-index.js	2.06 kB
packages/db/dist/esm/indexes/btree-index.js	2.19 kB
packages/db/dist/esm/indexes/index-registry.js	820 B
packages/db/dist/esm/indexes/reverse-index.js	557 B
packages/db/dist/esm/live-query-adapter.js	318 B
packages/db/dist/esm/local-only.js	916 B
packages/db/dist/esm/local-storage.js	2.12 kB
packages/db/dist/esm/optimistic-action.js	359 B
packages/db/dist/esm/paced-mutations.js	496 B
packages/db/dist/esm/proxy.js	3.75 kB
packages/db/dist/esm/query/builder/functions.js	1.47 kB
packages/db/dist/esm/query/builder/index.js	5.84 kB
packages/db/dist/esm/query/builder/ref-proxy.js	1.24 kB
packages/db/dist/esm/query/compiler/evaluators.js	1.89 kB
packages/db/dist/esm/query/compiler/expressions.js	430 B
packages/db/dist/esm/query/compiler/group-by.js	3.56 kB
packages/db/dist/esm/query/compiler/index.js	6.67 kB
packages/db/dist/esm/query/compiler/joins.js	2.5 kB
packages/db/dist/esm/query/compiler/lazy-targets.js	923 B
packages/db/dist/esm/query/compiler/order-by.js	1.74 kB
packages/db/dist/esm/query/compiler/select.js	1.53 kB
packages/db/dist/esm/query/effect.js	4.77 kB
packages/db/dist/esm/query/expression-helpers.js	1.43 kB
packages/db/dist/esm/query/ir.js	1.25 kB
packages/db/dist/esm/query/live-query-collection.js	360 B
packages/db/dist/esm/query/live/collection-config-builder.js	9.1 kB
packages/db/dist/esm/query/live/collection-registry.js	264 B
packages/db/dist/esm/query/live/collection-subscriber.js	1.93 kB
packages/db/dist/esm/query/live/internal.js	145 B
packages/db/dist/esm/query/live/utils.js	1.81 kB
packages/db/dist/esm/query/optimizer.js	2.92 kB
packages/db/dist/esm/query/predicate-utils.js	2.97 kB
packages/db/dist/esm/query/query-once.js	359 B
packages/db/dist/esm/query/subset-dedupe.js	960 B
packages/db/dist/esm/scheduler.js	1.3 kB
packages/db/dist/esm/SortedMap.js	1.3 kB
packages/db/dist/esm/strategies/debounceStrategy.js	247 B
packages/db/dist/esm/strategies/queueStrategy.js	428 B
packages/db/dist/esm/strategies/throttleStrategy.js	246 B
packages/db/dist/esm/transactions.js	3.04 kB
packages/db/dist/esm/utils.js	927 B
packages/db/dist/esm/utils/array-utils.js	273 B
packages/db/dist/esm/utils/browser-polyfills.js	304 B
packages/db/dist/esm/utils/btree.js	5.61 kB
packages/db/dist/esm/utils/comparison.js	1.11 kB
packages/db/dist/esm/utils/cursor.js	457 B
packages/db/dist/esm/utils/index-optimization.js	2.39 kB
packages/db/dist/esm/utils/type-guards.js	157 B
packages/db/dist/esm/utils/uuid.js	449 B
packages/db/dist/esm/virtual-props.js	360 B

_{compressed-size-action::db-package-size}

[github-actions]

Size Change: 0 B

Total Size: 4.22 kB

ℹ️ View Unchanged

Filename	Size
packages/react-db/dist/esm/index.js	249 B
packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.32 kB
packages/react-db/dist/esm/useLiveQuery.js	1.33 kB
packages/react-db/dist/esm/useLiveQueryEffect.js	355 B
packages/react-db/dist/esm/useLiveSuspenseQuery.js	567 B
packages/react-db/dist/esm/usePacedMutations.js	401 B

_{compressed-size-action::react-db-package-size}

[kevin-dp]

Should we rename removeQueryOwnership to removeQueryOwners in order to be consistent with addRowOwners naming?