Skip to content

feat(clerk-js): Type errors.global as ClerkGlobalHookError #7174

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 7, 2025
Merged

feat(clerk-js): Type errors.global as ClerkGlobalHookError #7174

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
784c38b
feat(react): Type `errors.global` as `ClerkGlobalHookError`
nikosdouvlis Nov 7, 2025
1f6771e
Merge branch 'main' into nikos/userland-errors-p5
dstaley Nov 7, 2025
25126a6
fix(clerk-js,shared): Replace unknown with ClerkError (#7177)
dstaley Nov 7, 2025
59df41c
chore(repo): Add changeset
dstaley Nov 7, 2025
ccb61e3
chore(shared): lint imports
dstaley Nov 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/moody-parks-scream.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'@clerk/clerk-js': minor
'@clerk/shared': minor
---

[Experimental] Add types for errors used in new custom flow APIs
3 changes: 2 additions & 1 deletion packages/clerk-js/src/core/events.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import type { ClerkError } from '@clerk/shared/error';
import { createEventBus } from '@clerk/shared/eventBus';
import type { TokenResource } from '@clerk/shared/types';

Expand All @@ -15,7 +16,7 @@ export const events = {

type TokenUpdatePayload = { token: TokenResource | null };
export type ResourceUpdatePayload = { resource: BaseResource };
export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
export type ResourceErrorPayload = { resource: BaseResource; error: ClerkError | null };
export type ResourceFetchPayload = { resource: BaseResource; status: 'idle' | 'fetching' };

type InternalEvents = {
Expand Down
51 changes: 27 additions & 24 deletions packages/clerk-js/src/core/signals.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { isClerkAPIResponseError } from '@clerk/shared/error';
import { type ClerkError, createClerkGlobalHookError, isClerkAPIResponseError } from '@clerk/shared/error';
import type { Errors, SignInSignal, SignUpSignal } from '@clerk/shared/types';
import { snakeToCamel } from '@clerk/shared/underscore';
import { computed, signal } from 'alien-signals';
Expand All @@ -7,7 +7,7 @@ import type { SignIn } from './resources/SignIn';
import type { SignUp } from './resources/SignUp';

export const signInResourceSignal = signal<{ resource: SignIn | null }>({ resource: null });
export const signInErrorSignal = signal<{ error: unknown }>({ error: null });
export const signInErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
export const signInFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });

export const signInComputedSignal: SignInSignal = computed(() => {
Expand All @@ -21,7 +21,7 @@ export const signInComputedSignal: SignInSignal = computed(() => {
});

export const signUpResourceSignal = signal<{ resource: SignUp | null }>({ resource: null });
export const signUpErrorSignal = signal<{ error: unknown }>({ error: null });
export const signUpErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
export const signUpFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });

export const signUpComputedSignal: SignUpSignal = computed(() => {
Expand All @@ -38,7 +38,7 @@ export const signUpComputedSignal: SignUpSignal = computed(() => {
* Converts an error to a parsed errors object that reports the specific fields that the error pertains to. Will put
* generic non-API errors into the global array.
*/
function errorsToParsedErrors(error: unknown): Errors {
function errorsToParsedErrors(error: ClerkError | null): Errors {
const parsedErrors: Errors = {
fields: {
firstName: null,
Expand All @@ -62,29 +62,32 @@ function errorsToParsedErrors(error: unknown): Errors {

if (!isClerkAPIResponseError(error)) {
parsedErrors.raw = [error];
parsedErrors.global = [error];
parsedErrors.global = [createClerkGlobalHookError(error)];
return parsedErrors;
}

error.errors.forEach(error => {
if (parsedErrors.raw) {
parsedErrors.raw.push(error);
} else {
parsedErrors.raw = [error];
}

if ('meta' in error && error.meta && 'paramName' in error.meta) {
const name = snakeToCamel(error.meta.paramName);
parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
return;
}

if (parsedErrors.global) {
parsedErrors.global.push(error);
} else {
parsedErrors.global = [error];
}
});
const hasFieldErrors = error.errors.some(error => 'meta' in error && error.meta && 'paramName' in error.meta);
if (hasFieldErrors) {
error.errors.forEach(error => {
if (parsedErrors.raw) {
parsedErrors.raw.push(error);
} else {
parsedErrors.raw = [error];
}
if ('meta' in error && error.meta && 'paramName' in error.meta) {
const name = snakeToCamel(error.meta.paramName);
parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
}
// Note that this assumes a given ClerkAPIResponseError will only have either field errors or global errors, but
// not both. If a global error is present, it will be discarded.
});

return parsedErrors;
}

// At this point, we know that `error` is a ClerkAPIResponseError and that it has no field errors.
parsedErrors.raw = [error];
parsedErrors.global = [createClerkGlobalHookError(error)];

Comment on lines +88 to 91
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Restore the raw API errors array

Errors.raw is documented (packages/shared/src/types/state.ts Line 74) as “The raw, unparsed errors from the Clerk API.” Storing the aggregate ClerkAPIResponseError here drops the per-error payload consumers rely on. Keep raw as the API error list.

Apply this diff to preserve the original payload:

-  parsedErrors.raw = [error];
+  parsedErrors.raw = [...error.errors];
   parsedErrors.global = [createClerkGlobalHookError(error)];
🤖 Prompt for AI Agents 
In packages/clerk-js/src/core/signals.ts around lines 88 to 91, parsedErrors.raw
is being set to the aggregate ClerkAPIResponseError object instead of the
original per-error payload; change the assignment to preserve the API error list
by setting parsedErrors.raw to the error.errors array (or an empty array
fallback if needed) so consumers receive the raw, unparsed error entries, while
keeping parsedErrors.global as createClerkGlobalHookError(error).

return parsedErrors;
}
3 changes: 2 additions & 1 deletion packages/clerk-js/src/core/state.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import type { ClerkError } from '@clerk/shared/error';
import type { State as StateInterface } from '@clerk/shared/types';
import { computed, effect } from 'alien-signals';

Expand Down Expand Up @@ -36,7 +37,7 @@ export class State implements StateInterface {
eventBus.on('resource:fetch', this.onResourceFetch);
}

private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
private onResourceError = (payload: { resource: BaseResource; error: ClerkError | null }) => {
if (payload.resource instanceof SignIn) {
this.signInErrorSignal({ error: payload.error });
}
Expand Down
3 changes: 3 additions & 0 deletions packages/shared/src/error.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ export { errorToJSON, parseError, parseErrors } from './errors/parseError';

export { ClerkAPIError } from './errors/clerkApiError';
export { ClerkAPIResponseError } from './errors/clerkApiResponseError';
export { ClerkError } from './errors/clerkError';

export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower';

Expand All @@ -27,3 +28,5 @@ export {
isUnauthorizedError,
isUserLockedError,
} from './errors/helpers';

export { createClerkGlobalHookError } from './errors/globalHookError';
14 changes: 5 additions & 9 deletions packages/shared/src/errors/clerkApiError.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,7 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
readonly meta: Meta;

constructor(json: ClerkAPIErrorJSON) {
const parsedError = this.parseJsonError(json);
this.code = parsedError.code;
this.message = parsedError.message;
this.longMessage = parsedError.longMessage;
this.meta = parsedError.meta;
}

private parseJsonError(json: ClerkAPIErrorJSON) {
return {
const parsedError = {
code: json.code,
message: json.message,
longMessage: json.long_message,
Expand All @@ -36,6 +28,10 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
} as unknown as Meta,
};
this.code = parsedError.code;
this.message = parsedError.message;
this.longMessage = parsedError.longMessage;
this.meta = parsedError.meta;
}
}

Expand Down
23 changes: 23 additions & 0 deletions packages/shared/src/errors/globalHookError.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
import { isClerkApiResponseError } from './clerkApiResponseError';
import type { ClerkError } from './clerkError';
import { isClerkRuntimeError } from './clerkRuntimeError';

/**
* Creates a ClerkGlobalHookError object from a ClerkError instance.
* It's a wrapper for all the different instances of Clerk errors that can
* be returned when using Clerk hooks.
*/
export function createClerkGlobalHookError(error: ClerkError) {
const predicates = {
isClerkApiResponseError,
isClerkRuntimeError,
} as const;

for (const [name, fn] of Object.entries(predicates)) {
Object.assign(error, { [name]: fn });
}

return error as ClerkError & typeof predicates;
}
Comment on lines +10 to +21
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Clarify predicate binding and avoid mutating the input parameter.

The function mutates the input error object by attaching predicates to it, which violates immutability principles. More critically, the attached predicates (isClerkApiResponseError, isClerkRuntimeError) are likely type guards that expect an error parameter (e.g., (error: unknown) => error is ClerkApiResponseError). Attaching them unbound creates a confusing API where consumers would need to call error.isClerkApiResponseError(error), which is redundant.

If the intent is to provide predicate methods that check the error itself, bind them by wrapping in closures:

 export function createClerkGlobalHookError(error: ClerkError) {
   const predicates = {
-    isClerkApiResponseError,
-    isClerkRuntimeError,
+    isClerkApiResponseError: () => isClerkApiResponseError(error),
+    isClerkRuntimeError: () => isClerkRuntimeError(error),
   } as const;
 
-  for (const [name, fn] of Object.entries(predicates)) {
-    Object.assign(error, { [name]: fn });
-  }
-
-  return error as ClerkError & typeof predicates;
+  return Object.assign({}, error, predicates) as ClerkError & typeof predicates;
 }

This eliminates mutation and provides a cleaner API where error.isClerkApiResponseError() checks the error itself.

Based on coding guidelines: "Prefer readonly properties for immutable data structures."

🤖 Prompt for AI Agents 
In packages/shared/src/errors/globalHookError.ts around lines 10 to 21, the
current implementation mutates the incoming error by assigning unbound predicate
functions to it; instead, return a new object that preserves the original error
properties (don’t mutate the input) and add readonly predicate methods that are
zero-argument closures which call the original type-guard predicates with the
original error value (e.g., () => isClerkApiResponseError(origError)); ensure
these added properties are non-writable/read-only (use Object.defineProperty or
equivalent) and return the result typed as ClerkError & typeof predicates so
consumers can call error.isClerkApiResponseError() without passing the error and
immutability is preserved.


export type ClerkGlobalHookError = ReturnType<typeof createClerkGlobalHookError>;
6 changes: 5 additions & 1 deletion packages/shared/src/types/state.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import type { ClerkGlobalHookError } from '../errors/globalHookError';
import type { SignInFutureResource } from './signInFuture';
import type { SignUpFutureResource } from './signUpFuture';

Expand Down Expand Up @@ -79,8 +80,9 @@ export interface Errors {
raw: unknown[] | null;
/**
* Parsed errors that are not related to any specific field.
* Does not include any errors that could be parsed as a field error
*/
global: unknown[] | null; // does not include any errors that could be parsed as a field error
global: ClerkGlobalHookError[] | null;
}

/**
Expand Down Expand Up @@ -143,6 +145,7 @@ export interface State {
* An alias for `effect()` from `alien-signals`, which can be used to subscribe to changes from Signals.
*
* @see https://github.com/stackblitz/alien-signals#usage
*
* @experimental This experimental API is subject to change.
*/
__internal_effect: (callback: () => void) => () => void;
Expand All @@ -152,6 +155,7 @@ export interface State {
* its dependencies change.
*
* @see https://github.com/stackblitz/alien-signals#usage
*
* @experimental This experimental API is subject to change.
*/
__internal_computed: <T>(getter: (previousValue?: T) => T) => () => T;
Expand Down