@stacksjs/stx 0.2.0 → 0.2.3

package/dist/performance-utils.d.ts

@@ -1,7 +1,28 @@
 /**
- * Get a cached regex pattern or compile and cache it
+ * 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
  */
@@ -18,10 +39,113 @@ export declare function memoize<T extends (...args: any[]) => any>(func: T, maxC
  * 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;
-// Global performance monitor instance
+/**
+ * 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
  */
@@ -46,13 +170,32 @@ declare class ExpressionEvaluatorPool {
   clear(): void;
 }
 /**
- * Performance monitor for tracking processing times
+ * 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;
 }

package/dist/plugin-system.d.ts

@@ -0,0 +1,128 @@
+import type { CustomDirective, StxOptions } from './types';
+/**
+ * Create a plugin with type safety
+ */
+export declare function definePlugin(plugin: StxPlugin): StxPlugin;
+/**
+ * Create a simple directive plugin
+ */
+export declare function createDirectivePlugin(name: string, directives: CustomDirective[], options?: Partial<Omit<StxPlugin, 'name' | 'registerDirectives'>>): StxPlugin;
+/**
+ * Create a simple filter plugin
+ */
+export declare function createFilterPlugin(name: string, filters: Record<string, (value: unknown, ...args: unknown[]) => unknown>, options?: Partial<Omit<StxPlugin, 'name' | 'registerFilters'>>): StxPlugin;
+/**
+ * Variables plugin that adds common variables to context
+ */
+export declare function createVariablesPlugin(variables: Record<string, unknown>): StxPlugin;
+/**
+ * Global plugin manager instance
+ */
+export declare const pluginManager: PluginManager;
+/**
+ * Debug plugin that logs all lifecycle events
+ */
+export declare const debugPlugin: StxPlugin;
+/**
+ * Timing plugin that measures processing time
+ */
+export declare const timingPlugin: StxPlugin;
+/**
+ * Context passed to lifecycle hooks
+ */
+export declare interface PluginContext {
+  template: string
+  context: Record<string, unknown>
+  filePath: string
+  options: StxOptions
+  dependencies: Set<string>
+  metadata: Record<string, unknown>
+}
+/**
+ * Result from a lifecycle hook
+ */
+export declare interface PluginHookResult {
+  template?: string
+  context?: Record<string, unknown>
+  skip?: boolean
+  metadata?: Record<string, unknown>
+}
+/**
+ * Error context passed to onError hook
+ */
+export declare interface PluginErrorContext extends PluginContext {
+  error: Error
+  phase: string
+  directive?: string
+}
+/**
+ * Plugin definition interface
+ */
+export declare interface StxPlugin {
+  name: string
+  version?: string
+  description?: string
+  dependencies?: string[]
+  priority?: number
+  beforeProcess?: (ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void
+  afterParse?: (ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void
+  beforeDirective?: (phase: DirectivePhase, ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void
+  afterDirective?: (phase: DirectivePhase, ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void
+  beforeRender?: (ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void
+  afterRender?: (ctx: PluginContext) => PluginHookResult | Promise<PluginHookResult> | void
+  onError?: (ctx: PluginErrorContext) => PluginHookResult | Promise<PluginHookResult> | void
+  registerDirectives?: () => CustomDirective[]
+  registerFilters?: () => Record<string, (value: unknown, ...args: unknown[]) => unknown>
+  onRegister?: (options: StxOptions) => void | Promise<void>
+  onUnregister?: () => void | Promise<void>
+}
+/**
+ * Directive type identifier for beforeDirective/afterDirective hooks
+ */
+export type DirectivePhase = | 'comments'
+  | 'escaped'
+  | 'stacks'
+  | 'layouts'
+  | 'includes'
+  | 'js'
+  | 'ts'
+  | 'custom'
+  | 'components'
+  | 'animation'
+  | 'routes'
+  | 'auth'
+  | 'csrf'
+  | 'method'
+  | 'loops'
+  | 'conditionals'
+  | 'forms'
+  | 'markdown'
+  | 'i18n'
+  | 'a11y'
+  | 'seo'
+  | 'expressions'
+/**
+ * Plugin manager that handles registration, lifecycle, and execution
+ */
+export declare class PluginManager {
+  private plugins: Map<string, StxPlugin>;
+  private sortedPlugins: StxPlugin[];
+  private initialized: any;
+  register(plugin: StxPlugin, options: StxOptions): Promise<void>;
+  unregister(name: string): Promise<boolean>;
+  get(name: string): StxPlugin | undefined;
+  has(name: string): boolean;
+  getAll(): StxPlugin[];
+  getAllDirectives(): CustomDirective[];
+  getAllFilters(): Record<string, (value: unknown, ...args: unknown[]) => unknown>;
+  runBeforeProcess(ctx: PluginContext): Promise<PluginContext>;
+  runAfterParse(ctx: PluginContext): Promise<PluginContext>;
+  runBeforeDirective(phase: DirectivePhase, ctx: PluginContext): Promise<PluginContext>;
+  runAfterDirective(phase: DirectivePhase, ctx: PluginContext): Promise<PluginContext>;
+  runBeforeRender(ctx: PluginContext): Promise<PluginContext>;
+  runAfterRender(ctx: PluginContext): Promise<PluginContext>;
+  runOnError(ctx: PluginErrorContext): Promise<PluginContext | null>;
+  private sortPlugins(): void;
+  private runHooks(hookName: 'beforeProcess' | 'afterParse' | 'beforeRender' | 'afterRender', ctx: PluginContext): Promise<PluginContext>;
+  private runDirectiveHooks(hookName: 'beforeDirective' | 'afterDirective', phase: DirectivePhase, ctx: PluginContext): Promise<PluginContext>;
+}

package/dist/precompiler.d.ts

@@ -0,0 +1,108 @@
+import { SourceMapGenerator } from './source-maps';
+import { TemplateParser,  } from './ast';
+import type { ASTNode, AttributeNode, ComponentNode, DirectiveNode, DocumentNode, ElementNode, ExpressionNode,  } from './ast';
+import type { SourceMapV3 } from './source-maps';
+// Export singleton instance
+export declare const compiler: TemplateCompiler;
+/**
+ * Compilation options
+ */
+export declare interface CompileOptions {
+  filename?: string
+  mode?: CompileMode
+  optimize?: boolean
+  sourceMaps?: boolean
+  module?: 'esm' | 'cjs' | 'iife'
+  functionName?: string
+  includeRuntime?: boolean
+  dev?: boolean
+  inlineDirectives?: string[]
+}
+/**
+ * Compilation result
+ */
+export declare interface CompileResult {
+  code: string
+  map?: SourceMapV3
+  analysis: {
+    /** Variables used in expressions */
+    usedVariables: Set<string>
+    /** Directives used */
+    usedDirectives: Set<string>
+    /** Components used */
+    usedComponents: Set<string>
+    /** Whether template has dynamic content */
+    isDynamic: boolean
+    /** Whether template uses slots */
+    hasSlots: boolean
+  }
+}
+declare interface CodegenContext {
+  code: string
+  indentLevel: number
+  sourceMapGenerator?: SourceMapGenerator
+  currentLine: number
+  currentColumn: number
+  sourceFile: string
+  mode: CompileMode
+  optimize: boolean
+  dev: boolean
+  usedVariables: Set<string>
+  usedDirectives: Set<string>
+  usedComponents: Set<string>
+  hasSlots: boolean
+  varCounter: number
+}
+/**
+ * Compilation mode
+ */
+export type CompileMode = 'ssr' | 'client' | 'universal'
+/**
+ * Template pre-compiler
+ */
+export declare class TemplateCompiler {
+  private parser: TemplateParser;
+  constructor();
+  compile(template: string, options?: CompileOptions): CompileResult;
+  compileFile(filePath: string, options?: CompileOptions): Promise<CompileResult>;
+  private createContext(options: {
+    sourceFile: string
+    mode: CompileMode
+    optimize: boolean
+    dev: boolean
+    sourceMaps: boolean
+  }): CodegenContext;
+  private generateRenderFunction(ast: DocumentNode, ctx: CodegenContext): string;
+  private analyzeAST(ast: DocumentNode, ctx: CodegenContext): void;
+  private generateNode(node: ASTNode, ctx: CodegenContext): string;
+  private generateText(text: string, _ctx: CodegenContext): string;
+  private generateExpression(node: ExpressionNode, _ctx: CodegenContext): string;
+  private generateDirective(node: DirectiveNode, ctx: CodegenContext): string;
+  private generateIf(condition: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateUnless(condition: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateForeach(params: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateFor(params: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateWhile(condition: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateIsset(params: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateEmpty(params: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateAuth(body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateGuest(body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateEnv(params: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateSwitch(params: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateSlot(params: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateSection(params: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generatePush(params: string | null, body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateOnce(body: ASTNode[] | null, ctx: CodegenContext): string;
+  private generateScript(body: ASTNode[] | null, _ctx: CodegenContext): string;
+  private generateStyle(node: { content: string, scoped: boolean }, _ctx: CodegenContext): string;
+  private generateElement(node: ElementNode, ctx: CodegenContext): string;
+  private generateAttribute(attr: AttributeNode, ctx: CodegenContext): string;
+  private parseAttributeValue(value: string, ctx: CodegenContext): string;
+  private generateComponent(node: ComponentNode, ctx: CodegenContext): string;
+  private splitConditionalBody(body: ASTNode[]): {
+    ifBody: ASTNode[]
+    elseifs: Array<{ condition: string, body: ASTNode[] }>
+    elseBody: ASTNode[]
+  };
+  private wrapModule(functionCode: string, functionName: string, format: 'esm' | 'cjs' | 'iife', _ctx: CodegenContext): string;
+}

package/dist/production-build.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Create and run a production build
+ */
+export declare function build(config: ProductionBuildConfig): Promise<BuildResult>;
+/**
+ * Create a production build instance
+ */
+export declare function createProductionBuild(config: ProductionBuildConfig): ProductionBuild;
+/**
+ * Default production config
+ */
+export declare function defineConfig(config: ProductionBuildConfig): ProductionBuildConfig;
+/**
+ * Production build configuration
+ */
+export declare interface ProductionBuildConfig {
+  entry: string | string[] | Record<string, string>
+  outDir: string
+  publicPath?: string
+  sourcemaps?: boolean | 'inline' | 'external' | 'hidden'
+  minify?: boolean | MinifyOptions
+  splitting?: boolean | SplittingOptions
+  css?: CssOptions
+  assets?: AssetOptions
+  compression?: CompressionOptions
+  analyze?: boolean | AnalyzeOptions
+  target?: string | string[]
+  define?: Record<string, string>
+  external?: string[]
+  plugins?: BuildPlugin[]
+}
+/**
+ * Minification options
+ */
+export declare interface MinifyOptions {
+  js?: boolean
+  css?: boolean
+  html?: boolean
+  dropConsole?: boolean
+  dropDebugger?: boolean
+  mangle?: boolean
+}
+/**
+ * Code splitting options
+ */
+export declare interface SplittingOptions {
+  vendor?: boolean
+  minSize?: number
+  maxSize?: number
+  chunkNames?: 'hash' | 'named' | 'deterministic'
+  manualChunks?: Record<string, string[]>
+}
+/**
+ * CSS options
+ */
+export declare interface CssOptions {
+  extract?: boolean
+  modules?: boolean | CssModulesOptions
+  postcss?: boolean | object
+  minify?: boolean
+  filename?: string
+}
+/**
+ * CSS modules options
+ */
+export declare interface CssModulesOptions {
+  pattern?: string
+  sourcemap?: boolean
+}
+/**
+ * Asset options
+ */
+export declare interface AssetOptions {
+  inlineLimit?: number
+  filename?: string
+  hash?: boolean
+  hashLength?: number
+  include?: string[]
+  exclude?: string[]
+}
+/**
+ * Compression options
+ */
+export declare interface CompressionOptions {
+  gzip?: boolean
+  brotli?: boolean
+  threshold?: number
+  deleteOriginal?: boolean
+}
+/**
+ * Bundle analysis options
+ */
+export declare interface AnalyzeOptions {
+  format?: 'html' | 'json' | 'text'
+  filename?: string
+  open?: boolean
+  gzipSize?: boolean
+  brotliSize?: boolean
+}
+/**
+ * Build plugin interface
+ */
+export declare interface BuildPlugin {
+  name: string
+  setup?: (build: ProductionBuild) => void | Promise<void>
+  buildStart?: () => void | Promise<void>
+  transform?: (code: string, id: string) => string | Promise<string> | null
+  buildEnd?: (result: BuildResult) => void | Promise<void>
+}
+/**
+ * Build result
+ */
+export declare interface BuildResult {
+  outputs: OutputFile[]
+  duration: number
+  totalSize: number
+  gzipSize: number
+  chunks: ChunkInfo[]
+  assets: AssetInfo[]
+  warnings: string[]
+  errors: string[]
+}
+/**
+ * Output file info
+ */
+export declare interface OutputFile {
+  path: string
+  type: 'js' | 'css' | 'html' | 'asset' | 'map'
+  size: number
+  gzipSize?: number
+  hash?: string
+  sources?: string[]
+  isEntry?: boolean
+}
+/**
+ * Chunk info
+ */
+export declare interface ChunkInfo {
+  name: string
+  file: string
+  size: number
+  modules: string[]
+  isVendor?: boolean
+  imports: string[]
+  dynamicImports: string[]
+}
+/**
+ * Asset info
+ */
+export declare interface AssetInfo {
+  name: string
+  file: string
+  size: number
+  source: string
+  mimeType?: string
+}
+/**
+ * Production Build orchestrator
+ */
+export declare class ProductionBuild {
+  private config: ProductionBuildConfig;
+  private startTime: number;
+  private outputs: OutputFile[];
+  private chunks: ChunkInfo[];
+  private assets: AssetInfo[];
+  private warnings: string[];
+  private errors: string[];
+  private moduleGraph: Map<string, Set<string>>;
+  private assetHashes: Map<string, string>;
+  constructor(config: ProductionBuildConfig);
+  build(): Promise<BuildResult>;
+  private collectEntries(): Map<string, string>;
+  private buildEntry(name: string, entryPath: string): Promise<void>;
+  private resolveRelativePath(from: string, to: string): string;
+  private processTemplate(content: string, filePath: string): Promise<string>;
+  private processCss(content: string, filePath: string): Promise<string>;
+  private processScript(content: string, filePath: string): Promise<string>;
+  private extractCss(): Promise<void>;
+  private processAssets(): Promise<void>;
+  private performCodeSplitting(): Promise<void>;
+  private minifyOutputs(): Promise<void>;
+  private minifyJs(code: string): string;
+  private minifyCss(css: string): string;
+  private minifyHtml(html: string): string;
+  private generateSourceMaps(): Promise<void>;
+  private fingerprintAssets(): Promise<void>;
+  private compressOutputs(): Promise<void>;
+  private analyzeBundle(): Promise<void>;
+  private generateAnalysisHtml(analysis: any): string;
+  private generateAnalysisText(analysis: any): string;
+  private runPluginHook(hook: string, arg?: any): Promise<void>;
+  private runPluginTransform(code: string, id: string): Promise<string>;
+  private generateHash(content: string | Buffer): string;
+  private getOutputName(name: string, type: OutputFile['type'], hash: string): string;
+  private formatSize(bytes: number): string;
+  private ensureDir(dir: string): void;
+  private walkDir(dir: string, callback: (path: string) => void): void;
+  private getResult(): BuildResult;
+}