fict 0.1.0 → 0.2.1

package/dist/plus.d.cts

@@ -1,48 +1,248 @@
-export { $ as $store } from './store-BmwKJIj6.cjs';
+export { $ as $store } from './store-UpSYx4_N.cjs';
 import { Component } from '@fictjs/runtime';
 
+/**
+ * @fileoverview Async data fetching with caching and Suspense support.
+ *
+ * The `resource` function creates a reactive data fetcher that:
+ * - Automatically cancels in-flight requests when args change
+ * - Supports Suspense for loading states
+ * - Provides caching with TTL and stale-while-revalidate
+ * - Handles errors gracefully
+ */
+/**
+ * The result of reading a resource.
+ *
+ * @typeParam T - The type of data returned by the fetcher
+ */
 interface ResourceResult<T> {
-    data: T | undefined;
-    loading: boolean;
-    error: unknown;
+    /** The fetched data, or undefined if not yet loaded or on error */
+    readonly data: T | undefined;
+    /** Whether the resource is currently loading (initial fetch or refetch) */
+    readonly loading: boolean;
+    /**
+     * Any error that occurred during fetching.
+     * Type is unknown since errors can be any value in JavaScript.
+     */
+    readonly error: unknown;
+    /** Manually trigger a refetch of the resource */
     refresh: () => void;
 }
+/**
+ * Cache configuration options for a resource.
+ */
 interface ResourceCacheOptions {
+    /**
+     * Caching mode:
+     * - `'memory'`: Cache responses in memory (default)
+     * - `'none'`: No caching, always refetch
+     * @default 'memory'
+     */
     mode?: 'memory' | 'none';
+    /**
+     * Time-to-live in milliseconds before cached data is considered stale.
+     * @default Infinity
+     */
     ttlMs?: number;
+    /**
+     * If true, return stale cached data immediately while refetching in background.
+     * @default false
+     */
     staleWhileRevalidate?: boolean;
+    /**
+     * If true, cache error responses as well.
+     * @default false
+     */
     cacheErrors?: boolean;
 }
+/**
+ * Configuration options for creating a resource.
+ *
+ * @typeParam T - The type of data returned by the fetcher
+ * @typeParam Args - The type of arguments passed to the fetcher
+ */
 interface ResourceOptions<T, Args> {
-    key?: unknown;
+    /**
+     * Custom cache key. Can be a static value or a function that computes
+     * the key from the args. If not provided, args are used as the key.
+     */
+    key?: unknown | ((args: Args) => unknown);
+    /**
+     * The fetcher function that performs the async data retrieval.
+     * Receives an AbortController signal for cancellation support.
+     */
     fetch: (ctx: {
         signal: AbortSignal;
     }, args: Args) => Promise<T>;
+    /**
+     * If true, the resource will throw a Suspense token while loading,
+     * enabling React-like Suspense boundaries.
+     * @default false
+     */
     suspense?: boolean;
+    /**
+     * Cache configuration options.
+     */
     cache?: ResourceCacheOptions;
+    /**
+     * A value or reactive getter that, when changed, resets the resource.
+     * Useful for clearing cache when certain conditions change.
+     */
     reset?: unknown | (() => unknown);
 }
 /**
- * Creates a resource factory that can be read with arguments.
+ * Return type of the resource factory.
  *
- * @param optionsOrFetcher - Configuration object or fetcher function
+ * @typeParam T - The type of data returned by the fetcher
+ * @typeParam Args - The type of arguments passed to the fetcher
+ */
+interface Resource<T, Args> {
+    /**
+     * Read the resource data, triggering a fetch if needed.
+     * Can accept static args or a reactive getter.
+     *
+     * @param argsAccessor - Arguments or a getter returning arguments
+     */
+    read(argsAccessor: (() => Args) | Args): ResourceResult<T>;
+    /**
+     * Invalidate cached data, causing the next read to refetch.
+     *
+     * @param key - Optional specific key to invalidate. If omitted, invalidates all.
+     */
+    invalidate(key?: unknown): void;
+    /**
+     * Prefetch data without reading it. Useful for eager loading.
+     *
+     * @param args - Arguments to pass to the fetcher
+     * @param keyOverride - Optional cache key override
+     */
+    prefetch(args: Args, keyOverride?: unknown): void;
+}
+/**
+ * Create a reactive async data resource.
+ *
+ * Resources handle async data fetching with automatic caching, cancellation,
+ * and optional Suspense integration.
+ *
+ * @param optionsOrFetcher - A fetcher function or full configuration object
+ * @returns A resource factory with read, invalidate, and prefetch methods
+ *
+ * @example
+ * ```tsx
+ * import { resource } from 'fict'
+ *
+ * // Simple fetcher
+ * const userResource = resource(
+ *   ({ signal }, userId: string) =>
+ *     fetch(`/api/users/${userId}`, { signal }).then(r => r.json())
+ * )
+ *
+ * // With full options
+ * const postsResource = resource({
+ *   fetch: ({ signal }, userId: string) =>
+ *     fetch(`/api/users/${userId}/posts`, { signal }).then(r => r.json()),
+ *   suspense: true,
+ *   cache: {
+ *     ttlMs: 60_000,
+ *     staleWhileRevalidate: true,
+ *   },
+ * })
+ *
+ * // Usage in component
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const { data, loading, error, refresh } = userResource.read(() => userId)
+ *
+ *   if (loading) return <Spinner />
+ *   if (error) return <ErrorMessage error={error} />
+ *   return <div>{data.name}</div>
+ * }
+ * ```
+ *
+ * @public
  */
 declare function resource<T, Args = void>(optionsOrFetcher: ((ctx: {
     signal: AbortSignal;
-}, args: Args) => Promise<T>) | ResourceOptions<T, Args>): {
-    read(argsAccessor: (() => Args) | Args): ResourceResult<T>;
-    invalidate: (key?: unknown) => void;
-    prefetch: (args: Args, keyOverride?: unknown) => void;
-};
+}, args: Args) => Promise<T>) | ResourceOptions<T, Args>): Resource<T, Args>;
+
+/**
+ * @fileoverview Lazy component loading with Suspense support.
+ *
+ * Creates a component that loads its implementation asynchronously,
+ * suspending rendering until the module is loaded.
+ */
 
+/** Module shape expected from dynamic imports */
 interface LazyModule<TProps extends Record<string, unknown>> {
     default: Component<TProps>;
 }
+/** Options for lazy loading behavior */
+interface LazyOptions {
+    /**
+     * Maximum number of retry attempts on load failure.
+     * Set to 0 to disable retries (default behavior).
+     * @default 0
+     */
+    maxRetries?: number;
+    /**
+     * Delay in milliseconds between retry attempts.
+     * Uses exponential backoff: delay * 2^(attempt - 1)
+     * @default 1000
+     */
+    retryDelay?: number;
+}
+/** Extended component with retry capability */
+interface LazyComponent<TProps extends Record<string, unknown>> extends Component<TProps> {
+    /**
+     * Reset the lazy component state, allowing it to retry loading.
+     * Useful when used with ErrorBoundary reset functionality.
+     */
+    reset: () => void;
+    /**
+     * Preload the component without rendering it.
+     * Returns a promise that resolves when the component is loaded.
+     */
+    preload: () => Promise<void>;
+}
 /**
  * Create a lazy component that suspends while loading.
+ *
+ * @param loader - Function that returns a promise resolving to the component module
+ * @param options - Optional configuration for retry behavior
+ * @returns A component that suspends during loading and supports retry on failure
+ *
+ * @example
+ * ```tsx
+ * import { lazy, Suspense } from 'fict'
+ *
+ * // Basic usage
+ * const LazyChart = lazy(() => import('./Chart'))
+ *
+ * // With retry options
+ * const LazyDashboard = lazy(() => import('./Dashboard'), {
+ *   maxRetries: 3,
+ *   retryDelay: 1000
+ * })
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<Loading />}>
+ *       <LazyChart />
+ *     </Suspense>
+ *   )
+ * }
+ *
+ * // Reset on error (with ErrorBoundary)
+ * <ErrorBoundary fallback={(err, reset) => (
+ *   <button onClick={() => { LazyChart.reset(); reset(); }}>Retry</button>
+ * )}>
+ *   <LazyChart />
+ * </ErrorBoundary>
+ * ```
+ *
+ * @public
  */
 declare function lazy<TProps extends Record<string, unknown> = Record<string, unknown>>(loader: () => Promise<LazyModule<TProps> | {
     default: Component<TProps>;
-}>): Component<TProps>;
+}>, options?: LazyOptions): LazyComponent<TProps>;
 
 export { type LazyModule, type ResourceCacheOptions, type ResourceOptions, type ResourceResult, lazy, resource };

package/dist/plus.d.ts

@@ -1,48 +1,248 @@
-export { $ as $store } from './store-BmwKJIj6.js';
+export { $ as $store } from './store-UpSYx4_N.js';
 import { Component } from '@fictjs/runtime';
 
+/**
+ * @fileoverview Async data fetching with caching and Suspense support.
+ *
+ * The `resource` function creates a reactive data fetcher that:
+ * - Automatically cancels in-flight requests when args change
+ * - Supports Suspense for loading states
+ * - Provides caching with TTL and stale-while-revalidate
+ * - Handles errors gracefully
+ */
+/**
+ * The result of reading a resource.
+ *
+ * @typeParam T - The type of data returned by the fetcher
+ */
 interface ResourceResult<T> {
-    data: T | undefined;
-    loading: boolean;
-    error: unknown;
+    /** The fetched data, or undefined if not yet loaded or on error */
+    readonly data: T | undefined;
+    /** Whether the resource is currently loading (initial fetch or refetch) */
+    readonly loading: boolean;
+    /**
+     * Any error that occurred during fetching.
+     * Type is unknown since errors can be any value in JavaScript.
+     */
+    readonly error: unknown;
+    /** Manually trigger a refetch of the resource */
     refresh: () => void;
 }
+/**
+ * Cache configuration options for a resource.
+ */
 interface ResourceCacheOptions {
+    /**
+     * Caching mode:
+     * - `'memory'`: Cache responses in memory (default)
+     * - `'none'`: No caching, always refetch
+     * @default 'memory'
+     */
     mode?: 'memory' | 'none';
+    /**
+     * Time-to-live in milliseconds before cached data is considered stale.
+     * @default Infinity
+     */
     ttlMs?: number;
+    /**
+     * If true, return stale cached data immediately while refetching in background.
+     * @default false
+     */
     staleWhileRevalidate?: boolean;
+    /**
+     * If true, cache error responses as well.
+     * @default false
+     */
     cacheErrors?: boolean;
 }
+/**
+ * Configuration options for creating a resource.
+ *
+ * @typeParam T - The type of data returned by the fetcher
+ * @typeParam Args - The type of arguments passed to the fetcher
+ */
 interface ResourceOptions<T, Args> {
-    key?: unknown;
+    /**
+     * Custom cache key. Can be a static value or a function that computes
+     * the key from the args. If not provided, args are used as the key.
+     */
+    key?: unknown | ((args: Args) => unknown);
+    /**
+     * The fetcher function that performs the async data retrieval.
+     * Receives an AbortController signal for cancellation support.
+     */
     fetch: (ctx: {
         signal: AbortSignal;
     }, args: Args) => Promise<T>;
+    /**
+     * If true, the resource will throw a Suspense token while loading,
+     * enabling React-like Suspense boundaries.
+     * @default false
+     */
     suspense?: boolean;
+    /**
+     * Cache configuration options.
+     */
     cache?: ResourceCacheOptions;
+    /**
+     * A value or reactive getter that, when changed, resets the resource.
+     * Useful for clearing cache when certain conditions change.
+     */
     reset?: unknown | (() => unknown);
 }
 /**
- * Creates a resource factory that can be read with arguments.
+ * Return type of the resource factory.
  *
- * @param optionsOrFetcher - Configuration object or fetcher function
+ * @typeParam T - The type of data returned by the fetcher
+ * @typeParam Args - The type of arguments passed to the fetcher
+ */
+interface Resource<T, Args> {
+    /**
+     * Read the resource data, triggering a fetch if needed.
+     * Can accept static args or a reactive getter.
+     *
+     * @param argsAccessor - Arguments or a getter returning arguments
+     */
+    read(argsAccessor: (() => Args) | Args): ResourceResult<T>;
+    /**
+     * Invalidate cached data, causing the next read to refetch.
+     *
+     * @param key - Optional specific key to invalidate. If omitted, invalidates all.
+     */
+    invalidate(key?: unknown): void;
+    /**
+     * Prefetch data without reading it. Useful for eager loading.
+     *
+     * @param args - Arguments to pass to the fetcher
+     * @param keyOverride - Optional cache key override
+     */
+    prefetch(args: Args, keyOverride?: unknown): void;
+}
+/**
+ * Create a reactive async data resource.
+ *
+ * Resources handle async data fetching with automatic caching, cancellation,
+ * and optional Suspense integration.
+ *
+ * @param optionsOrFetcher - A fetcher function or full configuration object
+ * @returns A resource factory with read, invalidate, and prefetch methods
+ *
+ * @example
+ * ```tsx
+ * import { resource } from 'fict'
+ *
+ * // Simple fetcher
+ * const userResource = resource(
+ *   ({ signal }, userId: string) =>
+ *     fetch(`/api/users/${userId}`, { signal }).then(r => r.json())
+ * )
+ *
+ * // With full options
+ * const postsResource = resource({
+ *   fetch: ({ signal }, userId: string) =>
+ *     fetch(`/api/users/${userId}/posts`, { signal }).then(r => r.json()),
+ *   suspense: true,
+ *   cache: {
+ *     ttlMs: 60_000,
+ *     staleWhileRevalidate: true,
+ *   },
+ * })
+ *
+ * // Usage in component
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const { data, loading, error, refresh } = userResource.read(() => userId)
+ *
+ *   if (loading) return <Spinner />
+ *   if (error) return <ErrorMessage error={error} />
+ *   return <div>{data.name}</div>
+ * }
+ * ```
+ *
+ * @public
  */
 declare function resource<T, Args = void>(optionsOrFetcher: ((ctx: {
     signal: AbortSignal;
-}, args: Args) => Promise<T>) | ResourceOptions<T, Args>): {
-    read(argsAccessor: (() => Args) | Args): ResourceResult<T>;
-    invalidate: (key?: unknown) => void;
-    prefetch: (args: Args, keyOverride?: unknown) => void;
-};
+}, args: Args) => Promise<T>) | ResourceOptions<T, Args>): Resource<T, Args>;
+
+/**
+ * @fileoverview Lazy component loading with Suspense support.
+ *
+ * Creates a component that loads its implementation asynchronously,
+ * suspending rendering until the module is loaded.
+ */
 
+/** Module shape expected from dynamic imports */
 interface LazyModule<TProps extends Record<string, unknown>> {
     default: Component<TProps>;
 }
+/** Options for lazy loading behavior */
+interface LazyOptions {
+    /**
+     * Maximum number of retry attempts on load failure.
+     * Set to 0 to disable retries (default behavior).
+     * @default 0
+     */
+    maxRetries?: number;
+    /**
+     * Delay in milliseconds between retry attempts.
+     * Uses exponential backoff: delay * 2^(attempt - 1)
+     * @default 1000
+     */
+    retryDelay?: number;
+}
+/** Extended component with retry capability */
+interface LazyComponent<TProps extends Record<string, unknown>> extends Component<TProps> {
+    /**
+     * Reset the lazy component state, allowing it to retry loading.
+     * Useful when used with ErrorBoundary reset functionality.
+     */
+    reset: () => void;
+    /**
+     * Preload the component without rendering it.
+     * Returns a promise that resolves when the component is loaded.
+     */
+    preload: () => Promise<void>;
+}
 /**
  * Create a lazy component that suspends while loading.
+ *
+ * @param loader - Function that returns a promise resolving to the component module
+ * @param options - Optional configuration for retry behavior
+ * @returns A component that suspends during loading and supports retry on failure
+ *
+ * @example
+ * ```tsx
+ * import { lazy, Suspense } from 'fict'
+ *
+ * // Basic usage
+ * const LazyChart = lazy(() => import('./Chart'))
+ *
+ * // With retry options
+ * const LazyDashboard = lazy(() => import('./Dashboard'), {
+ *   maxRetries: 3,
+ *   retryDelay: 1000
+ * })
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<Loading />}>
+ *       <LazyChart />
+ *     </Suspense>
+ *   )
+ * }
+ *
+ * // Reset on error (with ErrorBoundary)
+ * <ErrorBoundary fallback={(err, reset) => (
+ *   <button onClick={() => { LazyChart.reset(); reset(); }}>Retry</button>
+ * )}>
+ *   <LazyChart />
+ * </ErrorBoundary>
+ * ```
+ *
+ * @public
  */
 declare function lazy<TProps extends Record<string, unknown> = Record<string, unknown>>(loader: () => Promise<LazyModule<TProps> | {
     default: Component<TProps>;
-}>): Component<TProps>;
+}>, options?: LazyOptions): LazyComponent<TProps>;
 
 export { type LazyModule, type ResourceCacheOptions, type ResourceOptions, type ResourceResult, lazy, resource };

package/dist/plus.js

@@ -1,4 +1,4 @@
-export { $store } from './chunk-5AWNWCDT.js';
+export { $store } from './chunk-T5BGEI6S.js';
 import { createEffect, createSuspenseToken, onCleanup } from '@fictjs/runtime';
 import { createSignal } from '@fictjs/runtime/advanced';
 
@@ -207,12 +207,38 @@ function resource(optionsOrFetcher) {
     prefetch
   };
 }
-function lazy(loader) {
+function lazy(loader, options = {}) {
+  const { maxRetries = 0, retryDelay = 1e3 } = options;
   let loaded = null;
   let loadError = null;
   let loadingPromise = null;
   let pendingToken = null;
-  return (props) => {
+  let retryCount = 0;
+  const attemptLoad = () => {
+    return loader().then((mod) => {
+      loaded = mod.default;
+      loadError = null;
+      retryCount = 0;
+      pendingToken?.resolve();
+    }).catch((err) => {
+      if (retryCount < maxRetries) {
+        retryCount++;
+        const delay = retryDelay * Math.pow(2, retryCount - 1);
+        return new Promise((resolve) => {
+          setTimeout(() => {
+            resolve(attemptLoad());
+          }, delay);
+        });
+      }
+      loadError = err;
+      pendingToken?.reject(err);
+      return void 0;
+    }).finally(() => {
+      loadingPromise = null;
+      pendingToken = null;
+    });
+  };
+  const component = ((props) => {
     if (loaded) {
       return loaded(props);
     }
@@ -221,22 +247,31 @@ function lazy(loader) {
     }
     if (!loadingPromise) {
       pendingToken = createSuspenseToken();
-      loadingPromise = loader().then((mod) => {
-        loaded = mod.default;
-        pendingToken?.resolve();
-      }).catch((err) => {
-        loadError = err;
-        pendingToken?.reject(err);
-      }).finally(() => {
-        loadingPromise = null;
-        pendingToken = null;
-      });
+      loadingPromise = attemptLoad();
     }
     if (pendingToken) {
       throw pendingToken.token;
     }
     throw new Error("Lazy component failed to start loading");
+  });
+  component.reset = () => {
+    loadError = null;
+    loadingPromise = null;
+    pendingToken = null;
+    retryCount = 0;
+  };
+  component.preload = () => {
+    if (loaded) {
+      return Promise.resolve();
+    }
+    if (loadingPromise) {
+      return loadingPromise;
+    }
+    pendingToken = createSuspenseToken();
+    loadingPromise = attemptLoad();
+    return loadingPromise;
   };
+  return component;
 }
 
 export { lazy, resource };