/**
 * Leaderboard caching service for performance optimization.
 *
 * Provides in-memory caching of sorted leaderboards with automatic invalidation
 * on XP changes. Optimized for large servers (10k+ users) with:
 * - Top 100 user cache per guild and store (reduces memory footprint)
 * - TTL-based expiration (60 seconds)
 * - Event-driven cache invalidation
 * - O(1) cached reads, O(n log n) cache refresh
 * - Multi-store support: Each store has independent leaderboard cache
 *
 * Cache structure: Map<guildId, Map<storeId, data>>
 * Cache is automatically invalidated on xpChange, levelUp, and levelDown events.
 * Events include storeId field, ensuring only the affected store's cache is invalidated.
 *
 * @example
 * ```typescript
 * // Default store
 * const { entries, total } = await getLeaderboard('123...', 0, 10)
 *
 * // Custom store (e.g., reputation system)
 * const { entries, total } = await getLeaderboard('123...', 0, 10, { storeId: 'reputation' })
 *
 * // Each store maintains independent cache
 * // XP changes in reputation store only invalidate reputation cache
 * // Default store cache remains unaffected
 * ```
 */
import type { LeaderboardEntry, FlashcoreOptions } from '../types.js';
/**
 * Retrieves leaderboard with pagination support and total user count.
 * Uses cached data if available and fresh, otherwise triggers refresh.
 * Supports deep pagination beyond the cached top N.
 *
 * Complexity:
 * - O(1) for cached reads within cached range (within TTL)
 * - O(n log n) for cache refresh (all users sorted)
 * - O(n log n) for deep pagination fallback (full dataset sort and slice)
 *
 * @param guildId - Guild ID
 * @param offset - Starting position (0-indexed, default: 0)
 * @param limit - Number of entries to return (default: 10)
 * @param options - Optional Flashcore options (e.g., storeId for multi-store support)
 * @returns Object with entries array and total user count
 *
 * @example
 * ```typescript
 * // Get top 10 users (default store)
 * const { entries, total } = await getLeaderboard('123...', 0, 10)
 *
 * // Get users 11-20 (page 2, default store)
 * const { entries, total } = await getLeaderboard('123...', 10, 10)
 *
 * // Get users 101-110 (beyond cached top 100, default store)
 * const { entries, total } = await getLeaderboard('123...', 100, 10)
 *
 * // Get top 10 users from custom store
 * const { entries, total } = await getLeaderboard('123...', 0, 10, { storeId: 'reputation' })
 * ```
 */
export declare function getLeaderboard(guildId: string, offset?: number, limit?: number, options?: FlashcoreOptions): Promise<{
    entries: LeaderboardEntry[];
    total: number;
}>;
/**
 * Rebuilds leaderboard cache from Flashcore storage.
 * Fetches all users, sorts by XP (desc) then userId (asc), and caches top N.
 * Also updates the total users count for the guild.
 *
 * Complexity: O(n log n) where n = total users in guild
 *
 * @param guildId - Guild ID
 * @param options - Optional Flashcore options (e.g., storeId for multi-store support)
 *
 * @example
 * ```typescript
 * // Manually refresh cache (default store, usually automatic via events)
 * await refreshLeaderboard('123...')
 *
 * // Manually refresh cache for custom store
 * await refreshLeaderboard('123...', { storeId: 'reputation' })
 * ```
 */
export declare function refreshLeaderboard(guildId: string, options?: FlashcoreOptions): Promise<void>;
/**
 * Gets user's rank position in the leaderboard.
 * Returns null if user has no XP record.
 *
 * For users in top 100, uses cached data (O(n) search).
 * For users beyond cache, fetches all users and calculates position (O(n log n)).
 * Always returns the total number of tracked users from getAllUsers.
 *
 * @param guildId - Guild ID
 * @param userId - User ID
 * @param options - Optional Flashcore options (e.g., storeId for multi-store support)
 * @returns Rank info (1-indexed position and total users) or null if user not found
 *
 * @example
 * ```typescript
 * // Get user rank from default store
 * const rankInfo = await getUserRank('123...', '456...')
 * if (rankInfo) {
 *   console.log(`User is rank ${rankInfo.rank} out of ${rankInfo.total}`)
 * }
 *
 * // Get user rank from custom store
 * const repRank = await getUserRank('123...', '456...', { storeId: 'reputation' })
 * ```
 */
export declare function getUserRank(guildId: string, userId: string, options?: FlashcoreOptions): Promise<{
    rank: number;
    total: number;
} | null>;
/**
 * Invalidates cache for a specific guild and store.
 * Called automatically when XP changes via event listeners.
 *
 * Supports two modes:
 * - Specific store: Pass `{ storeId: 'name' }` to invalidate only that store
 * - All stores: Pass `{ all: true }` to invalidate all stores for the guild
 *
 * @param guildId - Guild ID
 * @param options - Optional Flashcore options or `{ all: true }` to invalidate all stores
 *
 * @example
 * ```typescript
 * // Manual cache invalidation for specific store (usually automatic)
 * invalidateCache('123...', { storeId: 'reputation' })
 *
 * // Invalidate all stores for a guild
 * invalidateCache('123...', { all: true })
 * ```
 */
export declare function invalidateCache(guildId: string, options?: FlashcoreOptions | {
    all: true;
}): void;
/**
 * Clears all cached leaderboards for all guilds and all stores.
 * Useful for testing or manual cache reset.
 *
 * @example
 * ```typescript
 * clearAllCaches()
 * ```
 */
export declare function clearAllCaches(): void;