@stacksjs/stx 0.2.155 → 0.2.156

package/dist/performance-utils.d.ts

@@ -1,3 +1,47 @@
+/**
+ * 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;
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    /**
+     * 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.
  *
@@ -23,6 +67,39 @@ 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
  */
@@ -40,151 +117,167 @@ export declare function memoize<T extends (...args: any[]) => any>(func: T, maxC
  */
 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
+ * Pool of worker contexts to avoid creating new Function instances
  */
-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'
+declare class ExpressionEvaluatorPool {
+    private pool;
+    private maxPoolSize;
+    private fnCache;
+    private fnCacheMaxSize;
+    getEvaluator(contextKeys: string[]): (...args: any[]) => any;
+    clear(): void;
 }
-};
-/**
- * Global performance monitor instance
- * @deprecated Use getPerformanceMonitor() for lazy loading
- */
-export declare const performanceMonitor: PerformanceMonitor;
+export declare const expressionEvaluatorPool: ExpressionEvaluatorPool;
 /**
  * Performance budget configuration
  */
-export declare interface PerformanceBudget {
-  maxTime: number
-  warnThreshold?: number
-  action?: 'log' | 'warn' | 'error' | 'throw'
+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 declare interface BudgetViolation {
-  label: string
-  actualTime: number
-  budgetTime: number
-  exceedancePercent: number
-  timestamp: Date
-  isWarning: boolean
+export interface BudgetViolation {
+    label: string;
+    actualTime: number;
+    budgetTime: number;
+    exceedancePercent: number;
+    timestamp: Date;
+    isWarning: boolean;
 }
 /**
  * Performance budget violation handler type
  */
-// eslint-disable-next-line pickier/no-unused-vars
 export type BudgetViolationHandler = (violation: BudgetViolation) => void;
-/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group, pickier/no-unused-vars */
 /**
- * Performance optimization utilities for stx
+ * 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;
+}
 /**
- * Generic LRU (Least Recently Used) cache implementation
- * Automatically evicts least recently used items when capacity is reached
+ * Default performance budgets for common operations
  */
-export declare class LRUCache<K, V> {
-  constructor(maxSize?: number);
-  get(key: K): V | undefined;
-  set(key: K, value: V): void;
-  has(key: K): boolean;
-  delete(key: K): boolean;
-  clear(): void;
-  get size(): number;
-  keys(): IterableIterator<K>;
-  values(): IterableIterator<V>;
-}
+export declare const defaultPerformanceBudgets: Record<string, PerformanceBudget>;
 /**
- * Cache for template processing results
+ * Get the global performance monitor instance (lazy-loaded)
+ * This avoids instantiating the monitor until it's actually needed
  */
-export declare class TemplateCache {
-  constructor(maxSize?: number, 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 };
-}
+export declare function getPerformanceMonitor(): PerformanceMonitor;
 /**
- * Pool of worker contexts to avoid creating new Function instances
+ * Global performance monitor instance
+ * @deprecated Use getPerformanceMonitor() for lazy loading
  */
-declare class ExpressionEvaluatorPool {
-  getEvaluator(contextKeys: string[]): (...args: any[]) => any;
-  clear(): void;
-}
+export declare const performanceMonitor: PerformanceMonitor;
 /**
- * Performance monitor for tracking processing times with budget support
+ * Apply default performance budgets to the monitor
  */
-export declare class PerformanceMonitor {
-  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>;
-  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;
-}
+export declare function applyDefaultBudgets(monitor?: PerformanceMonitor): void;
+/**
+ * Reset the performance monitor instance (useful for testing)
+ */
+export declare function resetPerformanceMonitor(): void;
+export {};

package/dist/placeholder.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Placeholder Token System
+ *
+ * Generates and resolves placeholder tokens for the template pre-compilation pipeline.
+ * During build mode, dynamic expressions are replaced with placeholder tokens.
+ * At serve time, only the placeholders are resolved with request-time data.
+ *
+ * @module placeholder
+ */
 /**
  * Reset the placeholder counter and registry (for testing / between builds).
  */
@@ -15,6 +24,15 @@ export declare function createPlaceholder(type: 'expr' | 'cond' | 'raw', expr: s
  * Used by the template compiler to build the CompiledTemplate.placeholders field.
  */
 export declare function getPlaceholderRegistry(): PlaceholderMap;
+/**
+ * A map of placeholder tokens to their original expressions.
+ */
+export interface PlaceholderMap {
+    [token: string]: {
+        type: 'expr' | 'cond' | 'raw';
+        expression: string;
+    };
+}
 /**
  * Extract all placeholder tokens from compiled HTML.
  *
@@ -34,12 +52,3 @@ export declare function replacePlaceholders(html: string, values: Map<string, st
  * Check if HTML contains any placeholder tokens.
  */
 export declare function hasPlaceholders(html: string): boolean;
-/**
- * A map of placeholder tokens to their original expressions.
- */
-export declare interface PlaceholderMap {
-  [token: string]: {
-    type: 'expr' | 'cond' | 'raw'
-    expression: string
-  }
-}