Skip to content
Source
Sign inSign up
TanStack/db

feat(db): expose authoritative base rows through collection.base #1982

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 2 commits intomain fromrefs/pull/1982/headmerged by KyleAMathews(GitHub profile, opens in a new tab)

Why

Sync adapters sometimes need the last applied source row while a local write is pending. collection.get(key) returns the visible row, which can include an optimistic change. Adapters currently read the private collection._state.syncedData map to make this comparison.

What changes

collection.base gives adapters a synchronous view of the applied source rows:

const sourceRow = collection.base.get(key)
const visibleRow = collection.get(key)

The base excludes optimistic inserts, updates, and deletes. It also excludes committed sync writes that still wait for reconciliation. The view uses the existing map, so later applied sync changes appear through the same reference. Reading collection.base does not start sync.

The TypeScript API exposes read methods and iteration, but it does not expose map writes. This is a type-level limit, not a runtime guard. JavaScript or a cast can mutate the map, and row values are not frozen. Such mutation bypasses collection publication, so callers must treat the view and its rows as read-only.

This PR adds no reconciliation state or behavior. It does not migrate existing adapters away from _state. It addresses the adapter request in #1625 as a narrow related feature. It does not complete or close the mutation-log RFC.

Verification

Focused tests cover optimistic writes, applied sync, queued sync, and reading before sync starts. The retention oracle now reads through collection.base. Ninety focused tests, TypeScript, formatting, and diff checks passed.

Checklist

  • I have tested this code locally with pnpm test.

Release impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

  • New Features
    • Added collection.base for synchronously reading authoritative rows applied from the data source, without optimistic changes. The read-only view excludes sync writes queued for reconciliation and does not start synchronization when accessed.
    • The base updates as sync writes are applied, including writes that are queued until an ongoing mutation completes.
    1. Review in Change Stack →

      Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Advanced

      Run ID: 5d55009d-28c0-47b4-8e58-79409bf4c576

      📥 Commits

      Reviewing files that changed from the base of the PR and between 5b85af08f2b02ff675d79c012a858e6b2bea3dbf and a6b18f668bb336c841d1ad9d9b7b7c70698674c5.

      📒 Files selected for processing (5)
      • .changeset/expose-authoritative-base-rows.md
      • docs/contributing/glossary.md
      • packages/db/src/collection/index.ts
      • packages/db/tests/collection-authoritative-base.test.ts
      • packages/db/tests/collection-state-retention-oracle.property.test.ts

      Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 3 remain after this review.


      📝 Walkthrough

      Walkthrough

      The collection now exposes applied authoritative rows through a read-only collection.base accessor. The accessor excludes optimistic mutations and queued sync writes, and reading it does not start sync. New tests cover its contents and sync behavior.

      Changes

      Authoritative collection base

      Layer / File(s)Summary
      Expose the authoritative base
      packages/db/src/collection/index.ts, docs/contributing/glossary.md, .changeset/expose-authoritative-base-rows.md
      Adds the CollectionBase type and CollectionImpl.base getter. The glossary and changeset describe which rows the accessor exposes and state that reading it does not start sync.
      Verify base reads and sync behavior
      packages/db/tests/collection-authoritative-base.test.ts, packages/db/tests/collection-state-retention-oracle.property.test.ts
      Tests base contents during optimistic mutations and sync commits, verifies that reading the base does not start sync, and updates the retained-state assertion to use collection.base.

      Priority: ⬇️ Low

      Estimated code review effort: 2 (Simple) | ~12 minutes

      Change: Feature

      Merge Risk: ⚪ Minimal · up to a6b18

      This adds a read-only way to read applied source rows from a collection, with tests and documentation. No merge-blocking risk was found.

      Security Architecture Review

      Security architecture risk: 🔵 Low · up to a6b18

      The accessor preserves existing synchronization behavior and does not establish a new security-boundary bypass. However, its read-only restriction is enforced only by TypeScript: callers can still mutate the backing map or rows at runtime. The reviewed scope does not establish how applications isolate collection handles from untrusted code.

      Retained concerns No architecture-level concerns identified.

      Security review details

      Security Blast Radius

      • inferred — The directly established exposure is the applied authoritative rows of a collection whose handle a caller already possesses. The getter introduces no credential, tenant selector, or remote operation. A larger cross-tenant or environment-wide attack scope is not established by the reviewed code.

      Trust Boundaries and Controls

      • inferred — The read-only type is an API discipline, not an authorization or runtime isolation control. Code holding the complete collection object already had access to the authoritative backing map through public _state, so this accessor does not establish a newly bypassed security boundary. Applications must not rely on optimistic visibility or this type restriction to isolate untrusted callers.

      Resilience and Maintainability Implications

      • observed — Managed sync application coordinates authoritative data, metadata, ordering, and publication. Pre-application cancellation rejects pending receipts without applying the queued base changes. Mutating the exposed alias bypasses those managed paths, but this capability predates the accessor.
      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 3 files. (2 skipped: 2 …Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      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 and concisely describes the main change: exposing authoritative base rows through collection.base.
      Description check✅ PassedThe description explains the motivation, implementation, behavior, limitations, verification, and release impact. It includes the required checklist and confirms that a changeset was generated. The se…
      Full details: Docstring Coverage

      Explanation

      Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 3 files. (2 skipped: 2 unsupported.)

      • Fix all pre-merge checks with AI
      ✨ Finishing Touches 💡 1
      📝 Generate docstrings 💡
      • Commit to this branch
      • Create a new PR
      🧪 Generate unit tests (beta)
      • Commit to this branch
      • Create a new PR
      • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

      Autopilot is currently an internal CodeRabbit preview.


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

      @tanstack/angular-db

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

      @tanstack/browser-db-sqlite-persistence

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

      @tanstack/capacitor-db-sqlite-persistence

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

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

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

      @tanstack/db

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

      @tanstack/db-ivm

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

      @tanstack/db-sqlite-persistence-core

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

      @tanstack/electric-db-collection

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

      @tanstack/electron-db-sqlite-persistence

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

      @tanstack/expo-db-sqlite-persistence

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

      @tanstack/node-db-sqlite-persistence

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

      @tanstack/offline-transactions

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

      @tanstack/powersync-db-collection

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

      @tanstack/query-db-collection

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

      @tanstack/react-db

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

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

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

      @tanstack/react-router-with-db

      npm i https://pkg.pr.new/@tanstack/react-router-with-db@1982

      @tanstack/rxdb-db-collection

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

      @tanstack/solid-db

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

      @tanstack/svelte-db

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

      @tanstack/tauri-db-sqlite-persistence

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

      @tanstack/trailbase-db-collection

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

      @tanstack/vue-db

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

      commit: a6b18f6

    3. Size Change: +116 B (+0.07%)

      Total Size: 175 kB

      📦 View Changed
      FilenameSizeChange
      packages/db/dist/esm/collection/index.js4.57 kB+116 B (+2.6%)
      ℹ️ View Unchanged
      FilenameSize
      packages/db/dist/esm/client.js3.61 kB
      packages/db/dist/esm/collection-options.js236 B
      packages/db/dist/esm/collection/change-events.js2.07 kB
      packages/db/dist/esm/collection/changes.js2.72 kB
      packages/db/dist/esm/collection/cleanup-queue.js808 B
      packages/db/dist/esm/collection/events.js481 B
      packages/db/dist/esm/collection/indexes.js2.06 kB
      packages/db/dist/esm/collection/lifecycle.js2.63 kB
      packages/db/dist/esm/collection/mutations.js2.59 kB
      packages/db/dist/esm/collection/state.js8.32 kB
      packages/db/dist/esm/collection/subscription.js8.63 kB
      packages/db/dist/esm/collection/sync.js4.96 kB
      packages/db/dist/esm/collection/transaction-metadata.js144 B
      packages/db/dist/esm/deferred.js207 B
      packages/db/dist/esm/errors.js5.49 kB
      packages/db/dist/esm/event-emitter.js961 B
      packages/db/dist/esm/index.js3.94 kB
      packages/db/dist/esm/indexes/auto-index.js841 B
      packages/db/dist/esm/indexes/base-index.js1.25 kB
      packages/db/dist/esm/indexes/basic-index.js2.01 kB
      packages/db/dist/esm/indexes/btree-index.js2.3 kB
      packages/db/dist/esm/indexes/index-registry.js820 B
      packages/db/dist/esm/indexes/reverse-index.js370 B
      packages/db/dist/esm/live-query-adapter.js318 B
      packages/db/dist/esm/live-query-observer.js4.53 kB
      packages/db/dist/esm/live-query-options.js731 B
      packages/db/dist/esm/live-query-window-controller.js4.12 kB
      packages/db/dist/esm/local-only.js989 B
      packages/db/dist/esm/local-storage.js2.17 kB
      packages/db/dist/esm/optimistic-action.js359 B
      packages/db/dist/esm/paced-mutations.js702 B
      packages/db/dist/esm/persisted-readiness.js195 B
      packages/db/dist/esm/proxy.js3.32 kB
      packages/db/dist/esm/query/builder/clone-query.js766 B
      packages/db/dist/esm/query/builder/functions.js1.45 kB
      packages/db/dist/esm/query/builder/index.js6.79 kB
      packages/db/dist/esm/query/builder/query-ir.js116 B
      packages/db/dist/esm/query/builder/ref-proxy-identity.js198 B
      packages/db/dist/esm/query/builder/ref-proxy.js1.35 kB
      packages/db/dist/esm/query/builder/wrapper-identity.js221 B
      packages/db/dist/esm/query/compiler/evaluators.js2.1 kB
      packages/db/dist/esm/query/compiler/expressions.js603 B
      packages/db/dist/esm/query/compiler/group-by.js4.2 kB
      packages/db/dist/esm/query/compiler/index.js9.39 kB
      packages/db/dist/esm/query/compiler/joins.js3.06 kB
      packages/db/dist/esm/query/compiler/lazy-targets.js1.14 kB
      packages/db/dist/esm/query/compiler/order-by.js2 kB
      packages/db/dist/esm/query/compiler/parent-routes.js319 B
      packages/db/dist/esm/query/compiler/query-equivalence.js455 B
      packages/db/dist/esm/query/compiler/route-metadata.js1.24 kB
      packages/db/dist/esm/query/compiler/select.js1.59 kB
      packages/db/dist/esm/query/effect.js4.86 kB
      packages/db/dist/esm/query/equality-value-identity.js591 B
      packages/db/dist/esm/query/expression-helpers.js1.45 kB
      packages/db/dist/esm/query/ir-stable-identity.js4.22 kB
      packages/db/dist/esm/query/ir.js1.69 kB
      packages/db/dist/esm/query/live-query-collection.js391 B
      packages/db/dist/esm/query/live/bucket-facade-adapter.js2.67 kB
      packages/db/dist/esm/query/live/collection-config-builder.js6.47 kB
      packages/db/dist/esm/query/live/collection-registry.js264 B
      packages/db/dist/esm/query/live/collection-subscriber.js2.05 kB
      packages/db/dist/esm/query/live/graph-scheduler.js303 B
      packages/db/dist/esm/query/live/internal.js145 B
      packages/db/dist/esm/query/live/materialized-pipeline.js2.32 kB
      packages/db/dist/esm/query/live/ordered-source-loader.js4.14 kB
      packages/db/dist/esm/query/live/subset-demand-controller.js1.65 kB
      packages/db/dist/esm/query/live/utils.js1.2 kB
      packages/db/dist/esm/query/optimizer.js2.92 kB
      packages/db/dist/esm/query/query-once.js359 B
      packages/db/dist/esm/query/runtime-reference-identity.js630 B
      packages/db/dist/esm/query/subset-dedupe.js493 B
      packages/db/dist/esm/scheduler.js1.13 kB
      packages/db/dist/esm/SortedMap.js1.58 kB
      packages/db/dist/esm/strategies/debounceStrategy.js331 B
      packages/db/dist/esm/strategies/queueStrategy.js488 B
      packages/db/dist/esm/strategies/throttleStrategy.js386 B
      packages/db/dist/esm/sync-persistence.js530 B
      packages/db/dist/esm/transactions.js3.89 kB
      packages/db/dist/esm/utils.js1.22 kB
      packages/db/dist/esm/utils/array-utils.js270 B
      packages/db/dist/esm/utils/browser-polyfills.js304 B
      packages/db/dist/esm/utils/btree.js3.02 kB
      packages/db/dist/esm/utils/callbacks.js174 B
      packages/db/dist/esm/utils/comparison.js1.59 kB
      packages/db/dist/esm/utils/cursor.js677 B
      packages/db/dist/esm/utils/error.js167 B
      packages/db/dist/esm/utils/get-or-create.js155 B
      packages/db/dist/esm/utils/index-optimization.js2.42 kB
      packages/db/dist/esm/utils/source-record.js140 B
      packages/db/dist/esm/utils/type-guards.js230 B
      packages/db/dist/esm/utils/uuid.js449 B
      packages/db/dist/esm/virtual-props.js413 B
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 8.51 kB

      ℹ️ View Unchanged
      FilenameSize
      packages/react-db/dist/esm/DbProvider.js317 B
      packages/react-db/dist/esm/HydrationBoundary.js263 B
      packages/react-db/dist/esm/index.js330 B
      packages/react-db/dist/esm/live-query-internals.js282 B
      packages/react-db/dist/esm/useLiveInfiniteQuery.js1.93 kB
      packages/react-db/dist/esm/useLiveQuery.js3.3 kB
      packages/react-db/dist/esm/useLiveQueryEffect.js355 B
      packages/react-db/dist/esm/useLiveSuspenseQuery.js1.33 kB
      packages/react-db/dist/esm/usePacedMutations.js401 B
      compressed-size-action::react-db-package-size

Sign in to join this conversation.