refactor(clerk-js): Consolidate resource events into single resource:state-change event

Author: bratsos

.changeset/fiery-games-pick.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Fix inconsistent `fetchStatus` during sign-in and sign-up flows where the resource would briefly show as `complete` while `fetchStatus` was still `fetching`

packages/clerk-js/src/core/__tests__/state.test.ts

@@ -3,9 +3,74 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { eventBus } from '../events';
 import { SignIn } from '../resources/SignIn';
 import { SignUp } from '../resources/SignUp';
-import { signInResourceSignal, signUpResourceSignal } from '../signals';
+import { signInFetchSignal, signInResourceSignal, signUpResourceSignal } from '../signals';
 import { State } from '../state';
 
+describe('Signal batching', () => {
+  let state: State;
+
+  beforeEach(() => {
+    signInResourceSignal({ resource: null });
+    signInFetchSignal({ status: 'idle' });
+    state = new State();
+  });
+
+  it('should produce at most 3 renders with clean fetchStatus transitions during an API call', async () => {
+    const signIn = new SignIn(null);
+    const snapshots: Array<{ fetchStatus: string; hasSignIn: boolean }> = [];
+
+    state.__internal_effect(() => {
+      const s = state.signInSignal();
+      snapshots.push({ fetchStatus: s.fetchStatus, hasSignIn: s.signIn !== null });
+    });
+
+    await signIn.__internal_future.password({ password: 'test123', identifier: 'test@example.com' }).catch(() => {
+      // Expected to fail since there's no real API
+    });
+
+    expect(snapshots.length).toBeLessThanOrEqual(3);
+
+    // fetchStatus follows a clean idle → fetching → idle progression
+    const transitions = snapshots.map(s => s.fetchStatus).filter((s, i, arr) => i === 0 || s !== arr[i - 1]);
+    expect(transitions).toEqual(['idle', 'fetching', 'idle']);
+  });
+
+  it('should skip resource-only updates while fetching and apply them on idle', () => {
+    const signIn = new SignIn({ id: 'signin_123', status: 'needs_identifier' } as any);
+
+    // Simulate fetchStatus: fetching (as runAsyncResourceTask would)
+    eventBus.emit('resource:state-change', { resource: signIn, error: null, fetchStatus: 'fetching' });
+    expect(signInFetchSignal().status).toBe('fetching');
+
+    // Simulate fromJSON updating the resource mid-flight (resource-only event)
+    eventBus.emit('resource:state-change', { resource: signIn });
+
+    // Resource signal should NOT have been updated — skipped while fetching
+    expect(signInResourceSignal().resource?.id).toBe('signin_123');
+
+    // Simulate task completion — resource is carried again with fetchStatus: idle
+    eventBus.emit('resource:state-change', { resource: signIn, error: null, fetchStatus: 'idle' });
+
+    // Now both resource and fetchStatus are consistent
+    expect(signInFetchSignal().status).toBe('idle');
+    expect(signInResourceSignal().resource).toBe(signIn);
+  });
+
+  it('should reflect new resource data immediately when no operation is in flight', () => {
+    let latestSignInId: string | undefined;
+
+    state.__internal_effect(() => {
+      latestSignInId = state.signInSignal().signIn?.id;
+    });
+
+    expect(latestSignInId).toBeUndefined();
+
+    new SignIn({ id: 'signin_123', status: 'needs_identifier' } as any);
+
+    expect(latestSignInId).toBe('signin_123');
+  });
+});
+
 describe('State', () => {
   let _state: State;
 
@@ -52,7 +117,7 @@ describe('State', () => {
         expect(existingSignUp.__internal_future.canBeDiscarded).toBe(false);
 
         // Act: Emit a resource update with a null SignUp (simulating client refresh with null sign_up)
-        const _nullSignUp = new SignUp(null);
+        new SignUp(null);
 
         // Assert: Signal should NOT be updated - should still have the existing SignUp
         expect(signUpResourceSignal().resource).toBe(existingSignUp);
@@ -96,11 +161,6 @@ describe('State', () => {
           resetSignUp: vi.fn().mockImplementation(function (this: typeof mockClient) {
             newSignUpFromReset = new SignUp(null);
             this.signUp = newSignUpFromReset;
-            // reset() emits resource:error to clear errors, but the signal update
-            // happens via resource:update when the new SignUp is created
-            eventBus.emit('resource:error', { resource: newSignUpFromReset, error: null });
-            // Emit resource:update to update the signal (simulating what happens in real flow)
-            eventBus.emit('resource:update', { resource: newSignUpFromReset });
           }),
         };
         SignUp.clerk = { client: mockClient } as any;
@@ -127,10 +187,10 @@ describe('State', () => {
 
       it('should allow resource update when new resource has an id (not a null update)', () => {
         // Arrange: Set up a SignUp with id
-        const _existingSignUp = new SignUp({ id: 'signup_123', status: 'missing_requirements' } as any);
+        new SignUp({ id: 'signup_123', status: 'missing_requirements' } as any);
         expect(signUpResourceSignal().resource?.id).toBe('signup_123');
 
-        // Act: Emit a resource update with a different SignUp that also has an id
+        // Act: Create a different SignUp that also has an id
         const newSignUp = new SignUp({ id: 'signup_456', status: 'complete' } as any);
 
         // Assert: Signal should be updated with the new SignUp
@@ -159,7 +219,7 @@ describe('State', () => {
         expect(existingSignIn.__internal_future.canBeDiscarded).toBe(false);
 
         // Act: Emit a resource update with a null SignIn (simulating client refresh with null sign_in)
-        const _nullSignIn = new SignIn(null);
+        new SignIn(null);
 
         // Assert: Signal should NOT be updated - should still have the existing SignIn
         expect(signInResourceSignal().resource).toBe(existingSignIn);
@@ -201,16 +261,13 @@ describe('State', () => {
           resetSignIn: vi.fn().mockImplementation(function (this: typeof mockClient) {
             newSignInFromReset = new SignIn(null);
             this.signIn = newSignInFromReset;
-            eventBus.emit('resource:error', { resource: newSignInFromReset, error: null });
-            eventBus.emit('resource:update', { resource: newSignInFromReset });
           }),
         };
         SignIn.clerk = { client: mockClient } as any;
 
         // Create a SignIn with id
         const existingSignIn = new SignIn({ id: 'signin_123', status: 'needs_identifier' } as any);
         expect(signInResourceSignal().resource?.id).toBe('signin_123');
-        expect(existingSignIn.__internal_future.canBeDiscarded).toBe(false);
 
         // Act: Call reset()
         await existingSignIn.__internal_future.reset();
@@ -224,10 +281,10 @@ describe('State', () => {
 
       it('should allow resource update when new resource has an id (not a null update)', () => {
         // Arrange: Set up a SignIn with id
-        const _existingSignIn = new SignIn({ id: 'signin_123', status: 'needs_identifier' } as any);
+        new SignIn({ id: 'signin_123', status: 'needs_identifier' } as any);
         expect(signInResourceSignal().resource?.id).toBe('signin_123');
 
-        // Act: Emit a resource update with a different SignIn that also has an id
+        // Act: Create a different SignIn that also has an id
         const newSignIn = new SignIn({ id: 'signin_456', status: 'complete' } as any);
 
         // Assert: Signal should be updated with the new SignIn
@@ -240,19 +297,19 @@ describe('State', () => {
   describe('Edge cases', () => {
     it('should handle rapid successive updates correctly', () => {
       // First update with valid SignUp
-      const _signUp1 = new SignUp({ id: 'signup_1', status: 'missing_requirements' } as any);
+      new SignUp({ id: 'signup_1', status: 'missing_requirements' } as any);
       expect(signUpResourceSignal().resource?.id).toBe('signup_1');
 
       // Second update with another valid SignUp
-      const _signUp2 = new SignUp({ id: 'signup_2', status: 'missing_requirements' } as any);
+      new SignUp({ id: 'signup_2', status: 'missing_requirements' } as any);
       expect(signUpResourceSignal().resource?.id).toBe('signup_2');
 
       // Null update should be ignored
-      const _nullSignUp = new SignUp(null);
+      new SignUp(null);
       expect(signUpResourceSignal().resource?.id).toBe('signup_2');
 
       // Another valid update should work
-      const _signUp3 = new SignUp({ id: 'signup_3', status: 'complete' } as any);
+      new SignUp({ id: 'signup_3', status: 'complete' } as any);
       expect(signUpResourceSignal().resource?.id).toBe('signup_3');
     });
 
@@ -262,10 +319,47 @@ describe('State', () => {
       expect(signUpResourceSignal().resource?.id).toBe('signup_123');
 
       // Manually emit update with the same instance (simulating fromJSON on same instance)
-      eventBus.emit('resource:update', { resource: signUp });
+      eventBus.emit('resource:state-change', { resource: signUp });
 
       // Signal should still have the same instance
       expect(signUpResourceSignal().resource).toBe(signUp);
     });
   });
+
+  describe('Client.destroy()', () => {
+    it('should update signals when resources are replaced with null instances', async () => {
+      const mockSetActive = vi.fn().mockResolvedValue({});
+      SignIn.clerk = { setActive: mockSetActive, client: { sessions: [{ id: 'session_123' }] } } as any;
+
+      const existingSignIn = new SignIn({
+        id: 'signin_123',
+        status: 'complete',
+        created_session_id: 'session_123',
+      } as any);
+      expect(signInResourceSignal().resource).toBe(existingSignIn);
+
+      await existingSignIn.__internal_future.finalize();
+      expect(existingSignIn.__internal_future.canBeDiscarded).toBe(true);
+
+      // Simulates what Client.destroy() does — creating a null resource replaces the existing one
+      const nullSignIn = new SignIn(null);
+
+      expect(signInResourceSignal().resource).toBe(nullSignIn);
+      expect(signInResourceSignal().resource?.id).toBeUndefined();
+    });
+  });
+
+  describe('fetchStatus clearing on reset', () => {
+    it('should clear fetchStatus to idle when resource is reset during an in-flight fetch', () => {
+      const signIn = new SignIn({ id: 'signin_123', status: 'needs_identifier' } as any);
+      eventBus.emit('resource:state-change', { resource: signIn, error: null, fetchStatus: 'fetching' });
+      expect(signInFetchSignal().status).toBe('fetching');
+
+      // Reset replaces the resource and clears fetchStatus in one event
+      const nullSignIn = new SignIn(null);
+      eventBus.emit('resource:state-change', { resource: nullSignIn, error: null, fetchStatus: 'idle' });
+
+      expect(signInFetchSignal().status).toBe('idle');
+    });
+  });
 });

packages/clerk-js/src/core/events.ts

@@ -9,24 +9,22 @@ export const events = {
   UserSignOut: 'user:signOut',
   EnvironmentUpdate: 'environment:update',
   SessionTokenResolved: 'session:tokenResolved',
-  ResourceUpdate: 'resource:update',
-  ResourceError: 'resource:error',
-  ResourceFetch: 'resource:fetch',
+  ResourceStateChange: 'resource:state-change',
 } as const;
 
 type TokenUpdatePayload = { token: TokenResource | null };
-export type ResourceUpdatePayload = { resource: BaseResource };
-export type ResourceErrorPayload = { resource: BaseResource; error: ClerkError | null };
-export type ResourceFetchPayload = { resource: BaseResource; status: 'idle' | 'fetching' };
+export type ResourceStateChangePayload = {
+  resource: BaseResource;
+  error?: ClerkError | null;
+  fetchStatus?: 'idle' | 'fetching';
+};
 
 type InternalEvents = {
   [events.TokenUpdate]: TokenUpdatePayload;
   [events.UserSignOut]: null;
   [events.EnvironmentUpdate]: null;
   [events.SessionTokenResolved]: null;
-  [events.ResourceUpdate]: ResourceUpdatePayload;
-  [events.ResourceError]: ResourceErrorPayload;
-  [events.ResourceFetch]: ResourceFetchPayload;
+  [events.ResourceStateChange]: ResourceStateChangePayload;
 };
 
 export const eventBus = createEventBus<InternalEvents>();

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

@@ -106,13 +106,13 @@ 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 });
+    eventBus.emit('resource:state-change', { resource: this.signIn as SignIn, error: null, fetchStatus: 'idle' });
   }
 
   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 });
+    eventBus.emit('resource:state-change', { resource: this.signUp as SignUp, error: null, fetchStatus: 'idle' });
   }
 
   clearCache(): void {

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

@@ -596,7 +596,7 @@ export class SignIn extends BaseResource implements SignInResource {
       this.clientTrustState = data.client_trust_state ?? undefined;
     }
 
-    eventBus.emit('resource:update', { resource: this });
+    eventBus.emit('resource:state-change', { resource: this });
     return this;
   }
 
@@ -1415,14 +1415,19 @@ class SignInFuture implements SignInFutureResource {
     return this.create({ ticket: ticket ?? undefined });
   }
 
+  /**
+   * Finalizes a completed sign-in by setting the active session.
+   * Like reset(), this does NOT set fetchStatus to 'fetching' — the sign-in
+   * is already complete, and setActive is a session-level operation.
+   */
   async finalize(params?: SignInFutureFinalizeParams): Promise<{ error: ClerkError | null }> {
     const { navigate } = params || {};
 
     if (!this.#resource.createdSessionId) {
       throw new Error('Cannot finalize sign-in without a created session.');
     }
 
-    return runAsyncResourceTask(this.#resource, async () => {
+    try {
       // Reload the client if the created session is not in the client's sessions. This can happen during modal SSO
       // flows where the in-memory client does not have the created session.
       if (SignIn.clerk.client && !SignIn.clerk.client.sessions.some(s => s.id === this.#resource.createdSessionId)) {
@@ -1431,12 +1436,15 @@ class SignInFuture implements SignInFutureResource {
 
       this.#canBeDiscarded = true;
       await SignIn.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
-    });
+      return { error: null };
+    } catch (err) {
+      return { error: err as ClerkError };
+    }
   }
 
   /**
    * 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,
+   * Unlike other methods, this does NOT set fetchStatus to 'fetching',
    * allowing for smooth UI transitions without loading states.
    */
   reset(): Promise<{ error: ClerkError | null }> {

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

@@ -510,7 +510,7 @@ export class SignUp extends BaseResource implements SignUpResource {
       this.locale = data.locale;
     }
 
-    eventBus.emit('resource:update', { resource: this });
+    eventBus.emit('resource:state-change', { resource: this });
     return this;
   }
 
@@ -1137,21 +1137,29 @@ class SignUpFuture implements SignUpFutureResource {
     return this.create({ ...params, ticket: ticket ?? undefined });
   }
 
+  /**
+   * Finalizes a completed sign-up by setting the active session.
+   * Like reset(), this does NOT set fetchStatus to 'fetching' — the sign-up
+   * is already complete, and setActive is a session-level operation.
+   */
   async finalize(params?: SignUpFutureFinalizeParams): Promise<{ error: ClerkError | null }> {
     const { navigate } = params || {};
-    return runAsyncResourceTask(this.#resource, async () => {
+
+    try {
       if (!this.#resource.createdSessionId) {
         throw new Error('Cannot finalize sign-up without a created session.');
       }
-
       this.#canBeDiscarded = true;
       await SignUp.clerk.setActive({ session: this.#resource.createdSessionId, navigate });
-    });
+      return { error: null };
+    } catch (err) {
+      return { error: err as ClerkError };
+    }
   }
 
   /**
    * 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,
+   * Unlike other methods, this does NOT set fetchStatus to 'fetching',
    * allowing for smooth UI transitions without loading states.
    */
   reset(): Promise<{ error: ClerkError | null }> {

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

@@ -27,13 +27,13 @@ export class Waitlist extends BaseResource implements WaitlistResource {
     this.updatedAt = unixEpochToDate(data.updated_at);
     this.createdAt = unixEpochToDate(data.created_at);
 
-    eventBus.emit('resource:update', { resource: this });
+    eventBus.emit('resource:state-change', { resource: this });
     return this;
   }
 
   async join(params: JoinWaitlistParams): Promise<{ error: ClerkError | null }> {
     return runAsyncResourceTask(this, async () => {
-      await Waitlist.join(params);
+      await this._basePost({ path: this.pathRoot, body: params });
     });
   }