feat(clerk-js): Add reset method to Sign[In|Up] resource

.changeset/add-signin-reset.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Add `reset` method to the sign-in resource.

.changeset/cozy-webs-matter.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Add `reset` method to the new signUp resource.

packages/clerk-js/src/core/resources/Client.ts

@@ -9,6 +9,7 @@ import type {
 } from '@clerk/shared/types';
 
 import { unixEpochToDate } from '../../utils/date';
+import { eventBus } from '../events';
 import { SessionTokenCache } from '../tokenCache';
 import { BaseResource, Session, SignIn, SignUp } from './internal';
 
@@ -93,6 +94,18 @@ export class Client extends BaseResource implements ClientResource {
     });
   }
 
+  resetSignIn(): void {
+    this.signIn = new SignIn(null);
+    // Cast needed because this.signIn is typed as SignInResource (interface), not SignIn (class extending BaseResource)
+    eventBus.emit('resource:error', { resource: this.signIn as SignIn, error: null });
+  }
+
+  resetSignUp(): void {
+    this.signUp = new SignUp(null);
+    // Cast needed because this.signUp is typed as SignUpResource (interface), not SignUp (class extending BaseResource)
+    eventBus.emit('resource:error', { resource: this.signUp as SignUp, error: null });
+  }
+
   clearCache(): void {
     return this.sessions.forEach(s => s.clearCache());
   }

packages/clerk-js/src/core/resources/SignIn.ts

@@ -650,7 +650,7 @@ class SignInFuture implements SignInFutureResource {
     verifyBackupCode: this.verifyBackupCode.bind(this),
   };
 
-  #hasBeenFinalized = false;
+  #canBeDiscarded = false;
   readonly #resource: SignIn;
 
   constructor(resource: SignIn) {
@@ -710,8 +710,8 @@ class SignInFuture implements SignInFutureResource {
     return this.#resource.secondFactorVerification;
   }
 
-  get hasBeenFinalized() {
-    return this.#hasBeenFinalized;
+  get canBeDiscarded() {
+    return this.#canBeDiscarded;
   }
 
   async sendResetPasswordEmailCode(): Promise<{ error: ClerkError | null }> {
@@ -1242,11 +1242,25 @@ class SignInFuture implements SignInFutureResource {
         await SignIn.clerk.client.reload();
       }
 
-      this.#hasBeenFinalized = true;
+      this.#canBeDiscarded = true;
       await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
     });
   }
 
+  /**
+   * Resets the current sign-in attempt by clearing all local state back to null.
+   * Unlike other methods, this does NOT emit resource:fetch with 'fetching' status,
+   * allowing for smooth UI transitions without loading states.
+   */
+  reset(): Promise<{ error: ClerkError | null }> {
+    if (!SignIn.clerk.client) {
+      throw new Error('Cannot reset sign-in without a client.');
+    }
+    this.#canBeDiscarded = true;
+    SignIn.clerk.client.resetSignIn();
+    return Promise.resolve({ error: null });
+  }
+
   private selectFirstFactor(
     params: Extract<SelectFirstFactorParams, { strategy: 'email_code' }>,
   ): EmailCodeFactor | null;

packages/clerk-js/src/core/resources/SignUp.ts

@@ -596,7 +596,7 @@ class SignUpFuture implements SignUpFutureResource {
     verifyPhoneCode: this.verifyPhoneCode.bind(this),
   };
 
-  #hasBeenFinalized = false;
+  #canBeDiscarded = false;
   readonly #resource: SignUp;
 
   constructor(resource: SignUp) {
@@ -701,8 +701,8 @@ class SignUpFuture implements SignUpFutureResource {
     return undefined;
   }
 
-  get hasBeenFinalized() {
-    return this.#hasBeenFinalized;
+  get canBeDiscarded() {
+    return this.#canBeDiscarded;
   }
 
   private async getCaptchaToken(): Promise<{
@@ -971,10 +971,24 @@ class SignUpFuture implements SignUpFutureResource {
         throw new Error('Cannot finalize sign-up without a created session.');
       }
 
-      this.#hasBeenFinalized = true;
+      this.#canBeDiscarded = true;
       await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
     });
   }
+
+  /**
+   * Resets the current sign-up attempt by clearing all local state back to null.
+   * Unlike other methods, this does NOT emit resource:fetch with 'fetching' status,
+   * allowing for smooth UI transitions without loading states.
+   */
+  reset(): Promise<{ error: ClerkError | null }> {
+    if (!SignUp.clerk.client) {
+      throw new Error('Cannot reset sign-up without a client.');
+    }
+    this.#canBeDiscarded = true;
+    SignUp.clerk.client.resetSignUp();
+    return Promise.resolve({ error: null });
+  }
 }
 
 class SignUpEnterpriseConnection extends BaseResource implements SignUpEnterpriseConnectionResource {

packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts

@@ -1,5 +1,7 @@
-import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { eventBus } from '../../events';
+import { signInErrorSignal, signInResourceSignal } from '../../signals';
 import { BaseResource } from '../internal';
 import { SignIn } from '../SignIn';
 
@@ -1890,5 +1892,117 @@ describe('SignIn', () => {
         await expect(signIn.__internal_future.finalize()).rejects.toThrow();
       });
     });
+
+    describe('reset', () => {
+      let mockClient: { signIn: SignIn; resetSignIn: ReturnType<typeof vi.fn> };
+
+      beforeEach(() => {
+        // Set up mock client with resetSignIn method that simulates what the real
+        // Client.resetSignIn does: creates a new SignIn, updates signals via events,
+        // and the State class responds by updating the actual signal values
+        mockClient = {
+          signIn: new SignIn(null),
+          resetSignIn: vi.fn().mockImplementation(function (this: typeof mockClient) {
+            const newSignIn = new SignIn(null);
+            this.signIn = newSignIn;
+            // Emit events like the real implementation
+            eventBus.emit('resource:error', { resource: newSignIn, error: null });
+            // Also update signals directly since State isn't set up in tests
+            signInResourceSignal({ resource: newSignIn });
+            signInErrorSignal({ error: null });
+          }),
+        };
+        SignIn.clerk = {
+          client: mockClient,
+        } as any;
+      });
+
+      afterEach(() => {
+        vi.clearAllMocks();
+        vi.restoreAllMocks();
+        // Reset signals to initial state
+        signInResourceSignal({ resource: null });
+        signInErrorSignal({ error: null });
+      });
+
+      it('does NOT emit resource:fetch with status fetching', async () => {
+        const emitSpy = vi.spyOn(eventBus, 'emit');
+        const mockFetch = vi.fn();
+        BaseResource._fetch = mockFetch;
+
+        const signIn = new SignIn({ id: 'signin_123', status: 'needs_first_factor' } as any);
+        await signIn.__internal_future.reset();
+
+        // Verify that resource:fetch was NOT called with status: 'fetching'
+        const fetchingCalls = emitSpy.mock.calls.filter(
+          call => call[0] === 'resource:fetch' && call[1]?.status === 'fetching',
+        );
+        expect(fetchingCalls).toHaveLength(0);
+        // Verify no API calls were made
+        expect(mockFetch).not.toHaveBeenCalled();
+      });
+
+      it('clears any previous errors by updating signInErrorSignal', async () => {
+        // Set an initial error
+        signInErrorSignal({ error: new Error('Previous error') });
+        expect(signInErrorSignal().error).toBeTruthy();
+
+        const signIn = new SignIn({ id: 'signin_123', status: 'needs_first_factor' } as any);
+        await signIn.__internal_future.reset();
+
+        // Verify that error signal was cleared
+        expect(signInErrorSignal().error).toBeNull();
+      });
+
+      it('returns error: null on success', async () => {
+        const signIn = new SignIn({ id: 'signin_123', status: 'needs_first_factor' } as any);
+        const result = await signIn.__internal_future.reset();
+
+        expect(result).toHaveProperty('error', null);
+      });
+
+      it('resets an existing signin with data to a fresh null state', async () => {
+        const signIn = new SignIn({
+          id: 'signin_123',
+          status: 'needs_first_factor',
+          identifier: 'user@example.com',
+        } as any);
+
+        // Verify initial state
+        expect(signIn.id).toBe('signin_123');
+        expect(signIn.status).toBe('needs_first_factor');
+        expect(signIn.identifier).toBe('user@example.com');
+
+        await signIn.__internal_future.reset();
+
+        // Verify that signInResourceSignal was updated with a new SignIn(null) instance
+        const updatedSignIn = signInResourceSignal().resource;
+        expect(updatedSignIn).toBeInstanceOf(SignIn);
+        expect(updatedSignIn?.id).toBeUndefined();
+        expect(updatedSignIn?.status).toBeNull();
+        expect(updatedSignIn?.identifier).toBeNull();
+      });
+
+      it('updates clerk.client.signIn with the fresh null instance', async () => {
+        const originalSignIn = new SignIn({
+          id: 'signin_123',
+          status: 'needs_first_factor',
+          identifier: 'user@example.com',
+        } as any);
+        mockClient.signIn = originalSignIn;
+
+        // Verify initial state
+        expect(mockClient.signIn.id).toBe('signin_123');
+        expect(mockClient.signIn.status).toBe('needs_first_factor');
+
+        await originalSignIn.__internal_future.reset();
+
+        // Verify that clerk.client.signIn was updated with a new SignIn(null) instance
+        expect(mockClient.signIn).toBeInstanceOf(SignIn);
+        expect(mockClient.signIn.id).toBeUndefined();
+        expect(mockClient.signIn.status).toBeNull();
+        expect(mockClient.signIn.identifier).toBeNull();
+      });
+    });
   });
 });

packages/clerk-js/src/core/resources/__tests__/SignUp.test.ts

@@ -1,5 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { eventBus } from '../../events';
+import { signUpErrorSignal, signUpResourceSignal } from '../../signals';
 import { BaseResource } from '../internal';
 import { SignUp } from '../SignUp';
 
@@ -701,5 +703,124 @@ describe('SignUp', () => {
         expect(result.error).toBeInstanceOf(Error);
       });
     });
+
+    describe('reset', () => {
+      let mockClient: { signUp: SignUp; resetSignUp: ReturnType<typeof vi.fn> };
+
+      beforeEach(() => {
+        // Set up mock client with resetSignUp method that simulates what the real
+        // Client.resetSignUp does: creates a new SignUp, updates signals via events,
+        // and the State class responds by updating the actual signal values
+        mockClient = {
+          signUp: new SignUp(null),
+          resetSignUp: vi.fn().mockImplementation(function (this: typeof mockClient) {
+            const newSignUp = new SignUp(null);
+            this.signUp = newSignUp;
+            // Emit events like the real implementation
+            eventBus.emit('resource:error', { resource: newSignUp, error: null });
+            // Also update signals directly since State isn't set up in tests
+            signUpResourceSignal({ resource: newSignUp });
+            signUpErrorSignal({ error: null });
+          }),
+        };
+        SignUp.clerk = {
+          client: mockClient,
+        } as any;
+      });
+
+      afterEach(() => {
+        vi.clearAllMocks();
+        vi.restoreAllMocks();
+        // Reset signals to initial state
+        signUpResourceSignal({ resource: null });
+        signUpErrorSignal({ error: null });
+      });
+
+      it('does NOT emit resource:fetch with status fetching', async () => {
+        const emitSpy = vi.spyOn(eventBus, 'emit');
+        const mockFetch = vi.fn();
+        BaseResource._fetch = mockFetch;
+
+        const signUp = new SignUp({ id: 'signup_123', status: 'missing_requirements' } as any);
+        await signUp.__internal_future.reset();
+
+        // Verify that resource:fetch was NOT called with status: 'fetching'
+        const fetchingCalls = emitSpy.mock.calls.filter(
+          call => call[0] === 'resource:fetch' && call[1]?.status === 'fetching',
+        );
+        expect(fetchingCalls).toHaveLength(0);
+        // Verify no API calls were made
+        expect(mockFetch).not.toHaveBeenCalled();
+      });
+
+      it('clears any previous errors by updating signUpErrorSignal', async () => {
+        // Set an initial error
+        signUpErrorSignal({ error: new Error('Previous error') });
+        expect(signUpErrorSignal().error).toBeTruthy();
+
+        const signUp = new SignUp({ id: 'signup_123', status: 'missing_requirements' } as any);
+        await signUp.__internal_future.reset();
+
+        // Verify that error signal was cleared
+        expect(signUpErrorSignal().error).toBeNull();
+      });
+
+      it('returns error: null on success', async () => {
+        const signUp = new SignUp({ id: 'signup_123', status: 'missing_requirements' } as any);
+        const result = await signUp.__internal_future.reset();
+
+        expect(result).toHaveProperty('error', null);
+      });
+
+      it('resets an existing signup with data to a fresh null state', async () => {
+        const signUp = new SignUp({
+          id: 'signup_123',
+          status: 'missing_requirements',
+          email_address: 'user@example.com',
+          first_name: 'John',
+        } as any);
+
+        // Verify initial state
+        expect(signUp.id).toBe('signup_123');
+        expect(signUp.emailAddress).toBe('user@example.com');
+        expect(signUp.firstName).toBe('John');
+
+        await signUp.__internal_future.reset();
+
+        // Verify that signUpResourceSignal was updated with a new SignUp(null) instance
+        const updatedSignUp = signUpResourceSignal().resource;
+        expect(updatedSignUp).toBeInstanceOf(SignUp);
+        expect(updatedSignUp?.id).toBeUndefined();
+        expect(updatedSignUp?.status).toBeNull();
+        expect(updatedSignUp?.emailAddress).toBeNull();
+        expect(updatedSignUp?.firstName).toBeNull();
+        expect(updatedSignUp?.lastName).toBeNull();
+        expect(updatedSignUp?.phoneNumber).toBeNull();
+      });
+
+      it('updates clerk.client.signUp with the fresh null instance', async () => {
+        const originalSignUp = new SignUp({
+          id: 'signup_123',
+          status: 'missing_requirements',
+          email_address: 'user@example.com',
+          first_name: 'John',
+        } as any);
+        mockClient.signUp = originalSignUp;
+
+        // Verify initial state
+        expect(mockClient.signUp.id).toBe('signup_123');
+        expect(mockClient.signUp.status).toBe('missing_requirements');
+        expect(mockClient.signUp.emailAddress).toBe('user@example.com');
+
+        await originalSignUp.__internal_future.reset();
+
+        // Verify that clerk.client.signUp was updated with a new SignUp(null) instance
+        expect(mockClient.signUp).toBeInstanceOf(SignUp);
+        expect(mockClient.signUp.id).toBeUndefined();
+        expect(mockClient.signUp.status).toBeNull();
+        expect(mockClient.signUp.emailAddress).toBeNull();
+        expect(mockClient.signUp.firstName).toBeNull();
+      });
+    });
   });
 });