@stacksjs/stx/dist/safe-evaluator.d.ts

A performant UI Framework. Powered by Bun.

/**
 * Configure the safe evaluator
 *
 * @example
 * ```typescript
 * configureSafeEvaluator({
 *   maxSanitizeDepth: 20,
 *   allowBracketNotation: true
 * })
 * ```
 */
export declare function configureSafeEvaluator(config: Partial<SafeEvaluatorConfig>): void;
/**
 * Reset configuration to defaults
 */
export declare function resetSafeEvaluatorConfig(): void;
/**
 * Get current configuration
 */
export declare function getSafeEvaluatorConfig(): SafeEvaluatorConfig;
/**
 * Sanitize an expression by checking for dangerous patterns
 */
export declare function sanitizeExpression(expression: string): string;
/**
 * Create a safer context object that only exposes safe properties
 */
export declare function createSafeContext(context: Record<string, unknown>): Record<string, unknown>;
/**
 * Safely evaluate an expression with the given context
 *
 * @param expression - The JavaScript expression to evaluate
 * @param context - Variables available during evaluation
 * @returns The result of the expression evaluation, or undefined on error
 *
 * @example
 * ```typescript
 * // Basic usage
 * const result = safeEvaluate('name.toUpperCase()', { name: 'hello' })
 *
 * // With type parameter for typed result
 * const count = safeEvaluate<number>('items.length', { items: [1, 2, 3] })
 * ```
 */
export declare function safeEvaluate<T = unknown>(expression: string, context: Record<string, unknown>): T | undefined;
/**
 * Check if an expression is safe to evaluate
 */
export declare function isExpressionSafe(expression: string): boolean;
/**
 * Safely evaluate an expression and return a boolean result
 * Used for conditional expressions in @if, @unless, etc.
 *
 * @param expression - The condition expression to evaluate
 * @param context - Variables available during evaluation
 * @returns Boolean result, defaults to false on error
 */
export declare function safeEvaluateCondition(expression: string, context: Record<string, unknown>): boolean;
/**
 * Safely evaluate an expression that returns an array
 * Used for loop iterations in @foreach, @for, etc.
 *
 * @param expression - The array expression to evaluate
 * @param context - Variables available during evaluation
 * @returns Array result, defaults to empty array on error
 */
export declare function safeEvaluateArray(expression: string, context: Record<string, unknown>): unknown[];
/**
 * Safely evaluate an expression that returns an object
 * Used for props, attributes, configuration objects
 *
 * @param expression - The object expression to evaluate
 * @param context - Variables available during evaluation
 * @returns Object result, defaults to empty object on error
 */
export declare function safeEvaluateObject(expression: string, context: Record<string, unknown>): Record<string, unknown>;
/**
 * Create a sandboxed function that can only access the provided context
 * This is a safer alternative to `new Function()` that validates expressions first
 *
 * @param expression - The expression to compile into a function
 * @param contextKeys - Variable names that will be available
 * @returns A function that takes context values and returns the result
 * @throws Error if expression contains dangerous patterns
 *
 * @example
 * ```typescript
 * const fn = createSafeFunction('x + y', ['x', 'y'])
 * const result = fn(1, 2) // returns 3
 * ```
 */
export declare function createSafeFunction(expression: string, contextKeys: string[]): (...args: unknown[]) => unknown;
/**
 * Safely evaluate a return expression (e.g., "return x + y")
 * Used for script block execution
 *
 * @param code - Code that may contain return statements
 * @param context - Variables available during evaluation
 * @returns The result of the code execution
 */
export declare function safeEvaluateCode(code: string, context: Record<string, unknown>): unknown;
/**
 * Validate a for loop expression for safety
 * Checks for dangerous patterns like eval, Function, import, etc.
 *
 * @param expression - The for loop expression (e.g., "let i = 0; i < n; i++")
 * @returns true if safe, false if potentially dangerous
 */
export declare function isForExpressionSafe(expression: string): boolean;
/**
 * Create a safe loop function with iteration limits
 *
 * @param loopType - 'for' or 'while'
 * @param expression - The loop expression or condition
 * @param body - The loop body template
 * @param contextKeys - Variable names available in context
 * @param maxIterations - Maximum iterations allowed (for while loops)
 * @returns A function that executes the loop safely
 */
export declare function createSafeLoopFunction(loopType: 'for' | 'while', expression: string, body: string, contextKeys: string[], maxIterations?: number): (...args: unknown[]) => string;
/**
 * Safe expression evaluator that reduces security risks from using new Function()
 */
/**
 * Safe evaluator configuration options
 */
export declare interface SafeEvaluatorConfig {
  maxSanitizeDepth: number
  allowBracketNotation: boolean
}