Add comprehensive error handling documentation and improve collection auto-restart behavior #285

KyleAMathews · 2025-07-18T21:15:20Z

Summary

Added comprehensive error handling documentation covering all TanStack DB error scenarios
Fixed collection operations to automatically restart from cleaned-up state (improves DX)
Updated navigation to include Error Handling guide in the docs

Changes

Documentation

New docs/error-handling.md - Comprehensive guide covering:
- SchemaValidationError with validation issues and paths
- Collection status states and error handling
- Transaction error handling and automatic rollbacks
- Collection operation errors (missing handlers, duplicate keys, etc.)
- Sync error handling for different collection types (Query, Electric, etc.)
- Error recovery patterns and best practices
- Complete examples with real-world error handling

Code Improvements

Fixed collection auto-restart behavior - Collections in cleaned-up state now automatically restart when operations are called, matching the behavior of other collection access patterns
Updated navigation - Added Error Handling to the Guides section

Test plan

Documentation follows existing conventions and style
All error handling examples use real APIs from the codebase
Collection auto-restart behavior tested and working
Navigation properly includes the new error handling page

🤖 Generated with Claude Code

… auto-restart behavior - Add error-handling.md documentation covering all TanStack DB error scenarios - Fix collection operations to automatically restart from cleaned-up state - Update navigation to include Error Handling guide - Document SchemaValidationError, transaction rollbacks, and sync error handling 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

changeset-bot · 2025-07-18T21:15:24Z

🦋 Changeset detected

Latest commit: 3e7d73f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@tanstack/db	Patch
@tanstack/electric-db-collection	Patch
@tanstack/query-db-collection	Patch
@tanstack/react-db	Patch
@tanstack/trailbase-db-collection	Patch
@tanstack/vue-db	Patch
@tanstack/db-example-react-todo	Patch

Not sure what this means? Click here to learn what changesets are.

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

pkg-pr-new · 2025-07-18T21:16:18Z

@tanstack/db-example-react-todo

@tanstack/db

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

@tanstack/electric-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 3e7d73f

github-actions · 2025-07-18T21:17:02Z

Size Change: -196 B (-0.51%)

Total Size: 38.4 kB

Filename	Size	Change
`./packages/db/dist/esm/collection.js`	8.66 kB	-26 B (-0.3%)
`./packages/db/dist/esm/errors.js`	0 B	-150 B (removed)	🏆
`./packages/db/dist/esm/index.js`	548 B	-20 B (-3.52%)

ℹ️ View Unchanged

Filename	Size
`./packages/db/dist/esm/deferred.js`	230 B
`./packages/db/dist/esm/local-only.js`	827 B
`./packages/db/dist/esm/local-storage.js`	2.09 kB
`./packages/db/dist/esm/optimistic-action.js`	294 B
`./packages/db/dist/esm/proxy.js`	4.19 kB
`./packages/db/dist/esm/query/builder/functions.js`	531 B
`./packages/db/dist/esm/query/builder/index.js`	3.68 kB
`./packages/db/dist/esm/query/builder/ref-proxy.js`	842 B
`./packages/db/dist/esm/query/compiler/evaluators.js`	1.34 kB
`./packages/db/dist/esm/query/compiler/group-by.js`	2.09 kB
`./packages/db/dist/esm/query/compiler/index.js`	1.75 kB
`./packages/db/dist/esm/query/compiler/joins.js`	1.2 kB
`./packages/db/dist/esm/query/compiler/order-by.js`	933 B
`./packages/db/dist/esm/query/compiler/select.js`	657 B
`./packages/db/dist/esm/query/ir.js`	318 B
`./packages/db/dist/esm/query/live-query-collection.js`	2.07 kB
`./packages/db/dist/esm/query/optimizer.js`	2.24 kB
`./packages/db/dist/esm/SortedMap.js`	1.24 kB
`./packages/db/dist/esm/transactions.js`	2.29 kB
`./packages/db/dist/esm/utils.js`	419 B

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

github-actions · 2025-07-18T21:17:47Z

Size Change: 0 B

Total Size: 1.05 kB

ℹ️ View Unchanged

Filename	Size
`./packages/react-db/dist/esm/index.js`	152 B
`./packages/react-db/dist/esm/useLiveQuery.js`	902 B

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

- Remove unused errors export from index.ts - Update collection-errors test to reflect new auto-restart behavior - Collections now automatically restart from cleaned-up state on operations

KyleAMathews

ss

packages/db/src/collection.ts

samwillis

This looks good, the one thing I would consider doing (which could be in a followup) is to make it easer to determine the reason for an error on a mutation. See the other comment.

samwillis · 2025-07-21T15:02:24Z

docs/error-handling.md

+try {
+  todoCollection.insert(newTodo)
+} catch (error) {
+  if (error.message.includes("collection is in error state")) {


This patten feels a little flaky if the message changes. A check for a prop or error type may be better?

I wander is an error.reason which is a fixed set of strings 'collection-error-sate' | 'key-conflict' | 'no-insert-handler' | 'validation-error'?

Or a distinct Error subclass for each type?

yeah — agree that named errors would be good — easy follow-up for AI to flip through

packages/db/src/collection.ts

Fix tests after collection auto-restart behavior change

307d901

- Remove unused errors export from index.ts - Update collection-errors test to reflect new auto-restart behavior - Collections now automatically restart from cleaned-up state on operations

KyleAMathews commented Jul 18, 2025

View reviewed changes

packages/db/src/collection.ts Show resolved Hide resolved

KyleAMathews requested a review from samwillis July 18, 2025 21:57

Merge branch 'main' into error-handling-docs

3e7d73f

samwillis approved these changes Jul 21, 2025

View reviewed changes

KyleAMathews merged commit ced0657 into main Jul 21, 2025
4 of 5 checks passed

KyleAMathews deleted the error-handling-docs branch July 21, 2025 16:34

github-actions bot mentioned this pull request Jul 21, 2025

ci: Version Packages #295

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add comprehensive error handling documentation and improve collection auto-restart behavior #285

Add comprehensive error handling documentation and improve collection auto-restart behavior #285

Uh oh!

KyleAMathews commented Jul 18, 2025

Uh oh!

changeset-bot bot commented Jul 18, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jul 18, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Jul 18, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Jul 18, 2025 •

edited

Loading

Uh oh!

KyleAMathews left a comment

Uh oh!

Uh oh!

samwillis left a comment

Uh oh!

samwillis Jul 21, 2025 •

edited

Loading

Uh oh!

KyleAMathews Jul 21, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Add comprehensive error handling documentation and improve collection auto-restart behavior #285

Add comprehensive error handling documentation and improve collection auto-restart behavior #285

Uh oh!

Conversation

KyleAMathews commented Jul 18, 2025

Summary

Changes

Documentation

Code Improvements

Test plan

Uh oh!

changeset-bot bot commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KyleAMathews left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

samwillis left a comment

Choose a reason for hiding this comment

Uh oh!

samwillis Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KyleAMathews Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

changeset-bot bot commented Jul 18, 2025 •

edited

Loading

pkg-pr-new bot commented Jul 18, 2025 •

edited

Loading

github-actions bot commented Jul 18, 2025 •

edited

Loading

github-actions bot commented Jul 18, 2025 •

edited

Loading

samwillis Jul 21, 2025 •

edited

Loading