chore(shared): Improve cache key creation

.changeset/lemon-facts-stare.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update how cache keys are created in SWR/RQ hooks.

packages/clerk-js/bundlewatch.config.json

@@ -6,7 +6,7 @@
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "123KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "63.2KB" },
     { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
-    { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
+    { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120.1KB" },
     { "path": "./dist/vendors*.js", "maxSize": "47KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
     { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

packages/shared/src/react/hooks/createBillingPaginatedHook.tsx

@@ -7,6 +7,7 @@ import {
   useUserContext,
 } from '../contexts';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -35,6 +36,16 @@ export interface HookParams
        * @default true
        */
       enabled?: boolean;
+      /**
+       * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache.
+       *
+       * @default undefined
+       *
+       * @hidden
+       *
+       * @experimental
+       */
+      __experimental_mode?: 'cache';
     }
   > {
   /**
@@ -110,28 +121,31 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar
 
     const isEnabled = !!hookParams && clerk.loaded && !!billingEnabled && (externalEnabled ?? true);
 
-    const result = usePagesOrInfinite<TParams, ClerkPaginatedResponse<TResource>>(
-      (hookParams || {}) as TParams,
-      fetchFn,
-      {
-        ...({
-          keepPreviousData: safeValues.keepPreviousData,
-          infinite: safeValues.infinite,
-        } as PaginatedHookConfig<unknown>),
+    const result = usePagesOrInfinite({
+      fetcher: fetchFn,
+      config: {
+        keepPreviousData: safeValues.keepPreviousData,
+        infinite: safeValues.infinite,
         enabled: isEnabled,
         ...(options?.unauthenticated ? {} : { isSignedIn: Boolean(user) }),
         __experimental_mode: safeValues.__experimental_mode,
+        initialPage: safeValues.initialPage,
+        pageSize: safeValues.pageSize,
       },
-      {
-        type: resourceType,
-        ...(options?.unauthenticated
-          ? { for: safeFor }
-          : {
+      keys: createCacheKeys({
+        stablePrefix: resourceType,
+        authenticated: !options?.unauthenticated,
+        tracked: options?.unauthenticated
+          ? ({ for: safeFor } as const)
+          : ({
               userId: user?.id,
-              ...(isForOrganization ? { orgId: organization?.id } : {}),
-            }),
-      },
-    );
+              ...(isForOrganization ? { [__CLERK_USE_RQ__ ? 'orgId' : '_orgId']: organization?.id } : {}),
+            } as const),
+        untracked: {
+          args: hookParams as TParams,
+        },
+      }),
+    });
 
     return result;
   };

packages/shared/src/react/hooks/createCacheKeys.ts

@@ -0,0 +1,21 @@
+/**
+ * @internal
+ */
+export function createCacheKeys<
+  Params,
+  StableKey extends string,
+  T extends Record<string, unknown> = Record<string, unknown>,
+  U extends Record<string, unknown> | undefined = undefined,
+>(params: {
+  stablePrefix: StableKey;
+  authenticated: boolean;
+  tracked: T;
+  untracked: U extends { args: Params } ? U : never;
+}) {
+  return {
+    queryKey: [params.stablePrefix, params.authenticated, params.tracked, params.untracked] as const,
+    invalidationKey: [params.stablePrefix, params.authenticated, params.tracked] as const,
+    stableKey: params.stablePrefix,
+    authenticated: params.authenticated,
+  };
+}

packages/shared/src/react/hooks/useAPIKeys.ts

@@ -1,9 +1,10 @@
 'use client';
 
 import { eventMethodCalled } from '../../telemetry/events/method-called';
-import type { APIKeyResource, ClerkPaginatedResponse, GetAPIKeysParams } from '../../types';
+import type { APIKeyResource, GetAPIKeysParams } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -92,17 +93,25 @@ export function useAPIKeys<T extends UseAPIKeysParams>(params?: T): UseAPIKeysRe
 
   const isEnabled = (safeValues.enabled ?? true) && clerk.loaded;
 
-  return usePagesOrInfinite<GetAPIKeysParams, ClerkPaginatedResponse<APIKeyResource>>(
-    hookParams,
-    clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
-    {
+  return usePagesOrInfinite({
+    fetcher: clerk.apiKeys?.getAll ? (params: GetAPIKeysParams) => clerk.apiKeys.getAll(params) : undefined,
+    config: {
       keepPreviousData: safeValues.keepPreviousData,
       infinite: safeValues.infinite,
       enabled: isEnabled,
+      isSignedIn: Boolean(clerk.user),
+      initialPage: safeValues.initialPage,
+      pageSize: safeValues.pageSize,
     },
-    {
-      type: 'apiKeys',
-      subject: safeValues.subject || '',
-    },
-  ) as UseAPIKeysReturn<T>;
+    keys: createCacheKeys({
+      stablePrefix: 'apiKeys',
+      authenticated: Boolean(clerk.user),
+      tracked: {
+        subject: safeValues.subject,
+      },
+      untracked: {
+        args: hookParams,
+      },
+    }),
+  }) as UseAPIKeysReturn<T>;
 }

packages/shared/src/react/hooks/useOrganization.tsx

@@ -1,7 +1,6 @@
 import { getCurrentOrganizationMembership } from '../../organization';
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type {
-  ClerkPaginatedResponse,
   GetDomainsParams,
   GetInvitationsParams,
   GetMembershipRequestParams,
@@ -19,6 +18,7 @@ import {
   useSessionContext,
 } from '../contexts';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
+import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
 
 /**
@@ -357,70 +357,93 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
           status: invitationsSafeValues.status,
         };
 
-  const domains = usePagesOrInfinite<GetDomainsParams, ClerkPaginatedResponse<OrganizationDomainResource>>(
-    {
-      ...domainParams,
-    },
-    organization?.getDomains,
-    {
+  const domains = usePagesOrInfinite({
+    fetcher: organization?.getDomains,
+    config: {
       keepPreviousData: domainSafeValues.keepPreviousData,
       infinite: domainSafeValues.infinite,
       enabled: !!domainParams,
+      isSignedIn: Boolean(organization),
+      initialPage: domainSafeValues.initialPage,
+      pageSize: domainSafeValues.pageSize,
     },
-    {
-      type: 'domains',
-      organizationId: organization?.id,
-    },
-  );
+    keys: createCacheKeys({
+      stablePrefix: 'domains',
+      authenticated: Boolean(organization),
+      tracked: {
+        organizationId: organization?.id,
+      },
+      untracked: {
+        args: domainParams,
+      },
+    }),
+  });
 
-  const membershipRequests = usePagesOrInfinite<
-    GetMembershipRequestParams,
-    ClerkPaginatedResponse<OrganizationMembershipRequestResource>
-  >(
-    {
-      ...membershipRequestParams,
-    },
-    organization?.getMembershipRequests,
-    {
+  const membershipRequests = usePagesOrInfinite({
+    fetcher: organization?.getMembershipRequests,
+    config: {
       keepPreviousData: membershipRequestSafeValues.keepPreviousData,
       infinite: membershipRequestSafeValues.infinite,
       enabled: !!membershipRequestParams,
+      isSignedIn: Boolean(organization),
+      initialPage: membershipRequestSafeValues.initialPage,
+      pageSize: membershipRequestSafeValues.pageSize,
     },
-    {
-      type: 'membershipRequests',
-      organizationId: organization?.id,
-    },
-  );
+    keys: createCacheKeys({
+      stablePrefix: 'membershipRequests',
+      authenticated: Boolean(organization),
+      tracked: {
+        organizationId: organization?.id,
+      },
+      untracked: {
+        args: membershipRequestParams,
+      },
+    }),
+  });
 
-  const memberships = usePagesOrInfinite<GetMembersParams, ClerkPaginatedResponse<OrganizationMembershipResource>>(
-    membersParams || {},
-    organization?.getMemberships,
-    {
+  const memberships = usePagesOrInfinite({
+    fetcher: organization?.getMemberships,
+    config: {
       keepPreviousData: membersSafeValues.keepPreviousData,
       infinite: membersSafeValues.infinite,
       enabled: !!membersParams,
+      isSignedIn: Boolean(organization),
+      initialPage: membersSafeValues.initialPage,
+      pageSize: membersSafeValues.pageSize,
     },
-    {
-      type: 'members',
-      organizationId: organization?.id,
-    },
-  );
+    keys: createCacheKeys({
+      stablePrefix: 'members',
+      authenticated: Boolean(organization),
+      tracked: {
+        organizationId: organization?.id,
+      },
+      untracked: {
+        args: membersParams,
+      },
+    }),
+  });
 
-  const invitations = usePagesOrInfinite<GetInvitationsParams, ClerkPaginatedResponse<OrganizationInvitationResource>>(
-    {
-      ...invitationsParams,
-    },
-    organization?.getInvitations,
-    {
+  const invitations = usePagesOrInfinite({
+    fetcher: organization?.getInvitations,
+    config: {
       keepPreviousData: invitationsSafeValues.keepPreviousData,
       infinite: invitationsSafeValues.infinite,
       enabled: !!invitationsParams,
+      isSignedIn: Boolean(organization),
+      initialPage: invitationsSafeValues.initialPage,
+      pageSize: invitationsSafeValues.pageSize,
     },
-    {
-      type: 'invitations',
-      organizationId: organization?.id,
-    },
-  );
+    keys: createCacheKeys({
+      stablePrefix: 'invitations',
+      authenticated: Boolean(organization),
+      tracked: {
+        organizationId: organization?.id,
+      },
+      untracked: {
+        args: invitationsParams,
+      },
+    }),
+  });
 
   if (organization === undefined) {
     return {