Merge branch 'main' into aa/fix-typedoc

Author: alexisintech

.changeset/modern-cars-fall.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Optimize Session.#hydrateCache to only cache token if it's new/different

.changeset/silly-jars-shave.md

@@ -0,0 +1,2 @@
+---
+---

.typedoc/custom-theme.mjs

@@ -44,6 +44,8 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
     const superPartials = this.partials;
 
+    this._insideFunctionSignature = false;
+
     this.partials = {
       ...superPartials,
       /**
@@ -153,10 +155,17 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
           );
         }
 
+        const prevInsideParams = this._insideFunctionSignature;
+        this._insideFunctionSignature = true;
         md.push(this.partials.signatureParameters(model.parameters || []));
+        this._insideFunctionSignature = prevInsideParams;
 
         if (model.type) {
-          md.push(`: ${this.partials.someType(model.type)}`);
+          const prevInsideType = this._insideFunctionSignature;
+          this._insideFunctionSignature = true;
+          const typeOutput = this.partials.someType(model.type);
+          this._insideFunctionSignature = prevInsideType;
+          md.push(`: ${typeOutput}`);
         }
 
         const result = md.join('');
@@ -353,6 +362,11 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
           .replace(/<code>/g, '')
           .replace(/<\/code>/g, '');
 
+        // Only wrap in <code> if NOT inside a function signature
+        if (this._insideFunctionSignature) {
+          return output;
+        }
+
         return `<code>${output}</code>`;
       },
       /**
@@ -371,6 +385,11 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
           .replace(/<code>/g, '')
           .replace(/<\/code>/g, '');
 
+        // Only wrap in <code> if NOT inside a function signature
+        if (this._insideFunctionSignature) {
+          return output;
+        }
+
         return `<code>${output}</code>`;
       },
       /**
@@ -394,6 +413,11 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
           )
           .join(delimiter);
 
+        // Only wrap in <code> if NOT inside a function signature
+        if (this._insideFunctionSignature) {
+          return output;
+        }
+
         return `<code>${output}</code>`;
       },
       /**
@@ -492,6 +516,32 @@ ${tabs}
           .replace(/<code>/g, '')
           .replace(/<\/code>/g, '');
 
+        // Only wrap in <code> if NOT inside a function signature
+        if (this._insideFunctionSignature) {
+          return output;
+        }
+
+        return `<code>${output}</code>`;
+      },
+      /**
+       * Ensures that reflection types (like Simplify wrapped types) are wrapped in a single codeblock
+       * @param {import('typedoc').ReflectionType} model
+       */
+      reflectionType: model => {
+        const defaultOutput = superPartials.reflectionType(model);
+
+        const output = defaultOutput
+          // Remove any backticks
+          .replace(/`/g, '')
+          // Remove any `<code>` and `</code>` tags
+          .replace(/<code>/g, '')
+          .replace(/<\/code>/g, '');
+
+        // Only wrap in <code> if NOT inside a function signature
+        if (this._insideFunctionSignature) {
+          return output;
+        }
+
         return `<code>${output}</code>`;
       },
       /**

packages/backend/src/tokens/verify.ts

@@ -40,22 +40,11 @@ export type VerifyTokenOptions = Simplify<
  * Verifies a Clerk-generated token signature. Networkless if the `jwtKey` is provided. Otherwise, performs a network call to retrieve the JWKS from the [Backend API](https://clerk.com/docs/reference/backend-api/tag/JWKS#operation/GetJWKS){{ target: '_blank' }}.
  *
  * @param token - The token to verify.
- * @param options - Options for verifying the token.
+ * @param options - Options for verifying the token. It is recommended to set these options as [environment variables](/docs/guides/development/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `verifyToken(token, { secretKey: process.env.CLERK_SECRET_KEY })`.
  *
  * @displayFunctionSignature
  * @hideReturns
  *
- * @paramExtension
- *
- * ### `VerifyTokenOptions`
- *
- * It is recommended to set these options as [environment variables](/docs/guides/development/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
- *
- * > [!WARNING]
- * You must provide either `jwtKey` or `secretKey`.
- *
- * <Typedoc src="backend/verify-token-options" />
- *
  * @example
  *
  * The following example demonstrates how to use the [JavaScript Backend SDK](https://clerk.com/docs/reference/backend/overview) to verify the token signature.

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

@@ -277,6 +277,41 @@ describe('SessionTokenCache', () => {
       // Critical: postMessage should NOT be called when handling a broadcast
       expect(mockBroadcastChannel.postMessage).not.toHaveBeenCalled();
     });
+
+    it('always broadcasts regardless of cache state', async () => {
+      mockBroadcastChannel.postMessage.mockClear();
+
+      const tokenId = 'sess_2GbDB4enNdCa5vS1zpC3Xzg9tK9';
+      const tokenResolver = Promise.resolve(
+        new Token({
+          id: tokenId,
+          jwt: mockJwt,
+          object: 'token',
+        }) as TokenResource,
+      );
+
+      SessionTokenCache.set({ tokenId, tokenResolver });
+      await tokenResolver;
+
+      expect(mockBroadcastChannel.postMessage).toHaveBeenCalledTimes(1);
+      const firstCall = mockBroadcastChannel.postMessage.mock.calls[0][0];
+      expect(firstCall.tokenId).toBe(tokenId);
+
+      mockBroadcastChannel.postMessage.mockClear();
+
+      const tokenResolver2 = Promise.resolve(
+        new Token({
+          id: tokenId,
+          jwt: mockJwt,
+          object: 'token',
+        }) as TokenResource,
+      );
+
+      SessionTokenCache.set({ tokenId, tokenResolver: tokenResolver2 });
+      await tokenResolver2;
+
+      expect(mockBroadcastChannel.postMessage).toHaveBeenCalledTimes(1);
+    });
   });
 
   describe('token expiration with absolute time', () => {

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

@@ -131,9 +131,15 @@ export class Session extends BaseResource implements SessionResource {
   };
 
   #hydrateCache = (token: TokenResource | null) => {
-    if (token) {
+    if (!token) {
+      return;
+    }
+
+    const tokenId = this.#getCacheId();
+    const existing = SessionTokenCache.get({ tokenId });
+    if (!existing) {
       SessionTokenCache.set({
-        tokenId: this.#getCacheId(),
+        tokenId,
         tokenResolver: Promise.resolve(token),
       });
     }

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

@@ -35,7 +35,7 @@ describe('Session', () => {
 
     beforeEach(() => {
       dispatchSpy = vi.spyOn(eventBus, 'emit');
-      BaseResource.clerk = clerkMock() as any;
+      BaseResource.clerk = clerkMock();
     });
 
     afterEach(() => {
@@ -76,7 +76,7 @@ describe('Session', () => {
     it('hydrates token cache from lastActiveToken', async () => {
       BaseResource.clerk = clerkMock({
         organization: new Organization({ id: 'activeOrganization' } as OrganizationJSON),
-      }) as any;
+      });
 
       const session = new Session({
         status: 'active',
@@ -100,10 +100,81 @@ describe('Session', () => {
       expect(dispatchSpy).toHaveBeenCalledTimes(2);
     });
 
+    it('does not re-cache token when Session is reconstructed with same token', async () => {
+      BaseResource.clerk = clerkMock({
+        organization: new Organization({ id: 'activeOrganization' } as OrganizationJSON),
+      });
+
+      SessionTokenCache.clear();
+
+      const session1 = new Session({
+        status: 'active',
+        id: 'session_1',
+        object: 'session',
+        user: createUser({}),
+        last_active_organization_id: 'activeOrganization',
+        last_active_token: { object: 'token', jwt: mockJwt },
+        actor: null,
+        created_at: new Date().getTime(),
+        updated_at: new Date().getTime(),
+      } as SessionJSON);
+
+      expect(SessionTokenCache.size()).toBe(1);
+      const cachedEntry1 = SessionTokenCache.get({ tokenId: 'session_1-activeOrganization' });
+      expect(cachedEntry1).toBeDefined();
+
+      const session2 = new Session({
+        status: 'active',
+        id: 'session_1',
+        object: 'session',
+        user: createUser({}),
+        last_active_organization_id: 'activeOrganization',
+        last_active_token: { object: 'token', jwt: mockJwt },
+        actor: null,
+        created_at: new Date().getTime(),
+        updated_at: new Date().getTime(),
+      } as SessionJSON);
+
+      expect(SessionTokenCache.size()).toBe(1);
+
+      const token1 = await session1.getToken();
+      const token2 = await session2.getToken();
+
+      expect(token1).toBe(token2);
+      expect(token1).toEqual(mockJwt);
+      expect(BaseResource.clerk.getFapiClient().request).not.toHaveBeenCalled();
+    });
+
+    it('caches token from cookie during degraded mode recovery', async () => {
+      BaseResource.clerk = clerkMock();
+
+      SessionTokenCache.clear();
+
+      const sessionFromCookie = new Session({
+        status: 'active',
+        id: 'session_1',
+        object: 'session',
+        user: createUser({}),
+        last_active_organization_id: null,
+        last_active_token: { object: 'token', jwt: mockJwt },
+        actor: null,
+        created_at: new Date().getTime(),
+        updated_at: new Date().getTime(),
+      } as SessionJSON);
+
+      expect(SessionTokenCache.size()).toBe(1);
+      const cachedEntry = SessionTokenCache.get({ tokenId: 'session_1' });
+      expect(cachedEntry).toBeDefined();
+
+      const token = await sessionFromCookie.getToken();
+      expect(token).toEqual(mockJwt);
+      expect(BaseResource.clerk.getFapiClient().request).not.toHaveBeenCalled();
+    });
+
     it('dispatches token:update event on getToken with active organization', async () => {
       BaseResource.clerk = clerkMock({
         organization: new Organization({ id: 'activeOrganization' } as OrganizationJSON),
-      }) as any;
+      });
 
       const session = new Session({
         status: 'active',
@@ -138,7 +209,7 @@ describe('Session', () => {
     it('does not dispatch token:update if template is provided', async () => {
       BaseResource.clerk = clerkMock({
         organization: new Organization({ id: 'activeOrganization' } as OrganizationJSON),
-      }) as any;
+      });
 
       const session = new Session({
         status: 'active',
@@ -159,7 +230,7 @@ describe('Session', () => {
     it('dispatches token:update when provided organization ID matches current active organization', async () => {
       BaseResource.clerk = clerkMock({
         organization: new Organization({ id: 'activeOrganization' } as OrganizationJSON),
-      }) as any;
+      });
 
       const session = new Session({
         status: 'active',
@@ -178,7 +249,7 @@ describe('Session', () => {
     });
 
     it('does not dispatch token:update when provided organization ID does not match current active organization', async () => {
-      BaseResource.clerk = clerkMock() as any;
+      BaseResource.clerk = clerkMock();
 
       const session = new Session({
         status: 'active',
@@ -240,7 +311,7 @@ describe('Session', () => {
     it(`uses the current session's lastActiveOrganizationId by default, not clerk.organization.id`, async () => {
       BaseResource.clerk = clerkMock({
         organization: new Organization({ id: 'oldActiveOrganization' } as OrganizationJSON),
-      }) as any;
+      });
 
       const session = new Session({
         status: 'active',
@@ -261,7 +332,7 @@ describe('Session', () => {
     });
 
     it('deduplicates concurrent getToken calls to prevent multiple API requests', async () => {
-      BaseResource.clerk = clerkMock() as any;
+      BaseResource.clerk = clerkMock();
 
       const session = new Session({
         status: 'active',
@@ -286,7 +357,7 @@ describe('Session', () => {
     });
 
     it('deduplicates concurrent getToken calls with same template', async () => {
-      BaseResource.clerk = clerkMock() as any;
+      BaseResource.clerk = clerkMock();
 
       const session = new Session({
         status: 'active',
@@ -313,7 +384,7 @@ describe('Session', () => {
     });
 
     it('does not deduplicate getToken calls with different templates', async () => {
-      BaseResource.clerk = clerkMock() as any;
+      BaseResource.clerk = clerkMock();
 
       const session = new Session({
         status: 'active',
@@ -335,7 +406,7 @@ describe('Session', () => {
     });
 
     it('does not deduplicate getToken calls with different organization IDs', async () => {
-      BaseResource.clerk = clerkMock() as any;
+      BaseResource.clerk = clerkMock();
 
       const session = new Session({
         status: 'active',
@@ -362,7 +433,7 @@ describe('Session', () => {
 
     beforeEach(() => {
       dispatchSpy = vi.spyOn(eventBus, 'emit');
-      BaseResource.clerk = clerkMock() as any;
+      BaseResource.clerk = clerkMock();
     });
 
     afterEach(() => {