docs: update agent skills for current APIs#1696
Open
KyleAMathews wants to merge 2 commits into
Open
Conversation
Contributor
📝 WalkthroughWalkthroughUpdates TanStack DB skill documentation and package patch metadata to version 0.6.17, covering current collection, query, adapter, persistence, transaction, and framework APIs and behavior. ChangesSkill documentation refresh
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 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. Comment |
More templates
@tanstack/angular-db
@tanstack/browser-db-sqlite-persistence
@tanstack/capacitor-db-sqlite-persistence
@tanstack/cloudflare-durable-objects-db-sqlite-persistence
@tanstack/db
@tanstack/db-ivm
@tanstack/db-sqlite-persistence-core
@tanstack/electric-db-collection
@tanstack/electron-db-sqlite-persistence
@tanstack/expo-db-sqlite-persistence
@tanstack/node-db-sqlite-persistence
@tanstack/offline-transactions
@tanstack/powersync-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/react-native-db-sqlite-persistence
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/tauri-db-sqlite-persistence
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit: |
Contributor
|
Size Change: 0 B Total Size: 125 kB ℹ️ View Unchanged
|
Contributor
|
Size Change: 0 B Total Size: 4.22 kB ℹ️ View Unchanged
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/db/skills/meta-framework/SKILL.md (1)
378-405: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winMake the “Wrong” example actually demonstrate duplicate instances.
The shown route-local collection is a single stable instance shared by that loader and component, so it is not incorrect for one global
QueryClientand business scope. Replace it with two separately created collections, or show a request/tenant-scoped client incorrectly reusing a process-global collection.🤖 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/skills/meta-framework/SKILL.md` around lines 378 - 405, Update the “Wrong” example in the collection-scope guidance to show two separately created collection instances within the same QueryClient and business scope, while keeping the “Correct” shared-module example and surrounding explanation intact. Ensure the loader and component use different collection objects so the duplicate-sync and split-state issue is actually demonstrated.
🤖 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.
Inline comments:
In `@packages/db/skills/db-core/custom-adapter/SKILL.md`:
- Around line 95-116: Define or clearly mark the waitForServerObservation helper
used by onInsert, onUpdate, and onDelete so the adapter example does not contain
an unresolved identifier. If implementing it, describe the provider/stream
observation mechanism and its completion behavior; otherwise label it as
pseudocode and provide guidance for replacing it with the target system’s
implementation.
In `@packages/react-db/skills/react-db/SKILL.md`:
- Around line 358-363: Update the InvalidSourceError example in the
query-builder alias troubleshooting section to match the current live-query
implementation, including the “Collection or subquery” wording and actionable
guidance, or paraphrase the complete message without preserving the outdated
incomplete quote.
---
Outside diff comments:
In `@packages/db/skills/meta-framework/SKILL.md`:
- Around line 378-405: Update the “Wrong” example in the collection-scope
guidance to show two separately created collection instances within the same
QueryClient and business scope, while keeping the “Correct” shared-module
example and surrounding explanation intact. Ensure the loader and component use
different collection objects so the duplicate-sync and split-state issue is
actually demonstrated.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 0f8bc1da-8667-4fa5-9086-e4cff6d40f34
📒 Files selected for processing (22)
.changeset/update-agent-skills.mdpackages/angular-db/skills/angular-db/SKILL.mdpackages/db/skills/db-core/SKILL.mdpackages/db/skills/db-core/collection-setup/SKILL.mdpackages/db/skills/db-core/collection-setup/references/electric-adapter.mdpackages/db/skills/db-core/collection-setup/references/local-adapters.mdpackages/db/skills/db-core/collection-setup/references/powersync-adapter.mdpackages/db/skills/db-core/collection-setup/references/query-adapter.mdpackages/db/skills/db-core/collection-setup/references/rxdb-adapter.mdpackages/db/skills/db-core/collection-setup/references/trailbase-adapter.mdpackages/db/skills/db-core/custom-adapter/SKILL.mdpackages/db/skills/db-core/live-queries/SKILL.mdpackages/db/skills/db-core/live-queries/references/operators.mdpackages/db/skills/db-core/mutations-optimistic/SKILL.mdpackages/db/skills/db-core/mutations-optimistic/references/transaction-api.mdpackages/db/skills/db-core/persistence/SKILL.mdpackages/db/skills/meta-framework/SKILL.mdpackages/offline-transactions/skills/offline/SKILL.mdpackages/react-db/skills/react-db/SKILL.mdpackages/solid-db/skills/solid-db/SKILL.mdpackages/svelte-db/skills/svelte-db/SKILL.mdpackages/vue-db/skills/vue-db/SKILL.md
Comment on lines
+95
to
+116
| const response = await fetch(config.endpoint, { | ||
| method: 'POST', | ||
| body: JSON.stringify(transaction.mutations[0].modified), | ||
| }) | ||
| await waitForServerObservation(response) | ||
| }, | ||
| onUpdate: async ({ transaction }) => { | ||
| const mut = transaction.mutations[0] | ||
| await fetch(`${config.endpoint}/${mut.key}`, { | ||
| const response = await fetch(`${config.endpoint}/${mut.key}`, { | ||
| method: 'PATCH', | ||
| body: JSON.stringify(mut.changes), | ||
| }) | ||
| await waitForServerObservation(response) | ||
| }, | ||
| onDelete: async ({ transaction }) => { | ||
| await fetch(`${config.endpoint}/${transaction.mutations[0].key}`, { | ||
| method: 'DELETE', | ||
| }) | ||
| const response = await fetch( | ||
| `${config.endpoint}/${transaction.mutations[0].key}`, | ||
| { | ||
| method: 'DELETE', | ||
| }, | ||
| ) | ||
| await waitForServerObservation(response) |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate file =="
git ls-files | grep -F 'packages/db/skills/db-core/custom-adapter/SKILL.md' || true
echo "== file size and relevant lines =="
if [ -f packages/db/skills/db-core/custom-adapter/SKILL.md ]; then
wc -l packages/db/skills/db-core/custom-adapter/SKILL.md
sed -n '1,140p' packages/db/skills/db-core/custom-adapter/SKILL.md | cat -n
fi
echo "== search helper usages/definitions =="
rg -n "waitForServerObservation|function waitForServerObservation|const waitForServerObservation|await waitForServerObservation" .Repository: TanStack/db
Length of output: 5607
Define or clarify waitForServerObservation.
This helper is used in the onInsert, onUpdate, and onDelete examples but is not imported or defined, so copying the adapter code produces an unresolved identifier. Add an implementation for that provider/stream, or mark the helper as pseudocode with implementation guidance.
🤖 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/skills/db-core/custom-adapter/SKILL.md` around lines 95 - 116,
Define or clearly mark the waitForServerObservation helper used by onInsert,
onUpdate, and onDelete so the adapter example does not contain an unresolved
identifier. If implementing it, describe the provider/stream observation
mechanism and its completion behavior; otherwise label it as pseudocode and
provide guidance for replacing it with the target system’s implementation.
Comment on lines
+358
to
+363
| If a query-builder alias throws | ||
| `InvalidSourceError: The value provided for alias "todo" is not a Collection`, | ||
| it can mean two copies of `@tanstack/db` are installed. Direct | ||
| `useLiveQuery(preCreatedCollection)` detection is structural and works across | ||
| package copies or realms, but `q.from({ todo: collection })` still validates | ||
| the source with the core collection class. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Locate and inspect the relevant source and documentation snippets.
git ls-files | rg '(^|/)SKILL\.md$|packages/db/src/errors\.ts$|invalidsource|InvalidSourceError' || true
echo '--- documentation snippet ---'
sed -n '345,370p' packages/react-db/skills/react-db/SKILL.md
echo '--- error implementation ---'
sed -n '360,400p' packages/db/src/errors.ts
echo '--- usages of InvalidSourceError messages ---'
rg -n "InvalidSourceError|not a Collection|subquery|source validation" packages || trueRepository: TanStack/db
Length of output: 46066
Synchronize the quoted InvalidSourceError message with the implementation.
InvalidSourceError now throws “Invalid source for live query: The value provided for alias "todo" is not a Collection or subquery...” and includes actionable guidance. Update the example to show the full message or paraphrase it so troubleshooting documentation doesn’t point users at an incomplete error text.
🤖 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/react-db/skills/react-db/SKILL.md` around lines 358 - 363, Update
the InvalidSourceError example in the query-builder alias troubleshooting
section to match the current live-query implementation, including the
“Collection or subquery” wording and actionable guidance, or paraphrase the
complete message without preserving the outdated incomplete quote.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This updates TanStack DB agent skills to match the current public APIs and behavior through
@tanstack/db0.6.17. Agents will now receive accurate guidance for query collections, live queries, mutations, persistence, adapters, and framework integrations instead of stale examples and defaults.Approach
QueryClientusage.materialize, arithmetic expressions, null/NaN behavior, virtual properties, and garbage collection.0.6.17and added patch changesets for every package that ships a changed skill.Key invariants
Non-goals
Verification
Frontmatter and relative Markdown links were also validated across all changed skill files.
Files changed
packages/db/skills/db-core/**: core setup, queries, adapters, mutations, and persistence guidance.packages/db/skills/meta-framework/SKILL.md: scoped collection ownership and loader patterns.packages/offline-transactions/skills/offline/SKILL.md: current UUID guidance..changeset/update-agent-skills.md: patch entries for all seven affected packages.Summary by CodeRabbit