@humanspeak/svelte-markdown/dist/utils/token-cache.d.ts

Fast, customizable markdown renderer for Svelte with built-in caching, TypeScript support, and Svelte 5 runes

/**
 * Token Cache
 *
 * Efficient caching layer for parsed markdown tokens.
 * Built on top of the existing MemoryCache infrastructure with
 * specialized features for markdown parsing optimization.
 *
 * Key features:
 * - Fast FNV-1a hashing for cache keys
 * - LRU eviction (inherited from MemoryCache)
 * - TTL support (inherited from MemoryCache)
 * - Handles large markdown documents efficiently
 *
 * @module token-cache
 */
import type { SvelteMarkdownOptions } from '../types.js';
import { MemoryCache } from './cache.js';
import type { Token, TokensList } from './markdown-parser.js';
/**
 * Fast non-cryptographic hash function using FNV-1a algorithm.
 * Optimized for speed over cryptographic security.
 *
 * FNV-1a (Fowler-Noll-Vo) provides:
 * - Fast computation (single pass through string)
 * - Good distribution (minimal collisions)
 * - Small output size (base36 string)
 *
 * @param str - String to hash
 * @returns Base36 hash string
 *
 * @example
 * ```typescript
 * const hash1 = hashString('# Hello World')
 * const hash2 = hashString('# Hello World!')
 * console.log(hash1 !== hash2) // true - different content = different hash
 * ```
 */
declare function hashString(str: string): string;
/**
 * Specialized cache for markdown token storage.
 * Extends MemoryCache with markdown-specific convenience methods.
 *
 * Inherits from MemoryCache:
 * - Automatic LRU eviction when maxSize is reached
 * - TTL-based expiration for time-sensitive content
 * - Advanced deletion (deleteByPrefix, deleteByMagicString)
 *
 * Performance characteristics:
 * - Cache hit: <1ms (vs 50-200ms parsing)
 * - Memory: ~5MB for 50 cached documents (default maxSize)
 * - Hash computation: ~0.05ms for 10KB, ~0.5ms for 100KB
 *
 * @class TokenCache
 * @extends MemoryCache<Token[] | TokensList>
 *
 * @example
 * ```typescript
 * // Create cache with custom settings
 * const cache = new TokenCache({
 *     maxSize: 100,        // Cache up to 100 documents
 *     ttl: 5 * 60 * 1000  // Expire after 5 minutes
 * })
 *
 * // Check cache before parsing
 * const cached = cache.getTokens(markdown, options)
 * if (cached) {
 *     return cached // Fast path - no parsing needed
 * }
 *
 * // Parse and cache
 * const tokens = lexer.lex(markdown)
 * cache.setTokens(markdown, options, tokens)
 * ```
 */
export declare class TokenCache extends MemoryCache<Token[] | TokensList> {
    /**
     * Creates a new TokenCache instance.
     *
     * @param options - Cache configuration
     * @param options.maxSize - Maximum number of documents to cache (default: 50)
     * @param options.ttl - Time-to-live in milliseconds (default: 5 minutes)
     */
    constructor(options?: {
        maxSize?: number;
        ttl?: number;
    });
    /**
     * Retrieves cached tokens for given markdown source and options.
     * Returns undefined if not cached or expired.
     *
     * @param source - Raw markdown string
     * @param options - Svelte markdown parser options
     * @returns Cached tokens or undefined
     *
     * @example
     * ```typescript
     * const tokens = cache.getTokens('# Hello', { gfm: true })
     * if (tokens) {
     *     console.log('Cache hit!')
     * }
     * ```
     */
    getTokens(source: string, options: SvelteMarkdownOptions): Token[] | TokensList | undefined;
    /**
     * Stores parsed tokens in cache for given markdown source and options.
     * If cache is full, oldest entry is evicted (LRU).
     *
     * @param source - Raw markdown string
     * @param options - Svelte markdown parser options
     * @param tokens - Parsed token array or token list
     *
     * @example
     * ```typescript
     * const tokens = lexer.lex(markdown)
     * cache.setTokens(markdown, options, tokens)
     * ```
     */
    setTokens(source: string, options: SvelteMarkdownOptions, tokens: Token[] | TokensList): void;
    /**
     * Checks if tokens are cached without retrieving them.
     * Useful for cache statistics or conditional logic.
     *
     * @param source - Raw markdown string
     * @param options - Svelte markdown parser options
     * @returns True if cached and not expired
     *
     * @example
     * ```typescript
     * if (cache.hasTokens(markdown, options)) {
     *     console.log('Cache hit - no parsing needed')
     * }
     * ```
     */
    hasTokens(source: string, options: SvelteMarkdownOptions): boolean;
    /**
     * Removes cached tokens for specific source and options.
     *
     * @param source - Raw markdown string
     * @param options - Svelte markdown parser options
     * @returns True if entry was removed, false if not found
     *
     * @example
     * ```typescript
     * cache.deleteTokens(markdown, options) // Remove specific cached entry
     * ```
     */
    deleteTokens(source: string, options: SvelteMarkdownOptions): boolean;
    /**
     * Removes all cached tokens from the cache.
     *
     * @example
     * ```typescript
     * cache.clearAllTokens() // Clear entire cache
     * ```
     */
    clearAllTokens(): void;
}
/**
 * Global singleton instance for shared token caching.
 * Use this instance across your application for maximum cache efficiency.
 *
 * @example
 * ```typescript
 * import { tokenCache } from './token-cache.js'
 *
 * const cached = tokenCache.getTokens(markdown, options)
 * if (!cached) {
 *     const tokens = lexer.lex(markdown)
 *     tokenCache.setTokens(markdown, options, tokens)
 * }
 * ```
 */
export declare const tokenCache: TokenCache;
/**
 * Export hash function for testing purposes.
 * @internal
 */
export { hashString };