feat(db): add explicit local write and transaction settlement APIs #1979
main fromrefs/pull/1979/head·merged by KyleAMathews(GitHub profile, opens in a new tab) Summary#
This PR adds clear names for two local write states before the 1.0 RC. Rows expose $hasPendingWrites, and transactions expose when('settled'). The older names can suggest backend confirmation, which neither API guarantees.
Behavior#
row.$hasPendingWrites is true while an unsettled optimistic mutation affects the row. Collection rows always publish it as the inverse of $synced. This includes rows from live queries and grouped queries. Local-only collections always report false.
const pending = collection.get(id)?.$hasPendingWrites
const pendingRows = createLiveQueryCollection({
query: (q) => q.from({ row: collection })
.where(({ row }) => eq(row.$hasPendingWrites, true)),
})
tx.when('settled') returns the same promise as tx.isPersisted.promise. It resolves with the transaction on success. It rejects with the original error on failure, or with undefined after a rollback without an error. For non-empty commits, the mutation function controls this boundary. Backend acknowledgement or read-back requires the mutation function to wait for that event.
Compatibility and scope#
$synced and isPersisted.promise remain available during pre-RC releases. Both carry @deprecated annotations, with removal planned for the 1.0 RC. They do not emit runtime warnings. The hasVirtualProps guard still accepts legacy rows with four virtual fields. Collection-published rows guarantee the new field.
The guides, reference pages, and bundled skills now teach the new names. This PR covers the status API portion of #1625. It does not add a mutation log, $writeStatus, other transaction milestones, or offline reconciliation.
Verification#
- TypeScript check and DB build passed.
- Two targeted Vitest runs passed 151 tests across transaction settlement, row metadata, and subscriptions.
- The minified public API check passed.
- Formatting and diff checks passed.
- The docs link check reports one unchanged broken link in
docs/contributing/oracle-coverage.md.
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).
Related to #1625
Summary by CodeRabbit#
- New Features
- Added
$hasPendingWritesto published rows to indicate whether a pending local write affects a row. It is always false for local-only collections and does not confirm server acknowledgement. - Added
transaction.when('settled')to observe transaction completion and handle settlement errors.
- Added
- Documentation
- Updated transaction guidance and examples to use the settlement API, clarifying that settlement alone does not guarantee backend confirmation.
- Marked
$syncedandisPersistedas deprecated; both remain available for now.
- 1
More templates
- todos
- offline-first-electron
- @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-transactions-react-native
- shopping-list-react-native
- @tanstack/db-example-solid-todo
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1979@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1979@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1979@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1979@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1979@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1979@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1979@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1979@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1979@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1979@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1979@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1979@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1979@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1979@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1979@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1979@tanstack/react-router-with-db
npm i https://pkg.pr.new/@tanstack/react-router-with-db@1979@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1979@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1979@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1979@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1979@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1979@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1979commit:
a223ac8Size Change: +292 B (+0.17%)
Total Size: 175 kB
📦 View Changed
Filename Size Change packages/db/dist/esm/collection/changes.js2.72 kB +14 B (+0.52%) packages/db/dist/esm/collection/state.js8.32 kB +16 B (+0.19%) packages/db/dist/esm/query/compiler/group-by.js4.2 kB +38 B (+0.91%) packages/db/dist/esm/transactions.js3.89 kB +171 B (+4.59%) 🔍 packages/db/dist/esm/virtual-props.js413 B +53 B (+14.72%) ⚠️ 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/cleanup-queue.js808 B packages/db/dist/esm/collection/events.js481 B packages/db/dist/esm/collection/index.js4.46 kB 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/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/index.js9.21 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.93 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/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 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:
8830851d-244c-46b8-b988-7affd1a05354📥 Commits
Reviewing files that changed from the base of the PR and between ad4378d1feb5bdf6c95556914640fe11d39b88ea and a223ac81d8a85154d61a1212bc19c7c434e2faa4.
📒 Files selected for processing (2)
packages/db/src/query/compiler/group-by.tspackages/db/tests/query/compiler/group-by-pipeline.test.tsIncluded review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 5 remain after this review.
📝 Walkthrough
Walkthrough#
The pull request adds
Transaction.when('settled')and the$hasPendingWritesrow property. It retainsisPersistedand$syncedas deprecated APIs. It updates query types, transaction guidance, examples, and tests for the new APIs.Changes#
Transaction Settlement API
packages/db/src/transactions.ts,packages/db/tests/transaction-settlement-deprecation.test-d.ts,packages/db/tests/optimistic-transaction-oracle.property.test.tsTransaction.when('settled')returns the existing persistence promise. The API documents success and rejection outcomes, while tests check its type and runtime outcomes.docs/guides/*,docs/reference/*,packages/db/skills/db-core/*,packages/db/src/collection/index.ts,packages/db/src/paced-mutations.ts,packages/powersync-db-collection/src/PowerSyncTransactor.ts,.changeset/clarify-write-status-apis.mdwhen('settled'). The documentation distinguishes settlement from backend acknowledgement and read-back, and marksisPersistedas deprecated.Pending-Write Row Property
packages/db/src/virtual-props.ts,packages/db/src/collection/state.ts,packages/db/src/query/builder/*,packages/db/src/query/compiler/group-by.tsVirtualRowPropsadds optional$hasPendingWrites;PublishedVirtualRowPropsrequires it. Row enrichment and grouped results set it as the inverse of$synced. Query references use the published type.packages/db/tests/*,packages/db-sqlite-persistence-core/tests/persisted.test.ts,scripts/test-minified-db.mjsPriority: ➖ Normal
Estimated code review effort: 3 (Moderate) | ~25 minutes
Change: Feature
Merge Risk: ⚪ Minimal · up to
a223aThis change adds an explicit pending-write row property and a transaction settlement method while keeping the deprecated aliases. No concrete merge-blocking risk was identified in the reviewed grouped-query changes.
Architecture Summary#
Architecture risk: 🔵 Low · up to
a223aThe change affects 5 systems.
Changed systems:
packages/db,docs,packages/db-sqlite-persistence-core,packages/powersync-db-collection,scriptsArchitecture concerns No architecture-level concerns identified.
Review details
Systems and components
Before / after behavior
tx.when('settled')instead oftx.isPersisted.promise.tx.when('settled')instead oftx.isPersisted.promise.tx.when('settled')as the outcome promise instead oftx.isPersisted.promise. They state that cancellation rejects the settled promise and ignores a later mutation-function result or rejection, while a publication-listener error rejectscommit()but leaves the completed transaction’s settled promise resolved.when('settled')instead ofisPersisted.promise.🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
✨ 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