introduce safeImport

Author: nikosdouvlis

packages/shared/package.json

@@ -80,6 +80,16 @@
         "default": "./dist/runtime/ui/index.js"
       }
     },
+    "./import": {
+      "import": {
+        "types": "./dist/runtime/import/index.d.mts",
+        "default": "./dist/runtime/import/index.mjs"
+      },
+      "require": {
+        "types": "./dist/runtime/import/index.d.ts",
+        "default": "./dist/runtime/import/index.js"
+      }
+    },
     "./types": {
       "import": {
         "types": "./dist/types/index.d.mts",

packages/shared/src/import/__tests__/safeImport.spec.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test, vi } from 'vitest';
+
+import * as retryModule from '../../retry';
+import { safeImport } from '../index';
+
+describe('safeImport', () => {
+  test('calls retry with correct configuration', async () => {
+    const retrySpy = vi.spyOn(retryModule, 'retry');
+    const testModule = './test-module';
+
+    try {
+      await safeImport(testModule);
+    } catch {
+      // Ignore import errors since we're just testing the retry configuration
+    }
+
+    expect(retrySpy).toHaveBeenCalledWith(
+      expect.any(Function),
+      expect.objectContaining({
+        initialDelay: 100,
+        retryImmediately: true,
+        factor: 2,
+      }),
+    );
+
+    retrySpy.mockRestore();
+  });
+
+  test('returns imported module on success', async () => {
+    const mockModule = { default: 'test-module', namedExport: 'value' };
+
+    // Mock the retry to immediately return our mock module
+    const retrySpy = vi.spyOn(retryModule, 'retry').mockResolvedValueOnce(mockModule);
+
+    const result = await safeImport('./test-module');
+
+    expect(result).toBe(mockModule);
+    expect(retrySpy).toHaveBeenCalledTimes(1);
+
+    retrySpy.mockRestore();
+  });
+
+  test('propagates import errors after retries', async () => {
+    const importError = new Error('Module not found');
+
+    // Mock retry to reject with our error
+    const retrySpy = vi.spyOn(retryModule, 'retry').mockRejectedValueOnce(importError);
+
+    await expect(safeImport('./non-existent-module')).rejects.toThrow('Module not found');
+
+    retrySpy.mockRestore();
+  });
+
+  test('configures shouldRetry to allow up to 3 retries', async () => {
+    const retrySpy = vi.spyOn(retryModule, 'retry');
+
+    try {
+      await safeImport('./test-module');
+    } catch {
+      // Ignore errors
+    }
+
+    const options = retrySpy.mock.calls[0][1];
+    const shouldRetry = options?.shouldRetry;
+
+    expect(shouldRetry).toBeDefined();
+    if (shouldRetry) {
+      // Test the shouldRetry logic
+      expect(shouldRetry(new Error('test'), 1)).toBe(true); // First retry
+      expect(shouldRetry(new Error('test'), 2)).toBe(true); // Second retry
+      expect(shouldRetry(new Error('test'), 3)).toBe(true); // Third retry
+      expect(shouldRetry(new Error('test'), 4)).toBe(false); // Fourth attempt should not retry
+    }
+
+    retrySpy.mockRestore();
+  });
+});

packages/shared/src/import/index.ts

@@ -0,0 +1,23 @@
+import { retry } from '../retry';
+
+/**
+ * Safely imports a module with automatic retries on failure.
+ * Useful for dynamic imports that might fail due to network issues or temporary loading problems.
+ * Retries up to 3 times with exponential backoff.
+ *
+ * @param modulePath - The path to the module to import
+ * @returns A promise that resolves to the imported module
+ *
+ * @example
+ * ```typescript
+ * const module = await safeImport('./my-module');
+ * ```
+ */
+export const safeImport = async <T = any>(modulePath: string): Promise<T> => {
+  return retry(() => import(modulePath) as Promise<T>, {
+    initialDelay: 100,
+    shouldRetry: (_, iterations) => iterations <= 3,
+    retryImmediately: true,
+    factor: 2,
+  });
+};

packages/shared/tsdown.config.mts

@@ -43,6 +43,7 @@ export default defineConfig(({ watch }) => {
         './src/types/index.ts',
         './src/dom/*.ts',
         './src/ui/index.ts',
+        './src/import/index.ts',
         './src/internal/clerk-js/*.ts',
         './src/internal/clerk-js/**/*.ts',
         '!./src/**/*.{test,spec}.{ts,tsx}',