/**
 * Generic Cache Utilities
 *
 * A lightweight localStorage-backed cache used by module-level cache wrappers.
 * Key behaviors:
 * - Default expiration: 1 day (configurable per cache)
 * - Search and filter requests bypass the cache and always fetch fresh data
 * - Lists are stored as a normalized map (id -> item) for fast lookups
 * - Provides both synchronous reads (`getCachedDataSync`) and async reads
 *   with API fallback (`getCachedData`)
 * - Single-item helpers available (`getCachedSingleItem`, `getCachedSingleItemSync`)
 *
 * The main async helper `getCachedData` now accepts a single options object
 * (`GetCachedDataOptions`) which includes `config`, optional `searchQuery`,
 * `filters`, `pageLimit` and extra `params` for the list API. Module cache
 * wrappers should call `getCachedData({ config, searchQuery, filters, pageLimit, params, headers })`.
 * Both `getCachedData` and `getCachedSingleItem` accept an optional `headers`
 * object which will be forwarded to the underlying `fetchData` calls.
 *
 * Organization:
 * - Types
 * - List Cache Functions
 * - Single Item Cache Functions
 * - Cache Utilities
 */
interface CacheConfig {
    cacheKey: string;
    apiUrl: string;
    expirationMs?: number;
    responseKey?: string;
    params?: Record<string, unknown>;
}
interface GetCachedDataOptions {
    config: CacheConfig;
    params?: Record<string, unknown>;
    headers?: Record<string, string>;
}
interface CachedData<T> {
    items: Record<string, T>;
    cachedAt: string;
    count: number;
    currentPage?: number;
}
interface CachedSingleData<T> {
    item: T;
    cachedAt: string;
}
interface ListResponse<T> {
    count: number;
    items: T[];
    currentPage?: number;
}
/**
 * Get synchronous cached data for a module
 * Returns empty result if cache is missing or stale
 *
 * @param cacheKey - localStorage key for the cache
 * @param expirationMs - Cache expiration time in milliseconds (default: 1 day)
 * @returns {count: number, items: T[]} - Cached data or empty array
 *
 * @example
 * const users = getCachedDataSync<UserBE>(LS_KEYS.USERS);
 * if (users.items.length > 0) {
 *   console.log(users.items[0].name);
 * }
 */
declare const getCachedDataSync: <T>(cacheKey: string, expirationMs?: number) => ListResponse<T>;
/**
 * Get cached data with API fallback for a module
 *
 * Accepts a single `GetCachedDataOptions` object. The function will return
 * cached results when fresh, or fetch from the API when the cache is stale
 * or when `searchQuery`/`filters` are present (those always bypass cache).
 *
 * @param opts - `GetCachedDataOptions` containing `config`, optional
 *               `searchQuery`, `filters`, `pageLimit`, and extra `params`
 * @returns Promise<{count: number, items: T[]}> - Cached or fresh data
 *
 * @example
 * const config = { cacheKey: LS_KEYS.USERS, apiUrl: USER_API_ROUTES.LIST, responseKey: 'users' };
 * // Basic usage (reads cache if fresh)
 * const users = await getCachedData<UserBE>({ config });
 *
 * // With search (bypasses cache)
 * const filtered = await getCachedData<UserBE>({ config, searchQuery: 'John' });
 *
 * // With filters and custom page limit
 * const active = await getCachedData<UserBE>({ config, filters: { enabled: true }, pageLimit: 200 });
 */
declare const getCachedData: <T>(opts: GetCachedDataOptions) => Promise<ListResponse<T>>;
/**
 * Get single cached item by ID from a list cache
 *
 * @param cacheKey - localStorage key for the cache
 * @param itemId - ID of the item to retrieve
 * @returns T | null - Cached item or null
 *
 * @example
 * const user = getCachedItemById<UserBE>(LS_KEYS.USERS, 'user-123');
 * if (user) {
 *   console.log(user.name);
 * }
 */
declare const getCachedItemById: <T extends {
    id: string;
}>(cacheKey: string, itemId: string) => T | null;
/**
 * Get synchronous cached single item
 * Returns null if cache is missing or stale
 *
 * @param cacheKey - localStorage key for the cache
 * @param expirationMs - Cache expiration time in milliseconds (default: 1 day)
 * @returns T | null - Cached item or null
 *
 * @example
 * const workspace = getCachedSingleItemSync<WorkspaceBE>(LS_KEYS.WORKSPACE);
 * if (workspace) {
 *   console.log(workspace.name);
 * }
 */
declare const getCachedSingleItemSync: <T>(cacheKey: string, expirationMs?: number) => T | null;
/**
 * Get cached single item with API fallback
 * Useful for workspace, profile, settings, etc.
 *
 * @param config - Cache configuration (cacheKey, apiUrl, expirationMs, responseKey)
 * @param params - Optional query parameters for API request
 * @returns Promise<T | null> - Cached or fresh item
 *
 * @example
 * const config = { cacheKey: LS_KEYS.WORKSPACE, apiUrl: '/api/workspace', responseKey: 'workspace' };
 * const workspace = await getCachedSingleItem<WorkspaceBE>(config, { subdomain: 'school1' });
 */
declare const getCachedSingleItem: <T>(config: CacheConfig, params?: Record<string, string>, headers?: Record<string, string>) => Promise<T | null>;
/**
 * Get cached data but fall back to the API when sync cache is empty.
 *
 * This helper first performs a quick synchronous cache check via
 * `getCachedDataSync`. If that returns an empty result it will call
 * the async `getCachedData` to fetch fresh data from the API and return
 * the result. Use this when callers want a fast-path cache read but also
 * need the ability to recall the API transparently when cache is missing.
 */
declare const getCachedDataWithFallback: <T>(config: CacheConfig, params?: Record<string, unknown>, headers?: Record<string, string>) => Promise<ListResponse<T>>;
/**
 * Async variant to get a single item by ID with API fallback.
 *
 * Unlike `getCachedItemById` (sync), this function will call the API
 * (via `getCachedDataWithFallback`) when the item is not available in
 * the local cache. Requires a full `CacheConfig` so the API URL is
 * available for fetching.
 */
declare const getCachedItemByIdAsync: <T extends {
    id: string;
}>(config: CacheConfig, itemId: string, params?: Record<string, unknown>, headers?: Record<string, string>) => Promise<T | null>;
/**
 * Invalidate (remove) cache for a module
 * Useful after create/update/delete operations
 *
 * @param cacheKey - localStorage key for the cache
 *
 * @example
 * invalidateCache(LS_KEYS.USERS);
 * const freshUsers = await getCachedData(config);
 */
declare const invalidateCache: (cacheKey: string) => void;
/**
 * Preload cache for a module
 * Useful to call on app initialization or login
 *
 * @param config - Cache configuration
 * @returns Promise<ListResponse<T>> - Preloaded data
 *
 * @example
 * const config = { cacheKey: LS_KEYS.USERS, apiUrl: USER_API_ROUTES.LIST, responseKey: 'users' };
 * await preloadCache(config);
 */
declare const preloadCache: <T>(config: CacheConfig) => Promise<ListResponse<T>>;
/**
 * Check if cache is stale (older than expiration time)
 *
 * @param cacheKey - localStorage key for the cache
 * @param expirationMs - Cache expiration time in milliseconds (default: 1 day)
 * @returns boolean - True if cache is stale or doesn't exist
 *
 * @example
 * if (isCacheStale(LS_KEYS.USERS)) {
 *   await getCachedData(config); // This will fetch fresh data
 * }
 */
declare const isCacheStale: (cacheKey: string, expirationMs?: number) => boolean;

export { type CacheConfig, type CachedData, type CachedSingleData, type GetCachedDataOptions, type ListResponse, getCachedData, getCachedDataSync, getCachedDataWithFallback, getCachedItemById, getCachedItemByIdAsync, getCachedSingleItem, getCachedSingleItemSync, invalidateCache, isCacheStale, preloadCache };