feat(clerk-js,clerk-react,types): Update signal hooks to always return values (#6605)

Author: dstaley

.changeset/rotten-falcons-cover.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/clerk-react': minor
+'@clerk/types': minor
+---
+
+[Experimental] Signals `isLoaded` removal

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

@@ -91,7 +91,7 @@ export class SignIn extends BaseResource implements SignInResource {
    *
    * An instance of `SignInFuture`, which has a different API than `SignIn`, intended to be used in custom flows.
    */
-  __internal_future: SignInFuture | null = new SignInFuture(this);
+  __internal_future: SignInFuture = new SignInFuture(this);
 
   /**
    * @internal Only used for internal purposes, and is not intended to be used directly.
@@ -638,7 +638,7 @@ class SignInFuture implements SignInFutureResource {
     });
   }
 
-  async finalize({ navigate }: { navigate?: SetActiveNavigate }): Promise<{ error: unknown }> {
+  async finalize({ navigate }: { navigate?: SetActiveNavigate } = {}): Promise<{ error: unknown }> {
     return runAsyncResourceTask(this.resource, async () => {
       if (!this.resource.createdSessionId) {
         throw new Error('Cannot finalize sign-in without a created session.');

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

@@ -87,7 +87,7 @@ export class SignUp extends BaseResource implements SignUpResource {
    *
    * An instance of `SignUpFuture`, which has a different API than `SignUp`, intended to be used in custom flows.
    */
-  __internal_future: SignUpFuture | null = new SignUpFuture(this);
+  __internal_future: SignUpFuture = new SignUpFuture(this);
 
   /**
    * @internal Only used for internal purposes, and is not intended to be used directly.
@@ -539,7 +539,7 @@ class SignUpFuture implements SignUpFutureResource {
     });
   }
 
-  async finalize({ navigate }: { navigate?: SetActiveNavigate }): Promise<{ error: unknown }> {
+  async finalize({ navigate }: { navigate?: SetActiveNavigate } = {}): Promise<{ error: unknown }> {
     return runAsyncResourceTask(this.resource, async () => {
       if (!this.resource.createdSessionId) {
         throw new Error('Cannot finalize sign-up without a created session.');

packages/react/src/hooks/useClerkSignal.ts

@@ -4,28 +4,36 @@ import { useCallback, useSyncExternalStore } from 'react';
 import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
 import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
 
-function useClerkSignal(signal: 'signIn'): ReturnType<SignInSignal> | null;
-function useClerkSignal(signal: 'signUp'): ReturnType<SignUpSignal> | null;
-function useClerkSignal(signal: 'signIn' | 'signUp'): ReturnType<SignInSignal> | ReturnType<SignUpSignal> | null {
+// These types are used to remove the `null` value from the underlying resource. This is safe because IsomorphicClerk
+// always returns a valid resource, even before Clerk is loaded, and if Clerk is loaded, the resource is guaranteed to
+// be non-null
+type NonNullSignInSignal = Omit<ReturnType<SignInSignal>, 'signIn'> & {
+  signIn: NonNullable<ReturnType<SignInSignal>['signIn']>;
+};
+type NonNullSignUpSignal = Omit<ReturnType<SignUpSignal>, 'signUp'> & {
+  signUp: NonNullable<ReturnType<SignUpSignal>['signUp']>;
+};
+
+function useClerkSignal(signal: 'signIn'): NonNullSignInSignal;
+function useClerkSignal(signal: 'signUp'): NonNullSignUpSignal;
+function useClerkSignal(signal: 'signIn' | 'signUp'): NonNullSignInSignal | NonNullSignUpSignal {
   useAssertWrappedByClerkProvider('useClerkSignal');
 
   const clerk = useIsomorphicClerkContext();
 
   const subscribe = useCallback(
     (callback: () => void) => {
-      if (!clerk.loaded || !clerk.__internal_state) {
+      if (!clerk.loaded) {
         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();
+            clerk.__internal_state.signInSignal();
             break;
           case 'signUp':
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- we know that the state is defined
-            clerk.__internal_state!.signUpSignal();
+            clerk.__internal_state.signUpSignal();
             break;
           default:
             throw new Error(`Unknown signal: ${signal}`);
@@ -36,15 +44,11 @@ function useClerkSignal(signal: 'signIn' | 'signUp'): ReturnType<SignInSignal> |
     [clerk, clerk.loaded, clerk.__internal_state],
   );
   const getSnapshot = useCallback(() => {
-    if (!clerk.__internal_state) {
-      return null;
-    }
-
     switch (signal) {
       case 'signIn':
-        return clerk.__internal_state.signInSignal();
+        return clerk.__internal_state.signInSignal() as NonNullSignInSignal;
       case 'signUp':
-        return clerk.__internal_state.signUpSignal();
+        return clerk.__internal_state.signUpSignal() as NonNullSignUpSignal;
       default:
         throw new Error(`Unknown signal: ${signal}`);
     }

packages/react/src/isomorphicClerk.ts

@@ -56,6 +56,7 @@ import type {
 
 import { errorThrower } from './errors/errorThrower';
 import { unsupportedNonBrowserDomainOrProxyUrlFunction } from './errors/messages';
+import { StateProxy } from './stateProxy';
 import type {
   BrowserClerk,
   BrowserClerkConstructor,
@@ -157,6 +158,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
   #proxyUrl: DomainOrProxyUrl['proxyUrl'];
   #publishableKey: string;
   #eventBus = createClerkEventBus();
+  #stateProxy: StateProxy;
 
   get publishableKey(): string {
     return this.#publishableKey;
@@ -249,6 +251,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     this.options = options;
     this.Clerk = Clerk;
     this.mode = inBrowser() ? 'browser' : 'server';
+    this.#stateProxy = new StateProxy(this);
 
     if (!this.options.sdkMetadata) {
       this.options.sdkMetadata = SDK_METADATA;
@@ -722,8 +725,8 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     return this.clerkjs?.billing;
   }
 
-  get __internal_state(): State | undefined {
-    return this.clerkjs?.__internal_state;
+  get __internal_state(): State {
+    return this.loaded && this.clerkjs ? this.clerkjs.__internal_state : this.#stateProxy;
   }
 
   get apiKeys(): APIKeysNamespace | undefined {

packages/react/src/stateProxy.ts

@@ -0,0 +1,113 @@
+import { inBrowser } from '@clerk/shared/browser';
+import type { Errors, State } from '@clerk/types';
+
+import { errorThrower } from './errors/errorThrower';
+import type { IsomorphicClerk } from './isomorphicClerk';
+
+const defaultErrors = (): Errors => ({
+  fields: {
+    firstName: null,
+    lastName: null,
+    emailAddress: null,
+    identifier: null,
+    phoneNumber: null,
+    password: null,
+    username: null,
+    code: null,
+    captcha: null,
+    legalAccepted: null,
+  },
+  raw: [],
+  global: [],
+});
+
+export class StateProxy implements State {
+  constructor(private isomorphicClerk: IsomorphicClerk) {}
+
+  private readonly signInSignalProxy = this.buildSignInProxy();
+  private readonly signUpSignalProxy = this.buildSignUpProxy();
+
+  signInSignal() {
+    return this.signInSignalProxy;
+  }
+  signUpSignal() {
+    return this.signUpSignalProxy;
+  }
+
+  private buildSignInProxy() {
+    const target = () => this.client.signIn.__internal_future;
+
+    return {
+      errors: defaultErrors(),
+      fetchStatus: 'idle' as const,
+      signIn: {
+        status: 'needs_identifier' as const,
+        availableStrategies: [],
+
+        create: this.gateMethod(target, 'create'),
+        password: this.gateMethod(target, 'password'),
+        sso: this.gateMethod(target, 'sso'),
+        finalize: this.gateMethod(target, 'finalize'),
+
+        emailCode: this.wrapMethods(() => target().emailCode, ['sendCode', 'verifyCode'] as const),
+        resetPasswordEmailCode: this.wrapMethods(() => target().resetPasswordEmailCode, [
+          'sendCode',
+          'verifyCode',
+          'submitPassword',
+        ] as const),
+      },
+    };
+  }
+
+  private buildSignUpProxy() {
+    const target = () => this.client.signUp.__internal_future;
+
+    return {
+      errors: defaultErrors(),
+      fetchStatus: 'idle' as const,
+      signUp: {
+        status: 'missing_requirements' as const,
+        unverifiedFields: [],
+
+        password: this.gateMethod(target, 'password'),
+        finalize: this.gateMethod(target, 'finalize'),
+
+        verifications: this.wrapMethods(() => target().verifications, ['sendEmailCode', 'verifyEmailCode'] as const),
+      },
+    };
+  }
+
+  __internal_effect(_: () => void): () => void {
+    throw new Error('__internal_effect called before Clerk is loaded');
+  }
+  __internal_computed<T>(_: (prev?: T) => T): () => T {
+    throw new Error('__internal_computed called before Clerk is loaded');
+  }
+
+  private get client() {
+    const c = this.isomorphicClerk.client;
+    if (!c) throw new Error('Clerk client not ready');
+    return c;
+  }
+
+  private gateMethod<T extends object, K extends keyof T & string>(getTarget: () => T, key: K) {
+    type F = Extract<T[K], (...args: unknown[]) => unknown>;
+    return (async (...args: Parameters<F>): Promise<ReturnType<F>> => {
+      if (!inBrowser()) {
+        return errorThrower.throw(`Attempted to call a method (${key}) that is not supported on the server.`);
+      }
+      if (!this.isomorphicClerk.loaded) {
+        await new Promise<void>(resolve => this.isomorphicClerk.addOnLoaded(resolve));
+      }
+      const t = getTarget();
+      return (t[key] as (...args: Parameters<F>) => ReturnType<F>).apply(t, args);
+    }) as F;
+  }
+
+  private wrapMethods<T extends object, K extends readonly (keyof T & string)[]>(
+    getTarget: () => T,
+    keys: K,
+  ): Pick<T, K[number]> {
+    return Object.fromEntries(keys.map(k => [k, this.gateMethod(getTarget, k)])) as Pick<T, K[number]>;
+  }
+}

packages/types/src/clerk.ts

@@ -235,7 +235,7 @@ export interface Clerk {
    * Entrypoint for Clerk's Signal API containing resource signals along with accessible versions of `computed()` and
    * `effect()` that can be used to subscribe to changes from Signals.
    */
-  __internal_state: State | undefined;
+  __internal_state: State;
 
   /**
    * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change.

packages/types/src/signIn.ts

@@ -124,6 +124,11 @@ export interface SignInResource extends ClerkResource {
    * @internal
    */
   __internal_toSnapshot: () => SignInJSONSnapshot;
+
+  /**
+   * @internal
+   */
+  __internal_future: SignInFutureResource;
 }
 
 export interface SignInFutureResource {
@@ -151,7 +156,7 @@ export interface SignInFutureResource {
     redirectUrl: string;
     redirectUrlComplete: string;
   }) => Promise<{ error: unknown }>;
-  finalize: (params: { navigate?: SetActiveNavigate }) => Promise<{ error: unknown }>;
+  finalize: (params?: { navigate?: SetActiveNavigate }) => Promise<{ error: unknown }>;
 }
 
 export type SignInStatus =

packages/types/src/signUp.ts

@@ -117,6 +117,11 @@ export interface SignUpResource extends ClerkResource {
   authenticateWithCoinbaseWallet: (params?: SignUpAuthenticateWithWeb3Params) => Promise<SignUpResource>;
   authenticateWithOKXWallet: (params?: SignUpAuthenticateWithWeb3Params) => Promise<SignUpResource>;
   __internal_toSnapshot: () => SignUpJSONSnapshot;
+
+  /**
+   * @internal
+   */
+  __internal_future: SignUpFutureResource;
 }
 
 export interface SignUpFutureResource {
@@ -127,7 +132,7 @@ export interface SignUpFutureResource {
     verifyEmailCode: (params: { code: string }) => Promise<{ error: unknown }>;
   };
   password: (params: { emailAddress: string; password: string }) => Promise<{ error: unknown }>;
-  finalize: (params: { navigate?: SetActiveNavigate }) => Promise<{ error: unknown }>;
+  finalize: (params?: { navigate?: SetActiveNavigate }) => Promise<{ error: unknown }>;
 }
 
 export type SignUpStatus = 'missing_requirements' | 'complete' | 'abandoned';