fix(sqlite): preserve persistence type contracts

[KyleAMathews]

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.
  • Added compatibility with Expo’s native SQLite database and parameter types.
  • Preserved transaction callback results reliably.
  • Added validation for unsupported SQLite bind parameter values.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: ce35e51f-5ada-4f47-9f99-789bea838405

📥 Commits

Reviewing files that changed from the base of the PR and between e5fe2ea and 02b48c4.

📒 Files selected for processing (9)

• .changeset/fix-sqlite-persistence-type-contracts.md
• packages/db-sqlite-persistence-core/src/persisted.ts
• packages/db-sqlite-persistence-core/tests/persisted-options-type-oracle.test-d.ts
• packages/db-sqlite-persistence-core/tests/persisted.test-d.ts
• packages/expo-db-sqlite-persistence/src/expo-sqlite-driver.ts
• packages/expo-db-sqlite-persistence/tests/expo-sqlite-driver.test-d.ts
• packages/expo-db-sqlite-persistence/tests/expo-sqlite-driver.test.ts
• packages/expo-db-sqlite-persistence/tests/helpers/expo-emulator-database-factory.ts
• packages/expo-db-sqlite-persistence/tests/helpers/expo-sqlite-test-db.ts

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

---

📝 Walkthrough

Walkthrough

The change updates persisted collection schema inference and aligns the Expo SQLite driver with Expo’s native types. It also 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/expo-sqlite-driver.ts, 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 name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	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 7 functions across 8 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: preserving SQLite persistence type contracts.
Description check	✅ Passed	The description clearly explains the changes, motivation, scope, exclusions, and verification results. It does not use the template headings or include the checklist and release-impact sections, but t…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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 7 functions across 8 files. (1 skipped: 1 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

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

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@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: 02b48c4

[github-actions]

Size Change: 0 B

Total Size: 165 kB

ℹ️ View Unchanged

Filename	Size
packages/db/dist/esm/client.js	3.66 kB
packages/db/dist/esm/collection-options.js	236 B
packages/db/dist/esm/collection/change-events.js	1.44 kB
packages/db/dist/esm/collection/changes.js	2.25 kB
packages/db/dist/esm/collection/cleanup-queue.js	794 B
packages/db/dist/esm/collection/events.js	481 B
packages/db/dist/esm/collection/index.js	4.63 kB
packages/db/dist/esm/collection/indexes.js	1.99 kB
packages/db/dist/esm/collection/lifecycle.js	2.15 kB
packages/db/dist/esm/collection/mutations.js	2.61 kB
packages/db/dist/esm/collection/state.js	6.51 kB
packages/db/dist/esm/collection/subscription.js	8.72 kB
packages/db/dist/esm/collection/sync.js	4.62 kB
packages/db/dist/esm/collection/transaction-metadata.js	144 B
packages/db/dist/esm/deferred.js	207 B
packages/db/dist/esm/errors.js	5.26 kB
packages/db/dist/esm/event-emitter.js	964 B
packages/db/dist/esm/index.js	3.71 kB
packages/db/dist/esm/indexes/auto-index.js	829 B
packages/db/dist/esm/indexes/base-index.js	1.14 kB
packages/db/dist/esm/indexes/basic-index.js	2.07 kB
packages/db/dist/esm/indexes/btree-index.js	2.26 kB
packages/db/dist/esm/indexes/index-registry.js	820 B
packages/db/dist/esm/indexes/reverse-index.js	376 B
packages/db/dist/esm/live-query-adapter.js	318 B
packages/db/dist/esm/live-query-observer.js	3.69 kB
packages/db/dist/esm/live-query-options.js	702 B
packages/db/dist/esm/live-query-window-controller.js	4.36 kB
packages/db/dist/esm/local-only.js	989 B
packages/db/dist/esm/local-storage.js	2.17 kB
packages/db/dist/esm/optimistic-action.js	359 B
packages/db/dist/esm/paced-mutations.js	496 B
packages/db/dist/esm/proxy.js	3.32 kB
packages/db/dist/esm/query/builder/functions.js	1.47 kB
packages/db/dist/esm/query/builder/index.js	6.69 kB
packages/db/dist/esm/query/builder/query-ir.js	116 B
packages/db/dist/esm/query/builder/ref-proxy.js	1.24 kB
packages/db/dist/esm/query/compiler/evaluators.js	1.92 kB
packages/db/dist/esm/query/compiler/expressions.js	560 B
packages/db/dist/esm/query/compiler/group-by.js	4.13 kB
packages/db/dist/esm/query/compiler/index.js	9.06 kB
packages/db/dist/esm/query/compiler/joins.js	2.95 kB
packages/db/dist/esm/query/compiler/lazy-targets.js	1.1 kB
packages/db/dist/esm/query/compiler/order-by.js	1.91 kB
packages/db/dist/esm/query/compiler/parent-routes.js	319 B
packages/db/dist/esm/query/compiler/route-metadata.js	1.24 kB
packages/db/dist/esm/query/compiler/select.js	1.58 kB
packages/db/dist/esm/query/effect.js	4.6 kB
packages/db/dist/esm/query/equality-value-identity.js	591 B
packages/db/dist/esm/query/expression-helpers.js	1.43 kB
packages/db/dist/esm/query/ir-stable-identity.js	4.04 kB
packages/db/dist/esm/query/ir.js	1.59 kB
packages/db/dist/esm/query/live-query-collection.js	391 B
packages/db/dist/esm/query/live/bucket-facade-adapter.js	2.73 kB
packages/db/dist/esm/query/live/collection-config-builder.js	6.97 kB
packages/db/dist/esm/query/live/collection-registry.js	264 B
packages/db/dist/esm/query/live/collection-subscriber.js	2.25 kB
packages/db/dist/esm/query/live/internal.js	145 B
packages/db/dist/esm/query/live/materialized-pipeline.js	2.32 kB
packages/db/dist/esm/query/live/ordered-source-loader.js	3.14 kB
packages/db/dist/esm/query/live/subset-demand-controller.js	1.26 kB
packages/db/dist/esm/query/live/utils.js	1.14 kB
packages/db/dist/esm/query/optimizer.js	2.91 kB
packages/db/dist/esm/query/query-once.js	359 B
packages/db/dist/esm/query/runtime-reference-identity.js	572 B
packages/db/dist/esm/query/subset-dedupe.js	486 B
packages/db/dist/esm/scheduler.js	1.34 kB
packages/db/dist/esm/SortedMap.js	1.3 kB
packages/db/dist/esm/strategies/debounceStrategy.js	247 B
packages/db/dist/esm/strategies/queueStrategy.js	428 B
packages/db/dist/esm/strategies/throttleStrategy.js	246 B
packages/db/dist/esm/transactions.js	3.71 kB
packages/db/dist/esm/utils.js	1.08 kB
packages/db/dist/esm/utils/array-utils.js	270 B
packages/db/dist/esm/utils/browser-polyfills.js	304 B
packages/db/dist/esm/utils/btree.js	4.51 kB
packages/db/dist/esm/utils/callbacks.js	174 B
packages/db/dist/esm/utils/comparison.js	1.49 kB
packages/db/dist/esm/utils/cursor.js	676 B
packages/db/dist/esm/utils/error.js	167 B
packages/db/dist/esm/utils/get-or-create.js	155 B
packages/db/dist/esm/utils/index-optimization.js	2.42 kB
packages/db/dist/esm/utils/type-guards.js	230 B
packages/db/dist/esm/utils/uuid.js	449 B
packages/db/dist/esm/virtual-props.js	360 B

_{compressed-size-action::db-package-size}

[github-actions]

Size Change: 0 B

Total Size: 7.34 kB

ℹ️ View Unchanged

Filename	Size
packages/react-db/dist/esm/DbProvider.js	317 B
packages/react-db/dist/esm/HydrationBoundary.js	263 B
packages/react-db/dist/esm/index.js	330 B
packages/react-db/dist/esm/live-query-internals.js	282 B
packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.9 kB
packages/react-db/dist/esm/useLiveQuery.js	2.68 kB
packages/react-db/dist/esm/useLiveQueryEffect.js	355 B
packages/react-db/dist/esm/useLiveSuspenseQuery.js	812 B
packages/react-db/dist/esm/usePacedMutations.js	401 B

_{compressed-size-action::react-db-package-size}