feat(db): expose authoritative base rows through collection.base #1982
main fromrefs/pull/1982/head·merged 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.basefor 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.
- Added
- 1
More templates
- todos
- @tanstack/db-example-react-next-ssr-e2e
- tanstack-start-example-basic
- @tanstack/db-example-paced-mutations-demo
- tanstack-start-db-projects-example
- @tanstack/db-example-react-start-ssr-e2e
- @tanstack/db-example-react-todo
- offline-first-electron
- @tanstack/db-example-solid-todo
- offline-transactions-react-native
- shopping-list-react-native
@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@1982commit:
a6b18f6Size Change: +116 B (+0.07%)
Total Size: 175 kB
📦 View Changed
Filename Size Change packages/db/dist/esm/collection/index.js4.57 kB +116 B (+2.6%) compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size 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 Size Change: 0 B
Total Size: 8.51 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size 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 KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
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.mddocs/contributing/glossary.mdpackages/db/src/collection/index.tspackages/db/tests/collection-authoritative-base.test.tspackages/db/tests/collection-state-retention-oracle.property.test.tsIncluded 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.baseaccessor. 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
packages/db/src/collection/index.ts,docs/contributing/glossary.md,.changeset/expose-authoritative-base-rows.mdCollectionBasetype andCollectionImpl.basegetter. The glossary and changeset describe which rows the accessor exposes and state that reading it does not start sync.packages/db/tests/collection-authoritative-base.test.ts,packages/db/tests/collection-state-retention-oracle.property.test.tscollection.base.Priority: ⬇️ Low
Estimated code review effort: 2 (Simple) | ~12 minutes
Change: Feature
Merge Risk: ⚪ Minimal · up to
a6b18This 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
a6b18The 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
Trust Boundaries and Controls
Resilience and Maintainability Implications
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
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.)
✨ Finishing Touches 💡 1
📝 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