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

Author: bratsos

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

@@ -3,9 +3,51 @@ 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(() => {
+    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 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 +94,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 +138,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 +164,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 +196,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 +238,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 +258,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 +274,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 +296,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

@@ -572,7 +572,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;
   }
 
@@ -1306,7 +1306,7 @@ class SignInFuture implements SignInFutureResource {
 
   /**
    * 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

@@ -517,7 +517,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;
   }
 
@@ -1126,7 +1126,7 @@ class SignUpFuture implements SignUpFutureResource {
 
   /**
    * 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 });
     });
   }
 

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

@@ -2032,9 +2032,8 @@ describe('SignIn', () => {
           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
+            eventBus.emit('resource:state-change', { resource: newSignIn, error: null, fetchStatus: 'idle' });
+            // Also update signals directly since State isn't set up in these tests
             signInResourceSignal({ resource: newSignIn });
             signInErrorSignal({ error: null });
           }),
@@ -2052,17 +2051,17 @@ describe('SignIn', () => {
         signInErrorSignal({ error: null });
       });
 
-      it('does NOT emit resource:fetch with status fetching', async () => {
+      it('does NOT set fetchStatus to 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'
+        // Verify that no event was emitted with fetchStatus: 'fetching'
         const fetchingCalls = emitSpy.mock.calls.filter(
-          call => call[0] === 'resource:fetch' && call[1]?.status === 'fetching',
+          call => call[0] === 'resource:state-change' && call[1]?.fetchStatus === 'fetching',
         );
         expect(fetchingCalls).toHaveLength(0);
         // Verify no API calls were made

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

@@ -989,9 +989,8 @@ describe('SignUp', () => {
           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
+            eventBus.emit('resource:state-change', { resource: newSignUp, error: null, fetchStatus: 'idle' });
+            // Also update signals directly since State isn't set up in these tests
             signUpResourceSignal({ resource: newSignUp });
             signUpErrorSignal({ error: null });
           }),
@@ -1009,17 +1008,17 @@ describe('SignUp', () => {
         signUpErrorSignal({ error: null });
       });
 
-      it('does NOT emit resource:fetch with status fetching', async () => {
+      it('does NOT set fetchStatus to 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'
+        // Verify that no event was emitted with fetchStatus: 'fetching'
         const fetchingCalls = emitSpy.mock.calls.filter(
-          call => call[0] === 'resource:fetch' && call[1]?.status === 'fetching',
+          call => call[0] === 'resource:state-change' && call[1]?.fetchStatus === 'fetching',
         );
         expect(fetchingCalls).toHaveLength(0);
         // Verify no API calls were made

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

@@ -1,5 +1,7 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 
+import { waitlistResourceSignal } from '../../signals';
+import { State } from '../../state';
 import { Waitlist } from '../internal';
 
 describe('Waitlist', () => {
@@ -17,4 +19,25 @@ describe('Waitlist', () => {
       updatedAt: new Date(5678),
     });
   });
+
+  describe('join()', () => {
+    it('should update the waitlist instance and signal with data from the server response', async () => {
+      const state = new State();
+      const waitlist = state.__internal_waitlist;
+      expect(waitlist.id).toBe('');
+
+      // Mock the network boundary — _basePost calls fromJSON on `this` with the response
+      vi.spyOn(waitlist as any, '_basePost').mockImplementation(async function (this: Waitlist) {
+        (this as any).fromJSON({ id: 'wl_abc123', created_at: 12345, updated_at: 5678 });
+        return this;
+      });
+
+      await waitlist.join({ emailAddress: 'test@example.com' });
+
+      // The instance should be updated in-place, and the signal should reflect it
+      expect(waitlist.id).toBe('wl_abc123');
+      expect(waitlistResourceSignal().resource).toBe(waitlist);
+      expect(waitlistResourceSignal().resource?.id).toBe('wl_abc123');
+    });
+  });
 });