Document how to destructure in Svelte

[KyleAMathews]

Fixes #414

Summary

This commit addresses issue #414 where users reported that destructuring the return value from useLiveQuery() breaks reactivity in Svelte 5.

Root Cause

This is a fundamental limitation of Svelte 5's reactivity system, not a bug in the library. When objects with getters are destructured, the destructuring evaluates getters once and captures the values at that moment, losing the reactive connection.

Solution

Added comprehensive documentation explaining:

• Why direct destructuring breaks reactivity
• Two correct usage patterns:
  1. Use dot notation (recommended): query.data, query.isLoading
  2. Wrap with $derived: const { data } = $derived(query)

Changes

• Updated JSDoc comments in useLiveQuery.svelte.ts with detailed explanation and examples
• Updated README.md with clear usage guidelines
• Added test case demonstrating the correct $derived pattern
• All 23 existing tests continue to pass

References

• Issue: Svelte 5 not reactive #414
• Svelte documentation: Svelte 5: better document breaking of universal reactivity with destructuring sveltejs/svelte#11002

🤖 Generated with Claude Code

🎯 Changes

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

[changeset-bot]

⚠️ No Changeset found

Latest commit: 897cf35

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

More templates

• todos
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@733

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/electric-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 897cf35

[github-actions]

Size Change: 0 B

Total Size: 84.3 kB

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/collection/change-events.js	1.63 kB
./packages/db/dist/esm/collection/changes.js	1.01 kB
./packages/db/dist/esm/collection/events.js	413 B
./packages/db/dist/esm/collection/index.js	3.23 kB
./packages/db/dist/esm/collection/indexes.js	1.16 kB
./packages/db/dist/esm/collection/lifecycle.js	1.8 kB
./packages/db/dist/esm/collection/mutations.js	2.52 kB
./packages/db/dist/esm/collection/state.js	3.8 kB
./packages/db/dist/esm/collection/subscription.js	2.2 kB
./packages/db/dist/esm/collection/sync.js	2.2 kB
./packages/db/dist/esm/deferred.js	230 B
./packages/db/dist/esm/errors.js	3.48 kB
./packages/db/dist/esm/event-emitter.js	798 B
./packages/db/dist/esm/index.js	1.62 kB
./packages/db/dist/esm/indexes/auto-index.js	794 B
./packages/db/dist/esm/indexes/base-index.js	835 B
./packages/db/dist/esm/indexes/btree-index.js	2 kB
./packages/db/dist/esm/indexes/lazy-index.js	1.21 kB
./packages/db/dist/esm/indexes/reverse-index.js	577 B
./packages/db/dist/esm/local-only.js	967 B
./packages/db/dist/esm/local-storage.js	2.42 kB
./packages/db/dist/esm/optimistic-action.js	294 B
./packages/db/dist/esm/proxy.js	3.86 kB
./packages/db/dist/esm/query/builder/functions.js	615 B
./packages/db/dist/esm/query/builder/index.js	4.04 kB
./packages/db/dist/esm/query/builder/ref-proxy.js	938 B
./packages/db/dist/esm/query/compiler/evaluators.js	1.55 kB
./packages/db/dist/esm/query/compiler/expressions.js	760 B
./packages/db/dist/esm/query/compiler/group-by.js	2.04 kB
./packages/db/dist/esm/query/compiler/index.js	2.21 kB
./packages/db/dist/esm/query/compiler/joins.js	2.65 kB
./packages/db/dist/esm/query/compiler/order-by.js	1.43 kB
./packages/db/dist/esm/query/compiler/select.js	1.28 kB
./packages/db/dist/esm/query/ir.js	785 B
./packages/db/dist/esm/query/live-query-collection.js	404 B
./packages/db/dist/esm/query/live/collection-config-builder.js	5.54 kB
./packages/db/dist/esm/query/live/collection-registry.js	233 B
./packages/db/dist/esm/query/live/collection-subscriber.js	2.11 kB
./packages/db/dist/esm/query/optimizer.js	3.26 kB
./packages/db/dist/esm/scheduler.js	1.29 kB
./packages/db/dist/esm/SortedMap.js	1.24 kB
./packages/db/dist/esm/transactions.js	3.05 kB
./packages/db/dist/esm/utils.js	1.01 kB
./packages/db/dist/esm/utils/browser-polyfills.js	365 B
./packages/db/dist/esm/utils/btree.js	6.01 kB
./packages/db/dist/esm/utils/comparison.js	754 B
./packages/db/dist/esm/utils/index-optimization.js	1.73 kB

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

[github-actions]

Size Change: 0 B

Total Size: 2.89 kB

ℹ️ View Unchanged

Filename	Size
./packages/react-db/dist/esm/index.js	168 B
./packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.41 kB
./packages/react-db/dist/esm/useLiveQuery.js	1.31 kB

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