fix conflicts about usePagesOrInfinite.swr

Author: panteliselef

packages/react/src/contexts/ClerkContextProvider.tsx

@@ -93,10 +93,7 @@ export function ClerkContextProvider(props: ClerkContextProvider) {
     <IsomorphicClerkContext.Provider value={clerkCtx}>
       <ClientContext.Provider value={clientCtx}>
         <SessionContext.Provider value={sessionCtx}>
-          <OrganizationProvider
-            // key={clerkStatus + queryStatus}
-            {...organizationCtx.value}
-          >
+          <OrganizationProvider {...organizationCtx.value}>
             <AuthContext.Provider value={authCtx}>
               <UserContext.Provider value={userCtx}>
                 <CheckoutProvider

packages/shared/src/react/hooks/usePageOrInfinite.types.ts

@@ -10,8 +10,17 @@ export type UsePagesOrInfiniteSignature = <
   CacheKeys extends Record<string, unknown> = Record<string, unknown>,
   TConfig extends PagesOrInfiniteConfig = PagesOrInfiniteConfig,
 >(
+  /**
+   * The parameters will be passed to the fetcher.
+   */
   params: Params,
+  /**
+   * A Promise returning function to fetch your data.
+   */
   fetcher: ((p: Params) => FetcherReturnData | Promise<FetcherReturnData>) | undefined,
+  /**
+   * Internal configuration of the hook.
+   */
   config: TConfig,
   cacheKeys: CacheKeys,
 ) => PaginatedResources<ExtractData<FetcherReturnData>, TConfig['infinite']>;

packages/shared/src/react/hooks/usePagesOrInfinite.rq.tsx

@@ -1,8 +1,8 @@
 'use client';
 
-import type { ClerkPaginatedResponse } from '@clerk/types';
 import { useCallback, useMemo, useRef, useState } from 'react';
 
+import type { ClerkPaginatedResponse } from '../../types';
 import { useClerkQueryClient } from '../clerk-rq/use-clerk-query-client';
 import { useClerkInfiniteQuery } from '../clerk-rq/useInfiniteQuery';
 import { useClerkQuery } from '../clerk-rq/useQuery';
@@ -19,8 +19,8 @@ export const usePagesOrInfinite: UsePagesOrInfiniteSignature = (params, fetcher,
 
   const enabled = config.enabled ?? true;
   const triggerInfinite = config.infinite ?? false;
-  // Support keepPreviousData
-  const _keepPreviousData = config.keepPreviousData ?? false;
+  // TODO: Support keepPreviousData
+  // const _keepPreviousData = config.keepPreviousData ?? false;
 
   const [queryClient] = useClerkQueryClient();
 

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

@@ -5,8 +5,31 @@ import { useRef } from 'react';
 import type { PagesOrInfiniteOptions } from '../types';
 
 /**
- * Shared helper to safely merge user-provided pagination options with defaults.
- * Caches initial page and page size for the lifecycle of the component.
+ * A hook that safely merges user-provided pagination options with default values.
+ * It caches initial pagination values (page and size) until component unmount to prevent unwanted rerenders.
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * // Example 1: With user-provided options
+ * const userOptions = { initialPage: 2, pageSize: 20, infinite: true };
+ * const defaults = { initialPage: 1, pageSize: 10, infinite: false };
+ * useWithSafeValues(userOptions, defaults);
+ * // Returns { initialPage: 2, pageSize: 20, infinite: true }
+ *
+ * // Example 2: With boolean true (use defaults)
+ * const params = true;
+ * const defaults = { initialPage: 1, pageSize: 10, infinite: false };
+ * useWithSafeValues(params, defaults);
+ * // Returns { initialPage: 1, pageSize: 10, infinite: false }
+ *
+ * // Example 3: With undefined options (fallback to defaults)
+ * const params = undefined;
+ * const defaults = { initialPage: 1, pageSize: 10, infinite: false };
+ * useWithSafeValues(params, defaults);
+ * // Returns { initialPage: 1, pageSize: 10, infinite: false }
+ * ```
  */
 export const useWithSafeValues = <T extends PagesOrInfiniteOptions>(params: T | true | undefined, defaultValues: T) => {
   const shouldUseDefaults = typeof params === 'boolean' && params;
@@ -33,6 +56,21 @@ export const useWithSafeValues = <T extends PagesOrInfiniteOptions>(params: T |
 /**
  * Returns an object containing only the keys from the first object that are not present in the second object.
  * Useful for extracting unique parameters that should be passed to a request while excluding common cache keys.
+ *
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * // Example 1: Basic usage
+ * const obj1 = { name: 'John', age: 30, city: 'NY' };
+ * const obj2 = { name: 'John', age: 30 };
+ * getDifferentKeys(obj1, obj2); // Returns { city: 'NY' }
+ *
+ * // Example 2: With cache keys
+ * const requestParams = { page: 1, limit: 10, userId: '123' };
+ * const cacheKeys = { userId: '123' };
+ * getDifferentKeys(requestParams, cacheKeys); // Returns { page: 1, limit: 10 }
+ * ```
  */
 export function getDifferentKeys(
   obj1: Record<string, unknown>,

packages/shared/src/react/hooks/usePagesOrInfinite.swr.tsx

@@ -6,12 +6,29 @@ import { useSWR, useSWRInfinite } from '../clerk-swr';
 import type { CacheSetter, ValueOrSetter } from '../types';
 import type { UsePagesOrInfiniteSignature } from './usePageOrInfinite.types';
 import { getDifferentKeys, useWithSafeValues } from './usePagesOrInfinite.shared';
+import { usePreviousValue } from './usePreviousValue';
 
 const cachingSWROptions = {
   dedupingInterval: 1000 * 60,
   focusThrottleInterval: 1000 * 60 * 2,
 } satisfies Parameters<typeof useSWR>[2];
 
+/**
+ * A flexible pagination hook that supports both traditional pagination and infinite loading.
+ * It provides a unified API for handling paginated data fetching, with built-in caching through SWR.
+ * The hook can operate in two modes:
+ * - Traditional pagination: Fetches one page at a time with page navigation
+ * - Infinite loading: Accumulates data as more pages are loaded.
+ *
+ * Features:
+ * - Cache management with SWR
+ * - Loading and error states
+ * - Page navigation helpers
+ * - Data revalidation and updates
+ * - Support for keeping previous data while loading.
+ *
+ * @internal
+ */
 export const usePagesOrInfinite: UsePagesOrInfiniteSignature = (params, fetcher, config, cacheKeys) => {
   const [paginatedPage, setPaginatedPage] = useState(params.initialPage ?? 1);
 
@@ -32,8 +49,35 @@ export const usePagesOrInfinite: UsePagesOrInfiniteSignature = (params, fetcher,
     pageSize: pageSizeRef.current,
   };
 
+  const previousIsSignedIn = usePreviousValue(isSignedIn);
+
+  // cacheMode being `true` indicates that the cache key is defined, but the fetcher is not.
+  // This allows to ready the cache instead of firing a request.
   const shouldFetch = !triggerInfinite && enabled && (!cacheMode ? !!fetcher : true);
-  const swrKey = isSignedIn ? pagesCacheKey : shouldFetch ? pagesCacheKey : null;
+
+  // Attention:
+  //
+  // This complex logic is necessary to ensure that the cached data is not used when the user is signed out.
+  // `useSWR` with `key` set to `null` and `keepPreviousData` set to `true` will return the previous cached data until the hook unmounts.
+  // So for hooks that render authenticated data, we need to ensure that the cached data is not used when the user is signed out.
+  //
+  // 1. Fetcher should not fire if user is signed out on mount. (fetcher does not run, loading states are not triggered)
+  // 2. If user was signed in and then signed out, cached data should become null. (fetcher runs and returns null, loading states are triggered)
+  //
+  // We achieve (2) by setting the key to the cache key when the user transitions to signed out and forcing the fetcher to return null.
+  const swrKey =
+    typeof isSignedIn === 'boolean'
+      ? previousIsSignedIn === true && isSignedIn === false
+        ? pagesCacheKey
+        : isSignedIn
+          ? shouldFetch
+            ? pagesCacheKey
+            : null
+          : null
+      : shouldFetch
+        ? pagesCacheKey
+        : null;
+
   const swrFetcher =
     !cacheMode && !!fetcher
       ? (cacheKeyParams: Record<string, unknown>) => {
@@ -53,6 +97,22 @@ export const usePagesOrInfinite: UsePagesOrInfiniteSignature = (params, fetcher,
     mutate: swrMutate,
   } = useSWR(swrKey, swrFetcher, { keepPreviousData, ...cachingSWROptions });
 
+  // Attention:
+  //
+  // Cache behavior for infinite loading when signing out:
+  //
+  // Unlike `useSWR` above (which requires complex transition handling), `useSWRInfinite` has simpler sign-out semantics:
+  // 1. When user is signed out on mount, the key getter returns `null`, preventing any fetches.
+  // 2. When user transitions from signed in to signed out, the key getter returns `null` for all page indices.
+  // 3. When `useSWRInfinite`'s key getter returns `null`, SWR will not fetch data and considers that page invalid.
+  // 4. Unlike paginated mode, `useSWRInfinite` does not support `keepPreviousData`, so there's no previous data retention.
+  //
+  // This simpler behavior works because:
+  // - `useSWRInfinite` manages multiple pages internally, each with its own cache key
+  // - When the key getter returns `null`, all page fetches are prevented and pages become invalid
+  // - Without `keepPreviousData`, the hook will naturally reflect the empty/invalid state
+  //
+  // Result: No special transition logic needed - just return `null` from key getter when `isSignedIn === false`.
   const {
     data: swrInfiniteData,
     isLoading: swrInfiniteIsLoading,
@@ -63,7 +123,7 @@ export const usePagesOrInfinite: UsePagesOrInfiniteSignature = (params, fetcher,
     mutate: swrInfiniteMutate,
   } = useSWRInfinite(
     pageIndex => {
-      if (!triggerInfinite || !enabled) {
+      if (!triggerInfinite || !enabled || isSignedIn === false) {
         return null;
       }
 
@@ -75,9 +135,9 @@ export const usePagesOrInfinite: UsePagesOrInfiniteSignature = (params, fetcher,
       };
     },
     cacheKeyParams => {
-      // @ts-ignore - swr provider passes back cacheKey object, compute fetcher params
+      // @ts-ignore - remove cache-only keys from request params
       const requestParams = getDifferentKeys(cacheKeyParams, cacheKeys);
-      // @ts-ignore - params narrowing deferred to fetcher time
+      // @ts-ignore - fetcher expects Params subset; narrowing at call-site
       return fetcher?.(requestParams);
     },
     cachingSWROptions,
@@ -160,7 +220,9 @@ export const usePagesOrInfinite: UsePagesOrInfiniteSignature = (params, fetcher,
     fetchPrevious,
     hasNextPage,
     hasPreviousPage,
+    // Let the hook return type define this type
     revalidate: revalidate as any,
+    // Let the hook return type define this type
     setData: setData as any,
   };
 };