docs: Improve onError documentation for TypeScript client #3335
Conversation
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
- Add critical information that returning empty object `{}` is required to continue syncing
- Document that returning void/undefined stops syncing permanently
- Add comprehensive examples showing retry patterns:
- Basic retry on server errors
- Async token refresh on 401
- Updating query parameters on 403
- Selective retry logic with counters
- Improve JSDoc with inline examples
- Add clear behavior table for return values
- Enhance error type documentation with properties
Fixes issue where users didn't know they must return at least `{}` to keep syncing,
causing accidental stream termination when just logging errors.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3335 +/- ##
==========================================
- Coverage 69.65% 69.60% -0.06%
==========================================
Files 178 178
Lines 9709 9709
Branches 336 333 -3
==========================================
- Hits 6763 6758 -5
- Misses 2944 2949 +5
Partials 2 2
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Added explicit statement that without an onError handler, any error will stop syncing permanently with no automatic retry behavior. This clarifies a potential misconception that there might be some default retry logic even without onError. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
✅ Deploy Preview for electric-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
IMPORTANT FIX: The previous commit incorrectly stated that there's no automatic retry without onError. This is wrong! The client DOES automatically retry with exponential backoff: - 5xx server errors → automatic retry - Network errors → automatic retry - 429 rate limits → automatic retry - 4xx client errors (except 429) → NO retry, onError invoked immediately The onError callback is only invoked: 1. After automatic retries are exhausted (for 5xx/network) 2. Immediately for non-retryable errors (4xx client errors) Updated all documentation to reflect this, and revised examples to show realistic use cases (mainly handling 4xx errors like 401 auth refresh). Thanks to reviewer for catching this critical error! 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
✅ Deploy Preview for electric-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Fixed critical bug in the onError callback:
- Changed from throwing error (which crashes the stream) to proper return values
- Return void to stop on 4xx client errors (except 401/403)
- Return {} to retry on network errors
- Added comment clarifying 5xx errors are auto-retried
- Maintains proper 401/403 token refresh behavior
Before: throw error would crash the stream
After: Proper return values control retry/stop behavior
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
Added comprehensive section on handling authentication errors with onError: - Complete example showing 401 token refresh - 403 forbidden handling - Proper return values for retry/stop behavior - Clarification that 5xx errors are auto-retried - Links to main onError documentation This complements the gatekeeper-auth example and provides inline documentation for the common auth error handling patterns. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
The gatekeeper-auth example is already embedded in the auth guide via <<< @../../examples/gatekeeper-auth/client/index.ts, which shows the onError handling pattern. No need for a duplicate example. The embedded example was already improved to show proper return values.
Added focused section on handling auth errors with onError that applies to both proxy and gatekeeper patterns. The proxy auth example doesn't show error handling, and this provides context for the embedded gatekeeper example. Kept it concise with just 401 token refresh example and links to full TypeScript client docs for complete error handling details.
KyleAMathews
deleted the
claude/improve-typescript-onerror-011CUQRudRY67rXtM3eqhNju
branch
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
KyleAMathews
temporarily deployed
to
Pull request
GitHub Actions
Inactive
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
{}is required to continue syncingFixes issue where users didn't know they must return at least
{}to keep syncing, causing accidental stream termination when just logging errors.🤖 Generated with Claude Code