sibujs 1.0.0-beta.1

package/dist/data.d.ts

@@ -0,0 +1,434 @@
+/**
+ * Configurable retry strategies for async operations.
+ * Used by `resource` and `query` for automatic error recovery.
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts. Default: 3 */
+    maxRetries?: number;
+    /** Retry strategy. Default: "exponential" */
+    strategy?: "exponential" | "linear" | "fixed";
+    /** Base delay in ms. Default: 1000 */
+    baseDelay?: number;
+    /** Maximum delay in ms (caps exponential growth). Default: 30000 */
+    maxDelay?: number;
+    /** Jitter factor (0-1) to randomize delay. Default: 0.1 */
+    jitter?: number;
+    /** Predicate to decide if an error is retryable. Default: () => true */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+}
+/**
+ * Calculate delay for a given attempt based on strategy.
+ */
+declare function calculateDelay(attempt: number, strategy: "exponential" | "linear" | "fixed", baseDelay: number, maxDelay: number, jitter: number): number;
+/**
+ * Execute an async function with retry logic.
+ * Returns the result or throws after all retries are exhausted.
+ *
+ * @param fn The async function to execute
+ * @param options Retry configuration
+ * @param onRetry Callback fired before each retry with error, attempt, and delay
+ * @param signal AbortSignal to cancel retries
+ *
+ * @example
+ * ```ts
+ * const data = await withRetry(() => fetch("/api/data").then(r => r.json()), {
+ *   maxRetries: 3,
+ *   strategy: "exponential",
+ *   shouldRetry: (err) => !(err instanceof TypeError),
+ * });
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions, onRetry?: (error: unknown, attempt: number, delay: number) => void, signal?: AbortSignal): Promise<T>;
+
+interface QueryOptions<T> {
+    /** Time in ms before cached data is considered stale. Default: 0 (always stale) */
+    staleTime?: number;
+    /** Time in ms to keep unused cache entries. Default: 300000 (5 min) */
+    cacheTime?: number;
+    /** Whether to fetch on creation. Default: true */
+    enabled?: boolean;
+    /** Retry options for failed fetches */
+    retry?: RetryOptions;
+    /** Initial data before first fetch */
+    initialData?: T;
+    /** Auto-refetch interval in ms */
+    refetchInterval?: number;
+    /** Refetch when window regains focus */
+    refetchOnWindowFocus?: boolean;
+    /** Refetch when network reconnects */
+    refetchOnReconnect?: boolean;
+    /** Called on successful fetch */
+    onSuccess?: (data: T) => void;
+    /** Called on fetch error */
+    onError?: (error: Error) => void;
+    /** Called on fetch settle (success or error) */
+    onSettled?: () => void;
+}
+interface QueryResult<T> {
+    /** Reactive getter for the cached data */
+    data: () => T | undefined;
+    /** Reactive getter: true when fetching with no cached data */
+    loading: () => boolean;
+    /** Reactive getter: true when any fetch is in progress */
+    fetching: () => boolean;
+    /** Reactive getter for the error state */
+    error: () => Error | undefined;
+    /** Reactive getter: whether cached data is stale */
+    isStale: () => boolean;
+    /** Manually trigger a refetch */
+    refetch: () => Promise<void>;
+    /** Cleanup subscriptions and timers */
+    dispose: () => void;
+}
+declare function query<T>(key: string | (() => string), fetcher: (ctx: {
+    signal: AbortSignal;
+    key: string;
+}) => Promise<T>, options?: QueryOptions<T>): QueryResult<T>;
+/** Invalidate queries matching a key or predicate, triggering refetch for active subscribers */
+declare function invalidateQueries(keyOrPredicate: string | ((key: string) => boolean)): void;
+/** Get cached data for a query key */
+declare function getQueryData<T>(key: string): T | undefined;
+/** Set cached data for a query key, notifying subscribers */
+declare function setQueryData<T>(key: string, data: T | ((prev: T | undefined) => T)): void;
+/** Clear the entire query cache */
+declare function clearQueryCache(): void;
+
+interface MutationOptions<TData, TVariables, TContext = unknown> {
+    /** Retry options for failed mutations */
+    retry?: RetryOptions;
+    /** Called before mutation — return context for rollback in onError */
+    onMutate?: (variables: TVariables) => TContext | Promise<TContext>;
+    /** Called on successful mutation */
+    onSuccess?: (data: TData, variables: TVariables, context: TContext) => void;
+    /** Called on mutation error — context from onMutate available for rollback */
+    onError?: (error: Error, variables: TVariables, context: TContext | undefined) => void;
+    /** Called on mutation settle (success or error) */
+    onSettled?: (data: TData | undefined, error: Error | undefined, variables: TVariables, context: TContext | undefined) => void;
+}
+interface MutationResult<TData, TVariables> {
+    /** Reactive getter for the mutation result data */
+    data: () => TData | undefined;
+    /** Reactive getter for the loading state */
+    loading: () => boolean;
+    /** Reactive getter for the error state */
+    error: () => Error | undefined;
+    /** Reactive getter: true if mutation succeeded */
+    isSuccess: () => boolean;
+    /** Reactive getter: true if mutation has not been called */
+    isIdle: () => boolean;
+    /** Fire-and-forget mutation trigger */
+    mutate: (variables: TVariables) => void;
+    /** Mutation trigger that returns a promise */
+    mutateAsync: (variables: TVariables) => Promise<TData>;
+    /** Reset state to idle */
+    reset: () => void;
+}
+declare function mutation<TData, TVariables = void, TContext = unknown>(mutationFn: (variables: TVariables) => Promise<TData>, options?: MutationOptions<TData, TVariables, TContext>): MutationResult<TData, TVariables>;
+
+interface InfiniteQueryOptions<TData, TPageParam = number> {
+    /** Get the param for the next page. Return undefined to signal end. */
+    getNextPageParam: (lastPage: TData, allPages: TData[]) => TPageParam | undefined;
+    /** Get the param for the previous page. Optional. */
+    getPreviousPageParam?: (firstPage: TData, allPages: TData[]) => TPageParam | undefined;
+    /** Initial page param. Default: 0 (for number) */
+    initialPageParam?: TPageParam;
+    /** Whether to fetch on creation. Default: true */
+    enabled?: boolean;
+    /** Retry options */
+    retry?: RetryOptions;
+    /** Called on successful page fetch */
+    onSuccess?: (data: TData[]) => void;
+    /** Called on fetch error */
+    onError?: (error: Error) => void;
+}
+interface InfiniteQueryResult<TData> {
+    /** All fetched pages combined */
+    data: () => TData[] | undefined;
+    /** Individual pages array */
+    pages: () => TData[];
+    /** True when loading the first page */
+    loading: () => boolean;
+    /** True when any fetch is in progress */
+    fetching: () => boolean;
+    /** True when fetching the next page */
+    fetchingNextPage: () => boolean;
+    /** True when fetching the previous page */
+    fetchingPreviousPage: () => boolean;
+    /** Error from the last fetch */
+    error: () => Error | undefined;
+    /** Whether there are more pages to fetch */
+    hasNextPage: () => boolean;
+    /** Whether there are previous pages */
+    hasPreviousPage: () => boolean;
+    /** Fetch the next page */
+    fetchNextPage: () => Promise<void>;
+    /** Fetch the previous page */
+    fetchPreviousPage: () => Promise<void>;
+    /** Refetch all pages */
+    refetch: () => Promise<void>;
+    /** Cleanup */
+    dispose: () => void;
+}
+declare function infiniteQuery<TData, TPageParam = number>(key: string | (() => string), fetcher: (ctx: {
+    signal: AbortSignal;
+    pageParam: TPageParam;
+}) => Promise<TData>, options: InfiniteQueryOptions<TData, TPageParam>): InfiniteQueryResult<TData>;
+
+/**
+ * Tracks the previous value of a reactive signal.
+ * Returns `undefined` on first read (there is no previous value yet).
+ *
+ * @param getter A reactive getter to track
+ * @returns A reactive getter for the previous value
+ *
+ * @example
+ * ```ts
+ * const [count, setCount] = signal(0);
+ * const prev = previous(count);
+ * prev(); // undefined
+ * setCount(5);
+ * prev(); // 0
+ * setCount(10);
+ * prev(); // 5
+ * ```
+ */
+declare function previous<T>(getter: () => T): () => T | undefined;
+
+/**
+ * Returns a debounced reactive getter that only updates after `delay` ms
+ * of inactivity from the source signal.
+ *
+ * @param getter A reactive getter to debounce
+ * @param delay Debounce delay in milliseconds
+ * @returns A reactive getter for the debounced value
+ *
+ * @example
+ * ```ts
+ * const [search, setSearch] = signal("");
+ * const debouncedSearch = debounce(search, 300);
+ * // debouncedSearch() only updates 300ms after the last setSearch call
+ * ```
+ */
+declare function debounce<T>(getter: () => T, delay: number): () => T;
+
+/**
+ * Returns a throttled reactive getter that updates at most once per `interval` ms.
+ * Leading edge: first change propagates immediately.
+ * Trailing edge: last change during cooldown propagates when cooldown ends.
+ *
+ * @param getter A reactive getter to throttle
+ * @param interval Throttle interval in milliseconds
+ * @returns A reactive getter for the throttled value
+ *
+ * @example
+ * ```ts
+ * const [scrollY, setScrollY] = signal(0);
+ * const throttled = throttle(scrollY, 100);
+ * // throttled() updates at most once every 100ms
+ * ```
+ */
+declare function throttle<T>(getter: () => T, interval: number): () => T;
+
+interface ResourceOptions<T> {
+    /** Initial data value before first fetch. Default: undefined */
+    initialValue?: T;
+    /** Retry options for failed fetches */
+    retry?: RetryOptions;
+    /** Whether to fetch immediately on creation. Default: true */
+    immediate?: boolean;
+    /** Called when a fetch starts */
+    onStart?: () => void;
+    /** Called on successful fetch */
+    onSuccess?: (data: T) => void;
+    /** Called on fetch error */
+    onError?: (error: Error) => void;
+    /** Called on fetch settle (success or error) */
+    onSettled?: () => void;
+}
+interface Resource<T> {
+    /** Reactive getter for the fetched data */
+    data: () => T | undefined;
+    /** Reactive getter for the loading state */
+    loading: () => boolean;
+    /** Reactive getter for the error state */
+    error: () => Error | undefined;
+    /** Manually trigger a refetch */
+    refetch: () => Promise<void>;
+    /** Mutate the cached data without refetching */
+    mutate: (value: T | ((prev: T | undefined) => T)) => void;
+    /** Abort the current in-flight request */
+    abort: () => void;
+    /** Cleanup all subscriptions and abort pending requests */
+    dispose: () => void;
+}
+/**
+ * Reactive async data primitive. Wraps a fetcher function and exposes
+ * `data()`, `loading()`, `error()` signals.
+ *
+ * Overload 1: fetcher with no source signal (manual or immediate fetch).
+ */
+declare function resource<T>(fetcher: (info: {
+    signal: AbortSignal;
+}) => Promise<T>, options?: ResourceOptions<T>): Resource<T>;
+/**
+ * Overload 2: fetcher with a reactive source signal.
+ * Auto-refetches when the source changes.
+ */
+declare function resource<T, S>(source: () => S, fetcher: (source: S, info: {
+    signal: AbortSignal;
+    prev: T | undefined;
+}) => Promise<T>, options?: ResourceOptions<T>): Resource<T>;
+
+/**
+ * Offline-first data store backed by IndexedDB with reactive state.
+ * Provides automatic sync when connectivity returns.
+ */
+interface OfflineStoreOptions<T> {
+    /** IndexedDB database name */
+    name: string;
+    /** Version for schema migrations */
+    version?: number;
+    /** Key path in the stored objects (default: "id") */
+    keyPath?: string;
+    /** Sync adapter for remote push/pull */
+    adapter?: SyncAdapter<T>;
+    /** Auto-sync when online status changes (default: true) */
+    autoSync?: boolean;
+}
+interface SyncAdapter<T> {
+    /** Push local changes to remote */
+    push: (changes: SyncChange<T>[]) => Promise<SyncResult>;
+    /** Pull remote changes since last sync */
+    pull: (since: number | null) => Promise<T[]>;
+    /** Conflict resolution strategy */
+    conflictStrategy: "client-wins" | "server-wins" | "manual";
+}
+interface SyncChange<T> {
+    type: "put" | "delete";
+    item: T;
+    timestamp: number;
+}
+interface SyncResult {
+    ok: boolean;
+    error?: string;
+}
+interface OfflineStore<T> {
+    /** Reactive getter for all items */
+    data: () => T[];
+    /** Get a single item by key */
+    get: (key: string | number) => Promise<T | undefined>;
+    /** Insert or update an item */
+    put: (item: T) => Promise<void>;
+    /** Delete an item by key */
+    remove: (key: string | number) => Promise<void>;
+    /** Query items with a filter */
+    query: (filter: (item: T) => boolean) => T[];
+    /** Whether a sync is in progress */
+    isSyncing: () => boolean;
+    /** Timestamp of last successful sync */
+    lastSynced: () => number | null;
+    /** Trigger a manual sync */
+    sync: () => Promise<void>;
+    /** Attach a sync adapter */
+    attach: (adapter: SyncAdapter<T>) => void;
+    /** Number of pending (un-synced) changes */
+    pendingCount: () => number;
+    /** Close the database connection */
+    close: () => void;
+}
+/**
+ * Create an offline-first reactive store backed by IndexedDB.
+ *
+ * @example
+ * ```ts
+ * const store = await offlineStore<Todo>({
+ *   name: "todos",
+ *   adapter: syncAdapter({
+ *     push: (changes) => fetch("/api/sync", { method: "POST", body: JSON.stringify(changes) }),
+ *     pull: (since) => fetch(`/api/todos?since=${since}`).then(r => r.json()),
+ *     conflictStrategy: "client-wins",
+ *   }),
+ * });
+ *
+ * await store.put({ id: "1", text: "Buy milk", done: false });
+ * store.data(); // [{ id: "1", text: "Buy milk", done: false }]
+ * ```
+ */
+declare function offlineStore<T extends Record<string, unknown>>(options: OfflineStoreOptions<T>): Promise<OfflineStore<T>>;
+/**
+ * Helper to create a sync adapter configuration.
+ */
+declare function syncAdapter<T>(config: SyncAdapter<T>): SyncAdapter<T>;
+
+type RouteLoaderFn<T = unknown> = (context: {
+    params: Record<string, string>;
+    path: string;
+}, info: {
+    signal: AbortSignal;
+}) => Promise<T>;
+interface LoaderRoute {
+    loader?: RouteLoaderFn;
+    path: string;
+}
+/**
+ * Execute a route loader and wrap its result in a reactive Resource.
+ */
+declare function executeLoader<T>(loader: RouteLoaderFn<T>, context: {
+    params: Record<string, string>;
+    path: string;
+}, options?: ResourceOptions<T>): Resource<T>;
+/**
+ * Access loader data from within a route component.
+ * Must be called inside a component rendered by a route with a loader.
+ */
+declare function loaderData<T = unknown>(): {
+    data: () => T | undefined;
+    loading: () => boolean;
+    error: () => Error | undefined;
+};
+/**
+ * Preload a route's data before navigation.
+ * Returns a promise that resolves when the loader completes.
+ */
+declare function preloadRoute(route: LoaderRoute, context: {
+    params: Record<string, string>;
+    path: string;
+}): Promise<unknown>;
+
+/**
+ * socket provides a reactive WebSocket connection with auto-reconnect
+ * and optional heartbeat support.
+ */
+declare function socket(url: string | (() => string), options?: {
+    protocols?: string | string[];
+    autoReconnect?: boolean;
+    reconnectDelay?: number;
+    maxReconnects?: number;
+    heartbeat?: {
+        interval: number;
+        message: string;
+    };
+}): {
+    data: () => unknown;
+    status: () => "connecting" | "open" | "closing" | "closed";
+    send: (data: string | ArrayBufferLike | Blob) => void;
+    close: () => void;
+    dispose: () => void;
+};
+
+/**
+ * stream provides reactive Server-Sent Events (SSE) integration.
+ * Wraps the EventSource API with reactive state for data, event name, and connection status.
+ */
+declare function stream(url: string, options?: {
+    withCredentials?: boolean;
+    autoReconnect?: boolean;
+}): {
+    data: () => string | null;
+    event: () => string | null;
+    status: () => "connecting" | "open" | "closed";
+    close: () => void;
+    dispose: () => void;
+};
+
+export { type InfiniteQueryOptions, type InfiniteQueryResult, type LoaderRoute, type MutationOptions, type MutationResult, type OfflineStore, type OfflineStoreOptions, type QueryOptions, type QueryResult, type Resource, type ResourceOptions, type RetryOptions, type RouteLoaderFn, type SyncAdapter, type SyncChange, type SyncResult, calculateDelay, clearQueryCache, debounce, executeLoader, getQueryData, infiniteQuery, invalidateQueries, loaderData, mutation, offlineStore, preloadRoute, previous, query, resource, setQueryData, socket, stream, syncAdapter, throttle, withRetry };