@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
201 lines • 6.23 kB
TypeScript
/**
* 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;
/**
* 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?: any): 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;
/**
* Get the global performance monitor instance (lazy-loaded)
* This avoids instantiating the monitor until it's actually needed
*/
export declare function getPerformanceMonitor(): 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;
// Global expression evaluator pool
export declare const expressionEvaluatorPool: ExpressionEvaluatorPool;
/**
* Default performance budgets for common operations
*/
export declare const defaultPerformanceBudgets: {
processDirectives: {
maxTime: 500;
warnThreshold: 0.8;
action: 'warn'
};
processTemplate: {
maxTime: 200;
warnThreshold: 0.8;
action: 'warn'
};
processIncludes: {
maxTime: 100;
warnThreshold: 0.8;
action: 'warn'
};
processLoops: {
maxTime: 50;
warnThreshold: 0.8;
action: 'warn'
};
processConditionals: {
maxTime: 50;
warnThreshold: 0.8;
action: 'warn'
};
processExpressions: {
maxTime: 100;
warnThreshold: 0.8;
action: 'warn'
};
renderComponent: {
maxTime: 150;
warnThreshold: 0.8;
action: 'warn'
};
buildWebComponents: {
maxTime: 1000;
warnThreshold: 0.8;
action: 'warn'
}
};
/**
* Global performance monitor instance
* @deprecated Use getPerformanceMonitor() for lazy loading
*/
export declare const performanceMonitor: PerformanceMonitor;
/**
* Performance budget configuration
*/
export declare interface PerformanceBudget {
maxTime: number
warnThreshold?: number
action?: 'log' | 'warn' | 'error' | 'throw'
}
/**
* Performance budget violation event
*/
export declare 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 optimization utilities for stx
*/
/**
* Generic LRU (Least Recently Used) cache implementation
* Automatically evicts least recently used items when capacity is reached
*/
export declare class LRUCache<K, V> {
private cache: any;
readonly private maxSize: number;
constructor(maxSize?: number);
get(key: K): V | undefined;
set(key: K, value: V): void;
has(key: K): boolean;
delete(key: K): boolean;
clear(): void;
keys(): IterableIterator<K>;
values(): IterableIterator<V>;
}
/**
* Cache for template processing results
*/
export declare class TemplateCache {
private cache: any;
private maxSize: number;
private ttl: number;
constructor(maxSize?: any, ttl?: number);
get(key: string): string | null;
set(key: string, result: string, dependencies?: Set<string>): void;
invalidateDependency(filePath: string): number;
clear(): void;
getStats(): { size: number, maxSize: number, hitRate?: number };
}
/**
* Pool of worker contexts to avoid creating new Function instances
*/
declare class ExpressionEvaluatorPool {
private pool: Array<{ func: (...args: any[]) => any, context: string[] }>;
private maxPoolSize: any;
getEvaluator(contextKeys: string[]): (...args: any[]) => any;
clear(): void;
}
/**
* Performance monitor for tracking processing times with budget support
*/
export declare class PerformanceMonitor {
private metrics: any;
private budgets: any;
private violations: BudgetViolation[];
private maxViolations: any;
private violationHandlers: BudgetViolationHandler[];
private enabled: any;
setEnabled(enabled: boolean): void;
isEnabled(): boolean;
setBudget(label: string, budget: PerformanceBudget): void;
setBudgets(budgets: Record<string, PerformanceBudget>): void;
removeBudget(label: string): void;
getBudgets(): Record<string, PerformanceBudget>;
onViolation(handler: BudgetViolationHandler): void;
offViolation(handler: BudgetViolationHandler): void;
time<T>(label: string, fn: () => T): T;
timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
private checkBudget(label: string, duration: number): void;
recordTime(label: string, duration: number): void;
getStats(label?: string): Record<string, any>;
getViolations(label?: string): BudgetViolation[];
getViolationStats(): { total: number, byLabel: Record<string, number>, warnings: number, errors: number };
clear(): void;
clearViolations(): void;
clearBudgets(): void;
reset(): void;
}