feat(shared): Replace callWithRetry and runWithExponentialBackoff with retry

.changeset/metal-bobcats-wash.md

@@ -0,0 +1,27 @@
+---
+'@clerk/shared': major
+---
+This new version introduces the following breaking changes:
+- Introduced a new `retry` utility function to replace the deprecated `callWithRetry`.
+- Removed the `callWithRetry` function and its associated tests.
+- Renamed `runWithExponentialBackOff` to `retry` for consistency.
+
+Migration steps:
+- Replace any usage of `callWithRetry` with the new `retry` function.
+- Update import statements from:
+ ```typescript
+ import { callWithRetry } from '@clerk/shared/callWithRetry';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```
+- Replace any usage of `runWithExponentialBackOff` with `retry`.
+- Update import statements from:
+ ```typescript
+ import { runWithExponentialBackOff } from '@clerk/shared/utils';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```

packages/backend/src/tokens/keys.ts

@@ -13,7 +13,7 @@ import {
 } from '../errors';
 import { runtime } from '../runtime';
 import { joinPaths } from '../util/path';
-import { callWithRetry } from '../util/shared';
+import { retry } from '../util/shared';
 
 type JsonWebKeyWithKid = JsonWebKey & { kid: string };
 
@@ -137,8 +137,8 @@ export async function loadClerkJWKFromRemote({
  reason: TokenVerificationErrorReason.RemoteJWKFailedToLoad,
  });
  }
- const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion);
- const { keys } = await callWithRetry<{ keys: JsonWebKeyWithKid[] }>(fetcher);
+ const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion) as Promise<{ keys: JsonWebKeyWithKid[] }>;
+ const { keys } = await retry(fetcher);
 
  if (!keys || !keys.length) {
  throw new TokenVerificationError({

packages/backend/src/util/shared.ts

@@ -1,5 +1,5 @@
 export { addClerkPrefix, getScriptUrl, getClerkJsMajorVersionOrTag } from '@clerk/shared/url';
-export { callWithRetry } from '@clerk/shared/callWithRetry';
+export { retry } from '@clerk/shared/retry';
 export {
  isDevelopmentFromSecretKey,
  isProductionFromSecretKey,
@@ -10,8 +10,8 @@ export {
 export { deprecated, deprecatedProperty } from '@clerk/shared/deprecated';
 
 import { buildErrorThrower } from '@clerk/shared/error';
+import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 // TODO: replace packageName with `${PACKAGE_NAME}@${PACKAGE_VERSION}` from tsup.config.ts
 export const errorThrower = buildErrorThrower({ packageName: '@clerk/backend' });
 
-import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 export const { isDevOrStagingUrl } = createDevOrStagingUrlCache();

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

@@ -1,6 +1,6 @@
 import { isBrowserOnline } from '@clerk/shared/browser';
+import { retry } from '@clerk/shared/retry';
 import { camelToSnake } from '@clerk/shared/underscore';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
 import type { ClerkAPIErrorJSON, ClientJSON, InstanceType } from '@clerk/types';
 
 import { buildEmailAddress as buildEmailAddressUtil, buildURL as buildUrlUtil, stringifyQueryParams } from '../utils';
@@ -235,9 +235,9 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  response =
  // retry only on GET requests for safety
  overwrittenRequestMethod === 'GET'
- ? await runWithExponentialBackOff(() => fetch(urlStr, fetchOpts), {
-firstDelay: 500,
-maxDelay: 3000,
+ ? await retry(() => fetch(urlStr, fetchOpts), {
+initialDelay: 500,
+maxDelayBetweenRetries: 3000,
  shouldRetry: (_: unknown, iterationsCount: number) => {
  return iterationsCount < maxTries;
  },

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

@@ -1,6 +1,6 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
 import { is4xxError } from '@clerk/shared/error';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
+import { retry } from '@clerk/shared/retry';
 import type {
  ActJWTClaim,
  CheckAuthorization,
@@ -84,7 +84,7 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
- return runWithExponentialBackOff(() => this._getToken(options), {
+ return retry(() => this._getToken(options), {
  shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
  });
  };

packages/shared/package.json

@@ -79,7 +79,7 @@
  "authorization",
  "authorization-errors",
  "browser",
- "callWithRetry",
+ "retry",
  "color",
  "cookie",
  "date",

packages/shared/src/__tests__/retry.test.ts

@@ -0,0 +1,208 @@
+import { retry } from '../retry';
+
+describe('retry', () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ test('resolves with the result of the callback', async () => {
+ const result = await retry(() => Promise.resolve('success'));
+ expect(result).toBe('success');
+ });
+
+ test('retries the callback until it succeeds', async () => {
+ let attempts = 0;
+ const result = retry(
+ () => {
+ attempts++;
+ if (attempts < 2) {
+ throw new Error('failed');
+ }
+ return Promise.resolve('success');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ jitter: false,
+ },
+ );
+ await jest.advanceTimersByTimeAsync(200);
+ expect(await result).toBe('success');
+ expect(attempts).toBe(2);
+ });
+
+ test('maxDelayBetweenRetries prevents delays from growing beyond the limit', async () => {
+ jest.useFakeTimers();
+ let attempts = 0;
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ maxDelayBetweenRetries: 300,
+ initialDelay: 100,
+ factor: 3,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 4,
+ },
+ ).catch(e => {
+ expect(e.message).toBe('failed');
+ });
+
+ // Run all timer advances before testing the promise
+ await jest.advanceTimersByTimeAsync(100);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ expect(attempts).toBe(1 + 4);
+ jest.useRealTimers();
+ });
+
+ test('respects initialDelay option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ { initialDelay: 200, jitter: false, shouldRetry: (_, count) => count <= 2 },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects retryImmediately option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 1000,
+ retryImmediately: true,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(101);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(1000);
+ expect(attempts).toBe(3);
+ });
+
+ test('disables immediate retry when retryImmediately is false', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 200,
+ retryImmediately: false,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects shouldRetry custom logic', async () => {
+ let attempts = 0;
+ const error = new Error('special error');
+
+ await retry(
+ () => {
+ attempts++;
+ throw error;
+ },
+ {
+ initialDelay: 100,
+ jitter: false,
+ shouldRetry: e => (e as Error).message !== 'special error',
+ },
+ ).catch(e => {
+ expect(e).toBe(error);
+ });
+
+ expect(attempts).toBe(1);
+ });
+
+ test('respects factor for exponential backoff', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 4,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 3,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(100);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(1600);
+ expect(attempts).toBe(4);
+ });
+
+ test('applies jitter by default', async () => {
+ let attempts = 0;
+
+ jest.spyOn(Math, 'random').mockReturnValue(0.5);
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ // First attempt that triggers the retry
+ expect(attempts).toBe(1);
+ // Flush all microtasks
+ await Promise.resolve();
+ // Normal delay without jitter
+ await jest.advanceTimersByTimeAsync(100);
+ // But the attempt is still 1 because with the jitter enabled,
+ // the delay is now 150
+ expect(attempts).toBe(1);
+ // Wait for 50ms more (100 + 50)
+ await jest.advanceTimersByTimeAsync(50);
+ // Should now reach the second attempt
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ });
+});

packages/shared/src/index.ts

@@ -12,7 +12,6 @@ export * from './utils';
 
 export { apiUrlFromPublishableKey } from './apiUrlFromPublishableKey';
 export * from './browser';
-export { callWithRetry } from './callWithRetry';
 export * from './color';
 export * from './constants';
 export * from './date';

packages/shared/src/loadScript.ts

@@ -1,4 +1,4 @@
-import { runWithExponentialBackOff } from './utils';
+import { retry } from './retry';
 
 const NO_DOCUMENT_ERROR = 'loadScript cannot be called when document does not exist';
 const NO_SRC_ERROR = 'loadScript cannot be called without a src';
@@ -47,5 +47,5 @@ export async function loadScript(src = '', opts: LoadScriptOptions): Promise<HTM
  });
  };
 
- return runWithExponentialBackOff(load, { shouldRetry: (_, iterations) => iterations < 5 });
+ return retry(load, { shouldRetry: (_, iterations) => iterations <= 5 });
 }

.changeset/metal-bobcats-wash.md

@@ -0,0 +1,27 @@
+---
+'@clerk/shared': major
+---
+This new version introduces the following breaking changes:
+- Introduced a new `retry` utility function to replace the deprecated `callWithRetry`.
+- Removed the `callWithRetry` function and its associated tests.
+- Renamed `runWithExponentialBackOff` to `retry` for consistency.
+
+Migration steps:
+- Replace any usage of `callWithRetry` with the new `retry` function.
+- Update import statements from:
+ ```typescript
+ import { callWithRetry } from '@clerk/shared/callWithRetry';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```
+- Replace any usage of `runWithExponentialBackOff` with `retry`.
+- Update import statements from:
+ ```typescript
+ import { runWithExponentialBackOff } from '@clerk/shared/utils';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```

packages/backend/src/tokens/keys.ts

@@ -13,7 +13,7 @@ import {
 } from '../errors';
 import { runtime } from '../runtime';
 import { joinPaths } from '../util/path';
-import { callWithRetry } from '../util/shared';
+import { retry } from '../util/shared';
 
 type JsonWebKeyWithKid = JsonWebKey & { kid: string };
 
@@ -137,8 +137,8 @@ export async function loadClerkJWKFromRemote({
  reason: TokenVerificationErrorReason.RemoteJWKFailedToLoad,
  });
  }
- const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion);
- const { keys } = await callWithRetry<{ keys: JsonWebKeyWithKid[] }>(fetcher);
+ const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion) as Promise<{ keys: JsonWebKeyWithKid[] }>;
+ const { keys } = await retry(fetcher);
 
  if (!keys || !keys.length) {
  throw new TokenVerificationError({

packages/backend/src/util/shared.ts

@@ -1,5 +1,5 @@
 export { addClerkPrefix, getScriptUrl, getClerkJsMajorVersionOrTag } from '@clerk/shared/url';
-export { callWithRetry } from '@clerk/shared/callWithRetry';
+export { retry } from '@clerk/shared/retry';
 export {
  isDevelopmentFromSecretKey,
  isProductionFromSecretKey,
@@ -10,8 +10,8 @@ export {
 export { deprecated, deprecatedProperty } from '@clerk/shared/deprecated';
 
 import { buildErrorThrower } from '@clerk/shared/error';
+import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 // TODO: replace packageName with `${PACKAGE_NAME}@${PACKAGE_VERSION}` from tsup.config.ts
 export const errorThrower = buildErrorThrower({ packageName: '@clerk/backend' });
 
-import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 export const { isDevOrStagingUrl } = createDevOrStagingUrlCache();

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

@@ -1,6 +1,6 @@
 import { isBrowserOnline } from '@clerk/shared/browser';
+import { retry } from '@clerk/shared/retry';
 import { camelToSnake } from '@clerk/shared/underscore';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
 import type { ClerkAPIErrorJSON, ClientJSON, InstanceType } from '@clerk/types';
 
 import { buildEmailAddress as buildEmailAddressUtil, buildURL as buildUrlUtil, stringifyQueryParams } from '../utils';
@@ -235,9 +235,9 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  response =
  // retry only on GET requests for safety
  overwrittenRequestMethod === 'GET'
- ? await runWithExponentialBackOff(() => fetch(urlStr, fetchOpts), {
-firstDelay: 500,
-maxDelay: 3000,
+ ? await retry(() => fetch(urlStr, fetchOpts), {
+initialDelay: 500,
+maxDelayBetweenRetries: 3000,
  shouldRetry: (_: unknown, iterationsCount: number) => {
  return iterationsCount < maxTries;
  },

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

@@ -1,6 +1,6 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
 import { is4xxError } from '@clerk/shared/error';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
+import { retry } from '@clerk/shared/retry';
 import type {
  ActJWTClaim,
  CheckAuthorization,
@@ -84,7 +84,7 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
- return runWithExponentialBackOff(() => this._getToken(options), {
+ return retry(() => this._getToken(options), {
  shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
  });
  };

packages/shared/package.json

@@ -79,7 +79,7 @@
  "authorization",
  "authorization-errors",
  "browser",
- "callWithRetry",
+ "retry",
  "color",
  "cookie",
  "date",

packages/shared/src/__tests__/retry.test.ts

@@ -0,0 +1,208 @@
+import { retry } from '../retry';
+
+describe('retry', () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ test('resolves with the result of the callback', async () => {
+ const result = await retry(() => Promise.resolve('success'));
+ expect(result).toBe('success');
+ });
+
+ test('retries the callback until it succeeds', async () => {
+ let attempts = 0;
+ const result = retry(
+ () => {
+ attempts++;
+ if (attempts < 2) {
+ throw new Error('failed');
+ }
+ return Promise.resolve('success');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ jitter: false,
+ },
+ );
+ await jest.advanceTimersByTimeAsync(200);
+ expect(await result).toBe('success');
+ expect(attempts).toBe(2);
+ });
+
+ test('maxDelayBetweenRetries prevents delays from growing beyond the limit', async () => {
+ jest.useFakeTimers();
+ let attempts = 0;
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ maxDelayBetweenRetries: 300,
+ initialDelay: 100,
+ factor: 3,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 4,
+ },
+ ).catch(e => {
+ expect(e.message).toBe('failed');
+ });
+
+ // Run all timer advances before testing the promise
+ await jest.advanceTimersByTimeAsync(100);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ expect(attempts).toBe(1 + 4);
+ jest.useRealTimers();
+ });
+
+ test('respects initialDelay option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ { initialDelay: 200, jitter: false, shouldRetry: (_, count) => count <= 2 },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects retryImmediately option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 1000,
+ retryImmediately: true,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(101);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(1000);
+ expect(attempts).toBe(3);
+ });
+
+ test('disables immediate retry when retryImmediately is false', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 200,
+ retryImmediately: false,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects shouldRetry custom logic', async () => {
+ let attempts = 0;
+ const error = new Error('special error');
+
+ await retry(
+ () => {
+ attempts++;
+ throw error;
+ },
+ {
+ initialDelay: 100,
+ jitter: false,
+ shouldRetry: e => (e as Error).message !== 'special error',
+ },
+ ).catch(e => {
+ expect(e).toBe(error);
+ });
+
+ expect(attempts).toBe(1);
+ });
+
+ test('respects factor for exponential backoff', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 4,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 3,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(100);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(1600);
+ expect(attempts).toBe(4);
+ });
+
+ test('applies jitter by default', async () => {
+ let attempts = 0;
+
+ jest.spyOn(Math, 'random').mockReturnValue(0.5);
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ // First attempt that triggers the retry
+ expect(attempts).toBe(1);
+ // Flush all microtasks
+ await Promise.resolve();
+ // Normal delay without jitter
+ await jest.advanceTimersByTimeAsync(100);
+ // But the attempt is still 1 because with the jitter enabled,
+ // the delay is now 150
+ expect(attempts).toBe(1);
+ // Wait for 50ms more (100 + 50)
+ await jest.advanceTimersByTimeAsync(50);
+ // Should now reach the second attempt
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ });
+});

packages/shared/src/index.ts

@@ -12,7 +12,6 @@ export * from './utils';
 
 export { apiUrlFromPublishableKey } from './apiUrlFromPublishableKey';
 export * from './browser';
-export { callWithRetry } from './callWithRetry';
 export * from './color';
 export * from './constants';
 export * from './date';

packages/shared/src/loadScript.ts

@@ -1,4 +1,4 @@
-import { runWithExponentialBackOff } from './utils';
+import { retry } from './retry';
 
 const NO_DOCUMENT_ERROR = 'loadScript cannot be called when document does not exist';
 const NO_SRC_ERROR = 'loadScript cannot be called without a src';
@@ -47,5 +47,5 @@ export async function loadScript(src = '', opts: LoadScriptOptions): Promise<HTM
  });
  };
 
- return runWithExponentialBackOff(load, { shouldRetry: (_, iterations) => iterations < 5 });
+ return retry(load, { shouldRetry: (_, iterations) => iterations <= 5 });
 }

.changeset/metal-bobcats-wash.md

@@ -0,0 +1,27 @@
+---
+'@clerk/shared': major
+---
+This new version introduces the following breaking changes:
+- Introduced a new `retry` utility function to replace the deprecated `callWithRetry`.
+- Removed the `callWithRetry` function and its associated tests.
+- Renamed `runWithExponentialBackOff` to `retry` for consistency.
+
+Migration steps:
+- Replace any usage of `callWithRetry` with the new `retry` function.
+- Update import statements from:
+ ```typescript
+ import { callWithRetry } from '@clerk/shared/callWithRetry';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```
+- Replace any usage of `runWithExponentialBackOff` with `retry`.
+- Update import statements from:
+ ```typescript
+ import { runWithExponentialBackOff } from '@clerk/shared/utils';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```

packages/backend/src/tokens/keys.ts

@@ -13,7 +13,7 @@ import {
 } from '../errors';
 import { runtime } from '../runtime';
 import { joinPaths } from '../util/path';
-import { callWithRetry } from '../util/shared';
+import { retry } from '../util/shared';
 
 type JsonWebKeyWithKid = JsonWebKey & { kid: string };
 
@@ -137,8 +137,8 @@ export async function loadClerkJWKFromRemote({
  reason: TokenVerificationErrorReason.RemoteJWKFailedToLoad,
  });
  }
- const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion);
- const { keys } = await callWithRetry<{ keys: JsonWebKeyWithKid[] }>(fetcher);
+ const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion) as Promise<{ keys: JsonWebKeyWithKid[] }>;
+ const { keys } = await retry(fetcher);
 
  if (!keys || !keys.length) {
  throw new TokenVerificationError({

packages/backend/src/util/shared.ts

@@ -1,5 +1,5 @@
 export { addClerkPrefix, getScriptUrl, getClerkJsMajorVersionOrTag } from '@clerk/shared/url';
-export { callWithRetry } from '@clerk/shared/callWithRetry';
+export { retry } from '@clerk/shared/retry';
 export {
  isDevelopmentFromSecretKey,
  isProductionFromSecretKey,
@@ -10,8 +10,8 @@ export {
 export { deprecated, deprecatedProperty } from '@clerk/shared/deprecated';
 
 import { buildErrorThrower } from '@clerk/shared/error';
+import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 // TODO: replace packageName with `${PACKAGE_NAME}@${PACKAGE_VERSION}` from tsup.config.ts
 export const errorThrower = buildErrorThrower({ packageName: '@clerk/backend' });
 
-import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 export const { isDevOrStagingUrl } = createDevOrStagingUrlCache();

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

@@ -1,6 +1,6 @@
 import { isBrowserOnline } from '@clerk/shared/browser';
+import { retry } from '@clerk/shared/retry';
 import { camelToSnake } from '@clerk/shared/underscore';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
 import type { ClerkAPIErrorJSON, ClientJSON, InstanceType } from '@clerk/types';
 
 import { buildEmailAddress as buildEmailAddressUtil, buildURL as buildUrlUtil, stringifyQueryParams } from '../utils';
@@ -235,9 +235,9 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  response =
  // retry only on GET requests for safety
  overwrittenRequestMethod === 'GET'
- ? await runWithExponentialBackOff(() => fetch(urlStr, fetchOpts), {
-firstDelay: 500,
-maxDelay: 3000,
+ ? await retry(() => fetch(urlStr, fetchOpts), {
+initialDelay: 500,
+maxDelayBetweenRetries: 3000,
  shouldRetry: (_: unknown, iterationsCount: number) => {
  return iterationsCount < maxTries;
  },

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

@@ -1,6 +1,6 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
 import { is4xxError } from '@clerk/shared/error';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
+import { retry } from '@clerk/shared/retry';
 import type {
  ActJWTClaim,
  CheckAuthorization,
@@ -84,7 +84,7 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
- return runWithExponentialBackOff(() => this._getToken(options), {
+ return retry(() => this._getToken(options), {
  shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
  });
  };

packages/shared/package.json

@@ -79,7 +79,7 @@
  "authorization",
  "authorization-errors",
  "browser",
- "callWithRetry",
+ "retry",
  "color",
  "cookie",
  "date",

packages/shared/src/__tests__/retry.test.ts

@@ -0,0 +1,208 @@
+import { retry } from '../retry';
+
+describe('retry', () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ test('resolves with the result of the callback', async () => {
+ const result = await retry(() => Promise.resolve('success'));
+ expect(result).toBe('success');
+ });
+
+ test('retries the callback until it succeeds', async () => {
+ let attempts = 0;
+ const result = retry(
+ () => {
+ attempts++;
+ if (attempts < 2) {
+ throw new Error('failed');
+ }
+ return Promise.resolve('success');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ jitter: false,
+ },
+ );
+ await jest.advanceTimersByTimeAsync(200);
+ expect(await result).toBe('success');
+ expect(attempts).toBe(2);
+ });
+
+ test('maxDelayBetweenRetries prevents delays from growing beyond the limit', async () => {
+ jest.useFakeTimers();
+ let attempts = 0;
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ maxDelayBetweenRetries: 300,
+ initialDelay: 100,
+ factor: 3,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 4,
+ },
+ ).catch(e => {
+ expect(e.message).toBe('failed');
+ });
+
+ // Run all timer advances before testing the promise
+ await jest.advanceTimersByTimeAsync(100);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ expect(attempts).toBe(1 + 4);
+ jest.useRealTimers();
+ });
+
+ test('respects initialDelay option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ { initialDelay: 200, jitter: false, shouldRetry: (_, count) => count <= 2 },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects retryImmediately option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 1000,
+ retryImmediately: true,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(101);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(1000);
+ expect(attempts).toBe(3);
+ });
+
+ test('disables immediate retry when retryImmediately is false', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 200,
+ retryImmediately: false,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects shouldRetry custom logic', async () => {
+ let attempts = 0;
+ const error = new Error('special error');
+
+ await retry(
+ () => {
+ attempts++;
+ throw error;
+ },
+ {
+ initialDelay: 100,
+ jitter: false,
+ shouldRetry: e => (e as Error).message !== 'special error',
+ },
+ ).catch(e => {
+ expect(e).toBe(error);
+ });
+
+ expect(attempts).toBe(1);
+ });
+
+ test('respects factor for exponential backoff', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 4,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 3,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(100);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(1600);
+ expect(attempts).toBe(4);
+ });
+
+ test('applies jitter by default', async () => {
+ let attempts = 0;
+
+ jest.spyOn(Math, 'random').mockReturnValue(0.5);
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ // First attempt that triggers the retry
+ expect(attempts).toBe(1);
+ // Flush all microtasks
+ await Promise.resolve();
+ // Normal delay without jitter
+ await jest.advanceTimersByTimeAsync(100);
+ // But the attempt is still 1 because with the jitter enabled,
+ // the delay is now 150
+ expect(attempts).toBe(1);
+ // Wait for 50ms more (100 + 50)
+ await jest.advanceTimersByTimeAsync(50);
+ // Should now reach the second attempt
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ });
+});

packages/shared/src/index.ts

@@ -12,7 +12,6 @@ export * from './utils';
 
 export { apiUrlFromPublishableKey } from './apiUrlFromPublishableKey';
 export * from './browser';
-export { callWithRetry } from './callWithRetry';
 export * from './color';
 export * from './constants';
 export * from './date';

packages/shared/src/loadScript.ts

@@ -1,4 +1,4 @@
-import { runWithExponentialBackOff } from './utils';
+import { retry } from './retry';
 
 const NO_DOCUMENT_ERROR = 'loadScript cannot be called when document does not exist';
 const NO_SRC_ERROR = 'loadScript cannot be called without a src';
@@ -47,5 +47,5 @@ export async function loadScript(src = '', opts: LoadScriptOptions): Promise<HTM
  });
  };
 
- return runWithExponentialBackOff(load, { shouldRetry: (_, iterations) => iterations < 5 });
+ return retry(load, { shouldRetry: (_, iterations) => iterations <= 5 });
 }

.changeset/metal-bobcats-wash.md

@@ -0,0 +1,27 @@
+---
+'@clerk/shared': major
+---
+This new version introduces the following breaking changes:
+- Introduced a new `retry` utility function to replace the deprecated `callWithRetry`.
+- Removed the `callWithRetry` function and its associated tests.
+- Renamed `runWithExponentialBackOff` to `retry` for consistency.
+
+Migration steps:
+- Replace any usage of `callWithRetry` with the new `retry` function.
+- Update import statements from:
+ ```typescript
+ import { callWithRetry } from '@clerk/shared/callWithRetry';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```
+- Replace any usage of `runWithExponentialBackOff` with `retry`.
+- Update import statements from:
+ ```typescript
+ import { runWithExponentialBackOff } from '@clerk/shared/utils';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```

packages/backend/src/tokens/keys.ts

@@ -13,7 +13,7 @@ import {
 } from '../errors';
 import { runtime } from '../runtime';
 import { joinPaths } from '../util/path';
-import { callWithRetry } from '../util/shared';
+import { retry } from '../util/shared';
 
 type JsonWebKeyWithKid = JsonWebKey & { kid: string };
 
@@ -137,8 +137,8 @@ export async function loadClerkJWKFromRemote({
  reason: TokenVerificationErrorReason.RemoteJWKFailedToLoad,
  });
  }
- const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion);
- const { keys } = await callWithRetry<{ keys: JsonWebKeyWithKid[] }>(fetcher);
+ const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion) as Promise<{ keys: JsonWebKeyWithKid[] }>;
+ const { keys } = await retry(fetcher);
 
  if (!keys || !keys.length) {
  throw new TokenVerificationError({

packages/backend/src/util/shared.ts

@@ -1,5 +1,5 @@
 export { addClerkPrefix, getScriptUrl, getClerkJsMajorVersionOrTag } from '@clerk/shared/url';
-export { callWithRetry } from '@clerk/shared/callWithRetry';
+export { retry } from '@clerk/shared/retry';
 export {
  isDevelopmentFromSecretKey,
  isProductionFromSecretKey,
@@ -10,8 +10,8 @@ export {
 export { deprecated, deprecatedProperty } from '@clerk/shared/deprecated';
 
 import { buildErrorThrower } from '@clerk/shared/error';
+import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 // TODO: replace packageName with `${PACKAGE_NAME}@${PACKAGE_VERSION}` from tsup.config.ts
 export const errorThrower = buildErrorThrower({ packageName: '@clerk/backend' });
 
-import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 export const { isDevOrStagingUrl } = createDevOrStagingUrlCache();

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

@@ -1,6 +1,6 @@
 import { isBrowserOnline } from '@clerk/shared/browser';
+import { retry } from '@clerk/shared/retry';
 import { camelToSnake } from '@clerk/shared/underscore';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
 import type { ClerkAPIErrorJSON, ClientJSON, InstanceType } from '@clerk/types';
 
 import { buildEmailAddress as buildEmailAddressUtil, buildURL as buildUrlUtil, stringifyQueryParams } from '../utils';
@@ -235,9 +235,9 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  response =
  // retry only on GET requests for safety
  overwrittenRequestMethod === 'GET'
- ? await runWithExponentialBackOff(() => fetch(urlStr, fetchOpts), {
-firstDelay: 500,
-maxDelay: 3000,
+ ? await retry(() => fetch(urlStr, fetchOpts), {
+initialDelay: 500,
+maxDelayBetweenRetries: 3000,
  shouldRetry: (_: unknown, iterationsCount: number) => {
  return iterationsCount < maxTries;
  },

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

@@ -1,6 +1,6 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
 import { is4xxError } from '@clerk/shared/error';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
+import { retry } from '@clerk/shared/retry';
 import type {
  ActJWTClaim,
  CheckAuthorization,
@@ -84,7 +84,7 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
- return runWithExponentialBackOff(() => this._getToken(options), {
+ return retry(() => this._getToken(options), {
  shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
  });
  };

packages/shared/package.json

@@ -79,7 +79,7 @@
  "authorization",
  "authorization-errors",
  "browser",
- "callWithRetry",
+ "retry",
  "color",
  "cookie",
  "date",

packages/shared/src/__tests__/retry.test.ts

@@ -0,0 +1,208 @@
+import { retry } from '../retry';
+
+describe('retry', () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ test('resolves with the result of the callback', async () => {
+ const result = await retry(() => Promise.resolve('success'));
+ expect(result).toBe('success');
+ });
+
+ test('retries the callback until it succeeds', async () => {
+ let attempts = 0;
+ const result = retry(
+ () => {
+ attempts++;
+ if (attempts < 2) {
+ throw new Error('failed');
+ }
+ return Promise.resolve('success');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ jitter: false,
+ },
+ );
+ await jest.advanceTimersByTimeAsync(200);
+ expect(await result).toBe('success');
+ expect(attempts).toBe(2);
+ });
+
+ test('maxDelayBetweenRetries prevents delays from growing beyond the limit', async () => {
+ jest.useFakeTimers();
+ let attempts = 0;
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ maxDelayBetweenRetries: 300,
+ initialDelay: 100,
+ factor: 3,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 4,
+ },
+ ).catch(e => {
+ expect(e.message).toBe('failed');
+ });
+
+ // Run all timer advances before testing the promise
+ await jest.advanceTimersByTimeAsync(100);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ expect(attempts).toBe(1 + 4);
+ jest.useRealTimers();
+ });
+
+ test('respects initialDelay option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ { initialDelay: 200, jitter: false, shouldRetry: (_, count) => count <= 2 },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects retryImmediately option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 1000,
+ retryImmediately: true,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(101);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(1000);
+ expect(attempts).toBe(3);
+ });
+
+ test('disables immediate retry when retryImmediately is false', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 200,
+ retryImmediately: false,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects shouldRetry custom logic', async () => {
+ let attempts = 0;
+ const error = new Error('special error');
+
+ await retry(
+ () => {
+ attempts++;
+ throw error;
+ },
+ {
+ initialDelay: 100,
+ jitter: false,
+ shouldRetry: e => (e as Error).message !== 'special error',
+ },
+ ).catch(e => {
+ expect(e).toBe(error);
+ });
+
+ expect(attempts).toBe(1);
+ });
+
+ test('respects factor for exponential backoff', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 4,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 3,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(100);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(1600);
+ expect(attempts).toBe(4);
+ });
+
+ test('applies jitter by default', async () => {
+ let attempts = 0;
+
+ jest.spyOn(Math, 'random').mockReturnValue(0.5);
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ // First attempt that triggers the retry
+ expect(attempts).toBe(1);
+ // Flush all microtasks
+ await Promise.resolve();
+ // Normal delay without jitter
+ await jest.advanceTimersByTimeAsync(100);
+ // But the attempt is still 1 because with the jitter enabled,
+ // the delay is now 150
+ expect(attempts).toBe(1);
+ // Wait for 50ms more (100 + 50)
+ await jest.advanceTimersByTimeAsync(50);
+ // Should now reach the second attempt
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ });
+});

packages/shared/src/index.ts

@@ -12,7 +12,6 @@ export * from './utils';
 
 export { apiUrlFromPublishableKey } from './apiUrlFromPublishableKey';
 export * from './browser';
-export { callWithRetry } from './callWithRetry';
 export * from './color';
 export * from './constants';
 export * from './date';

packages/shared/src/loadScript.ts

@@ -1,4 +1,4 @@
-import { runWithExponentialBackOff } from './utils';
+import { retry } from './retry';
 
 const NO_DOCUMENT_ERROR = 'loadScript cannot be called when document does not exist';
 const NO_SRC_ERROR = 'loadScript cannot be called without a src';
@@ -47,5 +47,5 @@ export async function loadScript(src = '', opts: LoadScriptOptions): Promise<HTM
  });
  };
 
- return runWithExponentialBackOff(load, { shouldRetry: (_, iterations) => iterations < 5 });
+ return retry(load, { shouldRetry: (_, iterations) => iterations <= 5 });
 }

.changeset/metal-bobcats-wash.md

@@ -0,0 +1,27 @@
+---
+'@clerk/shared': major
+---
+This new version introduces the following breaking changes:
+- Introduced a new `retry` utility function to replace the deprecated `callWithRetry`.
+- Removed the `callWithRetry` function and its associated tests.
+- Renamed `runWithExponentialBackOff` to `retry` for consistency.
+
+Migration steps:
+- Replace any usage of `callWithRetry` with the new `retry` function.
+- Update import statements from:
+ ```typescript
+ import { callWithRetry } from '@clerk/shared/callWithRetry';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```
+- Replace any usage of `runWithExponentialBackOff` with `retry`.
+- Update import statements from:
+ ```typescript
+ import { runWithExponentialBackOff } from '@clerk/shared/utils';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```

packages/backend/src/tokens/keys.ts

@@ -13,7 +13,7 @@ import {
 } from '../errors';
 import { runtime } from '../runtime';
 import { joinPaths } from '../util/path';
-import { callWithRetry } from '../util/shared';
+import { retry } from '../util/shared';
 
 type JsonWebKeyWithKid = JsonWebKey & { kid: string };
 
@@ -137,8 +137,8 @@ export async function loadClerkJWKFromRemote({
  reason: TokenVerificationErrorReason.RemoteJWKFailedToLoad,
  });
  }
- const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion);
- const { keys } = await callWithRetry<{ keys: JsonWebKeyWithKid[] }>(fetcher);
+ const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion) as Promise<{ keys: JsonWebKeyWithKid[] }>;
+ const { keys } = await retry(fetcher);
 
  if (!keys || !keys.length) {
  throw new TokenVerificationError({

packages/backend/src/util/shared.ts

@@ -1,5 +1,5 @@
 export { addClerkPrefix, getScriptUrl, getClerkJsMajorVersionOrTag } from '@clerk/shared/url';
-export { callWithRetry } from '@clerk/shared/callWithRetry';
+export { retry } from '@clerk/shared/retry';
 export {
  isDevelopmentFromSecretKey,
  isProductionFromSecretKey,
@@ -10,8 +10,8 @@ export {
 export { deprecated, deprecatedProperty } from '@clerk/shared/deprecated';
 
 import { buildErrorThrower } from '@clerk/shared/error';
+import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 // TODO: replace packageName with `${PACKAGE_NAME}@${PACKAGE_VERSION}` from tsup.config.ts
 export const errorThrower = buildErrorThrower({ packageName: '@clerk/backend' });
 
-import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 export const { isDevOrStagingUrl } = createDevOrStagingUrlCache();

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

@@ -1,6 +1,6 @@
 import { isBrowserOnline } from '@clerk/shared/browser';
+import { retry } from '@clerk/shared/retry';
 import { camelToSnake } from '@clerk/shared/underscore';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
 import type { ClerkAPIErrorJSON, ClientJSON, InstanceType } from '@clerk/types';
 
 import { buildEmailAddress as buildEmailAddressUtil, buildURL as buildUrlUtil, stringifyQueryParams } from '../utils';
@@ -235,9 +235,9 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  response =
  // retry only on GET requests for safety
  overwrittenRequestMethod === 'GET'
- ? await runWithExponentialBackOff(() => fetch(urlStr, fetchOpts), {
-firstDelay: 500,
-maxDelay: 3000,
+ ? await retry(() => fetch(urlStr, fetchOpts), {
+initialDelay: 500,
+maxDelayBetweenRetries: 3000,
  shouldRetry: (_: unknown, iterationsCount: number) => {
  return iterationsCount < maxTries;
  },

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

@@ -1,6 +1,6 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
 import { is4xxError } from '@clerk/shared/error';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
+import { retry } from '@clerk/shared/retry';
 import type {
  ActJWTClaim,
  CheckAuthorization,
@@ -84,7 +84,7 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
- return runWithExponentialBackOff(() => this._getToken(options), {
+ return retry(() => this._getToken(options), {
  shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
  });
  };

packages/shared/package.json

@@ -79,7 +79,7 @@
  "authorization",
  "authorization-errors",
  "browser",
- "callWithRetry",
+ "retry",
  "color",
  "cookie",
  "date",

packages/shared/src/__tests__/retry.test.ts

@@ -0,0 +1,208 @@
+import { retry } from '../retry';
+
+describe('retry', () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ test('resolves with the result of the callback', async () => {
+ const result = await retry(() => Promise.resolve('success'));
+ expect(result).toBe('success');
+ });
+
+ test('retries the callback until it succeeds', async () => {
+ let attempts = 0;
+ const result = retry(
+ () => {
+ attempts++;
+ if (attempts < 2) {
+ throw new Error('failed');
+ }
+ return Promise.resolve('success');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ jitter: false,
+ },
+ );
+ await jest.advanceTimersByTimeAsync(200);
+ expect(await result).toBe('success');
+ expect(attempts).toBe(2);
+ });
+
+ test('maxDelayBetweenRetries prevents delays from growing beyond the limit', async () => {
+ jest.useFakeTimers();
+ let attempts = 0;
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ maxDelayBetweenRetries: 300,
+ initialDelay: 100,
+ factor: 3,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 4,
+ },
+ ).catch(e => {
+ expect(e.message).toBe('failed');
+ });
+
+ // Run all timer advances before testing the promise
+ await jest.advanceTimersByTimeAsync(100);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ expect(attempts).toBe(1 + 4);
+ jest.useRealTimers();
+ });
+
+ test('respects initialDelay option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ { initialDelay: 200, jitter: false, shouldRetry: (_, count) => count <= 2 },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects retryImmediately option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 1000,
+ retryImmediately: true,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(101);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(1000);
+ expect(attempts).toBe(3);
+ });
+
+ test('disables immediate retry when retryImmediately is false', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 200,
+ retryImmediately: false,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects shouldRetry custom logic', async () => {
+ let attempts = 0;
+ const error = new Error('special error');
+
+ await retry(
+ () => {
+ attempts++;
+ throw error;
+ },
+ {
+ initialDelay: 100,
+ jitter: false,
+ shouldRetry: e => (e as Error).message !== 'special error',
+ },
+ ).catch(e => {
+ expect(e).toBe(error);
+ });
+
+ expect(attempts).toBe(1);
+ });
+
+ test('respects factor for exponential backoff', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 4,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 3,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(100);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(1600);
+ expect(attempts).toBe(4);
+ });
+
+ test('applies jitter by default', async () => {
+ let attempts = 0;
+
+ jest.spyOn(Math, 'random').mockReturnValue(0.5);
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ // First attempt that triggers the retry
+ expect(attempts).toBe(1);
+ // Flush all microtasks
+ await Promise.resolve();
+ // Normal delay without jitter
+ await jest.advanceTimersByTimeAsync(100);
+ // But the attempt is still 1 because with the jitter enabled,
+ // the delay is now 150
+ expect(attempts).toBe(1);
+ // Wait for 50ms more (100 + 50)
+ await jest.advanceTimersByTimeAsync(50);
+ // Should now reach the second attempt
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ });
+});

packages/shared/src/index.ts

@@ -12,7 +12,6 @@ export * from './utils';
 
 export { apiUrlFromPublishableKey } from './apiUrlFromPublishableKey';
 export * from './browser';
-export { callWithRetry } from './callWithRetry';
 export * from './color';
 export * from './constants';
 export * from './date';

packages/shared/src/loadScript.ts

@@ -1,4 +1,4 @@
-import { runWithExponentialBackOff } from './utils';
+import { retry } from './retry';
 
 const NO_DOCUMENT_ERROR = 'loadScript cannot be called when document does not exist';
 const NO_SRC_ERROR = 'loadScript cannot be called without a src';
@@ -47,5 +47,5 @@ export async function loadScript(src = '', opts: LoadScriptOptions): Promise<HTM
  });
  };
 
- return runWithExponentialBackOff(load, { shouldRetry: (_, iterations) => iterations < 5 });
+ return retry(load, { shouldRetry: (_, iterations) => iterations <= 5 });
 }

.changeset/metal-bobcats-wash.md

@@ -0,0 +1,27 @@
+---
+'@clerk/shared': major
+---
+This new version introduces the following breaking changes:
+- Introduced a new `retry` utility function to replace the deprecated `callWithRetry`.
+- Removed the `callWithRetry` function and its associated tests.
+- Renamed `runWithExponentialBackOff` to `retry` for consistency.
+
+Migration steps:
+- Replace any usage of `callWithRetry` with the new `retry` function.
+- Update import statements from:
+ ```typescript
+ import { callWithRetry } from '@clerk/shared/callWithRetry';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```
+- Replace any usage of `runWithExponentialBackOff` with `retry`.
+- Update import statements from:
+ ```typescript
+ import { runWithExponentialBackOff } from '@clerk/shared/utils';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```

packages/backend/src/tokens/keys.ts

@@ -13,7 +13,7 @@ import {
 } from '../errors';
 import { runtime } from '../runtime';
 import { joinPaths } from '../util/path';
-import { callWithRetry } from '../util/shared';
+import { retry } from '../util/shared';
 
 type JsonWebKeyWithKid = JsonWebKey & { kid: string };
 
@@ -137,8 +137,8 @@ export async function loadClerkJWKFromRemote({
  reason: TokenVerificationErrorReason.RemoteJWKFailedToLoad,
  });
  }
- const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion);
- const { keys } = await callWithRetry<{ keys: JsonWebKeyWithKid[] }>(fetcher);
+ const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion) as Promise<{ keys: JsonWebKeyWithKid[] }>;
+ const { keys } = await retry(fetcher);
 
  if (!keys || !keys.length) {
  throw new TokenVerificationError({

packages/backend/src/util/shared.ts

@@ -1,5 +1,5 @@
 export { addClerkPrefix, getScriptUrl, getClerkJsMajorVersionOrTag } from '@clerk/shared/url';
-export { callWithRetry } from '@clerk/shared/callWithRetry';
+export { retry } from '@clerk/shared/retry';
 export {
  isDevelopmentFromSecretKey,
  isProductionFromSecretKey,
@@ -10,8 +10,8 @@ export {
 export { deprecated, deprecatedProperty } from '@clerk/shared/deprecated';
 
 import { buildErrorThrower } from '@clerk/shared/error';
+import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 // TODO: replace packageName with `${PACKAGE_NAME}@${PACKAGE_VERSION}` from tsup.config.ts
 export const errorThrower = buildErrorThrower({ packageName: '@clerk/backend' });
 
-import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 export const { isDevOrStagingUrl } = createDevOrStagingUrlCache();

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

@@ -1,6 +1,6 @@
 import { isBrowserOnline } from '@clerk/shared/browser';
+import { retry } from '@clerk/shared/retry';
 import { camelToSnake } from '@clerk/shared/underscore';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
 import type { ClerkAPIErrorJSON, ClientJSON, InstanceType } from '@clerk/types';
 
 import { buildEmailAddress as buildEmailAddressUtil, buildURL as buildUrlUtil, stringifyQueryParams } from '../utils';
@@ -235,9 +235,9 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  response =
  // retry only on GET requests for safety
  overwrittenRequestMethod === 'GET'
- ? await runWithExponentialBackOff(() => fetch(urlStr, fetchOpts), {
-firstDelay: 500,
-maxDelay: 3000,
+ ? await retry(() => fetch(urlStr, fetchOpts), {
+initialDelay: 500,
+maxDelayBetweenRetries: 3000,
  shouldRetry: (_: unknown, iterationsCount: number) => {
  return iterationsCount < maxTries;
  },

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

@@ -1,6 +1,6 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
 import { is4xxError } from '@clerk/shared/error';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
+import { retry } from '@clerk/shared/retry';
 import type {
  ActJWTClaim,
  CheckAuthorization,
@@ -84,7 +84,7 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
- return runWithExponentialBackOff(() => this._getToken(options), {
+ return retry(() => this._getToken(options), {
  shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
  });
  };

packages/shared/package.json

@@ -79,7 +79,7 @@
  "authorization",
  "authorization-errors",
  "browser",
- "callWithRetry",
+ "retry",
  "color",
  "cookie",
  "date",

packages/shared/src/__tests__/retry.test.ts

@@ -0,0 +1,208 @@
+import { retry } from '../retry';
+
+describe('retry', () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ test('resolves with the result of the callback', async () => {
+ const result = await retry(() => Promise.resolve('success'));
+ expect(result).toBe('success');
+ });
+
+ test('retries the callback until it succeeds', async () => {
+ let attempts = 0;
+ const result = retry(
+ () => {
+ attempts++;
+ if (attempts < 2) {
+ throw new Error('failed');
+ }
+ return Promise.resolve('success');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ jitter: false,
+ },
+ );
+ await jest.advanceTimersByTimeAsync(200);
+ expect(await result).toBe('success');
+ expect(attempts).toBe(2);
+ });
+
+ test('maxDelayBetweenRetries prevents delays from growing beyond the limit', async () => {
+ jest.useFakeTimers();
+ let attempts = 0;
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ maxDelayBetweenRetries: 300,
+ initialDelay: 100,
+ factor: 3,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 4,
+ },
+ ).catch(e => {
+ expect(e.message).toBe('failed');
+ });
+
+ // Run all timer advances before testing the promise
+ await jest.advanceTimersByTimeAsync(100);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ expect(attempts).toBe(1 + 4);
+ jest.useRealTimers();
+ });
+
+ test('respects initialDelay option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ { initialDelay: 200, jitter: false, shouldRetry: (_, count) => count <= 2 },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects retryImmediately option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 1000,
+ retryImmediately: true,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(101);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(1000);
+ expect(attempts).toBe(3);
+ });
+
+ test('disables immediate retry when retryImmediately is false', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 200,
+ retryImmediately: false,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects shouldRetry custom logic', async () => {
+ let attempts = 0;
+ const error = new Error('special error');
+
+ await retry(
+ () => {
+ attempts++;
+ throw error;
+ },
+ {
+ initialDelay: 100,
+ jitter: false,
+ shouldRetry: e => (e as Error).message !== 'special error',
+ },
+ ).catch(e => {
+ expect(e).toBe(error);
+ });
+
+ expect(attempts).toBe(1);
+ });
+
+ test('respects factor for exponential backoff', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 4,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 3,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(100);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(1600);
+ expect(attempts).toBe(4);
+ });
+
+ test('applies jitter by default', async () => {
+ let attempts = 0;
+
+ jest.spyOn(Math, 'random').mockReturnValue(0.5);
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ // First attempt that triggers the retry
+ expect(attempts).toBe(1);
+ // Flush all microtasks
+ await Promise.resolve();
+ // Normal delay without jitter
+ await jest.advanceTimersByTimeAsync(100);
+ // But the attempt is still 1 because with the jitter enabled,
+ // the delay is now 150
+ expect(attempts).toBe(1);
+ // Wait for 50ms more (100 + 50)
+ await jest.advanceTimersByTimeAsync(50);
+ // Should now reach the second attempt
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ });
+});

packages/shared/src/index.ts

@@ -12,7 +12,6 @@ export * from './utils';
 
 export { apiUrlFromPublishableKey } from './apiUrlFromPublishableKey';
 export * from './browser';
-export { callWithRetry } from './callWithRetry';
 export * from './color';
 export * from './constants';
 export * from './date';

packages/shared/src/loadScript.ts

@@ -1,4 +1,4 @@
-import { runWithExponentialBackOff } from './utils';
+import { retry } from './retry';
 
 const NO_DOCUMENT_ERROR = 'loadScript cannot be called when document does not exist';
 const NO_SRC_ERROR = 'loadScript cannot be called without a src';
@@ -47,5 +47,5 @@ export async function loadScript(src = '', opts: LoadScriptOptions): Promise<HTM
  });
  };
 
- return runWithExponentialBackOff(load, { shouldRetry: (_, iterations) => iterations < 5 });
+ return retry(load, { shouldRetry: (_, iterations) => iterations <= 5 });
 }

.changeset/metal-bobcats-wash.md

@@ -0,0 +1,27 @@
+---
+'@clerk/shared': major
+---
+This new version introduces the following breaking changes:
+- Introduced a new `retry` utility function to replace the deprecated `callWithRetry`.
+- Removed the `callWithRetry` function and its associated tests.
+- Renamed `runWithExponentialBackOff` to `retry` for consistency.
+
+Migration steps:
+- Replace any usage of `callWithRetry` with the new `retry` function.
+- Update import statements from:
+ ```typescript
+ import { callWithRetry } from '@clerk/shared/callWithRetry';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```
+- Replace any usage of `runWithExponentialBackOff` with `retry`.
+- Update import statements from:
+ ```typescript
+ import { runWithExponentialBackOff } from '@clerk/shared/utils';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```

packages/backend/src/tokens/keys.ts

@@ -13,7 +13,7 @@ import {
 } from '../errors';
 import { runtime } from '../runtime';
 import { joinPaths } from '../util/path';
-import { callWithRetry } from '../util/shared';
+import { retry } from '../util/shared';
 
 type JsonWebKeyWithKid = JsonWebKey & { kid: string };
 
@@ -137,8 +137,8 @@ export async function loadClerkJWKFromRemote({
  reason: TokenVerificationErrorReason.RemoteJWKFailedToLoad,
  });
  }
- const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion);
- const { keys } = await callWithRetry<{ keys: JsonWebKeyWithKid[] }>(fetcher);
+ const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion) as Promise<{ keys: JsonWebKeyWithKid[] }>;
+ const { keys } = await retry(fetcher);
 
  if (!keys || !keys.length) {
  throw new TokenVerificationError({

packages/backend/src/util/shared.ts

@@ -1,5 +1,5 @@
 export { addClerkPrefix, getScriptUrl, getClerkJsMajorVersionOrTag } from '@clerk/shared/url';
-export { callWithRetry } from '@clerk/shared/callWithRetry';
+export { retry } from '@clerk/shared/retry';
 export {
  isDevelopmentFromSecretKey,
  isProductionFromSecretKey,
@@ -10,8 +10,8 @@ export {
 export { deprecated, deprecatedProperty } from '@clerk/shared/deprecated';
 
 import { buildErrorThrower } from '@clerk/shared/error';
+import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 // TODO: replace packageName with `${PACKAGE_NAME}@${PACKAGE_VERSION}` from tsup.config.ts
 export const errorThrower = buildErrorThrower({ packageName: '@clerk/backend' });
 
-import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 export const { isDevOrStagingUrl } = createDevOrStagingUrlCache();

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

@@ -1,6 +1,6 @@
 import { isBrowserOnline } from '@clerk/shared/browser';
+import { retry } from '@clerk/shared/retry';
 import { camelToSnake } from '@clerk/shared/underscore';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
 import type { ClerkAPIErrorJSON, ClientJSON, InstanceType } from '@clerk/types';
 
 import { buildEmailAddress as buildEmailAddressUtil, buildURL as buildUrlUtil, stringifyQueryParams } from '../utils';
@@ -235,9 +235,9 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  response =
  // retry only on GET requests for safety
  overwrittenRequestMethod === 'GET'
- ? await runWithExponentialBackOff(() => fetch(urlStr, fetchOpts), {
-firstDelay: 500,
-maxDelay: 3000,
+ ? await retry(() => fetch(urlStr, fetchOpts), {
+initialDelay: 500,
+maxDelayBetweenRetries: 3000,
  shouldRetry: (_: unknown, iterationsCount: number) => {
  return iterationsCount < maxTries;
  },

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

@@ -1,6 +1,6 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
 import { is4xxError } from '@clerk/shared/error';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
+import { retry } from '@clerk/shared/retry';
 import type {
  ActJWTClaim,
  CheckAuthorization,
@@ -84,7 +84,7 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
- return runWithExponentialBackOff(() => this._getToken(options), {
+ return retry(() => this._getToken(options), {
  shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
  });
  };

packages/shared/package.json

@@ -79,7 +79,7 @@
  "authorization",
  "authorization-errors",
  "browser",
- "callWithRetry",
+ "retry",
  "color",
  "cookie",
  "date",

packages/shared/src/__tests__/retry.test.ts

@@ -0,0 +1,208 @@
+import { retry } from '../retry';
+
+describe('retry', () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ test('resolves with the result of the callback', async () => {
+ const result = await retry(() => Promise.resolve('success'));
+ expect(result).toBe('success');
+ });
+
+ test('retries the callback until it succeeds', async () => {
+ let attempts = 0;
+ const result = retry(
+ () => {
+ attempts++;
+ if (attempts < 2) {
+ throw new Error('failed');
+ }
+ return Promise.resolve('success');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ jitter: false,
+ },
+ );
+ await jest.advanceTimersByTimeAsync(200);
+ expect(await result).toBe('success');
+ expect(attempts).toBe(2);
+ });
+
+ test('maxDelayBetweenRetries prevents delays from growing beyond the limit', async () => {
+ jest.useFakeTimers();
+ let attempts = 0;
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ maxDelayBetweenRetries: 300,
+ initialDelay: 100,
+ factor: 3,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 4,
+ },
+ ).catch(e => {
+ expect(e.message).toBe('failed');
+ });
+
+ // Run all timer advances before testing the promise
+ await jest.advanceTimersByTimeAsync(100);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ expect(attempts).toBe(1 + 4);
+ jest.useRealTimers();
+ });
+
+ test('respects initialDelay option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ { initialDelay: 200, jitter: false, shouldRetry: (_, count) => count <= 2 },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects retryImmediately option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 1000,
+ retryImmediately: true,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(101);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(1000);
+ expect(attempts).toBe(3);
+ });
+
+ test('disables immediate retry when retryImmediately is false', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 200,
+ retryImmediately: false,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects shouldRetry custom logic', async () => {
+ let attempts = 0;
+ const error = new Error('special error');
+
+ await retry(
+ () => {
+ attempts++;
+ throw error;
+ },
+ {
+ initialDelay: 100,
+ jitter: false,
+ shouldRetry: e => (e as Error).message !== 'special error',
+ },
+ ).catch(e => {
+ expect(e).toBe(error);
+ });
+
+ expect(attempts).toBe(1);
+ });
+
+ test('respects factor for exponential backoff', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 4,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 3,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(100);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(1600);
+ expect(attempts).toBe(4);
+ });
+
+ test('applies jitter by default', async () => {
+ let attempts = 0;
+
+ jest.spyOn(Math, 'random').mockReturnValue(0.5);
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ // First attempt that triggers the retry
+ expect(attempts).toBe(1);
+ // Flush all microtasks
+ await Promise.resolve();
+ // Normal delay without jitter
+ await jest.advanceTimersByTimeAsync(100);
+ // But the attempt is still 1 because with the jitter enabled,
+ // the delay is now 150
+ expect(attempts).toBe(1);
+ // Wait for 50ms more (100 + 50)
+ await jest.advanceTimersByTimeAsync(50);
+ // Should now reach the second attempt
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ });
+});

packages/shared/src/index.ts

@@ -12,7 +12,6 @@ export * from './utils';
 
 export { apiUrlFromPublishableKey } from './apiUrlFromPublishableKey';
 export * from './browser';
-export { callWithRetry } from './callWithRetry';
 export * from './color';
 export * from './constants';
 export * from './date';

packages/shared/src/loadScript.ts

@@ -1,4 +1,4 @@
-import { runWithExponentialBackOff } from './utils';
+import { retry } from './retry';
 
 const NO_DOCUMENT_ERROR = 'loadScript cannot be called when document does not exist';
 const NO_SRC_ERROR = 'loadScript cannot be called without a src';
@@ -47,5 +47,5 @@ export async function loadScript(src = '', opts: LoadScriptOptions): Promise<HTM
  });
  };
 
- return runWithExponentialBackOff(load, { shouldRetry: (_, iterations) => iterations < 5 });
+ return retry(load, { shouldRetry: (_, iterations) => iterations <= 5 });
 }

.changeset/metal-bobcats-wash.md

@@ -0,0 +1,27 @@
+---
+'@clerk/shared': major
+---
+This new version introduces the following breaking changes:
+- Introduced a new `retry` utility function to replace the deprecated `callWithRetry`.
+- Removed the `callWithRetry` function and its associated tests.
+- Renamed `runWithExponentialBackOff` to `retry` for consistency.
+
+Migration steps:
+- Replace any usage of `callWithRetry` with the new `retry` function.
+- Update import statements from:
+ ```typescript
+ import { callWithRetry } from '@clerk/shared/callWithRetry';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```
+- Replace any usage of `runWithExponentialBackOff` with `retry`.
+- Update import statements from:
+ ```typescript
+ import { runWithExponentialBackOff } from '@clerk/shared/utils';
+ ```
+ to:
+ ```typescript
+ import { retry } from '@clerk/shared/retry';
+ ```

packages/backend/src/tokens/keys.ts

@@ -13,7 +13,7 @@ import {
 } from '../errors';
 import { runtime } from '../runtime';
 import { joinPaths } from '../util/path';
-import { callWithRetry } from '../util/shared';
+import { retry } from '../util/shared';
 
 type JsonWebKeyWithKid = JsonWebKey & { kid: string };
 
@@ -137,8 +137,8 @@ export async function loadClerkJWKFromRemote({
  reason: TokenVerificationErrorReason.RemoteJWKFailedToLoad,
  });
  }
- const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion);
- const { keys } = await callWithRetry<{ keys: JsonWebKeyWithKid[] }>(fetcher);
+ const fetcher = () => fetchJWKSFromBAPI(apiUrl, secretKey, apiVersion) as Promise<{ keys: JsonWebKeyWithKid[] }>;
+ const { keys } = await retry(fetcher);
 
  if (!keys || !keys.length) {
  throw new TokenVerificationError({

packages/backend/src/util/shared.ts

@@ -1,5 +1,5 @@
 export { addClerkPrefix, getScriptUrl, getClerkJsMajorVersionOrTag } from '@clerk/shared/url';
-export { callWithRetry } from '@clerk/shared/callWithRetry';
+export { retry } from '@clerk/shared/retry';
 export {
  isDevelopmentFromSecretKey,
  isProductionFromSecretKey,
@@ -10,8 +10,8 @@ export {
 export { deprecated, deprecatedProperty } from '@clerk/shared/deprecated';
 
 import { buildErrorThrower } from '@clerk/shared/error';
+import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 // TODO: replace packageName with `${PACKAGE_NAME}@${PACKAGE_VERSION}` from tsup.config.ts
 export const errorThrower = buildErrorThrower({ packageName: '@clerk/backend' });
 
-import { createDevOrStagingUrlCache } from '@clerk/shared/keys';
 export const { isDevOrStagingUrl } = createDevOrStagingUrlCache();

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

@@ -1,6 +1,6 @@
 import { isBrowserOnline } from '@clerk/shared/browser';
+import { retry } from '@clerk/shared/retry';
 import { camelToSnake } from '@clerk/shared/underscore';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
 import type { ClerkAPIErrorJSON, ClientJSON, InstanceType } from '@clerk/types';
 
 import { buildEmailAddress as buildEmailAddressUtil, buildURL as buildUrlUtil, stringifyQueryParams } from '../utils';
@@ -235,9 +235,9 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  response =
  // retry only on GET requests for safety
  overwrittenRequestMethod === 'GET'
- ? await runWithExponentialBackOff(() => fetch(urlStr, fetchOpts), {
-firstDelay: 500,
-maxDelay: 3000,
+ ? await retry(() => fetch(urlStr, fetchOpts), {
+initialDelay: 500,
+maxDelayBetweenRetries: 3000,
  shouldRetry: (_: unknown, iterationsCount: number) => {
  return iterationsCount < maxTries;
  },

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

@@ -1,6 +1,6 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
 import { is4xxError } from '@clerk/shared/error';
-import { runWithExponentialBackOff } from '@clerk/shared/utils';
+import { retry } from '@clerk/shared/retry';
 import type {
  ActJWTClaim,
  CheckAuthorization,
@@ -84,7 +84,7 @@ export class Session extends BaseResource implements SessionResource {
  };
 
  getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
- return runWithExponentialBackOff(() => this._getToken(options), {
+ return retry(() => this._getToken(options), {
  shouldRetry: (error: unknown, currentIteration: number) => !is4xxError(error) && currentIteration < 4,
  });
  };

packages/shared/package.json

@@ -79,7 +79,7 @@
  "authorization",
  "authorization-errors",
  "browser",
- "callWithRetry",
+ "retry",
  "color",
  "cookie",
  "date",

packages/shared/src/__tests__/retry.test.ts

@@ -0,0 +1,208 @@
+import { retry } from '../retry';
+
+describe('retry', () => {
+ beforeEach(() => {
+ jest.useFakeTimers();
+ });
+
+ afterEach(() => {
+ jest.useRealTimers();
+ });
+
+ test('resolves with the result of the callback', async () => {
+ const result = await retry(() => Promise.resolve('success'));
+ expect(result).toBe('success');
+ });
+
+ test('retries the callback until it succeeds', async () => {
+ let attempts = 0;
+ const result = retry(
+ () => {
+ attempts++;
+ if (attempts < 2) {
+ throw new Error('failed');
+ }
+ return Promise.resolve('success');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ jitter: false,
+ },
+ );
+ await jest.advanceTimersByTimeAsync(200);
+ expect(await result).toBe('success');
+ expect(attempts).toBe(2);
+ });
+
+ test('maxDelayBetweenRetries prevents delays from growing beyond the limit', async () => {
+ jest.useFakeTimers();
+ let attempts = 0;
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ maxDelayBetweenRetries: 300,
+ initialDelay: 100,
+ factor: 3,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 4,
+ },
+ ).catch(e => {
+ expect(e.message).toBe('failed');
+ });
+
+ // Run all timer advances before testing the promise
+ await jest.advanceTimersByTimeAsync(100);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ await jest.advanceTimersByTimeAsync(300);
+ expect(attempts).toBe(1 + 4);
+ jest.useRealTimers();
+ });
+
+ test('respects initialDelay option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ { initialDelay: 200, jitter: false, shouldRetry: (_, count) => count <= 2 },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects retryImmediately option', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 1000,
+ retryImmediately: true,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(101);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(1000);
+ expect(attempts).toBe(3);
+ });
+
+ test('disables immediate retry when retryImmediately is false', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 200,
+ retryImmediately: false,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(200);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ });
+
+ test('respects shouldRetry custom logic', async () => {
+ let attempts = 0;
+ const error = new Error('special error');
+
+ await retry(
+ () => {
+ attempts++;
+ throw error;
+ },
+ {
+ initialDelay: 100,
+ jitter: false,
+ shouldRetry: e => (e as Error).message !== 'special error',
+ },
+ ).catch(e => {
+ expect(e).toBe(error);
+ });
+
+ expect(attempts).toBe(1);
+ });
+
+ test('respects factor for exponential backoff', async () => {
+ let attempts = 0;
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 4,
+ jitter: false,
+ shouldRetry: (_, count) => count <= 3,
+ },
+ ).catch(() => {});
+
+ expect(attempts).toBe(1);
+ await jest.advanceTimersByTimeAsync(100);
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(400);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(1600);
+ expect(attempts).toBe(4);
+ });
+
+ test('applies jitter by default', async () => {
+ let attempts = 0;
+
+ jest.spyOn(Math, 'random').mockReturnValue(0.5);
+
+ retry(
+ () => {
+ attempts++;
+ throw new Error('failed');
+ },
+ {
+ initialDelay: 100,
+ factor: 1,
+ shouldRetry: (_, count) => count <= 2,
+ },
+ ).catch(() => {});
+
+ // First attempt that triggers the retry
+ expect(attempts).toBe(1);
+ // Flush all microtasks
+ await Promise.resolve();
+ // Normal delay without jitter
+ await jest.advanceTimersByTimeAsync(100);
+ // But the attempt is still 1 because with the jitter enabled,
+ // the delay is now 150
+ expect(attempts).toBe(1);
+ // Wait for 50ms more (100 + 50)
+ await jest.advanceTimersByTimeAsync(50);
+ // Should now reach the second attempt
+ expect(attempts).toBe(2);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ await jest.advanceTimersByTimeAsync(150);
+ expect(attempts).toBe(3);
+ });
+});

packages/shared/src/index.ts

@@ -12,7 +12,6 @@ export * from './utils';
 
 export { apiUrlFromPublishableKey } from './apiUrlFromPublishableKey';
 export * from './browser';
-export { callWithRetry } from './callWithRetry';
 export * from './color';
 export * from './constants';
 export * from './date';

packages/shared/src/loadScript.ts

@@ -1,4 +1,4 @@
-import { runWithExponentialBackOff } from './utils';
+import { retry } from './retry';
 
 const NO_DOCUMENT_ERROR = 'loadScript cannot be called when document does not exist';
 const NO_SRC_ERROR = 'loadScript cannot be called without a src';
@@ -47,5 +47,5 @@ export async function loadScript(src = '', opts: LoadScriptOptions): Promise<HTM
  });
  };
 
- return runWithExponentialBackOff(load, { shouldRetry: (_, iterations) => iterations < 5 });
+ return retry(load, { shouldRetry: (_, iterations) => iterations <= 5 });
 }