chore(shared): Mark error utilities as internal #6328
Merged
+92
−0
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
🦋 Changeset detectedLatest commit: e23ce98 The changes in this PR will be included in the next version bump. This PR includes changesets to release 19 packages
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 |
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
📝 WalkthroughWalkthroughThis change updates the 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/elements
@clerk/clerk-expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/clerk-react
@clerk/react-router
@clerk/remix
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/themes
@clerk/types
@clerk/upgrade
@clerk/vue
commit: |
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
packages/shared/src/error.ts (1)
297-299: Minor: preferunknownoverErrorinisEmailLinkError
isEmailLinkErroraccepts any thrown value. Usingunknownmirrorscatch (e: unknown)patterns and prevents accidental reliance onErrormembers.-export function isEmailLinkError(err: Error): err is EmailLinkError { +export function isEmailLinkError(err: unknown): err is EmailLinkError { return (err as EmailLinkError)?.name === 'EmailLinkError'; }
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.changeset/new-taxes-fry.md(1 hunks)packages/shared/src/error.ts(6 hunks)
🧰 Additional context used
📓 Path-based instructions (5)
**/*.{js,jsx,ts,tsx}
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- .cursor/rules/development.mdc
packages/**/*.ts
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- .cursor/rules/development.mdc
packages/**/*.{ts,tsx,d.ts}
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- .cursor/rules/development.mdc
**/*.{ts,tsx}
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- .cursor/rules/development.mdc
- .cursor/rules/typescript.mdc
**/*
Instructions used from:
Sources:
⚙️ CodeRabbit Configuration File
🧠 Learnings (3)
📓 Common learnings
Learnt from: dstaley
PR: clerk/javascript#6116
File: .changeset/tangy-garlics-say.md:1-2
Timestamp: 2025-06-13T16:09:53.061Z
Learning: In the Clerk JavaScript repository, contributors create intentionally empty changeset files (containing only the YAML delimiters) when a PR touches only non-published parts of the codebase (e.g., sandbox assets). This signals that no package release is required, so such changesets should not be flagged as missing content.
Learnt from: LauraBeatris
PR: clerk/javascript#6273
File: packages/testing/src/playwright/unstable/page-objects/sessionTask.ts:22-27
Timestamp: 2025-07-11T17:12:28.495Z
Learning: In Clerk's test utilities, particularly for page objects like sessionTask.ts, when handling task type enums, prefer graceful handling of unknown/unsupported task types rather than throwing errors. This prevents breaking existing tests when new task types are introduced to the SessionTask['key'] union type.
Learnt from: wobsoriano
PR: clerk/javascript#6229
File: packages/backend/src/api/endpoints/MachineTokensApi.ts:47-89
Timestamp: 2025-07-01T15:20:41.834Z
Learning: In the Clerk JavaScript repository, for the MachineTokensApi class (packages/backend/src/api/endpoints/MachineTokensApi.ts), the maintainers prefer to rely on TypeScript types and readable property names for API documentation rather than JSDoc comments.
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Document public functions and APIs with JSDoc-style comments including @param, @returns, @throws, and @example
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/development.mdc:0-0
Timestamp: 2025-06-30T10:29:42.997Z
Learning: Applies to **/*.{js,jsx,ts,tsx} : Maintain comprehensive JSDoc comments for public APIs
Learnt from: wobsoriano
PR: clerk/javascript#5858
File: packages/clerk-js/src/core/modules/apiKeys/index.ts:84-97
Timestamp: 2025-06-10T17:35:08.986Z
Learning: In the APIKeys service methods (packages/clerk-js/src/core/modules/apiKeys/index.ts), error handling is intentionally delegated to the component level rather than being implemented within the service methods themselves. This architectural pattern allows calling components to handle errors according to their specific UI needs.
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/development.mdc:0-0
Timestamp: 2025-06-30T10:29:42.997Z
Learning: Applies to **/*.{js,jsx,ts,tsx} : All public APIs must be documented with JSDoc
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Use `public` explicitly for clarity in public APIs
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/development.mdc:0-0
Timestamp: 2025-06-30T10:29:42.997Z
Learning: Update documentation for API changes
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/monorepo.mdc:0-0
Timestamp: 2025-06-30T10:30:56.197Z
Learning: Applies to packages/*/package.json : All packages must be published under the @clerk namespace on npm.
Learnt from: panteliselef
PR: clerk/javascript#6285
File: packages/types/src/commerce.ts:1305-1305
Timestamp: 2025-07-11T18:08:14.697Z
Learning: In the Clerk JavaScript repository, when there's a conflict between naming consistency (camelCase) and avoiding breaking changes, the team prioritizes maintaining backward compatibility over enforcing naming conventions, even for experimental APIs.
.changeset/new-taxes-fry.md (9)
Learnt from: dstaley
PR: clerk/javascript#6116
File: .changeset/tangy-garlics-say.md:1-2
Timestamp: 2025-06-13T16:09:53.061Z
Learning: In the Clerk JavaScript repository, contributors create intentionally empty changeset files (containing only the YAML delimiters) when a PR touches only non-published parts of the codebase (e.g., sandbox assets). This signals that no package release is required, so such changesets should not be flagged as missing content.
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/monorepo.mdc:0-0
Timestamp: 2025-06-30T10:30:56.197Z
Learning: Applies to packages/@clerk/*/package.json : Framework packages must depend on '@clerk/clerk-js' for core functionality.
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/monorepo.mdc:0-0
Timestamp: 2025-06-30T10:30:56.197Z
Learning: Applies to packages/*/package.json : All packages must be published under the @clerk namespace on npm.
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/global.mdc:0-0
Timestamp: 2025-06-30T10:30:13.397Z
Learning: Applies to packages/*/package.json : All packages must be published under the @clerk namespace
Learnt from: wobsoriano
PR: clerk/javascript#5858
File: packages/clerk-js/src/core/modules/apiKeys/index.ts:84-97
Timestamp: 2025-06-10T17:35:08.986Z
Learning: In the APIKeys service methods (packages/clerk-js/src/core/modules/apiKeys/index.ts), error handling is intentionally delegated to the component level rather than being implemented within the service methods themselves. This architectural pattern allows calling components to handle errors according to their specific UI needs.
Learnt from: jacekradko
PR: clerk/javascript#5905
File: .changeset/six-ears-wash.md:1-3
Timestamp: 2025-06-26T03:27:05.535Z
Learning: In the Clerk JavaScript repository, changeset headers support single quotes syntax (e.g., '@clerk/backend': minor) and work fine with their current changesets integration, so there's no need to change them to double quotes.
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Use `private` for internal implementation details
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/monorepo.mdc:0-0
Timestamp: 2025-06-30T10:30:56.197Z
Learning: Applies to packages/{clerk-js,elements,themes}/**/* : Visual regression testing should be performed for UI components.
Learnt from: wobsoriano
PR: clerk/javascript#6099
File: packages/backend/src/api/endpoints/IdPOAuthAccessTokenApi.ts:7-14
Timestamp: 2025-06-10T20:38:08.982Z
Learning: Methods in `packages/backend/src/api/endpoints` (e.g., `IdPOAuthAccessTokenApi.verifySecret`) are currently not exposed publicly, so renaming them does not constitute a breaking change.
packages/shared/src/error.ts (13)
Learnt from: wobsoriano
PR: clerk/javascript#6229
File: packages/backend/src/api/endpoints/MachineTokensApi.ts:47-89
Timestamp: 2025-07-01T15:20:41.834Z
Learning: In the Clerk JavaScript repository, for the MachineTokensApi class (packages/backend/src/api/endpoints/MachineTokensApi.ts), the maintainers prefer to rely on TypeScript types and readable property names for API documentation rather than JSDoc comments.
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Document public functions and APIs with JSDoc-style comments including @param, @returns, @throws, and @example
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/development.mdc:0-0
Timestamp: 2025-06-30T10:29:42.997Z
Learning: Applies to **/*.{js,jsx,ts,tsx} : Maintain comprehensive JSDoc comments for public APIs
Learnt from: wobsoriano
PR: clerk/javascript#5858
File: packages/clerk-js/src/core/modules/apiKeys/index.ts:84-97
Timestamp: 2025-06-10T17:35:08.986Z
Learning: In the APIKeys service methods (packages/clerk-js/src/core/modules/apiKeys/index.ts), error handling is intentionally delegated to the component level rather than being implemented within the service methods themselves. This architectural pattern allows calling components to handle errors according to their specific UI needs.
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/development.mdc:0-0
Timestamp: 2025-06-30T10:29:42.997Z
Learning: Applies to **/*.{js,jsx,ts,tsx} : All public APIs must be documented with JSDoc
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/development.mdc:0-0
Timestamp: 2025-06-30T10:29:42.997Z
Learning: Update documentation for API changes
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Proper error handling with typed errors
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/development.mdc:0-0
Timestamp: 2025-06-30T10:29:42.997Z
Learning: Applies to **/*.{ts,tsx} : Use proper TypeScript error types
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/nextjs.mdc:0-0
Timestamp: 2025-06-30T10:31:43.578Z
Learning: Applies to app/api/**/*.ts : Document API endpoints with TypeScript interfaces
Learnt from: CR
PR: clerk/javascript#0
File: .cursor/rules/typescript.mdc:0-0
Timestamp: 2025-06-30T10:33:45.961Z
Learning: Applies to **/*.{ts,tsx} : Define custom error classes for domain-specific errors
Learnt from: LauraBeatris
PR: clerk/javascript#6273
File: packages/testing/src/playwright/unstable/page-objects/sessionTask.ts:22-27
Timestamp: 2025-07-11T17:12:28.495Z
Learning: In Clerk's test utilities, particularly for page objects like sessionTask.ts, when handling task type enums, prefer graceful handling of unknown/unsupported task types rather than throwing errors. This prevents breaking existing tests when new task types are introduced to the SessionTask['key'] union type.
Learnt from: panteliselef
PR: clerk/javascript#6285
File: packages/types/src/commerce.ts:1305-1305
Timestamp: 2025-07-11T18:08:14.697Z
Learning: In the Clerk JavaScript repository, when there's a conflict between naming consistency (camelCase) and avoiding breaking changes, the team prioritizes maintaining backward compatibility over enforcing naming conventions, even for experimental APIs.
Learnt from: LauraBeatris
PR: clerk/javascript#6117
File: packages/clerk-js/src/ui/components/SessionTasks/tasks/ForceOrganizationSelection.tsx:17-21
Timestamp: 2025-06-18T23:27:13.537Z
Learning: In Clerk's JavaScript codebase, query errors from hooks like useOrganizationList are not typically handled in AIO (All-in-One) components. Error handling may be connected with the Card context instead, suggesting a centralized error handling approach rather than component-level error handling.
🧬 Code Graph Analysis (1)
packages/shared/src/error.ts (3)
packages/types/src/api.ts (3)
ClerkAPIResponseError(50-57)ClerkRuntimeError(42-45)ClerkAPIError(4-40)packages/clerk-js/src/core/resources/Error.ts (8)
ClerkAPIResponseError(3-3)isKnownError(10-10)ClerkRuntimeError(2-2)MetamaskError(14-14)isClerkAPIResponseError(7-7)isMetamaskError(11-11)isClerkRuntimeError(8-8)isUserLockedError(12-12)packages/types/src/json.ts (1)
ClerkAPIErrorJSON(339-362)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: Build Packages
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (1)
.changeset/new-taxes-fry.md (1)
1-6: Changeset looks goodA patch bump for
@clerk/sharedis appropriate since only internal annotations were added and no public API changed.
Comment on lines
25
to
27
| export function isCaptchaError(e: ClerkAPIResponseError): boolean { | ||
| return ['captcha_invalid', 'captcha_not_enabled', 'captcha_missing_token'].includes(e.errors[0].code); | ||
| } |
There was a problem hiding this comment.
Guard against empty errors array in isCaptchaError
e.errors[0] can throw when the array is empty. A safer check avoids the out-of-bounds access and makes the intent clearer.
-export function isCaptchaError(e: ClerkAPIResponseError): boolean {
- return ['captcha_invalid', 'captcha_not_enabled', 'captcha_missing_token'].includes(e.errors[0].code);
-}
+export function isCaptchaError(e: ClerkAPIResponseError): boolean {
+ return (
+ e.errors?.some(err =>
+ ['captcha_invalid', 'captcha_not_enabled', 'captcha_missing_token'].includes(err.code),
+ ) ?? false
+ );
+}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| export function isCaptchaError(e: ClerkAPIResponseError): boolean { | |
| return ['captcha_invalid', 'captcha_not_enabled', 'captcha_missing_token'].includes(e.errors[0].code); | |
| } | |
| export function isCaptchaError(e: ClerkAPIResponseError): boolean { | |
| return ( | |
| e.errors?.some(err => | |
| ['captcha_invalid', 'captcha_not_enabled', 'captcha_missing_token'].includes(err.code), | |
| ) ?? false | |
| ); | |
| } |
🤖 Prompt for AI Agents
In packages/shared/src/error.ts around lines 25 to 27, the function
isCaptchaError accesses e.errors[0] without checking if the errors array is
empty, which can cause an out-of-bounds error. Fix this by first verifying that
e.errors exists and has at least one element before accessing e.errors[0].code,
ensuring the function safely handles empty or undefined errors arrays.
Comment on lines
44
to
47
| export function isNetworkError(e: any): boolean { | ||
| // TODO: revise during error handling epic | ||
| const message = (`${e.message}${e.name}` || '').toLowerCase().replace(/\s+/g, ''); | ||
| return message.includes('networkerror'); |
There was a problem hiding this comment.
🛠️ Refactor suggestion
isNetworkError crashes when e is null/undefined
Dereferencing e.message or e.name without optional chaining throws. Use null-safe access so the helper never surfaces its own exception.
-const message = (`${e.message}${e.name}` || '').toLowerCase().replace(/\s+/g, '');
+const message = (`${e?.message ?? ''}${e?.name ?? ''}`)
+ .toLowerCase()
+ .replace(/\s+/g, '');📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| export function isNetworkError(e: any): boolean { | |
| // TODO: revise during error handling epic | |
| const message = (`${e.message}${e.name}` || '').toLowerCase().replace(/\s+/g, ''); | |
| return message.includes('networkerror'); | |
| export function isNetworkError(e: any): boolean { | |
| // TODO: revise during error handling epic | |
| - const message = (`${e.message}${e.name}` || '').toLowerCase().replace(/\s+/g, ''); | |
| + const message = (`${e?.message ?? ''}${e?.name ?? ''}`) | |
| + .toLowerCase() | |
| + .replace(/\s+/g, ''); | |
| return message.includes('networkerror'); | |
| } |
🤖 Prompt for AI Agents
In packages/shared/src/error.ts around lines 44 to 47, the isNetworkError
function crashes when the input e is null or undefined because it directly
accesses e.message and e.name. To fix this, use optional chaining (e?.message
and e?.name) to safely access these properties without throwing, ensuring the
function never throws its own exception.
Comment on lines
131
to
142
| export function isUserLockedError(err: any) { | ||
| return isClerkAPIResponseError(err) && err.errors?.[0]?.code === 'user_locked'; | ||
| } | ||
|
|
||
| /** | ||
| * Checks if the provided error is a clerk api response error indicating a password was pwned. | ||
| * | ||
| * @internal | ||
| */ | ||
| export function isPasswordPwnedError(err: any) { | ||
| return isClerkAPIResponseError(err) && err.errors?.[0]?.code === 'form_password_pwned'; | ||
| } |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Use .some for clarity & safety in error-code helpers
Both isUserLockedError and isPasswordPwnedError assume at least one element in errors. A concise .some avoids undefined accesses and communicates intent.
-export function isUserLockedError(err: any) {
- return isClerkAPIResponseError(err) && err.errors?.[0]?.code === 'user_locked';
-}
+export function isUserLockedError(err: unknown): boolean {
+ return (
+ isClerkAPIResponseError(err) &&
+ err.errors?.some(e => e.code === 'user_locked') === true
+ );
+}
-export function isPasswordPwnedError(err: any) {
- return isClerkAPIResponseError(err) && err.errors?.[0]?.code === 'form_password_pwned';
-}
+export function isPasswordPwnedError(err: unknown): boolean {
+ return (
+ isClerkAPIResponseError(err) &&
+ err.errors?.some(e => e.code === 'form_password_pwned') === true
+ );
+}This also switches the param type to unknown, nudging consumers to perform their own narrowing.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| export function isUserLockedError(err: any) { | |
| return isClerkAPIResponseError(err) && err.errors?.[0]?.code === 'user_locked'; | |
| } | |
| /** | |
| * Checks if the provided error is a clerk api response error indicating a password was pwned. | |
| * | |
| * @internal | |
| */ | |
| export function isPasswordPwnedError(err: any) { | |
| return isClerkAPIResponseError(err) && err.errors?.[0]?.code === 'form_password_pwned'; | |
| } | |
| export function isUserLockedError(err: unknown): boolean { | |
| return ( | |
| isClerkAPIResponseError(err) && | |
| err.errors?.some(e => e.code === 'user_locked') === true | |
| ); | |
| } | |
| /** | |
| * Checks if the provided error is a clerk api response error indicating a password was pwned. | |
| * | |
| * @internal | |
| */ | |
| export function isPasswordPwnedError(err: unknown): boolean { | |
| return ( | |
| isClerkAPIResponseError(err) && | |
| err.errors?.some(e => e.code === 'form_password_pwned') === true | |
| ); | |
| } |
🤖 Prompt for AI Agents
In packages/shared/src/error.ts around lines 131 to 142, the functions
isUserLockedError and isPasswordPwnedError currently access the first element of
the errors array directly, which can cause issues if the array is empty or
undefined. Refactor these functions to use the .some method on the errors array
to check if any error object has the matching code, improving safety and
clarity. Also, change the parameter type from any to unknown to encourage proper
type narrowing by consumers.
anagstef
approved these changes
Jul 16, 2025
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.
Description
Marking them with
@internalprevens typedocs from being generated.Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit