feat(shared): Lax revalidation for RQ variant hooks

.changeset/young-impalas-grab.md

@@ -0,0 +1,14 @@
+---
+'@clerk/shared': patch
+---
+
+Relaxing requirements for RQ variant hooks to enable revalidation across different configurations of the same hook.
+
+```tsx
+
+const { revalidate } = useStatements({ initialPage: 1, pageSize: 10 });
+useStatements({ initialPage: 1, pageSize: 12 });
+
+// revalidate from first hook, now invalidates the second hook.
+void revalidate();
+```

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

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { ClerkResource } from '../../../types';
@@ -486,4 +486,66 @@ describe('createBillingPaginatedHook', () => {
  expect(result.current.pageCount).toBe(5);
  });
  });
+
+ describe('revalidate behavior', () => {
+ it('revalidate fetches fresh data for authenticated hook', async () => {
+ fetcherMock
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' } as DummyResource, { id: 'initial-2' } as DummyResource],
+ total_count: 2,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' } as DummyResource, { id: 'refetched-2' } as DummyResource],
+ total_count: 2,
+ });
+
+ const { result } = renderHook(() => useDummyAuth({ initialPage: 1, pageSize: 2 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }, { id: 'initial-2' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }, { id: 'refetched-2' }]));
+ expect(fetcherMock).toHaveBeenCalledTimes(2);
+ });
+
+ it('revalidate propagates to infinite counterpart only for React Query', async () => {
+ let seq = 0;
+ fetcherMock.mockImplementation(async (params: DummyParams) => {
+ seq++;
+ return {
+ data: Array.from({ length: params.pageSize ?? 2 }, (_, i) => ({
+ id: `item-${params.initialPage ?? 1}-${seq}-${i}`,
+ })) as DummyResource[],
+ total_count: 10,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useDummyAuth({ initialPage: 1, pageSize: 2 });
+ const infinite = useDummyAuth({ initialPage: 1, pageSize: 2, infinite: true } as any);
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcherMock.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcherMock.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcherMock).toHaveBeenCalledTimes(1));
+ }
+ });
+ });
 });

packages/shared/src/react/hooks/__tests__/useAPIKeys.spec.tsx

@@ -0,0 +1,213 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useAPIKeys } from '../useAPIKeys';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const getAllSpy = vi.fn(
+ async () =>
+ ({
+ data: [],
+ total_count: 0,
+ }) as { data: Array<Record<string, unknown>>; total_count: number },
+);
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ apiKeys: {
+ getAll: getAllSpy,
+ },
+ queryClient: defaultQueryClient,
+});
+
+vi.mock('../../contexts', () => {
+ return {
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ };
+});
+
+describe('useApiKeys', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ mockClerk.user = { id: 'user_1' };
+ });
+
+ it('revalidate fetches fresh API keys', async () => {
+ getAllSpy
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_initial' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_updated' }],
+ total_count: 1,
+ });
+
+ const { result } = renderHook(() => useAPIKeys({ subject: 'user_1', pageSize: 1 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'key_initial' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'key_updated' }]));
+ expect(getAllSpy).toHaveBeenCalledTimes(2);
+ });
+
+ it('cascades revalidation for related queries only when using React Query', async () => {
+ let sequence = 0;
+ getAllSpy.mockImplementation(async ({ initialPage }: { initialPage?: number } = {}) => {
+ sequence += 1;
+ const page = initialPage ?? 1;
+ return {
+ data: [{ id: `key-${page}-${sequence}` }],
+ total_count: 5,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const infinite = useAPIKeys({ subject: 'user_1', pageSize: 1, infinite: true });
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(getAllSpy).toHaveBeenCalledTimes(1));
+ }
+ });
+
+ it('handles revalidation with different pageSize configurations', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ pageSize }: { pageSize?: number } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-pageSize-${pageSize ?? 'unknown'}-${seq}` }],
+ total_count: 3,
+ };
+ });
+
+ const useHooks = () => {
+ const small = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const large = useAPIKeys({ subject: 'user_1', pageSize: 5 });
+ return { small, large };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.small.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.large.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.small.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('handles revalidation with different query filters', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ query }: { query?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-query-${query ?? 'empty'}-${seq}` }],
+ total_count: 2,
+ };
+ });
+
+ const useHooks = () => {
+ const defaultQuery = useAPIKeys({ subject: 'user_1', pageSize: 11, query: '' });
+ const filtered = useAPIKeys({ subject: 'user_1', pageSize: 11, query: 'search' });
+ return { defaultQuery, filtered };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.defaultQuery.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.filtered.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.defaultQuery.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('does not cascade revalidation across different subjects', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ subject }: { subject?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-subject-${subject ?? 'none'}-${seq}` }],
+ total_count: 4,
+ };
+ });
+
+ const useHooks = () => {
+ const primary = useAPIKeys({ subject: 'user_primary', pageSize: 1 });
+ const secondary = useAPIKeys({ subject: 'user_secondary', pageSize: 1 });
+ return { primary, secondary };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.primary.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.secondary.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.primary.revalidate();
+ });
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ const subjects = (getAllSpy.mock.calls as Array<unknown[]>).map(
+ call => (call[0] as { subject?: string } | undefined)?.subject,
+ );
+ expect(subjects).not.toContain('user_secondary');
+ expect(subjects[0] === undefined || subjects[0] === 'user_primary').toBe(true);
+ });
+});

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

@@ -503,6 +503,35 @@ describe('usePagesOrInfinite - behaviors mirrored from useCoreOrganization', ()
 });
 
 describe('usePagesOrInfinite - revalidate behavior', () => {
+ it('refetches current data when revalidate is invoked', async () => {
+ const fetcher = vi
+ .fn()
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' }],
+ total_count: 1,
+ });
+
+ const params = { initialPage: 1, pageSize: 1 };
+ const config = buildConfig(params);
+ const keys = buildKeys('t-revalidate-refresh', params);
+
+ const { result } = renderUsePagesOrInfinite({ fetcher, config, keys });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }]);
+
+ await act(async () => {
+ await (result.current as any).revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }]));
+ expect(fetcher).toHaveBeenCalledTimes(2);
+ });
+
  it('pagination mode: isFetching toggles during revalidate, isLoading stays false after initial load', async () => {
  const deferred = createDeferredPromise();
  let callCount = 0;
@@ -652,6 +681,47 @@ describe('usePagesOrInfinite - revalidate behavior', () => {
  { id: 'p2-1-revalidate' },
  ]);
  });
+
+ it('cascades revalidation to related queries only in React Query mode', async () => {
+ const params = { initialPage: 1, pageSize: 1 };
+ const keys = buildKeys('t-revalidate-cascade', params, { userId: 'user_123' });
+ const fetcher = vi.fn(async ({ initialPage }: any) => ({
+ data: [{ id: `item-${initialPage}-${fetcher.mock.calls.length}` }],
+ total_count: 3,
+ }));
+
+ const useBoth = () => {
+ const paginated = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params),
+ keys,
+ });
+ const infinite = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params, { infinite: true }),
+ keys,
+ });
+
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcher.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcher.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcher).toHaveBeenCalledTimes(1));
+ }
+ });
 });
 
 describe('usePagesOrInfinite - error propagation', () => {

.changeset/young-impalas-grab.md

@@ -0,0 +1,14 @@
+---
+'@clerk/shared': patch
+---
+
+Relaxing requirements for RQ variant hooks to enable revalidation across different configurations of the same hook.
+
+```tsx
+
+const { revalidate } = useStatements({ initialPage: 1, pageSize: 10 });
+useStatements({ initialPage: 1, pageSize: 12 });
+
+// revalidate from first hook, now invalidates the second hook.
+void revalidate();
+```

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

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { ClerkResource } from '../../../types';
@@ -486,4 +486,66 @@ describe('createBillingPaginatedHook', () => {
  expect(result.current.pageCount).toBe(5);
  });
  });
+
+ describe('revalidate behavior', () => {
+ it('revalidate fetches fresh data for authenticated hook', async () => {
+ fetcherMock
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' } as DummyResource, { id: 'initial-2' } as DummyResource],
+ total_count: 2,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' } as DummyResource, { id: 'refetched-2' } as DummyResource],
+ total_count: 2,
+ });
+
+ const { result } = renderHook(() => useDummyAuth({ initialPage: 1, pageSize: 2 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }, { id: 'initial-2' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }, { id: 'refetched-2' }]));
+ expect(fetcherMock).toHaveBeenCalledTimes(2);
+ });
+
+ it('revalidate propagates to infinite counterpart only for React Query', async () => {
+ let seq = 0;
+ fetcherMock.mockImplementation(async (params: DummyParams) => {
+ seq++;
+ return {
+ data: Array.from({ length: params.pageSize ?? 2 }, (_, i) => ({
+ id: `item-${params.initialPage ?? 1}-${seq}-${i}`,
+ })) as DummyResource[],
+ total_count: 10,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useDummyAuth({ initialPage: 1, pageSize: 2 });
+ const infinite = useDummyAuth({ initialPage: 1, pageSize: 2, infinite: true } as any);
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcherMock.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcherMock.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcherMock).toHaveBeenCalledTimes(1));
+ }
+ });
+ });
 });

packages/shared/src/react/hooks/__tests__/useAPIKeys.spec.tsx

@@ -0,0 +1,213 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useAPIKeys } from '../useAPIKeys';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const getAllSpy = vi.fn(
+ async () =>
+ ({
+ data: [],
+ total_count: 0,
+ }) as { data: Array<Record<string, unknown>>; total_count: number },
+);
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ apiKeys: {
+ getAll: getAllSpy,
+ },
+ queryClient: defaultQueryClient,
+});
+
+vi.mock('../../contexts', () => {
+ return {
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ };
+});
+
+describe('useApiKeys', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ mockClerk.user = { id: 'user_1' };
+ });
+
+ it('revalidate fetches fresh API keys', async () => {
+ getAllSpy
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_initial' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_updated' }],
+ total_count: 1,
+ });
+
+ const { result } = renderHook(() => useAPIKeys({ subject: 'user_1', pageSize: 1 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'key_initial' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'key_updated' }]));
+ expect(getAllSpy).toHaveBeenCalledTimes(2);
+ });
+
+ it('cascades revalidation for related queries only when using React Query', async () => {
+ let sequence = 0;
+ getAllSpy.mockImplementation(async ({ initialPage }: { initialPage?: number } = {}) => {
+ sequence += 1;
+ const page = initialPage ?? 1;
+ return {
+ data: [{ id: `key-${page}-${sequence}` }],
+ total_count: 5,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const infinite = useAPIKeys({ subject: 'user_1', pageSize: 1, infinite: true });
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(getAllSpy).toHaveBeenCalledTimes(1));
+ }
+ });
+
+ it('handles revalidation with different pageSize configurations', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ pageSize }: { pageSize?: number } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-pageSize-${pageSize ?? 'unknown'}-${seq}` }],
+ total_count: 3,
+ };
+ });
+
+ const useHooks = () => {
+ const small = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const large = useAPIKeys({ subject: 'user_1', pageSize: 5 });
+ return { small, large };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.small.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.large.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.small.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('handles revalidation with different query filters', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ query }: { query?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-query-${query ?? 'empty'}-${seq}` }],
+ total_count: 2,
+ };
+ });
+
+ const useHooks = () => {
+ const defaultQuery = useAPIKeys({ subject: 'user_1', pageSize: 11, query: '' });
+ const filtered = useAPIKeys({ subject: 'user_1', pageSize: 11, query: 'search' });
+ return { defaultQuery, filtered };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.defaultQuery.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.filtered.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.defaultQuery.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('does not cascade revalidation across different subjects', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ subject }: { subject?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-subject-${subject ?? 'none'}-${seq}` }],
+ total_count: 4,
+ };
+ });
+
+ const useHooks = () => {
+ const primary = useAPIKeys({ subject: 'user_primary', pageSize: 1 });
+ const secondary = useAPIKeys({ subject: 'user_secondary', pageSize: 1 });
+ return { primary, secondary };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.primary.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.secondary.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.primary.revalidate();
+ });
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ const subjects = (getAllSpy.mock.calls as Array<unknown[]>).map(
+ call => (call[0] as { subject?: string } | undefined)?.subject,
+ );
+ expect(subjects).not.toContain('user_secondary');
+ expect(subjects[0] === undefined || subjects[0] === 'user_primary').toBe(true);
+ });
+});

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

@@ -503,6 +503,35 @@ describe('usePagesOrInfinite - behaviors mirrored from useCoreOrganization', ()
 });
 
 describe('usePagesOrInfinite - revalidate behavior', () => {
+ it('refetches current data when revalidate is invoked', async () => {
+ const fetcher = vi
+ .fn()
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' }],
+ total_count: 1,
+ });
+
+ const params = { initialPage: 1, pageSize: 1 };
+ const config = buildConfig(params);
+ const keys = buildKeys('t-revalidate-refresh', params);
+
+ const { result } = renderUsePagesOrInfinite({ fetcher, config, keys });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }]);
+
+ await act(async () => {
+ await (result.current as any).revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }]));
+ expect(fetcher).toHaveBeenCalledTimes(2);
+ });
+
  it('pagination mode: isFetching toggles during revalidate, isLoading stays false after initial load', async () => {
  const deferred = createDeferredPromise();
  let callCount = 0;
@@ -652,6 +681,47 @@ describe('usePagesOrInfinite - revalidate behavior', () => {
  { id: 'p2-1-revalidate' },
  ]);
  });
+
+ it('cascades revalidation to related queries only in React Query mode', async () => {
+ const params = { initialPage: 1, pageSize: 1 };
+ const keys = buildKeys('t-revalidate-cascade', params, { userId: 'user_123' });
+ const fetcher = vi.fn(async ({ initialPage }: any) => ({
+ data: [{ id: `item-${initialPage}-${fetcher.mock.calls.length}` }],
+ total_count: 3,
+ }));
+
+ const useBoth = () => {
+ const paginated = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params),
+ keys,
+ });
+ const infinite = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params, { infinite: true }),
+ keys,
+ });
+
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcher.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcher.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcher).toHaveBeenCalledTimes(1));
+ }
+ });
 });
 
 describe('usePagesOrInfinite - error propagation', () => {

.changeset/young-impalas-grab.md

@@ -0,0 +1,14 @@
+---
+'@clerk/shared': patch
+---
+
+Relaxing requirements for RQ variant hooks to enable revalidation across different configurations of the same hook.
+
+```tsx
+
+const { revalidate } = useStatements({ initialPage: 1, pageSize: 10 });
+useStatements({ initialPage: 1, pageSize: 12 });
+
+// revalidate from first hook, now invalidates the second hook.
+void revalidate();
+```

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

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { ClerkResource } from '../../../types';
@@ -486,4 +486,66 @@ describe('createBillingPaginatedHook', () => {
  expect(result.current.pageCount).toBe(5);
  });
  });
+
+ describe('revalidate behavior', () => {
+ it('revalidate fetches fresh data for authenticated hook', async () => {
+ fetcherMock
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' } as DummyResource, { id: 'initial-2' } as DummyResource],
+ total_count: 2,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' } as DummyResource, { id: 'refetched-2' } as DummyResource],
+ total_count: 2,
+ });
+
+ const { result } = renderHook(() => useDummyAuth({ initialPage: 1, pageSize: 2 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }, { id: 'initial-2' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }, { id: 'refetched-2' }]));
+ expect(fetcherMock).toHaveBeenCalledTimes(2);
+ });
+
+ it('revalidate propagates to infinite counterpart only for React Query', async () => {
+ let seq = 0;
+ fetcherMock.mockImplementation(async (params: DummyParams) => {
+ seq++;
+ return {
+ data: Array.from({ length: params.pageSize ?? 2 }, (_, i) => ({
+ id: `item-${params.initialPage ?? 1}-${seq}-${i}`,
+ })) as DummyResource[],
+ total_count: 10,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useDummyAuth({ initialPage: 1, pageSize: 2 });
+ const infinite = useDummyAuth({ initialPage: 1, pageSize: 2, infinite: true } as any);
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcherMock.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcherMock.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcherMock).toHaveBeenCalledTimes(1));
+ }
+ });
+ });
 });

packages/shared/src/react/hooks/__tests__/useAPIKeys.spec.tsx

@@ -0,0 +1,213 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useAPIKeys } from '../useAPIKeys';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const getAllSpy = vi.fn(
+ async () =>
+ ({
+ data: [],
+ total_count: 0,
+ }) as { data: Array<Record<string, unknown>>; total_count: number },
+);
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ apiKeys: {
+ getAll: getAllSpy,
+ },
+ queryClient: defaultQueryClient,
+});
+
+vi.mock('../../contexts', () => {
+ return {
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ };
+});
+
+describe('useApiKeys', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ mockClerk.user = { id: 'user_1' };
+ });
+
+ it('revalidate fetches fresh API keys', async () => {
+ getAllSpy
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_initial' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_updated' }],
+ total_count: 1,
+ });
+
+ const { result } = renderHook(() => useAPIKeys({ subject: 'user_1', pageSize: 1 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'key_initial' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'key_updated' }]));
+ expect(getAllSpy).toHaveBeenCalledTimes(2);
+ });
+
+ it('cascades revalidation for related queries only when using React Query', async () => {
+ let sequence = 0;
+ getAllSpy.mockImplementation(async ({ initialPage }: { initialPage?: number } = {}) => {
+ sequence += 1;
+ const page = initialPage ?? 1;
+ return {
+ data: [{ id: `key-${page}-${sequence}` }],
+ total_count: 5,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const infinite = useAPIKeys({ subject: 'user_1', pageSize: 1, infinite: true });
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(getAllSpy).toHaveBeenCalledTimes(1));
+ }
+ });
+
+ it('handles revalidation with different pageSize configurations', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ pageSize }: { pageSize?: number } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-pageSize-${pageSize ?? 'unknown'}-${seq}` }],
+ total_count: 3,
+ };
+ });
+
+ const useHooks = () => {
+ const small = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const large = useAPIKeys({ subject: 'user_1', pageSize: 5 });
+ return { small, large };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.small.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.large.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.small.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('handles revalidation with different query filters', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ query }: { query?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-query-${query ?? 'empty'}-${seq}` }],
+ total_count: 2,
+ };
+ });
+
+ const useHooks = () => {
+ const defaultQuery = useAPIKeys({ subject: 'user_1', pageSize: 11, query: '' });
+ const filtered = useAPIKeys({ subject: 'user_1', pageSize: 11, query: 'search' });
+ return { defaultQuery, filtered };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.defaultQuery.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.filtered.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.defaultQuery.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('does not cascade revalidation across different subjects', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ subject }: { subject?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-subject-${subject ?? 'none'}-${seq}` }],
+ total_count: 4,
+ };
+ });
+
+ const useHooks = () => {
+ const primary = useAPIKeys({ subject: 'user_primary', pageSize: 1 });
+ const secondary = useAPIKeys({ subject: 'user_secondary', pageSize: 1 });
+ return { primary, secondary };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.primary.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.secondary.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.primary.revalidate();
+ });
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ const subjects = (getAllSpy.mock.calls as Array<unknown[]>).map(
+ call => (call[0] as { subject?: string } | undefined)?.subject,
+ );
+ expect(subjects).not.toContain('user_secondary');
+ expect(subjects[0] === undefined || subjects[0] === 'user_primary').toBe(true);
+ });
+});

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

@@ -503,6 +503,35 @@ describe('usePagesOrInfinite - behaviors mirrored from useCoreOrganization', ()
 });
 
 describe('usePagesOrInfinite - revalidate behavior', () => {
+ it('refetches current data when revalidate is invoked', async () => {
+ const fetcher = vi
+ .fn()
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' }],
+ total_count: 1,
+ });
+
+ const params = { initialPage: 1, pageSize: 1 };
+ const config = buildConfig(params);
+ const keys = buildKeys('t-revalidate-refresh', params);
+
+ const { result } = renderUsePagesOrInfinite({ fetcher, config, keys });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }]);
+
+ await act(async () => {
+ await (result.current as any).revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }]));
+ expect(fetcher).toHaveBeenCalledTimes(2);
+ });
+
  it('pagination mode: isFetching toggles during revalidate, isLoading stays false after initial load', async () => {
  const deferred = createDeferredPromise();
  let callCount = 0;
@@ -652,6 +681,47 @@ describe('usePagesOrInfinite - revalidate behavior', () => {
  { id: 'p2-1-revalidate' },
  ]);
  });
+
+ it('cascades revalidation to related queries only in React Query mode', async () => {
+ const params = { initialPage: 1, pageSize: 1 };
+ const keys = buildKeys('t-revalidate-cascade', params, { userId: 'user_123' });
+ const fetcher = vi.fn(async ({ initialPage }: any) => ({
+ data: [{ id: `item-${initialPage}-${fetcher.mock.calls.length}` }],
+ total_count: 3,
+ }));
+
+ const useBoth = () => {
+ const paginated = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params),
+ keys,
+ });
+ const infinite = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params, { infinite: true }),
+ keys,
+ });
+
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcher.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcher.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcher).toHaveBeenCalledTimes(1));
+ }
+ });
 });
 
 describe('usePagesOrInfinite - error propagation', () => {

.changeset/young-impalas-grab.md

@@ -0,0 +1,14 @@
+---
+'@clerk/shared': patch
+---
+
+Relaxing requirements for RQ variant hooks to enable revalidation across different configurations of the same hook.
+
+```tsx
+
+const { revalidate } = useStatements({ initialPage: 1, pageSize: 10 });
+useStatements({ initialPage: 1, pageSize: 12 });
+
+// revalidate from first hook, now invalidates the second hook.
+void revalidate();
+```

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

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { ClerkResource } from '../../../types';
@@ -486,4 +486,66 @@ describe('createBillingPaginatedHook', () => {
  expect(result.current.pageCount).toBe(5);
  });
  });
+
+ describe('revalidate behavior', () => {
+ it('revalidate fetches fresh data for authenticated hook', async () => {
+ fetcherMock
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' } as DummyResource, { id: 'initial-2' } as DummyResource],
+ total_count: 2,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' } as DummyResource, { id: 'refetched-2' } as DummyResource],
+ total_count: 2,
+ });
+
+ const { result } = renderHook(() => useDummyAuth({ initialPage: 1, pageSize: 2 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }, { id: 'initial-2' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }, { id: 'refetched-2' }]));
+ expect(fetcherMock).toHaveBeenCalledTimes(2);
+ });
+
+ it('revalidate propagates to infinite counterpart only for React Query', async () => {
+ let seq = 0;
+ fetcherMock.mockImplementation(async (params: DummyParams) => {
+ seq++;
+ return {
+ data: Array.from({ length: params.pageSize ?? 2 }, (_, i) => ({
+ id: `item-${params.initialPage ?? 1}-${seq}-${i}`,
+ })) as DummyResource[],
+ total_count: 10,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useDummyAuth({ initialPage: 1, pageSize: 2 });
+ const infinite = useDummyAuth({ initialPage: 1, pageSize: 2, infinite: true } as any);
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcherMock.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcherMock.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcherMock).toHaveBeenCalledTimes(1));
+ }
+ });
+ });
 });

packages/shared/src/react/hooks/__tests__/useAPIKeys.spec.tsx

@@ -0,0 +1,213 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useAPIKeys } from '../useAPIKeys';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const getAllSpy = vi.fn(
+ async () =>
+ ({
+ data: [],
+ total_count: 0,
+ }) as { data: Array<Record<string, unknown>>; total_count: number },
+);
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ apiKeys: {
+ getAll: getAllSpy,
+ },
+ queryClient: defaultQueryClient,
+});
+
+vi.mock('../../contexts', () => {
+ return {
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ };
+});
+
+describe('useApiKeys', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ mockClerk.user = { id: 'user_1' };
+ });
+
+ it('revalidate fetches fresh API keys', async () => {
+ getAllSpy
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_initial' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_updated' }],
+ total_count: 1,
+ });
+
+ const { result } = renderHook(() => useAPIKeys({ subject: 'user_1', pageSize: 1 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'key_initial' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'key_updated' }]));
+ expect(getAllSpy).toHaveBeenCalledTimes(2);
+ });
+
+ it('cascades revalidation for related queries only when using React Query', async () => {
+ let sequence = 0;
+ getAllSpy.mockImplementation(async ({ initialPage }: { initialPage?: number } = {}) => {
+ sequence += 1;
+ const page = initialPage ?? 1;
+ return {
+ data: [{ id: `key-${page}-${sequence}` }],
+ total_count: 5,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const infinite = useAPIKeys({ subject: 'user_1', pageSize: 1, infinite: true });
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(getAllSpy).toHaveBeenCalledTimes(1));
+ }
+ });
+
+ it('handles revalidation with different pageSize configurations', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ pageSize }: { pageSize?: number } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-pageSize-${pageSize ?? 'unknown'}-${seq}` }],
+ total_count: 3,
+ };
+ });
+
+ const useHooks = () => {
+ const small = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const large = useAPIKeys({ subject: 'user_1', pageSize: 5 });
+ return { small, large };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.small.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.large.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.small.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('handles revalidation with different query filters', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ query }: { query?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-query-${query ?? 'empty'}-${seq}` }],
+ total_count: 2,
+ };
+ });
+
+ const useHooks = () => {
+ const defaultQuery = useAPIKeys({ subject: 'user_1', pageSize: 11, query: '' });
+ const filtered = useAPIKeys({ subject: 'user_1', pageSize: 11, query: 'search' });
+ return { defaultQuery, filtered };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.defaultQuery.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.filtered.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.defaultQuery.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('does not cascade revalidation across different subjects', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ subject }: { subject?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-subject-${subject ?? 'none'}-${seq}` }],
+ total_count: 4,
+ };
+ });
+
+ const useHooks = () => {
+ const primary = useAPIKeys({ subject: 'user_primary', pageSize: 1 });
+ const secondary = useAPIKeys({ subject: 'user_secondary', pageSize: 1 });
+ return { primary, secondary };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.primary.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.secondary.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.primary.revalidate();
+ });
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ const subjects = (getAllSpy.mock.calls as Array<unknown[]>).map(
+ call => (call[0] as { subject?: string } | undefined)?.subject,
+ );
+ expect(subjects).not.toContain('user_secondary');
+ expect(subjects[0] === undefined || subjects[0] === 'user_primary').toBe(true);
+ });
+});

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

@@ -503,6 +503,35 @@ describe('usePagesOrInfinite - behaviors mirrored from useCoreOrganization', ()
 });
 
 describe('usePagesOrInfinite - revalidate behavior', () => {
+ it('refetches current data when revalidate is invoked', async () => {
+ const fetcher = vi
+ .fn()
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' }],
+ total_count: 1,
+ });
+
+ const params = { initialPage: 1, pageSize: 1 };
+ const config = buildConfig(params);
+ const keys = buildKeys('t-revalidate-refresh', params);
+
+ const { result } = renderUsePagesOrInfinite({ fetcher, config, keys });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }]);
+
+ await act(async () => {
+ await (result.current as any).revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }]));
+ expect(fetcher).toHaveBeenCalledTimes(2);
+ });
+
  it('pagination mode: isFetching toggles during revalidate, isLoading stays false after initial load', async () => {
  const deferred = createDeferredPromise();
  let callCount = 0;
@@ -652,6 +681,47 @@ describe('usePagesOrInfinite - revalidate behavior', () => {
  { id: 'p2-1-revalidate' },
  ]);
  });
+
+ it('cascades revalidation to related queries only in React Query mode', async () => {
+ const params = { initialPage: 1, pageSize: 1 };
+ const keys = buildKeys('t-revalidate-cascade', params, { userId: 'user_123' });
+ const fetcher = vi.fn(async ({ initialPage }: any) => ({
+ data: [{ id: `item-${initialPage}-${fetcher.mock.calls.length}` }],
+ total_count: 3,
+ }));
+
+ const useBoth = () => {
+ const paginated = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params),
+ keys,
+ });
+ const infinite = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params, { infinite: true }),
+ keys,
+ });
+
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcher.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcher.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcher).toHaveBeenCalledTimes(1));
+ }
+ });
 });
 
 describe('usePagesOrInfinite - error propagation', () => {

.changeset/young-impalas-grab.md

@@ -0,0 +1,14 @@
+---
+'@clerk/shared': patch
+---
+
+Relaxing requirements for RQ variant hooks to enable revalidation across different configurations of the same hook.
+
+```tsx
+
+const { revalidate } = useStatements({ initialPage: 1, pageSize: 10 });
+useStatements({ initialPage: 1, pageSize: 12 });
+
+// revalidate from first hook, now invalidates the second hook.
+void revalidate();
+```

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

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { ClerkResource } from '../../../types';
@@ -486,4 +486,66 @@ describe('createBillingPaginatedHook', () => {
  expect(result.current.pageCount).toBe(5);
  });
  });
+
+ describe('revalidate behavior', () => {
+ it('revalidate fetches fresh data for authenticated hook', async () => {
+ fetcherMock
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' } as DummyResource, { id: 'initial-2' } as DummyResource],
+ total_count: 2,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' } as DummyResource, { id: 'refetched-2' } as DummyResource],
+ total_count: 2,
+ });
+
+ const { result } = renderHook(() => useDummyAuth({ initialPage: 1, pageSize: 2 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }, { id: 'initial-2' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }, { id: 'refetched-2' }]));
+ expect(fetcherMock).toHaveBeenCalledTimes(2);
+ });
+
+ it('revalidate propagates to infinite counterpart only for React Query', async () => {
+ let seq = 0;
+ fetcherMock.mockImplementation(async (params: DummyParams) => {
+ seq++;
+ return {
+ data: Array.from({ length: params.pageSize ?? 2 }, (_, i) => ({
+ id: `item-${params.initialPage ?? 1}-${seq}-${i}`,
+ })) as DummyResource[],
+ total_count: 10,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useDummyAuth({ initialPage: 1, pageSize: 2 });
+ const infinite = useDummyAuth({ initialPage: 1, pageSize: 2, infinite: true } as any);
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcherMock.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcherMock.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcherMock).toHaveBeenCalledTimes(1));
+ }
+ });
+ });
 });

packages/shared/src/react/hooks/__tests__/useAPIKeys.spec.tsx

@@ -0,0 +1,213 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useAPIKeys } from '../useAPIKeys';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const getAllSpy = vi.fn(
+ async () =>
+ ({
+ data: [],
+ total_count: 0,
+ }) as { data: Array<Record<string, unknown>>; total_count: number },
+);
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ apiKeys: {
+ getAll: getAllSpy,
+ },
+ queryClient: defaultQueryClient,
+});
+
+vi.mock('../../contexts', () => {
+ return {
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ };
+});
+
+describe('useApiKeys', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ mockClerk.user = { id: 'user_1' };
+ });
+
+ it('revalidate fetches fresh API keys', async () => {
+ getAllSpy
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_initial' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_updated' }],
+ total_count: 1,
+ });
+
+ const { result } = renderHook(() => useAPIKeys({ subject: 'user_1', pageSize: 1 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'key_initial' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'key_updated' }]));
+ expect(getAllSpy).toHaveBeenCalledTimes(2);
+ });
+
+ it('cascades revalidation for related queries only when using React Query', async () => {
+ let sequence = 0;
+ getAllSpy.mockImplementation(async ({ initialPage }: { initialPage?: number } = {}) => {
+ sequence += 1;
+ const page = initialPage ?? 1;
+ return {
+ data: [{ id: `key-${page}-${sequence}` }],
+ total_count: 5,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const infinite = useAPIKeys({ subject: 'user_1', pageSize: 1, infinite: true });
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(getAllSpy).toHaveBeenCalledTimes(1));
+ }
+ });
+
+ it('handles revalidation with different pageSize configurations', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ pageSize }: { pageSize?: number } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-pageSize-${pageSize ?? 'unknown'}-${seq}` }],
+ total_count: 3,
+ };
+ });
+
+ const useHooks = () => {
+ const small = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const large = useAPIKeys({ subject: 'user_1', pageSize: 5 });
+ return { small, large };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.small.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.large.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.small.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('handles revalidation with different query filters', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ query }: { query?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-query-${query ?? 'empty'}-${seq}` }],
+ total_count: 2,
+ };
+ });
+
+ const useHooks = () => {
+ const defaultQuery = useAPIKeys({ subject: 'user_1', pageSize: 11, query: '' });
+ const filtered = useAPIKeys({ subject: 'user_1', pageSize: 11, query: 'search' });
+ return { defaultQuery, filtered };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.defaultQuery.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.filtered.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.defaultQuery.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('does not cascade revalidation across different subjects', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ subject }: { subject?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-subject-${subject ?? 'none'}-${seq}` }],
+ total_count: 4,
+ };
+ });
+
+ const useHooks = () => {
+ const primary = useAPIKeys({ subject: 'user_primary', pageSize: 1 });
+ const secondary = useAPIKeys({ subject: 'user_secondary', pageSize: 1 });
+ return { primary, secondary };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.primary.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.secondary.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.primary.revalidate();
+ });
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ const subjects = (getAllSpy.mock.calls as Array<unknown[]>).map(
+ call => (call[0] as { subject?: string } | undefined)?.subject,
+ );
+ expect(subjects).not.toContain('user_secondary');
+ expect(subjects[0] === undefined || subjects[0] === 'user_primary').toBe(true);
+ });
+});

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

@@ -503,6 +503,35 @@ describe('usePagesOrInfinite - behaviors mirrored from useCoreOrganization', ()
 });
 
 describe('usePagesOrInfinite - revalidate behavior', () => {
+ it('refetches current data when revalidate is invoked', async () => {
+ const fetcher = vi
+ .fn()
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' }],
+ total_count: 1,
+ });
+
+ const params = { initialPage: 1, pageSize: 1 };
+ const config = buildConfig(params);
+ const keys = buildKeys('t-revalidate-refresh', params);
+
+ const { result } = renderUsePagesOrInfinite({ fetcher, config, keys });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }]);
+
+ await act(async () => {
+ await (result.current as any).revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }]));
+ expect(fetcher).toHaveBeenCalledTimes(2);
+ });
+
  it('pagination mode: isFetching toggles during revalidate, isLoading stays false after initial load', async () => {
  const deferred = createDeferredPromise();
  let callCount = 0;
@@ -652,6 +681,47 @@ describe('usePagesOrInfinite - revalidate behavior', () => {
  { id: 'p2-1-revalidate' },
  ]);
  });
+
+ it('cascades revalidation to related queries only in React Query mode', async () => {
+ const params = { initialPage: 1, pageSize: 1 };
+ const keys = buildKeys('t-revalidate-cascade', params, { userId: 'user_123' });
+ const fetcher = vi.fn(async ({ initialPage }: any) => ({
+ data: [{ id: `item-${initialPage}-${fetcher.mock.calls.length}` }],
+ total_count: 3,
+ }));
+
+ const useBoth = () => {
+ const paginated = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params),
+ keys,
+ });
+ const infinite = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params, { infinite: true }),
+ keys,
+ });
+
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcher.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcher.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcher).toHaveBeenCalledTimes(1));
+ }
+ });
 });
 
 describe('usePagesOrInfinite - error propagation', () => {

.changeset/young-impalas-grab.md

@@ -0,0 +1,14 @@
+---
+'@clerk/shared': patch
+---
+
+Relaxing requirements for RQ variant hooks to enable revalidation across different configurations of the same hook.
+
+```tsx
+
+const { revalidate } = useStatements({ initialPage: 1, pageSize: 10 });
+useStatements({ initialPage: 1, pageSize: 12 });
+
+// revalidate from first hook, now invalidates the second hook.
+void revalidate();
+```

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

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { ClerkResource } from '../../../types';
@@ -486,4 +486,66 @@ describe('createBillingPaginatedHook', () => {
  expect(result.current.pageCount).toBe(5);
  });
  });
+
+ describe('revalidate behavior', () => {
+ it('revalidate fetches fresh data for authenticated hook', async () => {
+ fetcherMock
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' } as DummyResource, { id: 'initial-2' } as DummyResource],
+ total_count: 2,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' } as DummyResource, { id: 'refetched-2' } as DummyResource],
+ total_count: 2,
+ });
+
+ const { result } = renderHook(() => useDummyAuth({ initialPage: 1, pageSize: 2 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }, { id: 'initial-2' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }, { id: 'refetched-2' }]));
+ expect(fetcherMock).toHaveBeenCalledTimes(2);
+ });
+
+ it('revalidate propagates to infinite counterpart only for React Query', async () => {
+ let seq = 0;
+ fetcherMock.mockImplementation(async (params: DummyParams) => {
+ seq++;
+ return {
+ data: Array.from({ length: params.pageSize ?? 2 }, (_, i) => ({
+ id: `item-${params.initialPage ?? 1}-${seq}-${i}`,
+ })) as DummyResource[],
+ total_count: 10,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useDummyAuth({ initialPage: 1, pageSize: 2 });
+ const infinite = useDummyAuth({ initialPage: 1, pageSize: 2, infinite: true } as any);
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcherMock.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcherMock.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcherMock).toHaveBeenCalledTimes(1));
+ }
+ });
+ });
 });

packages/shared/src/react/hooks/__tests__/useAPIKeys.spec.tsx

@@ -0,0 +1,213 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useAPIKeys } from '../useAPIKeys';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const getAllSpy = vi.fn(
+ async () =>
+ ({
+ data: [],
+ total_count: 0,
+ }) as { data: Array<Record<string, unknown>>; total_count: number },
+);
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ apiKeys: {
+ getAll: getAllSpy,
+ },
+ queryClient: defaultQueryClient,
+});
+
+vi.mock('../../contexts', () => {
+ return {
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ };
+});
+
+describe('useApiKeys', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ mockClerk.user = { id: 'user_1' };
+ });
+
+ it('revalidate fetches fresh API keys', async () => {
+ getAllSpy
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_initial' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_updated' }],
+ total_count: 1,
+ });
+
+ const { result } = renderHook(() => useAPIKeys({ subject: 'user_1', pageSize: 1 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'key_initial' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'key_updated' }]));
+ expect(getAllSpy).toHaveBeenCalledTimes(2);
+ });
+
+ it('cascades revalidation for related queries only when using React Query', async () => {
+ let sequence = 0;
+ getAllSpy.mockImplementation(async ({ initialPage }: { initialPage?: number } = {}) => {
+ sequence += 1;
+ const page = initialPage ?? 1;
+ return {
+ data: [{ id: `key-${page}-${sequence}` }],
+ total_count: 5,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const infinite = useAPIKeys({ subject: 'user_1', pageSize: 1, infinite: true });
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(getAllSpy).toHaveBeenCalledTimes(1));
+ }
+ });
+
+ it('handles revalidation with different pageSize configurations', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ pageSize }: { pageSize?: number } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-pageSize-${pageSize ?? 'unknown'}-${seq}` }],
+ total_count: 3,
+ };
+ });
+
+ const useHooks = () => {
+ const small = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const large = useAPIKeys({ subject: 'user_1', pageSize: 5 });
+ return { small, large };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.small.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.large.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.small.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('handles revalidation with different query filters', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ query }: { query?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-query-${query ?? 'empty'}-${seq}` }],
+ total_count: 2,
+ };
+ });
+
+ const useHooks = () => {
+ const defaultQuery = useAPIKeys({ subject: 'user_1', pageSize: 11, query: '' });
+ const filtered = useAPIKeys({ subject: 'user_1', pageSize: 11, query: 'search' });
+ return { defaultQuery, filtered };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.defaultQuery.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.filtered.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.defaultQuery.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('does not cascade revalidation across different subjects', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ subject }: { subject?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-subject-${subject ?? 'none'}-${seq}` }],
+ total_count: 4,
+ };
+ });
+
+ const useHooks = () => {
+ const primary = useAPIKeys({ subject: 'user_primary', pageSize: 1 });
+ const secondary = useAPIKeys({ subject: 'user_secondary', pageSize: 1 });
+ return { primary, secondary };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.primary.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.secondary.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.primary.revalidate();
+ });
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ const subjects = (getAllSpy.mock.calls as Array<unknown[]>).map(
+ call => (call[0] as { subject?: string } | undefined)?.subject,
+ );
+ expect(subjects).not.toContain('user_secondary');
+ expect(subjects[0] === undefined || subjects[0] === 'user_primary').toBe(true);
+ });
+});

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

@@ -503,6 +503,35 @@ describe('usePagesOrInfinite - behaviors mirrored from useCoreOrganization', ()
 });
 
 describe('usePagesOrInfinite - revalidate behavior', () => {
+ it('refetches current data when revalidate is invoked', async () => {
+ const fetcher = vi
+ .fn()
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' }],
+ total_count: 1,
+ });
+
+ const params = { initialPage: 1, pageSize: 1 };
+ const config = buildConfig(params);
+ const keys = buildKeys('t-revalidate-refresh', params);
+
+ const { result } = renderUsePagesOrInfinite({ fetcher, config, keys });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }]);
+
+ await act(async () => {
+ await (result.current as any).revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }]));
+ expect(fetcher).toHaveBeenCalledTimes(2);
+ });
+
  it('pagination mode: isFetching toggles during revalidate, isLoading stays false after initial load', async () => {
  const deferred = createDeferredPromise();
  let callCount = 0;
@@ -652,6 +681,47 @@ describe('usePagesOrInfinite - revalidate behavior', () => {
  { id: 'p2-1-revalidate' },
  ]);
  });
+
+ it('cascades revalidation to related queries only in React Query mode', async () => {
+ const params = { initialPage: 1, pageSize: 1 };
+ const keys = buildKeys('t-revalidate-cascade', params, { userId: 'user_123' });
+ const fetcher = vi.fn(async ({ initialPage }: any) => ({
+ data: [{ id: `item-${initialPage}-${fetcher.mock.calls.length}` }],
+ total_count: 3,
+ }));
+
+ const useBoth = () => {
+ const paginated = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params),
+ keys,
+ });
+ const infinite = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params, { infinite: true }),
+ keys,
+ });
+
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcher.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcher.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcher).toHaveBeenCalledTimes(1));
+ }
+ });
 });
 
 describe('usePagesOrInfinite - error propagation', () => {

.changeset/young-impalas-grab.md

@@ -0,0 +1,14 @@
+---
+'@clerk/shared': patch
+---
+
+Relaxing requirements for RQ variant hooks to enable revalidation across different configurations of the same hook.
+
+```tsx
+
+const { revalidate } = useStatements({ initialPage: 1, pageSize: 10 });
+useStatements({ initialPage: 1, pageSize: 12 });
+
+// revalidate from first hook, now invalidates the second hook.
+void revalidate();
+```

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

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { ClerkResource } from '../../../types';
@@ -486,4 +486,66 @@ describe('createBillingPaginatedHook', () => {
  expect(result.current.pageCount).toBe(5);
  });
  });
+
+ describe('revalidate behavior', () => {
+ it('revalidate fetches fresh data for authenticated hook', async () => {
+ fetcherMock
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' } as DummyResource, { id: 'initial-2' } as DummyResource],
+ total_count: 2,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' } as DummyResource, { id: 'refetched-2' } as DummyResource],
+ total_count: 2,
+ });
+
+ const { result } = renderHook(() => useDummyAuth({ initialPage: 1, pageSize: 2 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }, { id: 'initial-2' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }, { id: 'refetched-2' }]));
+ expect(fetcherMock).toHaveBeenCalledTimes(2);
+ });
+
+ it('revalidate propagates to infinite counterpart only for React Query', async () => {
+ let seq = 0;
+ fetcherMock.mockImplementation(async (params: DummyParams) => {
+ seq++;
+ return {
+ data: Array.from({ length: params.pageSize ?? 2 }, (_, i) => ({
+ id: `item-${params.initialPage ?? 1}-${seq}-${i}`,
+ })) as DummyResource[],
+ total_count: 10,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useDummyAuth({ initialPage: 1, pageSize: 2 });
+ const infinite = useDummyAuth({ initialPage: 1, pageSize: 2, infinite: true } as any);
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcherMock.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcherMock.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcherMock).toHaveBeenCalledTimes(1));
+ }
+ });
+ });
 });

packages/shared/src/react/hooks/__tests__/useAPIKeys.spec.tsx

@@ -0,0 +1,213 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useAPIKeys } from '../useAPIKeys';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const getAllSpy = vi.fn(
+ async () =>
+ ({
+ data: [],
+ total_count: 0,
+ }) as { data: Array<Record<string, unknown>>; total_count: number },
+);
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ apiKeys: {
+ getAll: getAllSpy,
+ },
+ queryClient: defaultQueryClient,
+});
+
+vi.mock('../../contexts', () => {
+ return {
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ };
+});
+
+describe('useApiKeys', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ mockClerk.user = { id: 'user_1' };
+ });
+
+ it('revalidate fetches fresh API keys', async () => {
+ getAllSpy
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_initial' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_updated' }],
+ total_count: 1,
+ });
+
+ const { result } = renderHook(() => useAPIKeys({ subject: 'user_1', pageSize: 1 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'key_initial' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'key_updated' }]));
+ expect(getAllSpy).toHaveBeenCalledTimes(2);
+ });
+
+ it('cascades revalidation for related queries only when using React Query', async () => {
+ let sequence = 0;
+ getAllSpy.mockImplementation(async ({ initialPage }: { initialPage?: number } = {}) => {
+ sequence += 1;
+ const page = initialPage ?? 1;
+ return {
+ data: [{ id: `key-${page}-${sequence}` }],
+ total_count: 5,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const infinite = useAPIKeys({ subject: 'user_1', pageSize: 1, infinite: true });
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(getAllSpy).toHaveBeenCalledTimes(1));
+ }
+ });
+
+ it('handles revalidation with different pageSize configurations', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ pageSize }: { pageSize?: number } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-pageSize-${pageSize ?? 'unknown'}-${seq}` }],
+ total_count: 3,
+ };
+ });
+
+ const useHooks = () => {
+ const small = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const large = useAPIKeys({ subject: 'user_1', pageSize: 5 });
+ return { small, large };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.small.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.large.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.small.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('handles revalidation with different query filters', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ query }: { query?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-query-${query ?? 'empty'}-${seq}` }],
+ total_count: 2,
+ };
+ });
+
+ const useHooks = () => {
+ const defaultQuery = useAPIKeys({ subject: 'user_1', pageSize: 11, query: '' });
+ const filtered = useAPIKeys({ subject: 'user_1', pageSize: 11, query: 'search' });
+ return { defaultQuery, filtered };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.defaultQuery.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.filtered.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.defaultQuery.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('does not cascade revalidation across different subjects', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ subject }: { subject?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-subject-${subject ?? 'none'}-${seq}` }],
+ total_count: 4,
+ };
+ });
+
+ const useHooks = () => {
+ const primary = useAPIKeys({ subject: 'user_primary', pageSize: 1 });
+ const secondary = useAPIKeys({ subject: 'user_secondary', pageSize: 1 });
+ return { primary, secondary };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.primary.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.secondary.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.primary.revalidate();
+ });
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ const subjects = (getAllSpy.mock.calls as Array<unknown[]>).map(
+ call => (call[0] as { subject?: string } | undefined)?.subject,
+ );
+ expect(subjects).not.toContain('user_secondary');
+ expect(subjects[0] === undefined || subjects[0] === 'user_primary').toBe(true);
+ });
+});

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

@@ -503,6 +503,35 @@ describe('usePagesOrInfinite - behaviors mirrored from useCoreOrganization', ()
 });
 
 describe('usePagesOrInfinite - revalidate behavior', () => {
+ it('refetches current data when revalidate is invoked', async () => {
+ const fetcher = vi
+ .fn()
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' }],
+ total_count: 1,
+ });
+
+ const params = { initialPage: 1, pageSize: 1 };
+ const config = buildConfig(params);
+ const keys = buildKeys('t-revalidate-refresh', params);
+
+ const { result } = renderUsePagesOrInfinite({ fetcher, config, keys });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }]);
+
+ await act(async () => {
+ await (result.current as any).revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }]));
+ expect(fetcher).toHaveBeenCalledTimes(2);
+ });
+
  it('pagination mode: isFetching toggles during revalidate, isLoading stays false after initial load', async () => {
  const deferred = createDeferredPromise();
  let callCount = 0;
@@ -652,6 +681,47 @@ describe('usePagesOrInfinite - revalidate behavior', () => {
  { id: 'p2-1-revalidate' },
  ]);
  });
+
+ it('cascades revalidation to related queries only in React Query mode', async () => {
+ const params = { initialPage: 1, pageSize: 1 };
+ const keys = buildKeys('t-revalidate-cascade', params, { userId: 'user_123' });
+ const fetcher = vi.fn(async ({ initialPage }: any) => ({
+ data: [{ id: `item-${initialPage}-${fetcher.mock.calls.length}` }],
+ total_count: 3,
+ }));
+
+ const useBoth = () => {
+ const paginated = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params),
+ keys,
+ });
+ const infinite = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params, { infinite: true }),
+ keys,
+ });
+
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcher.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcher.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcher).toHaveBeenCalledTimes(1));
+ }
+ });
 });
 
 describe('usePagesOrInfinite - error propagation', () => {

.changeset/young-impalas-grab.md

@@ -0,0 +1,14 @@
+---
+'@clerk/shared': patch
+---
+
+Relaxing requirements for RQ variant hooks to enable revalidation across different configurations of the same hook.
+
+```tsx
+
+const { revalidate } = useStatements({ initialPage: 1, pageSize: 10 });
+useStatements({ initialPage: 1, pageSize: 12 });
+
+// revalidate from first hook, now invalidates the second hook.
+void revalidate();
+```

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

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { ClerkResource } from '../../../types';
@@ -486,4 +486,66 @@ describe('createBillingPaginatedHook', () => {
  expect(result.current.pageCount).toBe(5);
  });
  });
+
+ describe('revalidate behavior', () => {
+ it('revalidate fetches fresh data for authenticated hook', async () => {
+ fetcherMock
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' } as DummyResource, { id: 'initial-2' } as DummyResource],
+ total_count: 2,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' } as DummyResource, { id: 'refetched-2' } as DummyResource],
+ total_count: 2,
+ });
+
+ const { result } = renderHook(() => useDummyAuth({ initialPage: 1, pageSize: 2 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }, { id: 'initial-2' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }, { id: 'refetched-2' }]));
+ expect(fetcherMock).toHaveBeenCalledTimes(2);
+ });
+
+ it('revalidate propagates to infinite counterpart only for React Query', async () => {
+ let seq = 0;
+ fetcherMock.mockImplementation(async (params: DummyParams) => {
+ seq++;
+ return {
+ data: Array.from({ length: params.pageSize ?? 2 }, (_, i) => ({
+ id: `item-${params.initialPage ?? 1}-${seq}-${i}`,
+ })) as DummyResource[],
+ total_count: 10,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useDummyAuth({ initialPage: 1, pageSize: 2 });
+ const infinite = useDummyAuth({ initialPage: 1, pageSize: 2, infinite: true } as any);
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcherMock.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcherMock.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcherMock).toHaveBeenCalledTimes(1));
+ }
+ });
+ });
 });

packages/shared/src/react/hooks/__tests__/useAPIKeys.spec.tsx

@@ -0,0 +1,213 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useAPIKeys } from '../useAPIKeys';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const getAllSpy = vi.fn(
+ async () =>
+ ({
+ data: [],
+ total_count: 0,
+ }) as { data: Array<Record<string, unknown>>; total_count: number },
+);
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ apiKeys: {
+ getAll: getAllSpy,
+ },
+ queryClient: defaultQueryClient,
+});
+
+vi.mock('../../contexts', () => {
+ return {
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ };
+});
+
+describe('useApiKeys', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ mockClerk.user = { id: 'user_1' };
+ });
+
+ it('revalidate fetches fresh API keys', async () => {
+ getAllSpy
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_initial' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'key_updated' }],
+ total_count: 1,
+ });
+
+ const { result } = renderHook(() => useAPIKeys({ subject: 'user_1', pageSize: 1 }), { wrapper });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'key_initial' }]);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'key_updated' }]));
+ expect(getAllSpy).toHaveBeenCalledTimes(2);
+ });
+
+ it('cascades revalidation for related queries only when using React Query', async () => {
+ let sequence = 0;
+ getAllSpy.mockImplementation(async ({ initialPage }: { initialPage?: number } = {}) => {
+ sequence += 1;
+ const page = initialPage ?? 1;
+ return {
+ data: [{ id: `key-${page}-${sequence}` }],
+ total_count: 5,
+ };
+ });
+
+ const useBoth = () => {
+ const paginated = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const infinite = useAPIKeys({ subject: 'user_1', pageSize: 1, infinite: true });
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(getAllSpy).toHaveBeenCalledTimes(1));
+ }
+ });
+
+ it('handles revalidation with different pageSize configurations', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ pageSize }: { pageSize?: number } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-pageSize-${pageSize ?? 'unknown'}-${seq}` }],
+ total_count: 3,
+ };
+ });
+
+ const useHooks = () => {
+ const small = useAPIKeys({ subject: 'user_1', pageSize: 1 });
+ const large = useAPIKeys({ subject: 'user_1', pageSize: 5 });
+ return { small, large };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.small.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.large.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.small.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('handles revalidation with different query filters', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ query }: { query?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-query-${query ?? 'empty'}-${seq}` }],
+ total_count: 2,
+ };
+ });
+
+ const useHooks = () => {
+ const defaultQuery = useAPIKeys({ subject: 'user_1', pageSize: 11, query: '' });
+ const filtered = useAPIKeys({ subject: 'user_1', pageSize: 11, query: 'search' });
+ return { defaultQuery, filtered };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.defaultQuery.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.filtered.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.defaultQuery.revalidate();
+ });
+
+ const isRQ = Boolean((globalThis as any).__CLERK_USE_RQ__);
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ if (isRQ) {
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ }
+ });
+
+ it('does not cascade revalidation across different subjects', async () => {
+ let seq = 0;
+ getAllSpy.mockImplementation(async ({ subject }: { subject?: string } = {}) => {
+ seq += 1;
+ return {
+ data: [{ id: `key-subject-${subject ?? 'none'}-${seq}` }],
+ total_count: 4,
+ };
+ });
+
+ const useHooks = () => {
+ const primary = useAPIKeys({ subject: 'user_primary', pageSize: 1 });
+ const secondary = useAPIKeys({ subject: 'user_secondary', pageSize: 1 });
+ return { primary, secondary };
+ };
+
+ const { result } = renderHook(useHooks, { wrapper });
+
+ await waitFor(() => expect(result.current.primary.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.secondary.isLoading).toBe(false));
+
+ getAllSpy.mockClear();
+
+ await act(async () => {
+ await result.current.primary.revalidate();
+ });
+
+ await waitFor(() => expect(getAllSpy.mock.calls.length).toBeGreaterThanOrEqual(1));
+
+ expect(getAllSpy).toHaveBeenCalledTimes(1);
+ const subjects = (getAllSpy.mock.calls as Array<unknown[]>).map(
+ call => (call[0] as { subject?: string } | undefined)?.subject,
+ );
+ expect(subjects).not.toContain('user_secondary');
+ expect(subjects[0] === undefined || subjects[0] === 'user_primary').toBe(true);
+ });
+});

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

@@ -503,6 +503,35 @@ describe('usePagesOrInfinite - behaviors mirrored from useCoreOrganization', ()
 });
 
 describe('usePagesOrInfinite - revalidate behavior', () => {
+ it('refetches current data when revalidate is invoked', async () => {
+ const fetcher = vi
+ .fn()
+ .mockResolvedValueOnce({
+ data: [{ id: 'initial-1' }],
+ total_count: 1,
+ })
+ .mockResolvedValueOnce({
+ data: [{ id: 'refetched-1' }],
+ total_count: 1,
+ });
+
+ const params = { initialPage: 1, pageSize: 1 };
+ const config = buildConfig(params);
+ const keys = buildKeys('t-revalidate-refresh', params);
+
+ const { result } = renderUsePagesOrInfinite({ fetcher, config, keys });
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.data).toEqual([{ id: 'initial-1' }]);
+
+ await act(async () => {
+ await (result.current as any).revalidate();
+ });
+
+ await waitFor(() => expect(result.current.data).toEqual([{ id: 'refetched-1' }]));
+ expect(fetcher).toHaveBeenCalledTimes(2);
+ });
+
  it('pagination mode: isFetching toggles during revalidate, isLoading stays false after initial load', async () => {
  const deferred = createDeferredPromise();
  let callCount = 0;
@@ -652,6 +681,47 @@ describe('usePagesOrInfinite - revalidate behavior', () => {
  { id: 'p2-1-revalidate' },
  ]);
  });
+
+ it('cascades revalidation to related queries only in React Query mode', async () => {
+ const params = { initialPage: 1, pageSize: 1 };
+ const keys = buildKeys('t-revalidate-cascade', params, { userId: 'user_123' });
+ const fetcher = vi.fn(async ({ initialPage }: any) => ({
+ data: [{ id: `item-${initialPage}-${fetcher.mock.calls.length}` }],
+ total_count: 3,
+ }));
+
+ const useBoth = () => {
+ const paginated = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params),
+ keys,
+ });
+ const infinite = usePagesOrInfinite({
+ fetcher,
+ config: buildConfig(params, { infinite: true }),
+ keys,
+ });
+
+ return { paginated, infinite };
+ };
+
+ const { result } = renderHook(useBoth, { wrapper });
+
+ await waitFor(() => expect(result.current.paginated.isLoading).toBe(false));
+ await waitFor(() => expect(result.current.infinite.isLoading).toBe(false));
+
+ fetcher.mockClear();
+
+ await act(async () => {
+ await result.current.paginated.revalidate();
+ });
+
+ if (__CLERK_USE_RQ__) {
+ await waitFor(() => expect(fetcher.mock.calls.length).toBeGreaterThanOrEqual(2));
+ } else {
+ await waitFor(() => expect(fetcher).toHaveBeenCalledTimes(1));
+ }
+ });
 });
 
 describe('usePagesOrInfinite - error propagation', () => {