Skip to content
Source
Sign inSign up
TanStack/db

feat(db): add explicit local write and transaction settlement APIs #1979

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 3 commits intomain fromrefs/pull/1979/headmerged 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 $hasPendingWrites to 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.
  • Documentation
    • Updated transaction guidance and examples to use the settlement API, clarifying that settlement alone does not guarantee backend confirmation.
    • Marked $synced and isPersisted as deprecated; both remain available for now.
    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: 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.ts
      • packages/db/tests/query/compiler/group-by-pipeline.test.ts

      Included 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 $hasPendingWrites row property. It retains isPersisted and $synced as deprecated APIs. It updates query types, transaction guidance, examples, and tests for the new APIs.

      Changes

      Transaction Settlement API

      Layer / File(s)Summary
      Settlement method and outcome checks
      packages/db/src/transactions.ts, packages/db/tests/transaction-settlement-deprecation.test-d.ts, packages/db/tests/optimistic-transaction-oracle.property.test.ts
      Transaction.when('settled') returns the existing persistence promise. The API documents success and rejection outcomes, while tests check its type and runtime outcomes.
      Settlement guidance and examples
      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.md
      Transaction examples and guidance now use when('settled'). The documentation distinguishes settlement from backend acknowledgement and read-back, and marks isPersisted as deprecated.

      Pending-Write Row Property

      Layer / File(s)Summary
      Row-property contract and query integration
      packages/db/src/virtual-props.ts, packages/db/src/collection/state.ts, packages/db/src/query/builder/*, packages/db/src/query/compiler/group-by.ts
      VirtualRowProps adds optional $hasPendingWrites; PublishedVirtualRowProps requires it. Row enrichment and grouped results set it as the inverse of $synced. Query references use the published type.
      Publication, query, and compatibility checks
      packages/db/tests/*, packages/db-sqlite-persistence-core/tests/persisted.test.ts, scripts/test-minified-db.mjs
      Tests cover the field on published, local-only, grouped, and optimistic rows, along with query filtering and type compatibility. Helpers exclude the new virtual property when comparing user data.

      Priority: ➖ Normal

      Estimated code review effort: 3 (Moderate) | ~25 minutes

      Change: Feature

      Merge Risk: ⚪ Minimal · up to a223a

      This 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 a223a

      The change affects 5 systems.

      Changed systems: packages/db, docs, packages/db-sqlite-persistence-core, packages/powersync-db-collection, scripts

      Architecture concerns No architecture-level concerns identified.

      Review details

      Systems and components

      • observed — packages/db (library) was modified; 34 changed files map to changed impact.
      • observed — docs (service) was modified; 18 changed files map to changed impact.
      • observed — packages/db-sqlite-persistence-core (library) was modified; 1 changed file maps to changed impact.
      • observed — packages/powersync-db-collection (library) was modified; 1 changed file maps to changed impact.

      Before / after behavior

      • observed — Modified behavior in docs/guides/error-handling.md: The insert example now waits for tx.when('settled') instead of tx.isPersisted.promise.
      • observed — Modified behavior in docs/guides/error-handling.md: The update example now waits for tx.when('settled') instead of tx.isPersisted.promise.
      • observed — Modified behavior in docs/guides/error-handling.md: The cancellation and publication-listener descriptions now identify tx.when('settled') as the outcome promise instead of tx.isPersisted.promise. They state that cancellation rejects the settled promise and ignores a later mutation-function result or rejection, while a publication-listener error rejects commit() but leaves the completed transaction’s settled promise resolved.
      • observed — Modified behavior in docs/guides/error-handling.md: The best-practice item now advises handling rejections from when('settled') instead of isPersisted.promise.
      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 32 files.Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly identifies the two primary changes: explicit local write-state and transaction-settlement APIs.
      Description check✅ PassedThe description explains the behavior, compatibility impact, release impact, scope, and verification results. It includes checklist and release-impact sections, although the required Changes heading i…
      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.
      • 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@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@1979

      commit: a223ac8

    3. Size Change: +292 B (+0.17%)

      Total Size: 175 kB

      📦 View Changed
      FilenameSizeChange
      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%)⚠️
      ℹ️ 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/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
      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.