feat(clerk-js,clerk-react,types): Introduce state signals

packages/clerk-js/package.json

@@ -75,6 +75,7 @@
     "@swc/helpers": "^0.5.17",
     "@zxcvbn-ts/core": "3.0.4",
     "@zxcvbn-ts/language-common": "3.0.4",
+    "alien-signals": "^2.0.5",
     "browser-tabs-lock": "1.3.0",
     "copy-to-clipboard": "3.3.3",
     "core-js": "3.41.0",

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

@@ -154,6 +154,7 @@ import {
   Waitlist,
 } from './resources/internal';
 import { navigateToTask } from './sessionTasks';
+import { State } from './state';
 import { warnings } from './warnings';
 
 type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
@@ -211,6 +212,7 @@ export class Clerk implements ClerkInterface {
   public user: UserResource | null | undefined;
   public __internal_country?: string | null;
   public telemetry: TelemetryCollector | undefined;
+  public __internal_state: State = new State();
 
   protected internal_last_error: ClerkAPIError | null = null;
   // converted to protected environment to support `updateEnvironment` type assertion

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

@@ -1,20 +1,25 @@
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/types';
 
+import type { SignIn } from './resources';
+
 export const events = {
   TokenUpdate: 'token:update',
   UserSignOut: 'user:signOut',
   EnvironmentUpdate: 'environment:update',
   SessionTokenResolved: 'session:tokenResolved',
+  SignInUpdate: 'signin:update',
 } as const;
 
 type TokenUpdatePayload = { token: TokenResource | null };
+export type SignInUpdatePayload = { resource: SignIn };
 
 type InternalEvents = {
   [events.TokenUpdate]: TokenUpdatePayload;
   [events.UserSignOut]: null;
   [events.EnvironmentUpdate]: null;
   [events.SessionTokenResolved]: null;
+  [events.SignInUpdate]: SignInUpdatePayload;
 };
 
 export const eventBus = createEventBus<InternalEvents>();

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

@@ -66,6 +66,7 @@ import {
   clerkVerifyPasskeyCalledBeforeCreate,
   clerkVerifyWeb3WalletCalledBeforeCreate,
 } from '../errors';
+import { eventBus } from '../events';
 import { BaseResource, UserData, Verification } from './internal';
 
 export class SignIn extends BaseResource implements SignInResource {
@@ -451,6 +452,8 @@ export class SignIn extends BaseResource implements SignInResource {
       this.createdSessionId = data.created_session_id;
       this.userData = new UserData(data.user_data);
     }
+
+    eventBus.emit('signin:update', { resource: this });
     return this;
   }
 

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

@@ -0,0 +1,5 @@
+import { signal } from 'alien-signals';
+
+import type { SignIn } from './resources/SignIn';
+
+export const signInSignal = signal<{ resource: SignIn | null }>({ resource: null });

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

@@ -0,0 +1,20 @@
+import type { State as StateInterface } from '@clerk/types';
+import { computed, effect } from 'alien-signals';
+
+import { eventBus, type SignInUpdatePayload } from './events';
+import { signInSignal } from './signals';
+
+export class State implements StateInterface {
+  signInSignal = signInSignal;
+
+  __internal_effect = effect;
+  __internal_computed = computed;
+
+  constructor() {
+    eventBus.on('signin:update', this.onSignInUpdated);
+  }
+
+  private onSignInUpdated = (payload: SignInUpdatePayload) => {
+    this.signInSignal({ resource: payload.resource });
+  };
+}

packages/react/src/experimental.ts

@@ -1,6 +1,7 @@
 export { CheckoutButton } from './components/CheckoutButton';
 export { PlanDetailsButton } from './components/PlanDetailsButton';
 export { SubscriptionDetailsButton } from './components/SubscriptionDetailsButton';
+export { useSignInSignal } from './hooks/useClerkSignal';
 
 export type {
   __experimental_CheckoutButtonProps as CheckoutButtonProps,

packages/react/src/hooks/useClerkSignal.ts

@@ -0,0 +1,55 @@
+import type { SignInResource } from '@clerk/types';
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
+import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
+
+function useClerkSignal(signal: 'signIn'): { isLoaded: boolean; signIn: SignInResource | null } {
+  useAssertWrappedByClerkProvider('useSignInSignal');
+
+  const clerk = useIsomorphicClerkContext();
+
+  const subscribe = useCallback(
+    (callback: () => void) => {
+      if (!clerk.loaded || !clerk.__internal_state) {
+        return () => {};
+      }
+
+      return clerk.__internal_state.__internal_effect(() => {
+        switch (signal) {
+          case 'signIn':
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- we know that the state is defined
+            clerk.__internal_state!.signInSignal();
+            break;
+          default:
+            throw new Error(`Unknown signal: ${signal}`);
+        }
+        callback();
+      });
+    },
+    [clerk, clerk.loaded, clerk.__internal_state],
+  );
+  const getSnapshot = useCallback(() => {
+    if (!clerk.__internal_state) {
+      return null;
+    }
+
+    switch (signal) {
+      case 'signIn':
+        return clerk.__internal_state.signInSignal().resource;
+      default:
+        throw new Error(`Unknown signal: ${signal}`);
+    }
+  }, [clerk.__internal_state]);
+
+  const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  return {
+    isLoaded: clerk.loaded,
+    [signal]: value,
+  };
+}
+
+export function useSignInSignal() {
+  return useClerkSignal('signIn');
+}

packages/react/src/isomorphicClerk.ts

@@ -44,6 +44,7 @@ import type {
   SignUpProps,
   SignUpRedirectOptions,
   SignUpResource,
+  State,
   TaskSelectOrganizationProps,
   UnsubscribeCallback,
   UserButtonProps,
@@ -714,6 +715,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     return this.clerkjs?.billing;
   }
 
+  get __internal_state(): State | undefined {
+    return this.clerkjs?.__internal_state;
+  }
+
   get apiKeys(): APIKeysNamespace | undefined {
     return this.clerkjs?.apiKeys;
   }

packages/types/src/clerk.ts

@@ -54,6 +54,7 @@ import type { SessionVerificationLevel } from './sessionVerification';
 import type { SignInResource } from './signIn';
 import type { SignUpResource } from './signUp';
 import type { ClientJSONSnapshot, EnvironmentJSONSnapshot } from './snapshots';
+import type { State } from './state';
 import type { Web3Strategy } from './strategies';
 import type { TelemetryCollector } from './telemetry';
 import type { UserResource } from './user';
@@ -227,6 +228,8 @@ export interface Clerk {
   /** Current User. */
   user: UserResource | null | undefined;
 
+  __internal_state: State | undefined;
+
   /**
    * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.
    * @see https://clerk.com/docs/billing/overview

packages/types/src/index.ts

@@ -49,6 +49,7 @@ export * from './sessionVerification';
 export * from './signIn';
 export * from './signUp';
 export * from './ssr';
+export * from './state';
 export * from './strategies';
 export * from './theme';
 export * from './token';

packages/types/src/state.ts

@@ -0,0 +1,12 @@
+import type { SignInResource } from './signIn';
+
+export interface State {
+  signInSignal: {
+    (): {
+      resource: SignInResource | null;
+    };
+    (value: { resource: SignInResource | null }): void;
+  };
+  __internal_effect: (callback: () => void) => () => void;
+  __internal_computed: <T>(getter: (previousValue?: T) => T) => () => T;
+}