Skip to content
Source
Sign inSign up
TanStack/db

fix(sqlite): preserve persistence type contracts #1866

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

Summary

  • preserve transforming schema input/output inference when persistedCollectionOptions is passed to createCollection
  • align the Expo SQLite structural boundary with the installed expo-sqlite overloads
  • return transaction callback results even though Expo's exclusive transaction API returns void
  • validate driver bind values against Expo's supported SQLite value domain
  • add type/runtime oracles for the repaired contracts

Historical context

The schema-composition gap dates to the original helper API; the stale #1453 explored the same overload direction. The Expo database boundary was handwritten rather than derived from Expo's real overloads, and the test double returned callback values even though the vendor API returns void, masking the transaction-result bug.

This PR intentionally does not adopt the coordinator-wire or atomic-resume extensions proposed in #1845 and #1846; those remain separate design work.

Verification

  • direct TypeScript checks for the core and Expo persistence packages
  • core runtime suite: 96/96
  • Expo runtime suite: 45/45
  • focused Expo driver suite: 8/8
  • production builds for db-ivm, db, core persistence, and Expo persistence
  • package lint, Prettier, and diff hygiene

The schema oracle fails on the previous main because the row degrades to object / Record<string, unknown>. A hostile Expo implementation that trusts the vendor transaction return fails by returning undefined; the repaired driver captures the callback result outside the vendor boundary.

Summary by CodeRabbit

  • Bug Fixes
    • Preserved schema input and output type inference when creating persisted collections.
    • Improved key type inference and validation for transformed schemas.
    • Improved validation of persistence configuration and synchronization options.
    • Added compatibility with Expo’s native SQLite database and parameter types.
    • Preserved transaction callback results reliably.
    • Added validation for unsupported SQLite bind parameter values.
    • Improved type safety when using transformed schemas and persisted collection options.
    1. Review Change StackReview Change Stack

      Understand this PR’s impact

      Explore downstream dependencies and potential security impact with Blast Radius.

      View blast radius →

      Important

      Review skipped

      Review was skipped as selected files did not have any reviewable changes.

      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Advanced

      Run ID: f3a0b333-9b60-42f6-8ef4-eb4abb2cf43e

      📥 Commits

      Reviewing files that changed from the base of the PR and between 6fd845c8fd7c3e470bf63c8eb7df5c6e428e9bbe and c4e9499bf04db95f75bf364b36aca32421770574.

      You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

      Use the checkbox below for a quick retry:

      • 🔍 Trigger review

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Advanced

      Run ID: 9344a30e-ed33-4086-82bd-8ab3b75c00fe

      📥 Commits

      Reviewing files that changed from the base of the PR and between 02b48c4171ff8eede7e80a2917bb4a131332caa6 and 6fd845c8fd7c3e470bf63c8eb7df5c6e428e9bbe.

      📒 Files selected for processing (3)
      • packages/db-sqlite-persistence-core/tests/persisted-options-type-oracle.test-d.ts
      • packages/expo-db-sqlite-persistence/tests/expo-sqlite-driver.test-d.ts
      • packages/expo-db-sqlite-persistence/tests/expo-sqlite-driver.test.ts
      🚧 Files skipped from review as they are similar to previous changes (2)
      • packages/expo-db-sqlite-persistence/tests/expo-sqlite-driver.test.ts
      • packages/db-sqlite-persistence-core/tests/persisted-options-type-oracle.test-d.ts

      Included review availability: Your plan provides up to 8 included reviews per hour; 2 remain after this review.


      📝 Walkthrough

      Walkthrough

      The change updates persisted collection schema inference and aligns the Expo SQLite driver with native Expo types. It preserves transaction callback results, validates bind values, and adds type-level and runtime tests.

      Changes

      SQLite persistence contracts

      Layer / File(s)Summary
      Persisted collection schema contracts
      packages/db-sqlite-persistence-core/src/persisted.ts, packages/db-sqlite-persistence-core/tests/*
      persistedCollectionOptions adds schema-aware overloads that preserve schema input and output types. Existing overloads exclude schema options. Type tests cover transformed schemas, key inference, sync mode, and persistence requirements.
      Expo SQLite driver contracts and runtime behavior
      packages/expo-db-sqlite-persistence/src/*, packages/expo-db-sqlite-persistence/tests/*, .changeset/fix-sqlite-persistence-type-contracts.md
      The driver uses Expo SQLite bind and result types, captures transaction callback results, and rejects unsupported bind values. Tests cover native database compatibility, transaction results, bind validation, and updated emulator helpers. The changeset records patch releases for both packages.

      Priority: ⬇️ Low

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

      Change: Bug fix

      🚥 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 7 functions across 8 files.Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title is concise, specific, and accurately summarizes the primary change: preserving SQLite persistence type contracts.
      Description check✅ PassedThe description clearly explains the changes, motivation, historical context, verification results, and scope exclusions. It does not use the template's explicit "Changes", "Checklist", or "Release Im…
      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.
      ✨ 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

      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@1866

      @tanstack/browser-db-sqlite-persistence

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

      @tanstack/capacitor-db-sqlite-persistence

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

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

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

      @tanstack/db

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

      @tanstack/db-ivm

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

      @tanstack/db-sqlite-persistence-core

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

      @tanstack/electric-db-collection

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

      @tanstack/electron-db-sqlite-persistence

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

      @tanstack/expo-db-sqlite-persistence

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

      @tanstack/node-db-sqlite-persistence

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

      @tanstack/offline-transactions

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

      @tanstack/powersync-db-collection

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

      @tanstack/query-db-collection

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

      @tanstack/react-db

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

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

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

      @tanstack/react-router-with-db

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

      @tanstack/rxdb-db-collection

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

      @tanstack/solid-db

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

      @tanstack/svelte-db

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

      @tanstack/tauri-db-sqlite-persistence

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

      @tanstack/trailbase-db-collection

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

      @tanstack/vue-db

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

      commit: c4e9499

    3. Size Change: 0 B

      Total Size: 165 kB

      ℹ️ View Unchanged
      FilenameSize
      packages/db/dist/esm/client.js3.66 kB
      packages/db/dist/esm/collection-options.js236 B
      packages/db/dist/esm/collection/change-events.js1.44 kB
      packages/db/dist/esm/collection/changes.js2.25 kB
      packages/db/dist/esm/collection/cleanup-queue.js794 B
      packages/db/dist/esm/collection/events.js481 B
      packages/db/dist/esm/collection/index.js4.62 kB
      packages/db/dist/esm/collection/indexes.js1.99 kB
      packages/db/dist/esm/collection/lifecycle.js2.15 kB
      packages/db/dist/esm/collection/mutations.js2.61 kB
      packages/db/dist/esm/collection/state.js6.51 kB
      packages/db/dist/esm/collection/subscription.js8.73 kB
      packages/db/dist/esm/collection/sync.js4.63 kB
      packages/db/dist/esm/collection/transaction-metadata.js144 B
      packages/db/dist/esm/deferred.js207 B
      packages/db/dist/esm/errors.js5.26 kB
      packages/db/dist/esm/event-emitter.js964 B
      packages/db/dist/esm/index.js3.71 kB
      packages/db/dist/esm/indexes/auto-index.js829 B
      packages/db/dist/esm/indexes/base-index.js1.14 kB
      packages/db/dist/esm/indexes/basic-index.js2.07 kB
      packages/db/dist/esm/indexes/btree-index.js2.26 kB
      packages/db/dist/esm/indexes/index-registry.js820 B
      packages/db/dist/esm/indexes/reverse-index.js376 B
      packages/db/dist/esm/live-query-adapter.js318 B
      packages/db/dist/esm/live-query-observer.js3.69 kB
      packages/db/dist/esm/live-query-options.js702 B
      packages/db/dist/esm/live-query-window-controller.js4.36 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.js496 B
      packages/db/dist/esm/proxy.js3.32 kB
      packages/db/dist/esm/query/builder/functions.js1.47 kB
      packages/db/dist/esm/query/builder/index.js6.69 kB
      packages/db/dist/esm/query/builder/query-ir.js116 B
      packages/db/dist/esm/query/builder/ref-proxy.js1.24 kB
      packages/db/dist/esm/query/compiler/evaluators.js1.92 kB
      packages/db/dist/esm/query/compiler/expressions.js560 B
      packages/db/dist/esm/query/compiler/group-by.js4.13 kB
      packages/db/dist/esm/query/compiler/index.js9.06 kB
      packages/db/dist/esm/query/compiler/joins.js2.95 kB
      packages/db/dist/esm/query/compiler/lazy-targets.js1.1 kB
      packages/db/dist/esm/query/compiler/order-by.js1.91 kB
      packages/db/dist/esm/query/compiler/parent-routes.js319 B
      packages/db/dist/esm/query/compiler/route-metadata.js1.24 kB
      packages/db/dist/esm/query/compiler/select.js1.58 kB
      packages/db/dist/esm/query/effect.js4.6 kB
      packages/db/dist/esm/query/equality-value-identity.js591 B
      packages/db/dist/esm/query/expression-helpers.js1.43 kB
      packages/db/dist/esm/query/ir-stable-identity.js4.04 kB
      packages/db/dist/esm/query/ir.js1.59 kB
      packages/db/dist/esm/query/live-query-collection.js391 B
      packages/db/dist/esm/query/live/bucket-facade-adapter.js2.73 kB
      packages/db/dist/esm/query/live/collection-config-builder.js6.97 kB
      packages/db/dist/esm/query/live/collection-registry.js264 B
      packages/db/dist/esm/query/live/collection-subscriber.js2.26 kB
      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.js3.14 kB
      packages/db/dist/esm/query/live/subset-demand-controller.js1.26 kB
      packages/db/dist/esm/query/live/utils.js1.14 kB
      packages/db/dist/esm/query/optimizer.js2.91 kB
      packages/db/dist/esm/query/query-once.js359 B
      packages/db/dist/esm/query/runtime-reference-identity.js572 B
      packages/db/dist/esm/query/subset-dedupe.js486 B
      packages/db/dist/esm/scheduler.js1.34 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.71 kB
      packages/db/dist/esm/utils.js1.08 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.js4.51 kB
      packages/db/dist/esm/utils/callbacks.js174 B
      packages/db/dist/esm/utils/comparison.js1.49 kB
      packages/db/dist/esm/utils/cursor.js676 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/type-guards.js230 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: 7.34 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.9 kB
      packages/react-db/dist/esm/useLiveQuery.js2.68 kB
      packages/react-db/dist/esm/useLiveQueryEffect.js355 B
      packages/react-db/dist/esm/useLiveSuspenseQuery.js812 B
      packages/react-db/dist/esm/usePacedMutations.js401 B
      compressed-size-action::react-db-package-size

Sign in to join this conversation.