refactor(shared): Update exported error typeguard functions from error.ts, align error class naming #7490

kduprey · 2025-12-17T01:29:02Z

Description

Currently, in handleError() in clerk-js/src/ui/utils/errorHandler.ts the function runs through each type of predefined error type we have and handles the error from there. If the error is a ClerkRuntimeError, the intended handler is never reached due to type overlap between ClerkAPIResponseError and ClerkRuntimeError.

Both interfaces extend ClerkError which causes ClerkRuntimeError error types to be handled by handleClerkApiError versus handleClerkRuntimeError given the order of the logic gates.

We have recently added createErrorTypeGuard() to properly check the error type against the provided interface, and utility functions were added to each error definition file (e.g. clerkRuntimeError.ts). We do have pre-existing functions in shared/src/errors/helpers.ts however, they are not using the new type guard check functions provided from each error definition file.

This removes the old/faulty error type checks from helpers.ts in favour of the new type guard functions, updates the exported functions in shared/src/error.ts, and also aligns the naming pattern for isClerkApiResponseError and isClerkAPIResponseError.

USER-4239

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

Refactor
- Improved consistency in error handling functions and type guards
- Enhanced error metadata support for API errors

_{✏️ Tip: You can customize this high-level summary in your review settings.}

…r.ts, align error class naming Signed-off-by: Kenton Duprey <[email protected]>

changeset-bot · 2025-12-17T01:29:06Z

🦋 Changeset detected

Latest commit: 6741930

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

This PR includes changesets to release 22 packages

Name	Type
@clerk/shared	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/clerk-expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/clerk-react	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/themes	Patch
@clerk/types	Patch
@clerk/vue	Patch
@clerk/localizations	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

vercel · 2025-12-17T01:29:07Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Dec 18, 2025 0:29am

coderabbitai · 2025-12-17T01:29:08Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

This pull request refactors Clerk's error handling infrastructure by consolidating duplicate type guard implementations and aligning naming conventions. Type guards previously defined in helpers.ts are removed and replaced with imports from their respective error modules. Additionally, inconsistent "ClerkApi" naming patterns are standardized to "ClerkAPI" across type guards and class definitions.

Changes

Cohort / File(s)	Summary
Changeset metadata `.changeset/sweet-singers-beg.md`	Adds changeset entry documenting patch version bump for `@clerk/shared` with description of internal error handling refactor.
Type guard consolidation and import updates `packages/shared/src/errors/helpers.ts`, `packages/shared/src/errors/globalHookError.ts`	Removes duplicate implementations of `isClerkAPIResponseError` and `isClerkRuntimeError` from helpers.ts; updates globalHookError.ts to import `isClerkAPIResponseError` from its source module instead of helpers.
Naming alignment for error classes and guards `packages/shared/src/errors/clerkApiError.ts`, `packages/shared/src/errors/clerkApiResponseError.ts`	Renames `ClerkApiErrorMeta` to `ClerkAPIErrorMeta` and `isClerkApiError` to `isClerkAPIError` in clerkApiError.ts; renames `isClerkApiResponseError` to `isClerkAPIResponseError` in clerkApiResponseError.ts. ClerkAPIError class now includes `readonly meta` property and constructor for JSON parsing.
Public API re-export updates `packages/shared/src/error.ts`	Adds re-exports of type guards `isClerkAPIError`, `isClerkAPIResponseError`, `isClerkError`, and `isClerkRuntimeError` directly from their respective modules; removes re-exports of `isClerkAPIResponseError` and `isClerkRuntimeError` from helpers aggregated export.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Areas requiring attention:
- packages/shared/src/error.ts: Verify that public API re-export structure is correct and doesn't create naming conflicts or unintended duplicate exports.
- packages/shared/src/errors/clerkApiError.ts: Validate the new constructor logic for JSON metadata parsing and ensure the meta property correctly reflects the type parameter.
- Cross-file consistency: Confirm that all imports of renamed type guards throughout the codebase (especially isClerkAPIError and isClerkAPIResponseError) are properly updated.

Poem

🐰 Errors once tangled in helper's nest,
Now each guard stands its own test.
API names polished with care,
Type safety shines everywhere!
No more confusion, the path is clear—
Robust error handling draws near. ✨

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately describes the main refactoring changes: updating exported error typeguard functions and aligning error class naming conventions in the shared package.
Linked Issues check	✅ Passed	All coding requirements from USER-4239 are met: old faulty error checks removed from helpers.ts, new per-error type guard functions integrated, exported functions updated in error.ts, and naming conventions aligned for isClerkAPIResponseError consistency.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to USER-4239 objectives: updating error type guards, aligning naming conventions, and fixing type overlap issues. No extraneous modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Signed-off-by: Kenton Duprey <[email protected]>

pkg-pr-new · 2025-12-17T01:35:12Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7490

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7490

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7490

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7490

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7490

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7490

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@7490

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@7490

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7490

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7490

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7490

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7490

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7490

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7490

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@7490

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7490

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@7490

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7490

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7490

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7490

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@7490

@clerk/types

npm i https://pkg.pr.new/@clerk/types@7490

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7490

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7490

commit: 6741930

kduprey · 2025-12-17T02:32:52Z

@coderabbitai review

coderabbitai · 2025-12-17T02:32:58Z

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/shared/src/errors/clerkApiError.ts (1)
9-35: Review type safety in generic parameter and constructor.

Several type safety considerations:

Line 9: The generic parameter default is any, which bypasses TypeScript's type checking. Per coding guidelines, prefer unknown when the type is uncertain.

Line 29: The metadata parsing uses as unknown as Meta, which completely bypasses type safety. The parsed metadata structure may not actually match the expected Meta type.

Consider this safer approach:
-export class ClerkAPIError<Meta extends ClerkAPIErrorMeta = any> implements ClerkAPIErrorInterface {
+export class ClerkAPIError<Meta extends ClerkAPIErrorMeta = ClerkAPIErrorMeta> implements ClerkAPIErrorInterface {
   static kind = 'ClerkAPIError';
   readonly code: string;
   readonly message: string;
   readonly longMessage: string | undefined;
   readonly meta: Meta;

   constructor(json: ClerkAPIErrorJSON) {
     const parsedError = {
       code: json.code,
       message: json.message,
       longMessage: json.long_message,
       meta: {
         paramName: json.meta?.param_name,
         sessionId: json.meta?.session_id,
         emailAddresses: json.meta?.email_addresses,
         identifiers: json.meta?.identifiers,
         zxcvbn: json.meta?.zxcvbn,
         plan: json.meta?.plan,
         isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
-      } as unknown as Meta,
+      } as Meta,
     };
     this.code = parsedError.code;
     this.message = parsedError.message;
     this.longMessage = parsedError.longMessage;
     this.meta = parsedError.meta;
   }
 }
This approach:

Uses ClerkAPIErrorMeta as the default instead of any

Removes the double assertion (as unknown as Meta)

Still allows flexibility for specific metadata types through the generic parameter

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 54cd476 and d948e0d.

📒 Files selected for processing (6)

.changeset/sweet-singers-beg.md (1 hunks)
packages/shared/src/error.ts (1 hunks)
packages/shared/src/errors/clerkApiError.ts (2 hunks)
packages/shared/src/errors/clerkApiResponseError.ts (1 hunks)
packages/shared/src/errors/globalHookError.ts (2 hunks)
packages/shared/src/errors/helpers.ts (1 hunks)

🧰 Additional context used

📓 Path-based instructions (9)

**/*.{js,jsx,ts,tsx}