Document how to destructure in Svelte (#733)

* docs(svelte-db): Add documentation for destructuring reactivity issue (#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: #414
- Svelte documentation: sveltejs/svelte#11002

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* chore(svelte-db): Revert README changes to keep it minimal

The README is intentionally kept small, so reverting the detailed
documentation. The comprehensive documentation remains in the JSDoc
comments in useLiveQuery.svelte.ts.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* chore: Remove package-lock.json (project uses pnpm)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

Author: KyleAMathews

packages/svelte-db/src/useLiveQuery.svelte.ts

@@ -68,13 +68,38 @@ function toValue<T>(value: MaybeGetter<T>): T {
  * @param queryFn - Query function that defines what data to fetch
  * @param deps - Array of reactive dependencies that trigger query re-execution when changed
  * @returns Reactive object with query data, state, and status information
+ *
+ * @remarks
+ * **IMPORTANT - Destructuring in Svelte 5:**
+ * Direct destructuring breaks reactivity. To destructure, wrap with `$derived`:
+ *
+ * ❌ **Incorrect** - Loses reactivity:
+ * ```ts
+ * const { data, isLoading } = useLiveQuery(...)
+ * ```
+ *
+ * ✅ **Correct** - Maintains reactivity:
+ * ```ts
+ * // Option 1: Use dot notation (recommended)
+ * const query = useLiveQuery(...)
+ * // Access: query.data, query.isLoading
+ *
+ * // Option 2: Wrap with $derived for destructuring
+ * const query = useLiveQuery(...)
+ * const { data, isLoading } = $derived(query)
+ * ```
+ *
+ * This is a fundamental Svelte 5 limitation, not a library bug. See:
+ * https://github.com/sveltejs/svelte/issues/11002
+ *
  * @example
- * // Basic query with object syntax
+ * // Basic query with object syntax (recommended pattern)
  * const todosQuery = useLiveQuery((q) =>
  *   q.from({ todos: todosCollection })
  *    .where(({ todos }) => eq(todos.completed, false))
  *    .select(({ todos }) => ({ id: todos.id, text: todos.text }))
  * )
+ * // Access via: todosQuery.data, todosQuery.isLoading, etc.
  *
  * @example
  * // With reactive dependencies
@@ -86,6 +111,14 @@ function toValue<T>(value: MaybeGetter<T>): T {
  * )
  *
  * @example
+ * // Destructuring with $derived (if needed)
+ * const query = useLiveQuery((q) =>
+ *   q.from({ todos: todosCollection })
+ * )
+ * const { data, isLoading, isError } = $derived(query)
+ * // Now data, isLoading, and isError maintain reactivity
+ *
+ * @example
  * // Join pattern
  * const issuesQuery = useLiveQuery((q) =>
  *   q.from({ issues: issueCollection })

packages/svelte-db/tests/useLiveQuery.svelte.test.ts

@@ -116,6 +116,96 @@ describe(`Query Collections`, () => {
     })
   })
 
+  it(`should maintain reactivity when destructuring return values with $derived`, () => {
+    const collection = createCollection(
+      mockSyncCollectionOptions<Person>({
+        id: `test-persons-destructure`,
+        getKey: (person: Person) => person.id,
+        initialData: initialPersons,
+      })
+    )
+
+    cleanup = $effect.root(() => {
+      // IMPORTANT: In Svelte 5, destructuring breaks reactivity unless wrapped in $derived
+      // This is the correct pattern for destructuring (Issue #414)
+      const query = useLiveQuery((q) =>
+        q
+          .from({ persons: collection })
+          .where(({ persons }) => gt(persons.age, 30))
+          .select(({ persons }) => ({
+            id: persons.id,
+            name: persons.name,
+            age: persons.age,
+          }))
+      )
+
+      // Destructure using $derived to maintain reactivity
+      const { data, state, isReady, isLoading } = $derived(query)
+
+      flushSync()
+
+      // Initial state checks
+      expect(isReady).toBe(true)
+      expect(isLoading).toBe(false)
+      expect(state.size).toBe(1)
+      expect(data).toHaveLength(1)
+      expect(data[0]).toMatchObject({
+        id: `3`,
+        name: `John Smith`,
+        age: 35,
+      })
+
+      // Add a new person that matches the filter
+      collection.utils.begin()
+      collection.utils.write({
+        type: `insert`,
+        value: {
+          id: `4`,
+          name: `Alice Johnson`,
+          age: 40,
+          email: `[email protected]`,
+          isActive: true,
+          team: `team1`,
+        },
+      })
+      collection.utils.commit()
+
+      flushSync()
+
+      // Verify destructured values are still reactive after collection change
+      expect(state.size).toBe(2)
+      expect(data).toHaveLength(2)
+      expect(data.some((p) => p.id === `4`)).toBe(true)
+      expect(data.some((p) => p.id === `3`)).toBe(true)
+
+      // Remove a person
+      collection.utils.begin()
+      collection.utils.write({
+        type: `delete`,
+        value: {
+          id: `3`,
+          name: `John Smith`,
+          age: 35,
+          email: `[email protected]`,
+          isActive: true,
+          team: `team1`,
+        },
+      })
+      collection.utils.commit()
+
+      flushSync()
+
+      // Verify destructured values still track changes
+      expect(state.size).toBe(1)
+      expect(data).toHaveLength(1)
+      expect(data[0]).toMatchObject({
+        id: `4`,
+        name: `Alice Johnson`,
+        age: 40,
+      })
+    })
+  })
+
   it(`should be able to query a collection with live updates`, () => {
     const collection = createCollection(
       mockSyncCollectionOptions<Person>({