@suspensive/react/dist/lazy.d.mts

Suspensive interfaces for react

import { ComponentType, LazyExoticComponent } from "react";

//#region src/lazy.d.ts
interface LazyOptions {
  onSuccess?: ({
    load
  }: {
    load: () => Promise<void>;
  }) => void;
  onError?: ({
    error,
    load
  }: {
    error: unknown;
    load: () => Promise<void>;
  }) => undefined;
}
/**
 * Creates a lazy function with custom default options
 *
 * The default `lazy` export is equivalent to `createLazy({})`.
 *
 * @experimental This is experimental feature.
 *
 * @description
 * The created lazy function will execute individual callbacks first, then default callbacks.
 * For onSuccess: individual onSuccess → default onSuccess
 * For onError: individual onError → default onError
 *
 * @example
 * ```tsx
 * import { createLazy } from '@suspensive/react'
 *
 * // Create a lazy factory with custom default options
 * const lazy = createLazy({
 *   onSuccess: () => console.log('Component loaded successfully'),
 *   onError: ({ error }) => console.error('Component loading failed:', error)
 * })
 *
 * // Use the factory to create lazy components
 * const Component1 = lazy(() => import('./Component1'))
 * const Component2 = lazy(() => import('./Component2'))
 *
 * // Individual options are executed after default options
 * const Component3 = lazy(() => import('./Component3'), {
 *   onError: ({ error }) => {
 *     console.error('Individual error handling:', error)
 *     // This callback runs after the default onError callback
 *   }
 * })
 * ```
 */
declare const createLazy: (defaultOptions: LazyOptions) => <T extends ComponentType<any>>(load: () => Promise<{
  default: T;
}>, options?: LazyOptions) => LazyExoticComponent<T> & {
  load: () => Promise<void>;
};
/**
 * A wrapper around React.lazy that provides error handling and success callbacks
 *
 * This is equivalent to `createLazy({})` - a lazy function with no default options.
 *
 * @experimental This is experimental feature.
 *
 * @example
 * ```tsx
 * import { lazy, Suspense } from '@suspensive/react'
 *
 * // Basic usage
 * const Component = lazy(() => import('./Component'))
 *
 * // With error handling and success callbacks
 * const ReloadComponent = lazy(() => import('./ReloadComponent'), {
 *   onError: ({ error }) => console.error('Loading failed:', error),
 *   onSuccess: () => console.log('Component loaded successfully')
 * })
 *
 * // Preloading component
 * function PreloadExample() {
 *   const handlePreload = () => {
 *     Component.load() // Preload the component
 *   }
 *
 *   return (
 *     <div>
 *       <button onClick={handlePreload}>Preload Component</button>
 *       <Suspense fallback={<div>Loading...</div>}>
 *         <Component />
 *       </Suspense>
 *     </div>
 *   )
 * }
 *
 * // Using createLazy for factory pattern
 * const lazy = createLazy({
 *   onError: ({ error }) => console.error('Default error handling:', error)
 * })
 * const CustomComponent = lazy(() => import('./CustomComponent'))
 * ```
 *
 * @returns A lazy component with additional `load` method for preloading
 * @property {() => Promise<void>} load - Preloads the component without rendering it. Useful for prefetching components in the background.
 */
declare const lazy: <T extends ComponentType<any>>(load: () => Promise<{
  default: T;
}>, options?: LazyOptions) => LazyExoticComponent<T> & {
  load: () => Promise<void>;
};
interface ReloadOnErrorStorage {
  getItem: (key: string) => string | null;
  setItem: (key: string, value: string) => void;
  removeItem: (key: string) => void;
}
interface ReloadOnErrorOptions extends LazyOptions {
  /**
   * The number of times to retry the loading of the component. \
   * If `true`, the component will be retried indefinitely.
   *
   * @default 1
   */
  retry?: number | boolean;
  /**
   * The delay between retries. \
   * If a function is provided, it will be called with the current retry count.
   *
   * @default 0
   */
  retryDelay?: number | ((retryCount: number) => number);
  /**
   * The storage to use for the retry count. \
   * If not provided, it assumes that you are in a browser environment and uses `window.sessionStorage`.
   *
   * @default window.sessionStorage
   */
  storage?: ReloadOnErrorStorage;
  /**
   * The function to use to reload the component. \
   * If not provided, it assumes that you are in a browser environment and uses `window.location.reload`.
   *
   * @default window.location.reload
   */
  reload?: (timeoutId: ReturnType<typeof setTimeout>) => void;
}
/**
 * Options for reloading page if the component fails to load.
 *
 * @experimental This is experimental feature.
 *
 * @example
 * ```tsx
 * import { createLazy, reloadOnError } from '@suspensive/react'
 *
 * const lazy = createLazy(reloadOnError({ retry: 1, retryDelay: 1000 }))
 * const Component = lazy(() => import('./Component'))
 * ```
 */
declare const reloadOnError: ({
  retry,
  retryDelay,
  storage,
  reload,
  ...options
}: ReloadOnErrorOptions) => LazyOptions;
//#endregion
export { createLazy, lazy, reloadOnError };
//# sourceMappingURL=lazy.d.mts.map