Add missing TSDocs

Author: jacekradko

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

@@ -4,6 +4,9 @@ import { debugLogger } from '@/utils/debug';
 
 import { Token } from './resources/internal';
 
+/**
+ * Identifies a cached token entry by tokenId and optional audience.
+ */
 interface TokenCacheKeyJSON {
   audience?: string;
   tokenId: string;
@@ -52,11 +55,14 @@ export interface TokenBroadcastMetadata {
 
 type Seconds = number;
 
+/**
+ * Internal cache value containing the entry, expiration metadata, and cleanup timer.
+ */
 interface TokenCacheValue {
   createdAt: Seconds;
   entry: TokenCacheEntry;
-  expiresIn?: Seconds;
   expiresAt?: Seconds;
+  expiresIn?: Seconds;
   timeoutId?: ReturnType<typeof setTimeout>;
 }
 
@@ -105,7 +111,14 @@ const LEEWAY = 10;
 // This value should have the same value as the INTERVAL_IN_MS in SessionCookiePoller
 const SYNC_LEEWAY = 5;
 
+/**
+ * Converts between cache key objects and string representations.
+ * Format: `prefix::tokenId::audience`
+ */
 export class TokenCacheKey {
+  /**
+   * Parses a cache key string into a TokenCacheKey instance.
+   */
   static fromKey(key: string): TokenCacheKey {
     const [prefix, tokenId, audience = ''] = key.split(DELIMITER);
     return new TokenCacheKey(prefix, { audience, tokenId });
@@ -119,16 +132,26 @@ export class TokenCacheKey {
     this.data = data;
   }
 
+  /**
+   * Converts the key to its string representation for Map storage.
+   */
   toKey(): string {
     const { tokenId, audience } = this.data;
     return [this.prefix, tokenId, audience || ''].join(DELIMITER);
   }
 }
 
+/**
+ * Generates a unique token identifier from session context.
+ * Format: `sessionId-template-organizationId` (omitting falsy values).
+ */
 const computeTokenId = (sessionId: string, template?: string, organizationId?: string | null): string => {
   return [sessionId, template, organizationId].filter(Boolean).join('-');
 };
 
+/**
+ * Message format for BroadcastChannel token synchronization between tabs.
+ */
 interface SessionTokenEvent {
   organizationId?: string | null;
   sessionId: string;
@@ -138,6 +161,10 @@ interface SessionTokenEvent {
   traceId: string;
 }
 
+/**
+ * Creates an in-memory token cache with BroadcastChannel synchronization across tabs.
+ * Automatically manages token expiration and cleanup via scheduled timeouts.
+ */
 const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
   const cache = new Map<string, TokenCacheValue>();
 
@@ -199,6 +226,10 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
     return value.entry;
   };
 
+  /**
+   * Processes token updates from other tabs via BroadcastChannel.
+   * Validates token ID, parses JWT, and updates cache if token is newer than existing entry.
+   */
   const handleBroadcastMessage = async ({ data }: MessageEvent<SessionTokenEvent>) => {
     const expectedTokenId = computeTokenId(data.sessionId, data.template, data.organizationId);
     if (data.tokenId !== expectedTokenId) {
@@ -320,6 +351,10 @@ const MemoryTokenCache = (prefix = KEY_PREFIX): TokenCache => {
     }
   };
 
+  /**
+   * Internal cache setter that stores an entry and schedules expiration cleanup.
+   * Resolves the token promise to extract expiration claims and set a deletion timeout.
+   */
   const setInternal = (entry: TokenCacheEntry) => {
     const cacheKey = new TokenCacheKey(prefix, {
       audience: entry.audience,