@stacksjs/stx 0.2.154 → 0.2.156

package/dist/errors/logger.d.ts

@@ -1,61 +1,135 @@
-import { isDevelopment } from '../env';
-export declare const errorRecovery: ErrorRecovery;
-// Global error logger instance
-export declare const errorLogger: ErrorLogger;
-export declare const devHelpers: DevHelpers;
+/**
+ * Error Logger and Recovery
+ *
+ * Provides error logging, recovery strategies, and development helpers.
+ *
+ * @module errors/logger
+ */
 /**
  * Error recovery strategies
  *
  * NOTE: Auto-recovery is opt-in via configuration.
  * Use configureErrorHandling({ enableAutoRecovery: true }) to enable.
  */
-export declare interface ErrorRecovery {
-  isEnabled(): boolean
-  fixCommonSyntaxErrors(template: string): { fixed: string, fixes: string[] }
-  createFallbackContent(sectionType: string, error: Error): string
+export interface ErrorRecovery {
+    isEnabled(): boolean;
+    fixCommonSyntaxErrors(template: string): {
+        fixed: string;
+        fixes: string[];
+    };
+    createFallbackContent(sectionType: string, error: Error): string;
 }
+export declare const errorRecovery: ErrorRecovery;
 /**
  * Error logger configuration options
  */
-export declare interface ErrorLoggerOptions {
-  maxErrors?: number
-  enableFileLogging?: boolean
-  logFilePath?: string
-  logFormat?: 'json' | 'text'
-  maxFileSize?: number
-  maxLogFiles?: number
-  minLevel?: 'all' | 'error' | 'warning'
+export interface ErrorLoggerOptions {
+    /** Maximum number of errors to keep in memory (default: 1000) */
+    maxErrors?: number;
+    /** Enable file logging */
+    enableFileLogging?: boolean;
+    /** Path to log file (default: '.stx/errors.log') */
+    logFilePath?: string;
+    /** Log format: 'json' for structured logs, 'text' for human-readable (default: 'json') */
+    logFormat?: 'json' | 'text';
+    /** Maximum log file size in bytes before rotation (default: 10MB) */
+    maxFileSize?: number;
+    /** Number of rotated log files to keep (default: 5) */
+    maxLogFiles?: number;
+    /** Minimum error level to log to file: 'all', 'error', 'warning' (default: 'all') */
+    minLevel?: 'all' | 'error' | 'warning';
 }
 /**
  * Error log entry structure
  */
-export declare interface ErrorLogEntry {
-  timestamp: Date
-  error: Error
-  context?: unknown
-  level?: 'error' | 'warning' | 'info'
+export interface ErrorLogEntry {
+    timestamp: Date;
+    error: Error;
+    context?: unknown;
+    level?: 'error' | 'warning' | 'info';
 }
 /**
- * Development mode helpers
+ * Error logging and monitoring with optional file persistence
  */
-export declare interface DevHelpers {
-  isDevelopment(): boolean
-  logDetailedError(error: Error, context?: unknown): void
-  createErrorReport(error: Error, context?: unknown): string
+export declare class ErrorLogger {
+    private errors;
+    private maxErrors;
+    private enableFileLogging;
+    private logFilePath;
+    private logFormat;
+    private maxFileSize;
+    private maxLogFiles;
+    private minLevel;
+    private writeQueue;
+    constructor(options?: ErrorLoggerOptions);
+    /**
+     * Configure the error logger
+     */
+    configure(options: ErrorLoggerOptions): void;
+    /**
+     * Log an error with optional context
+     */
+    log(error: Error, context?: unknown, level?: 'error' | 'warning' | 'info'): void;
+    /**
+     * Check if error level should be logged based on minLevel setting
+     */
+    private shouldLog;
+    /**
+     * Format an error entry for logging
+     */
+    private formatEntry;
+    /**
+     * Write error entry to file (async, non-blocking)
+     */
+    private writeToFile;
+    /**
+     * Rotate log files if current file exceeds max size
+     */
+    private rotateIfNeeded;
+    /**
+     * Get recent errors from memory
+     */
+    getRecentErrors(limit?: number): ErrorLogEntry[];
+    /**
+     * Get errors filtered by type
+     */
+    getErrorsByType(errorType: string): ErrorLogEntry[];
+    /**
+     * Get errors filtered by level
+     */
+    getErrorsByLevel(level: 'error' | 'warning' | 'info'): ErrorLogEntry[];
+    /**
+     * Clear all errors from memory
+     */
+    clear(): void;
+    /**
+     * Clear log file
+     */
+    clearLogFile(): Promise<void>;
+    /**
+     * Get error statistics
+     */
+    getStats(): {
+        total: number;
+        byType: Record<string, number>;
+        byLevel: Record<string, number>;
+    };
+    /**
+     * Export errors to a file (for debugging/reporting)
+     */
+    exportToFile(filePath: string, format?: 'json' | 'text'): Promise<void>;
+    /**
+     * Wait for all pending writes to complete
+     */
+    flush(): Promise<void>;
 }
+export declare const errorLogger: ErrorLogger;
 /**
- * Error logging and monitoring with optional file persistence
+ * Development mode helpers
  */
-export declare class ErrorLogger {
-  constructor(options?: ErrorLoggerOptions);
-  configure(options: ErrorLoggerOptions): void;
-  log(error: Error, context?: unknown, level?: 'error' | 'warning' | 'info'): void;
-  getRecentErrors(limit?: number): ErrorLogEntry[];
-  getErrorsByType(errorType: string): ErrorLogEntry[];
-  getErrorsByLevel(level: 'error' | 'warning' | 'info'): ErrorLogEntry[];
-  clear(): void;
-  clearLogFile(): Promise<void>;
-  getStats(): { total: number, byType: Record<string, number>, byLevel: Record<string, number> };
-  exportToFile(filePath: string, format?: 'json' | 'text'): Promise<void>;
-  flush(): Promise<void>;
+export interface DevHelpers {
+    isDevelopment(): boolean;
+    logDetailedError(error: Error, context?: unknown): void;
+    createErrorReport(error: Error, context?: unknown): string;
 }
+export declare const devHelpers: DevHelpers;

package/dist/errors/sanitizer.d.ts

@@ -1,3 +1,56 @@
+/**
+ * Parameter and Content Sanitization
+ *
+ * Provides sanitization utilities for directive parameters, file paths,
+ * expressions, and component props.
+ *
+ * @module errors/sanitizer
+ */
+/**
+ * Options for parameter sanitization
+ */
+export interface SanitizeOptions {
+    /** Allow HTML in parameter values (default: false) */
+    allowHtml?: boolean;
+    /** Maximum length for string parameters (default: 10000) */
+    maxLength?: number;
+    /** Allow special characters (default: true for most, false for paths) */
+    allowSpecialChars?: boolean;
+    /** Custom sanitization function */
+    customSanitizer?: (value: string) => string;
+}
+/**
+ * Result of parameter sanitization
+ */
+export interface SanitizedParam {
+    /** Sanitized value */
+    value: string;
+    /** Whether the value was modified */
+    modified: boolean;
+    /** Warnings generated during sanitization */
+    warnings: string[];
+}
+/**
+ * Validation utilities
+ */
+export declare const validators: {
+    /**
+     * Validate file path is safe and doesn't escape the allowed directory
+     */
+    isValidFilePath(filePath: string, allowedDir?: string): boolean;
+    /**
+     * Validate template variable name
+     */
+    isValidVariableName(name: string): boolean;
+    /**
+     * Validate directive name
+     */
+    isValidDirectiveName(name: string): boolean;
+    /**
+     * Check if string contains potentially malicious content
+     */
+    isSafeContent(content: string): boolean;
+};
 /**
  * Sanitize a directive parameter value
  */
@@ -18,26 +71,3 @@ export declare function sanitizeDirectiveParams(params: string[], options?: Sani
  * Validate and sanitize component props
  */
 export declare function sanitizeComponentProps(props: Record<string, unknown>): Record<string, unknown>;
-/**
- * Validation utilities
- */
-export declare const validators: {
-  
-};
-/**
- * Options for parameter sanitization
- */
-export declare interface SanitizeOptions {
-  allowHtml?: boolean
-  maxLength?: number
-  allowSpecialChars?: boolean
-  customSanitizer?: (value: string) => string
-}
-/**
- * Result of parameter sanitization
- */
-export declare interface SanitizedParam {
-  value: string
-  modified: boolean
-  warnings: string[]
-}

package/dist/errors/types.d.ts

@@ -1,4 +1,24 @@
+/**
+ * Error Types and Classes
+ *
+ * Custom error classes for better error classification and handling.
+ *
+ * @module errors/types
+ */
 import type { ErrorCode } from './codes';
+/**
+ * Error handling configuration
+ */
+export interface ErrorConfig {
+    /** Show relative paths instead of absolute (default: false) */
+    showRelativePaths: boolean;
+    /** Base directory for relative path calculation */
+    baseDir?: string;
+    /** Enable auto-recovery for common syntax errors (default: false in production) */
+    enableAutoRecovery: boolean;
+    /** Log warnings when auto-recovery is applied */
+    logRecoveryWarnings: boolean;
+}
 /**
  * Configure error handling behavior
  */
@@ -15,65 +35,58 @@ export declare function resetErrorConfig(): void;
  * Format file path based on configuration
  */
 export declare function formatFilePath(filePath: string): string;
-/**
- * Error handling configuration
- */
-export declare interface ErrorConfig {
-  showRelativePaths: boolean
-  baseDir?: string
-  enableAutoRecovery: boolean
-  logRecoveryWarnings: boolean
-}
-/**
- * Error context information
- */
-export declare interface ErrorContext {
-  filePath: string
-  template: string
-  offset: number
-  match: string
-}
 /**
  * Base STX error class
  */
 export declare class StxError extends Error {
-  numericCode: ErrorCode;
-  public code: string;
-  public filePath?: string;
-  public line?: number;
-  public column?: number;
-  public context?: string;
-  constructor(message: string, code: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+    code: string;
+    filePath?: string | undefined;
+    line?: number | undefined;
+    column?: number | undefined;
+    context?: string | undefined;
+    /** Numeric error code for programmatic handling */
+    numericCode: ErrorCode;
+    constructor(message: string, code: string, filePath?: string | undefined, line?: number | undefined, column?: number | undefined, context?: string | undefined, numericCode?: ErrorCode);
 }
 /**
  * Syntax error in template
  */
 export declare class StxSyntaxError extends StxError {
-  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+    constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
 }
 /**
  * Runtime error during template processing
  */
 export declare class StxRuntimeError extends StxError {
-  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+    constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
 }
 /**
  * Security-related error
  */
 export declare class StxSecurityError extends StxError {
-  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+    constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
 }
 /**
  * File operation error
  */
 export declare class StxFileError extends StxError {
-  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+    constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
 }
 /**
  * Validation error - these are ALWAYS fatal and cannot be recovered from.
  * Used for enforcing coding standards like prohibited DOM API usage.
  */
 export declare class StxValidationError extends StxError {
-  readonly isFatal: boolean;
-  constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+    /** Validation errors are always fatal and should never be caught/recovered */
+    readonly isFatal: boolean;
+    constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}
+/**
+ * Error context information
+ */
+export interface ErrorContext {
+    filePath: string;
+    template: string;
+    offset: number;
+    match: string;
 }

package/dist/events.d.ts

@@ -1,3 +1,87 @@
+/**
+ * Event Directives Module
+ *
+ * Provides Alpine.js-style event handling for STX templates.
+ * Transforms `@click`, `@keydown.enter`, etc. into client-side event listeners.
+ *
+ * ## Supported Syntax
+ *
+ * ### Basic Events
+ * ```html
+ * <button @click="count++">Increment</button>
+ * <button @click="handleClick()">Click me</button>
+ * <form @submit="handleSubmit()">...</form>
+ * ```
+ *
+ * ### Event Modifiers
+ * ```html
+ * <form @submit.prevent="handleSubmit()">...</form>
+ * <a @click.prevent.stop="navigate()">Link</a>
+ * <button @click.once="initialize()">Init</button>
+ * <div @click.self="onlyThis()">...</div>
+ * <input @keydown.capture="log()">
+ * ```
+ *
+ * ### Key Modifiers
+ * ```html
+ * <input @keydown.enter="submit()">
+ * <input @keyup.escape="cancel()">
+ * <input @keydown.space="toggle()">
+ * <input @keydown.ctrl.s="save()">
+ * <input @keydown.meta.enter="send()">
+ * ```
+ *
+ * ### Mouse Modifiers
+ * ```html
+ * <div @click.left="handleLeft()">
+ * <div @click.right="handleRight()">
+ * <div @click.middle="handleMiddle()">
+ * ```
+ *
+ * ### Special Variables
+ * ```html
+ * <input @input="value = $event.target.value">
+ * <button @click="handleClick($el)">Uses element</button>
+ * ```
+ *
+ * @module events
+ */
+export interface ParsedEvent {
+    /** Original attribute string (e.g., "@click.prevent") */
+    attribute: string;
+    /** Event name (e.g., "click", "keydown") */
+    event: string;
+    /** Handler expression (e.g., "count++", "handleClick()") */
+    handler: string;
+    /** Event modifiers */
+    modifiers: EventModifiers;
+    /** Unique element ID for binding */
+    elementId: string;
+}
+export interface EventModifiers {
+    /** Call preventDefault() */
+    prevent: boolean;
+    /** Call stopPropagation() */
+    stop: boolean;
+    /** Only fire once */
+    once: boolean;
+    /** Use capture mode */
+    capture: boolean;
+    /** Only fire if event.target === element */
+    self: boolean;
+    /** Passive event listener */
+    passive: boolean;
+    /** Key modifiers (enter, escape, space, etc.) */
+    keys: string[];
+    /** System modifiers (ctrl, alt, shift, meta) */
+    systemKeys: string[];
+    /** Mouse button (left, right, middle) */
+    mouse: string | null;
+    /** Debounce delay in ms */
+    debounce: number | null;
+    /** Throttle delay in ms */
+    throttle: number | null;
+}
 /**
  * `@click="doThing"` names a function, so it must be INVOKED — not evaluated.
  *
@@ -36,8 +120,8 @@ export declare function generateRuntimeScript(events: ParsedEvent[]): string;
  * @returns Object with processed template and collected bindings
  */
 export declare function extractAndProcessEvents(template: string): {
-  template: string
-  bindings: ParsedEvent[]
+    template: string;
+    bindings: ParsedEvent[];
 };
 /**
  * Process event directives in a template.
@@ -59,26 +143,3 @@ export declare function processEventDirectives(template: string, context: Record
  * Check if a template contains event directives
  */
 export declare function hasEventDirectives(template: string): boolean;
-// =============================================================================
-// Types
-// =============================================================================
-export declare interface ParsedEvent {
-  attribute: string
-  event: string
-  handler: string
-  modifiers: EventModifiers
-  elementId: string
-}
-export declare interface EventModifiers {
-  prevent: boolean
-  stop: boolean
-  once: boolean
-  capture: boolean
-  self: boolean
-  passive: boolean
-  keys: string[]
-  systemKeys: string[]
-  mouse: string | null
-  debounce: number | null
-  throttle: number | null
-}

package/dist/expressions.d.ts

@@ -1,3 +1,41 @@
+/**
+ * Module for processing template expressions and filters
+ *
+ * Expression Syntax:
+ * ==================
+ * - `{{ expression }}` - Escaped output (HTML entities escaped)
+ * - `{!! expression !!}` - Raw/unescaped output
+ * - `{{ expression | filter }}` - Apply filter to expression
+ * - `{{ expression | filter:arg1,arg2 }}` - Filter with arguments
+ * - `{{ expression | filter1 | filter2 }}` - Filter chain
+ *
+ * Filter Parsing:
+ * ===============
+ * The filter parser uses character-by-character parsing to handle:
+ * - Pipe `|` as filter separator (but not `||` logical OR)
+ * - Colon `:` as argument separator
+ * - Quoted strings with proper escape handling
+ * - Nested parentheses in expressions
+ *
+ * Key parsing rules:
+ * - `||` (double pipe) is preserved as logical OR, not filter separator
+ * - Arguments after `:` are split by `,` respecting quotes and parens
+ * - Filter names must be alphanumeric with underscores
+ *
+ * Available Built-in Filters:
+ * ===========================
+ * String: uppercase, lowercase, capitalize, truncate, replace, stripTags
+ * Number: number, currency, abs, round
+ * Array: join, first, last, length, reverse, slice
+ * Utility: escape, json, default, urlencode
+ * i18n: translate, pluralize, date
+ */
+/**
+ * Add basic filter support to expressions
+ * Filter functions receive the value to transform, optional args, and the context object
+ */
+export type FilterFunction = (value: any, context: Record<string, any>, ...args: any[]) => any;
+export declare const defaultFilters: Record<string, FilterFunction>;
 /**
  * Register a custom filter
  *
@@ -68,6 +106,18 @@ export declare function usesSignalsInScript(template: string): boolean;
  * attributes and surrounding HTML are left alone.
  */
 export declare function interpolateScriptExpressions(scriptBody: string, context: Record<string, any>): string;
+/**
+ * Options for {@link interpolateScriptsInTemplate}.
+ */
+export interface InterpolateScriptsOptions {
+    /**
+     * Skip `<script server>` tags. Useful when the template still contains
+     * unstripped server scripts (e.g. inside `processDirectives`) whose bodies
+     * are executed rather than embedded — running `{{ }}` substitution on
+     * them would produce invalid JS. Default: `false`.
+     */
+    skipServer?: boolean;
+}
 /**
  * Interpolate server expressions inside every `<script>` tag in a template,
  * skipping any script that opts out via `data-raw`, `type="application/json"`,
@@ -97,45 +147,3 @@ export declare function evaluateExpression(expression: string, context: Record<s
  * HTML unescape function to reverse escapeHtml
  */
 export declare function unescapeHtml(html: string): string;
-// =============================================================================
-// Built-in Filters
-// =============================================================================
-export declare const defaultFilters: {
-  uppercase: (value: any, _context: Record<string, any>) => unknown;
-  lowercase: (value: any, _context: Record<string, any>) => unknown;
-  capitalize: (value: any, _context: Record<string, any>) => unknown;
-  number: (value: any, _context: Record<string, any>, decimals?: number) => unknown;
-  fmt: (value: any, _context: Record<string, any>, locale?: string) => unknown;
-  join: (value: any, _context: Record<string, any>, separator?: string) => unknown;
-  escape: (value: any, _context: Record<string, any>) => unknown;
-  translate: (value: any, context: Record<string, any>, params?: Record<string, any>) => unknown;
-  t: (value: any, context: Record<string, any>, params?: Record<string, any>) => unknown;
-  truncate: (value: any, _context: Record<string, any>, length?: number, suffix?: string) => unknown;
-  date: (value: any, _context: Record<string, any>, format?: string, locale?: string) => unknown;
-  currency: (value: any, _context: Record<string, any>, currencyCode?: string, locale?: string) => unknown;
-  pluralize: (value: any, _context: Record<string, any>, singular: string, plural?: string) => unknown;
-  first: (value: any, _context: Record<string, any>) => unknown;
-  last: (value: any, _context: Record<string, any>) => unknown;
-  length: (value: any, _context: Record<string, any>) => unknown;
-  json: (value: any, _context: Record<string, any>, pretty?: boolean) => unknown;
-  default: (value: any, _context: Record<string, any>, defaultValue?: any) => unknown;
-  reverse: (value: any, _context: Record<string, any>) => unknown;
-  slice: (value: any, _context: Record<string, any>, start?: number, end?: number) => unknown;
-  replace: (value: any, _context: Record<string, any>, search: string, replacement?: string) => unknown;
-  stripTags: (value: any, _context: Record<string, any>) => unknown;
-  urlencode: (value: any, _context: Record<string, any>) => unknown;
-  abs: (value: any, _context: Record<string, any>) => unknown;
-  round: (value: any, _context: Record<string, any>, decimals?: number) => unknown
-};
-/**
- * Options for {@link interpolateScriptsInTemplate}.
- */
-export declare interface InterpolateScriptsOptions {
-  skipServer?: boolean
-}
-/**
- * Add basic filter support to expressions
- * Filter functions receive the value to transform, optional args, and the context object
- */
-// eslint-disable-next-line pickier/no-unused-vars
-export type FilterFunction = (value: any, context: Record<string, any>, ...args: any[]) => any;