revali/dist/index.d.ts

Framework-agnostic stale-while-revalidate (SWR) data fetching library. A minimal yet powerful caching library for JavaScript/TypeScript.

type Fetcher<T> = (signal?: AbortSignal) => Promise<T>;
type Subscriber<T> = (data: T | undefined, error?: Error) => void;
interface RevaliOptions {
    retries?: number;
    retryDelay?: number;
    ttl?: number;
    maxCacheSize?: number;
    revalidateOnFocus?: boolean;
    revalidateOnReconnect?: boolean;
    refreshInterval?: number;
    refreshWhenHidden?: boolean;
    refreshWhenOffline?: boolean;
    dedupingInterval?: number;
    abortOnRevalidate?: boolean;
    abortTimeout?: number;
    signal?: AbortSignal;
}
interface CacheEntry<T> {
    data: T | undefined;
    timestamp: number;
    error?: Error;
    fetcher: Fetcher<T>;
    options: RevaliOptions;
    abortController?: AbortController;
}
interface RevaliState<T> {
    data?: T;
    error?: Error;
    isLoading: boolean;
    isValidating: boolean;
}
declare class CancellationError extends Error {
    name: string;
    constructor(message: string);
}
declare const DEFAULT_OPTIONS: Required<Omit<RevaliOptions, 'signal'>> & {
    signal?: AbortSignal;
};

declare function revaliFetch<T>(key: string, fetcher: Fetcher<T>, options?: RevaliOptions): Promise<T>;
/**
 * Cancel request for a specific key
 */
declare function cancelRequest(key: string): boolean;
/**
 * Cancel all active requests
 */
declare function cancelAllRequests(): number;
/**
 * Check if a request is cancelled
 */
declare function isRequestCancelled(key: string): boolean;

declare function subscribe<T>(key: string, fn: Subscriber<T>): () => void;

declare function clearCache(key?: string): void;
declare function getCacheInfo(): {
    size: number;
    keys: string[];
};

/**
 * manually update cache data
 */
declare function mutate<T>(key: string, data: T | ((prev: T | undefined) => T), shouldRevalidate?: boolean): T;

/**
 * clean up all cache and subscribers
 */
declare function cleanup(): void;

/**
 * initialize auto revalidation listener
 */
declare function initAutoRevalidation(): void;
/**
 * manually trigger revalidation
 */
declare function triggerRevalidation(): void;

/**
 * Clean up all polling tasks
 */
declare function cleanupPolling(): void;
/**
 * Get information about active polling tasks
 */
declare function getPollingInfo(): {
    activeCount: number;
    keys: string[];
};
/**
 * Check if a key has active polling
 */
declare function hasActivePolling(key: string): boolean;

interface UseRevaliResult<T> {
    data: T | undefined;
    error: Error | undefined;
    isLoading: boolean;
    isValidating: boolean;
    mutate: (data: T | ((prev: T | undefined) => T), shouldRevalidate?: boolean) => T;
}
/**
 * React hook for Revali data fetching with stale-while-revalidate pattern
 *
 * @param key - Unique cache key for the data
 * @param fetcher - Function that returns a Promise with the data
 * @param options - Revali options (TTL, retries, polling, etc.)
 * @returns Object with data, error, loading states, and mutate function
 */
declare function useRevali<T>(key: string, fetcher: () => Promise<T>, options?: RevaliOptions): UseRevaliResult<T>;

/**
 * Cancel request for a specific key
 */
declare function cancel(key: string): boolean;
/**
 * Cancel all active requests
 */
declare function cancelAll(): number;
/**
 * Check if a key has been cancelled
 */
declare function isCancelled(key: string): boolean;
/**
 * Get information about active cancellation controllers
 */
declare function getCancellationInfo(): {
    activeCount: number;
    keys: string[];
};
/**
 * Check if an error is a cancellation error
 */
declare function isCancellationError(error: unknown): error is CancellationError | DOMException;

export { type CacheEntry, CancellationError, DEFAULT_OPTIONS, type Fetcher, type RevaliOptions, type RevaliState, type Subscriber, type UseRevaliResult, cancel, cancelAll, cancelAllRequests, cancelRequest, cleanup, cleanupPolling, clearCache, getCacheInfo, getCancellationInfo, getPollingInfo, hasActivePolling, initAutoRevalidation, isCancellationError, isCancelled, isRequestCancelled, mutate, revaliFetch, subscribe, triggerRevalidation, useRevali };