refactor(db): extract shared live-query adapter helpers (RFC #1623 step 2) #1641
main fromrefs/pull/1641/head·merged by kevin-dp(GitHub profile, opens in a new tab) The first real deduplication slice of RFC #1623 — the first PR that touches adapter src/ and shrinks copy-paste. Follows the conformance suite (#1636), which guards this refactor.
Base: stacked on test/live-query-conformance-suite (#1636) so the conformance suite verifies the refactored adapters. Re-target to main once #1636 lands.
What's extracted#
Three helpers added to @tanstack/db (packages/db/src/live-query-adapter.ts), and all five adapters migrated to them:
isCollection(value)— one structural, multi-realm-safe collection guard. Replaces the duck-typed check copy-pasted in React/Vue/Svelte/Angular and Solid'sinstanceof CollectionImpl.instanceofgives false negatives across dual-package/multi-realm boundaries — the exact hazard the conformance suite hit — so consolidating on duck typing is also a correctness win.isSingleResultCollection(collection)— sharedfindOnecardinality check (wasconfig.singleResult, five times).getLiveQueryStatusFlags(status)—status → { isLoading, isReady, isIdle, isError, isCleanedUp }.
Honest scope note#
This slice is smaller than the RFC's "7 duplicated items" might suggest — and that's a real finding. Only the reactivity-free logic lifts cleanly into plain functions:
getLiveQueryStatusFlagsfits React's snapshot path, but the reactive adapters (Vue/Svelte/Solid/Angular) each expose every flag as its owncomputed/signal, so an object-returning helper doesn't fit them — forcing it would add code.- Input/disabled classification, status derivation, and change→state projection are all coupled to each framework's reactivity. They can't be lifted into plain helpers without the observer.
So this PR takes the clean, universal wins now (notably unifying isCollection and killing the instanceof divergence). The larger dedup is exactly what the observer (step 3) exists to do — and per the design decision, that observer will carry both a snapshot and the ChangeMessage[] so granular adapters (Vue/Svelte) keep fine-grained updates while others consume the snapshot.
Verification#
No behavior change. All five adapter suites green (including the conformance suite that guards this), and @tanstack/db (2456 tests) green. Minor changeset for @tanstack/db (new exports) + patch for the adapters.
🤖 Generated with Claude Code
Summary by CodeRabbit#
New Features
- Added shared live-query helpers for detecting collections, handling single-result collections, and mapping query status flags.
- Framework adapters now use the same shared logic for live queries, improving consistency across React, Vue, Svelte, Solid, and Angular.
Bug Fixes
- Improved collection detection in cases where objects come from different runtime contexts.
- Single-result live queries now return the expected item more reliably across adapters.
- 1
More templates
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1641@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1641@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1641@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1641@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1641@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1641@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1641@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1641@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1641@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1641@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1641@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1641@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1641@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1641@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1641@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1641@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1641@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1641@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1641@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1641@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1641@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1641commit:
4cf25aeSize Change: +383 B (+0.31%)
Total Size: 125 kB
📦 View Changed
Filename Size Change packages/db/dist/esm/index.js3.16 kB +65 B (+2.1%) packages/db/dist/esm/live-query-adapter.js318 B +318 B (new file) 🆕 compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size packages/db/dist/esm/collection/change-events.js1.43 kB packages/db/dist/esm/collection/changes.js1.38 kB packages/db/dist/esm/collection/cleanup-queue.js810 B packages/db/dist/esm/collection/events.js434 B packages/db/dist/esm/collection/index.js3.62 kB packages/db/dist/esm/collection/indexes.js1.99 kB packages/db/dist/esm/collection/lifecycle.js1.69 kB packages/db/dist/esm/collection/mutations.js2.47 kB packages/db/dist/esm/collection/state.js5.4 kB packages/db/dist/esm/collection/subscription.js3.74 kB packages/db/dist/esm/collection/sync.js2.88 kB packages/db/dist/esm/collection/transaction-metadata.js144 B packages/db/dist/esm/deferred.js207 B packages/db/dist/esm/errors.js5.1 kB packages/db/dist/esm/event-emitter.js748 B packages/db/dist/esm/indexes/auto-index.js829 B packages/db/dist/esm/indexes/base-index.js767 B packages/db/dist/esm/indexes/basic-index.js2.06 kB packages/db/dist/esm/indexes/btree-index.js2.19 kB packages/db/dist/esm/indexes/index-registry.js820 B packages/db/dist/esm/indexes/reverse-index.js557 B packages/db/dist/esm/local-only.js916 B packages/db/dist/esm/local-storage.js2.12 kB packages/db/dist/esm/optimistic-action.js359 B packages/db/dist/esm/paced-mutations.js496 B packages/db/dist/esm/proxy.js3.75 kB packages/db/dist/esm/query/builder/functions.js1.47 kB packages/db/dist/esm/query/builder/index.js5.84 kB packages/db/dist/esm/query/builder/ref-proxy.js1.24 kB packages/db/dist/esm/query/compiler/evaluators.js1.89 kB packages/db/dist/esm/query/compiler/expressions.js430 B packages/db/dist/esm/query/compiler/group-by.js3.56 kB packages/db/dist/esm/query/compiler/index.js6.67 kB packages/db/dist/esm/query/compiler/joins.js2.5 kB packages/db/dist/esm/query/compiler/lazy-targets.js923 B packages/db/dist/esm/query/compiler/order-by.js1.74 kB packages/db/dist/esm/query/compiler/select.js1.53 kB packages/db/dist/esm/query/effect.js4.77 kB packages/db/dist/esm/query/expression-helpers.js1.43 kB packages/db/dist/esm/query/ir.js1.25 kB packages/db/dist/esm/query/live-query-collection.js360 B packages/db/dist/esm/query/live/collection-config-builder.js9.1 kB packages/db/dist/esm/query/live/collection-registry.js264 B packages/db/dist/esm/query/live/collection-subscriber.js1.93 kB packages/db/dist/esm/query/live/internal.js145 B packages/db/dist/esm/query/live/utils.js1.81 kB packages/db/dist/esm/query/optimizer.js2.92 kB packages/db/dist/esm/query/predicate-utils.js2.97 kB packages/db/dist/esm/query/query-once.js359 B packages/db/dist/esm/query/subset-dedupe.js960 B packages/db/dist/esm/scheduler.js1.3 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.04 kB packages/db/dist/esm/utils.js927 B packages/db/dist/esm/utils/array-utils.js273 B packages/db/dist/esm/utils/browser-polyfills.js304 B packages/db/dist/esm/utils/btree.js5.61 kB packages/db/dist/esm/utils/comparison.js1.11 kB packages/db/dist/esm/utils/cursor.js457 B packages/db/dist/esm/utils/index-optimization.js2.39 kB packages/db/dist/esm/utils/type-guards.js157 B packages/db/dist/esm/utils/uuid.js449 B packages/db/dist/esm/virtual-props.js360 B Size Change: 0 B
Total Size: 4.26 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size packages/react-db/dist/esm/index.js249 B packages/react-db/dist/esm/useLiveInfiniteQuery.js1.32 kB packages/react-db/dist/esm/useLiveQuery.js1.37 kB packages/react-db/dist/esm/useLiveQueryEffect.js355 B packages/react-db/dist/esm/useLiveSuspenseQuery.js567 B packages/react-db/dist/esm/usePacedMutations.js401 B 🧹 Nitpick comments (2)
packages/angular-db/src/index.ts (1)
281-283: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winPrefer a narrower cast than
Signal<any>forcollection.Casting to
Signal<any>discards all type information from the declaredInjectLiveQueryResult/InjectLiveQueryResultWithSingleResultCollectionreturn shapes (Signal<Collection<...> | null>), so the implementation body is no longer checked against either overload'scollectionfield. As per coding guidelines, "Avoid usinganytypes; useunknowninstead when the type is truly unknown, and provide proper type annotations for return values."♻️ Suggested refactor
- // Loosely typed so the impl return stays compatible with every overload - // (the shared `isCollection` guard narrows the computed to `Collection | null`). - collection: collection as Signal<any>, + // Loosely typed so the impl return stays compatible with every overload + // (the shared `isCollection` guard narrows the computed to `Collection | null`). + collection: collection as Signal<Collection<any, any, any> | null>,🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/angular-db/src/index.ts` around lines 281 - 283, The `collection` field in the `injectLiveQuery` return object is cast too broadly to `Signal<any>`, which erases the intended `InjectLiveQueryResult`/`InjectLiveQueryResultWithSingleResultCollection` typing. Update the implementation to use a narrower, specific signal type that matches the computed `Collection<...> | null` shape (or a shared union/unknown-based annotation if needed) so the overload contract stays checked. Locate the change in `injectLiveQuery` where `collection` is assigned and replace the `Signal<any>` cast with a properly typed return annotation or assertion.Source: Coding guidelines
packages/db/src/live-query-adapter.ts (1)
22-32: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAvoid
anyinside this shared guard. Castvalueonce toRecord<string, unknown>after the object check, then probe the properties from that typed reference.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/db/src/live-query-adapter.ts` around lines 22 - 32, The shared type guard in isCollection currently uses repeated any casts to inspect properties; replace those with a single post-null object cast to Record<string, unknown> and read subscribeChanges, startSyncImmediate, and id from that typed reference. Keep the same runtime checks, but ensure the guard no longer relies on any inside the predicate.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. Nitpick comments: In `@packages/angular-db/src/index.ts`: - Around line 281-283: The `collection` field in the `injectLiveQuery` return object is cast too broadly to `Signal<any>`, which erases the intended `InjectLiveQueryResult`/`InjectLiveQueryResultWithSingleResultCollection` typing. Update the implementation to use a narrower, specific signal type that matches the computed `Collection<...> | null` shape (or a shared union/unknown-based annotation if needed) so the overload contract stays checked. Locate the change in `injectLiveQuery` where `collection` is assigned and replace the `Signal<any>` cast with a properly typed return annotation or assertion. In `@packages/db/src/live-query-adapter.ts`: - Around line 22-32: The shared type guard in isCollection currently uses repeated any casts to inspect properties; replace those with a single post-null object cast to Record<string, unknown> and read subscribeChanges, startSyncImmediate, and id from that typed reference. Keep the same runtime checks, but ensure the guard no longer relies on any inside the predicate.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
f92418ce-9388-43da-b94f-d8cbe3d645d6📥 Commits
Reviewing files that changed from the base of the PR and between 3ec3e7ae1b2fa5ab9fee3ebaebb6d97c9487d29b and 4cf25ae5dee5348e9848c7fed37251c4913ba6fe.
📒 Files selected for processing (8)
.changeset/extract-adapter-helpers.mdpackages/angular-db/src/index.tspackages/db/src/index.tspackages/db/src/live-query-adapter.tspackages/react-db/src/useLiveQuery.tspackages/solid-db/src/useLiveQuery.tspackages/svelte-db/src/useLiveQuery.svelte.tspackages/vue-db/src/useLiveQuery.ts
KyleAMathews(GitHub profile, opens in a new tab) approved these changes
:shipit:
kevin-dp(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
📝 Walkthrough
Walkthrough#
Shared live-query adapter helper functions (isCollection, isSingleResultCollection, getLiveQueryStatusFlags) are added to
@tanstack/dband re-exported. React, Vue, Svelte, Solid, and Angular useLiveQuery/injectLiveQuery implementations are migrated to use these shared helpers, replacing per-adapter duck-typing and instanceof checks.Changes#
Live-query adapter helper extraction and migration
packages/db/src/live-query-adapter.ts,packages/db/src/index.ts,.changeset/extract-adapter-helpers.mdisCollection,isSingleResultCollection,LiveQueryStatusFlags, andgetLiveQueryStatusFlags, re-exports them from the package, and records the change in a changeset with version bumps.packages/react-db/src/useLiveQuery.tsCollectionImplinstanceof/manual checks withisCollection, usesisSingleResultCollectionfor snapshot single-result detection, and derives status flags viagetLiveQueryStatusFlags.packages/solid-db/src/useLiveQuery.tsinstanceof CollectionImplchecks withisCollectionand switches single-result detection ingetData()toisSingleResultCollection.packages/svelte-db/src/useLiveQuery.svelte.tsisCollectionand single-result config checks withisSingleResultCollection.packages/vue-db/src/useLiveQuery.tsisCollectionand single-result config checks withisSingleResultCollection.packages/angular-db/src/index.tsisCollection, single-result config check withisSingleResultCollection, and casts the returned collection signal toSignal<any>.Estimated code review effort: 3 (Moderate) | ~25 minutes
Suggested reviewers:
samwillis🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
✨ Finishing Touches
📝 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