stunk/dist/query/index.d.ts

Stunk is a lightweight, framework-agnostic state management library for JavaScript and TypeScript. It uses chunk-based state units for efficient updates, reactivity, and performance optimization in React, Vue(WIP), Svelte(Coming soon), and Vanilla JS/TS a

import { A as AsyncChunk } from '../mutation-DLvwAQ6L.js';
export { c as AsyncState, d as AsyncStateWithPagination, M as Mutation, j as MutationFn, g as MutationOptions, b as MutationResult, h as MutationState, P as PaginatedAsyncChunk, e as PaginatedParamAsyncChunk, f as asyncChunk, i as infiniteAsyncChunk, m as mutation, p as paginatedAsyncChunk } from '../mutation-DLvwAQ6L.js';
import { C as Chunk } from '../core-DAc7hZla.js';

interface GlobalQueryConfig {
    /**
     * Default configuration applied to all asyncChunk instances.
     * Per-chunk options always override these defaults.
     */
    query?: {
        /** Time in ms before data is considered stale (default: 0) */
        staleTime?: number;
        /** Time in ms to cache data after last subscriber leaves (default: 300_000) */
        cacheTime?: number;
        /** Auto-refetch interval in ms */
        refetchInterval?: number;
        /** Refetch when window regains focus (default: false) */
        refetchOnWindowFocus?: boolean;
        /** Number of retries on failure (default: 0) */
        retryCount?: number;
        /** Delay in ms between retries (default: 1000) */
        retryDelay?: number;
        /** Global error handler — called when all retries are exhausted */
        onError?: (error: Error) => void;
        /** Global success handler — called after every successful fetch */
        onSuccess?: (data: unknown) => void;
    };
    /**
     * Default configuration applied to all mutation instances.
     * Reserved for when mutation() ships — per-mutation options always override.
     */
    mutation?: {
        /** Global error handler for mutations */
        onError?: (error: Error) => void;
        /** Global success handler for mutations */
        onSuccess?: (data: unknown) => void;
    };
}
/**
 * Configures global defaults for all `asyncChunk` and `mutation` instances.
 *
 * Call this once at app entry — before any `asyncChunk` is created.
 * Per-chunk options always take precedence over these defaults.
 *
 * @param config.query  - Defaults for all async chunks (staleTime, retryCount, onError, etc.)
 * @param config.mutation - Defaults for all mutations (onError, onSuccess)
 *
 * @example
 * import { configureQuery } from "stunk/query";
 *
 * configureQuery({
 *   query: {
 *     staleTime: 30_000,
 *     retryCount: 3,
 *     refetchOnWindowFocus: true,
 *     onError: (err) => toast.error(err.message),
 *   },
 *   mutation: {
 *     onError: (err) => toast.error(err.message),
 *     onSuccess: () => toast.success("Done!"),
 *   },
 * });
 */
declare function configureQuery(config: GlobalQueryConfig): void;
/**
 * Returns the current global query config.
 * Used internally by asyncChunk and mutation to read defaults.
 */
declare function getGlobalQueryConfig(): GlobalQueryConfig;
/**
 * Resets the global config back to defaults.
 * Primarily useful in tests to avoid config bleed between test cases.
 *
 * @example
 * afterEach(() => resetQueryConfig());
 */
declare function resetQueryConfig(): void;

type InferAsyncData<T> = T extends AsyncChunk<infer U, Error> ? U : never;
type CombinedData<T extends Record<string, AsyncChunk<any>>> = {
    [K in keyof T]: InferAsyncData<T[K]> | null;
};
type CombinedState<T extends Record<string, AsyncChunk<any>>> = {
    loading: boolean;
    error: Error | null;
    errors: Partial<{
        [K in keyof T]: Error;
    }>;
    data: CombinedData<T>;
};

/**
 * Combines multiple async chunks into a single unified state chunk.
 *
 * The result tracks `loading` (true if any chunk is loading), `error` (first
 * error encountered), `errors` (per-chunk errors), and `data` (per-chunk data).
 *
 * @param chunks - A record of named `AsyncChunk` instances.
 * @returns A `Chunk<CombinedState<T>>` that reflects the live state of all inputs.
 *
 * @example
 * const combined = combineAsyncChunks({ user: userChunk, posts: postsChunk });
 * combined.get(); // { loading, error, errors, data: { user, posts } }
 */
declare function combineAsyncChunks<T extends Record<string, AsyncChunk<any>>>(chunks: T): Chunk<CombinedState<T>>;

export { AsyncChunk, type GlobalQueryConfig, combineAsyncChunks, configureQuery, getGlobalQueryConfig, resetQueryConfig };