@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/performance-utils.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Performance optimization utilities for stx
+ */
+/**
+ * Generic LRU (Least Recently Used) cache implementation
+ * Automatically evicts least recently used items when capacity is reached
+ */
+/**
+ * How a cache measures what it is holding, when entry count is not enough.
+ *
+ * A count-bounded cache assumes entries are roughly one size. That holds for
+ * the caches here that store paths or small fragments, and stops holding as
+ * soon as the values are rendered output: one entry can be tens of kilobytes
+ * and another a few bytes, so `maxSize` stops describing the footprint at all
+ * (stacksjs/stx#1945). Passing `sizeOf` and `maxBytes` bounds the bytes as
+ * well, which is the number a memory-constrained host actually has to budget.
+ */
+export interface LRUCacheOptions<V> {
+    /** Bytes this cache may retain across all entries. */
+    maxBytes: number;
+    /** What one value costs. Called once per `set`, so keep it cheap. */
+    sizeOf: (value: V) => number;
+}
+export declare class LRUCache<K, V> {
+    private cache;
+    private readonly maxSize;
+    private options;
+    private sizes;
+    private bytes;
+    constructor(maxSize?: number, options?: LRUCacheOptions<V>);
+    /** Bytes currently retained. Zero unless the cache is byte-bounded. */
+    get byteSize(): number;
+    /**
+     * Change the byte budget, evicting immediately down to the new one.
+     *
+     * The caches here are module state, built when the module loads and so before
+     * any config has been read. A host that wants a different ceiling -- or none
+     * at all -- can only say so afterwards, and it should take effect on what is
+     * already held rather than only on what arrives next: a container that has
+     * just told stx to keep 4MB is not helped by a cache that keeps its current
+     * 32MB until the entries happen to age out.
+     *
+     * A no-op on a cache built without a budget: giving one bytes it never
+     * measured would evict against a total that is always zero.
+     */
+    setMaxBytes(maxBytes: number): void;
+    /**
+     * Get a value from the cache, moving it to most recently used
+     */
+    get(key: K): V | undefined;
+    /**
+     * Set a value in the cache
+     */
+    set(key: K, value: V): void;
+    /**
+     * Check if key exists in cache
+     */
+    has(key: K): boolean;
+    /**
+     * Delete a key from the cache
+     */
+    delete(key: K): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get the current size of the cache
+     */
+    get size(): number;
+    /**
+     * Get all keys in the cache (oldest to newest)
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Get all values in the cache (oldest to newest)
+     */
+    values(): IterableIterator<V>;
+}
+/**
+ * Get a cached regex pattern or compile and cache it.
+ *
+ * IMPORTANT: For global patterns (flags include 'g'), this function returns
+ * a NEW RegExp instance each time to avoid shared `lastIndex` state issues.
+ * Only non-global patterns are cached.
+ *
+ * @param pattern - The regex pattern string
+ * @param flags - Optional regex flags (e.g., 'i', 'g', 'gi')
+ * @returns A RegExp instance (cached for non-global, new for global)
+ *
+ * @example
+ * ```typescript
+ * // Safe to cache - non-global pattern
+ * const pattern = getCachedRegex('@if\\s*\\(', 'i')
+ *
+ * // Not cached - global patterns always return new instance
+ * const global = getCachedRegex('@directive', 'g')
+ * ```
+ */
+export declare function getCachedRegex(pattern: string, flags?: string): RegExp;
+/**
+ * Clear the regex cache (useful for testing)
+ */
+export declare function clearRegexCache(): void;
+/**
+ * Cache for template processing results
+ */
+export declare class TemplateCache {
+    private cache;
+    private maxSize;
+    private ttl;
+    constructor(maxSize?: number, ttl?: number);
+    /**
+     * Get cached result if available and not expired
+     */
+    get(key: string): string | null;
+    /**
+     * Store result in cache
+     */
+    set(key: string, result: string, dependencies?: Set<string>): void;
+    /**
+     * Invalidate cache entries that depend on a specific file
+     */
+    invalidateDependency(filePath: string): number;
+    /**
+     * Clear all cached entries
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hitRate?: number;
+    };
+}
+/**
+ * Debounce function calls to avoid excessive processing
+ */
+export declare function debounce<T extends (...args: any[]) => any>(func: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle function calls to limit execution frequency
+ */
+export declare function throttle<T extends (...args: any[]) => any>(func: T, delay: number): (...args: Parameters<T>) => ReturnType<T> | undefined;
+/**
+ * Memoize function results to avoid repeated calculations
+ */
+export declare function memoize<T extends (...args: any[]) => any>(func: T, maxCacheSize?: number): T;
+/**
+ * Optimized string replacement that reuses regex patterns with case-preserving support
+ */
+export declare function optimizedReplace(text: string, pattern: string | RegExp, replacement: string | ((match: string, ...args: any[]) => string), flags?: string): string;
+/**
+ * Pool of worker contexts to avoid creating new Function instances
+ */
+declare class ExpressionEvaluatorPool {
+    private pool;
+    private maxPoolSize;
+    private fnCache;
+    private fnCacheMaxSize;
+    getEvaluator(contextKeys: string[]): (...args: any[]) => any;
+    clear(): void;
+}
+export declare const expressionEvaluatorPool: ExpressionEvaluatorPool;
+/**
+ * Performance budget configuration
+ */
+export interface PerformanceBudget {
+    /** Maximum allowed time in milliseconds */
+    maxTime: number;
+    /** Warning threshold (percentage of maxTime, e.g., 0.8 = 80%) */
+    warnThreshold?: number;
+    /** Action to take on budget violation: 'log', 'warn', 'error', 'throw' */
+    action?: 'log' | 'warn' | 'error' | 'throw';
+}
+/**
+ * Performance budget violation event
+ */
+export interface BudgetViolation {
+    label: string;
+    actualTime: number;
+    budgetTime: number;
+    exceedancePercent: number;
+    timestamp: Date;
+    isWarning: boolean;
+}
+/**
+ * Performance budget violation handler type
+ */
+export type BudgetViolationHandler = (violation: BudgetViolation) => void;
+/**
+ * Performance monitor for tracking processing times with budget support
+ */
+export declare class PerformanceMonitor {
+    private metrics;
+    private budgets;
+    private violations;
+    private maxViolations;
+    private violationHandlers;
+    private enabled;
+    /**
+     * Enable or disable performance monitoring
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if monitoring is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Set a performance budget for a specific operation
+     *
+     * @param label - Operation label
+     * @param budget - Budget configuration
+     *
+     * @example
+     * ```typescript
+     * performanceMonitor.setBudget('processDirectives', {
+     *   maxTime: 100, // 100ms max
+     *   warnThreshold: 0.8, // warn at 80ms
+     *   action: 'warn'
+     * })
+     * ```
+     */
+    setBudget(label: string, budget: PerformanceBudget): void;
+    /**
+     * Set multiple performance budgets at once
+     */
+    setBudgets(budgets: Record<string, PerformanceBudget>): void;
+    /**
+     * Remove a performance budget
+     */
+    removeBudget(label: string): void;
+    /**
+     * Get all configured budgets
+     */
+    getBudgets(): Record<string, PerformanceBudget>;
+    /**
+     * Add a handler for budget violations
+     */
+    onViolation(handler: BudgetViolationHandler): void;
+    /**
+     * Remove a violation handler
+     */
+    offViolation(handler: BudgetViolationHandler): void;
+    /**
+     * Time a function execution
+     */
+    time<T>(label: string, fn: () => T): T;
+    /**
+     * Time an async function execution
+     */
+    timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Check if a duration violates the budget
+     */
+    private checkBudget;
+    /**
+     * Record a timing measurement
+     */
+    recordTime(label: string, duration: number): void;
+    /**
+     * Get performance statistics
+     */
+    getStats(label?: string): Record<string, any>;
+    /**
+     * Get all budget violations
+     */
+    getViolations(label?: string): BudgetViolation[];
+    /**
+     * Get violation statistics
+     */
+    getViolationStats(): {
+        total: number;
+        byLabel: Record<string, number>;
+        warnings: number;
+        errors: number;
+    };
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+    /**
+     * Clear all violations
+     */
+    clearViolations(): void;
+    /**
+     * Clear budgets
+     */
+    clearBudgets(): void;
+    /**
+     * Reset everything (metrics, violations, budgets)
+     */
+    reset(): void;
+}
+/**
+ * Default performance budgets for common operations
+ */
+export declare const defaultPerformanceBudgets: Record<string, PerformanceBudget>;
+/**
+ * Get the global performance monitor instance (lazy-loaded)
+ * This avoids instantiating the monitor until it's actually needed
+ */
+export declare function getPerformanceMonitor(): PerformanceMonitor;
+/**
+ * Global performance monitor instance
+ * @deprecated Use getPerformanceMonitor() for lazy loading
+ */
+export declare const performanceMonitor: PerformanceMonitor;
+/**
+ * Apply default performance budgets to the monitor
+ */
+export declare function applyDefaultBudgets(monitor?: PerformanceMonitor): void;
+/**
+ * Reset the performance monitor instance (useful for testing)
+ */
+export declare function resetPerformanceMonitor(): void;
+export {};