From 8f19a748ee6756ebcc7ee384096e25c168f03024 Mon Sep 17 00:00:00 2001
From: Valter Balegas <balegas@electric-sql.com>
Date: Tue, 14 Apr 2026 09:27:37 +0100
Subject: [PATCH 1/2] docs(react-db): add CRITICAL mistakes for === in where
 and useLiveQuery destructuring
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AI agents frequently make two mistakes that cause runtime crashes:

1. Using `===` instead of `eq()` in `.where()` callbacks — returns a
   boolean instead of a query expression, throwing
   InvalidWhereExpressionError

2. Assigning `useLiveQuery()` directly to a variable instead of
   destructuring `{ data }` — then calling `.map()` on the result
   object, throwing "map is not a function"

Both are documented in db-core/live-queries but agents often only read
the react-db skill. Adding the warnings here where they'll actually
be seen.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 packages/react-db/skills/react-db/SKILL.md | 42 ++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/packages/react-db/skills/react-db/SKILL.md b/packages/react-db/skills/react-db/SKILL.md
index fb864ac8f..582880676 100644
--- a/packages/react-db/skills/react-db/SKILL.md
+++ b/packages/react-db/skills/react-db/SKILL.md
@@ -302,6 +302,48 @@ See meta-framework/SKILL.md for full preloading patterns.
 
 ## Common Mistakes
 
+### CRITICAL Using === instead of eq() in .where()
+
+Wrong — throws `InvalidWhereExpressionError` at runtime:
+
+```tsx
+const { data } = useLiveQuery((q) =>
+  q.from({ todo: todoCollection }).where(({ todo }) => todo.completed === true),
+  [],
+)
+```
+
+Correct — use expression functions from `@tanstack/react-db`:
+
+```tsx
+import { useLiveQuery, eq } from '@tanstack/react-db'
+
+const { data } = useLiveQuery((q) =>
+  q.from({ todo: todoCollection }).where(({ todo }) => eq(todo.completed, true)),
+  [],
+)
+```
+
+JavaScript `===`, `!==`, `<`, `>` return a boolean, not a query expression. Always use `eq`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `not`, `like`, `ilike`, `isNull`, `isUndefined`, `inArray`. See db-core/live-queries/SKILL.md for the full operator reference.
+
+### CRITICAL Assigning useLiveQuery result directly instead of destructuring
+
+Wrong — crashes with "map is not a function":
+
+```tsx
+const todos = useLiveQuery((q) => q.from({ todo: todoCollection }), [])
+return todos.map(t => <li>{t.text}</li>)  // TypeError: todos.map is not a function
+```
+
+Correct — destructure `{ data }` with a default:
+
+```tsx
+const { data: todos = [] } = useLiveQuery((q) => q.from({ todo: todoCollection }), [])
+return todos.map(t => <li key={t.id}>{t.text}</li>)
+```
+
+`useLiveQuery` returns an object `{ data, isLoading, status, ... }`, not the array directly.
+
 ### CRITICAL Missing external values in dependency array
 
 Wrong:

From be75c3d283175dae6b27c1c08d38761c3a8b2fb1 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Tue, 14 Apr 2026 08:29:11 +0000
Subject: [PATCH 2/2] ci: apply automated fixes

---
 packages/react-db/skills/react-db/SKILL.md | 23 +++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/packages/react-db/skills/react-db/SKILL.md b/packages/react-db/skills/react-db/SKILL.md
index 582880676..596569342 100644
--- a/packages/react-db/skills/react-db/SKILL.md
+++ b/packages/react-db/skills/react-db/SKILL.md
@@ -307,8 +307,11 @@ See meta-framework/SKILL.md for full preloading patterns.
 Wrong — throws `InvalidWhereExpressionError` at runtime:
 
 ```tsx
-const { data } = useLiveQuery((q) =>
-  q.from({ todo: todoCollection }).where(({ todo }) => todo.completed === true),
+const { data } = useLiveQuery(
+  (q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => todo.completed === true),
   [],
 )
 ```
@@ -318,8 +321,11 @@ Correct — use expression functions from `@tanstack/react-db`:
 ```tsx
 import { useLiveQuery, eq } from '@tanstack/react-db'
 
-const { data } = useLiveQuery((q) =>
-  q.from({ todo: todoCollection }).where(({ todo }) => eq(todo.completed, true)),
+const { data } = useLiveQuery(
+  (q) =>
+    q
+      .from({ todo: todoCollection })
+      .where(({ todo }) => eq(todo.completed, true)),
   [],
 )
 ```
@@ -332,14 +338,17 @@ Wrong — crashes with "map is not a function":
 
 ```tsx
 const todos = useLiveQuery((q) => q.from({ todo: todoCollection }), [])
-return todos.map(t => <li>{t.text}</li>)  // TypeError: todos.map is not a function
+return todos.map((t) => <li>{t.text}</li>) // TypeError: todos.map is not a function
 ```
 
 Correct — destructure `{ data }` with a default:
 
 ```tsx
-const { data: todos = [] } = useLiveQuery((q) => q.from({ todo: todoCollection }), [])
-return todos.map(t => <li key={t.id}>{t.text}</li>)
+const { data: todos = [] } = useLiveQuery(
+  (q) => q.from({ todo: todoCollection }),
+  [],
+)
+return todos.map((t) => <li key={t.id}>{t.text}</li>)
 ```
 
 `useLiveQuery` returns an object `{ data, isLoading, status, ... }`, not the array directly.