Skip to content
Source
Sign inSign up
TanStack/db

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

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 2 commits intomain fromrefs/pull/1664/headmerged 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.

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.
    1. More templates

      @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

    2. Review Change Stack

      📝 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

      • 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 nameStatusExplanation
      Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
      Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Title check✅ PassedThe title clearly summarizes the main change: extracting query ownership helpers in query-db-collection.
      Description check✅ PassedThe 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
      Comment `@coderabbitai help` to get the list of available commands.
    3. Size Change: 0 B

      Total Size: 125 kB

      ℹ️ View Unchanged
      FilenameSize
      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
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 4.22 kB

      ℹ️ View Unchanged
      FilenameSize
      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
      compressed-size-action::react-db-package-size
    5. kevin-dp(GitHub profile, opens in a new tab) approved these changes

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

Sign in to join this conversation.