solve-engine 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/Configuration-fVpd-HC-.d.cts

@@ -0,0 +1,228 @@
+/**
+ * Configuration Module for solve-js Engine
+ *
+ * This module provides the **single source of truth** for all engine configuration.
+ * Every configurable aspect of the engine, from safety limits and performance
+ * budgets to VM constraints and worker pool sizing, is defined here.
+ *
+ * ### Design principles
+ *
+ * 1. **Engine owns its config.** The engine defines its own config shape and defaults.
+ *    Consumers (e.g., the Obsidian plugin) pass partial overrides; all unspecified
+ *    fields fall back to `DEFAULT_CONFIG`.
+ *
+ * 2. **Self-documenting.** Every interface and field has descriptive JSDoc so the
+ *    config is understandable at a glance, whether you're using the engine as an
+ *    npm package or reading the source.
+ *
+ * 3. **Minimal consumer knowledge.** Consumers only need to pass `Partial<EngineConfig>`.
+ *    They don't need to replicate the full config shape, just the fields they
+ *    want to override.
+ *
+ * @module Configuration
+ */
+/**
+ * Date-related configuration.
+ * Controls the bounds and formatting for date/time expression evaluation
+ * (e.g., `today + 20 days`, `last monday`).
+ */
+interface DateConfig {
+    /** Default offset in days for relative date calculations when no offset is specified */
+    readonly defaultOffsetDays: number;
+    /** Maximum allowed positive offset in years (safety limit) */
+    readonly maxOffsetYears: number;
+    /** Maximum allowed negative offset in years (safety limit) */
+    readonly minOffsetYears: number;
+    /** Default date string format for display (moment.js format string) */
+    readonly defaultFormat: string;
+}
+/**
+ * Dice-related configuration.
+ * Controls dice expression evaluation (e.g., `roll(1, 100)`, `3d6`).
+ */
+interface DiceConfig {
+    /** Default number of sides on a die when not specified */
+    readonly defaultSides: number;
+    /** Maximum allowed sides per die (prevents excessive allocation) */
+    readonly maxSides: number;
+    /** Maximum number of dice in a single roll expression */
+    readonly maxDice: number;
+    /** Default number of dice when not specified */
+    readonly defaultDice: number;
+}
+/**
+ * Performance-related configuration.
+ * Controls caching, timeouts, and processing limits to prevent runaway
+ * resource consumption on large documents.
+ */
+interface PerformanceConfig {
+    /**
+     * Maximum number of entries in {@link ExpressionEngine}'s bytecode cache
+     * (per-instance, keyed by expression text) before the oldest entry is
+     * evicted. Raise this for documents with many distinct expressions if
+     * repeated re-evaluation (e.g. scrolling) is re-parsing instead of
+     * hitting cache, bug fix (release hardening pass): this field used to
+     * be read nowhere; the cache size was a hardcoded, unconfigurable
+     * constant. Note this does NOT bound {@link LineCache}, which has no
+     * size limit of its own.
+     */
+    readonly defaultCacheSize: number;
+    /** Maximum number of document lines processed in a single pass */
+    readonly maxDocumentLines: number;
+    /** Maximum time (ms) allowed for parsing a single expression before timeout */
+    readonly parseTimeoutMs: number;
+    /** Maximum time (ms) allowed for executing a single expression before timeout */
+    readonly executionTimeoutMs: number;
+}
+/**
+ * Validation / safety-limit configuration.
+ * Protects against runaway expressions that could cause excessive memory use
+ * or stack overflow. These limits are checked during lexing and parsing.
+ */
+/** Bounds on untrusted input: expression length and nesting depth. */
+interface ValidationConfig {
+    /** Maximum expression length in characters. Prevents excessively long strings from entering the pipeline. */
+    readonly maxExpressionLength: number;
+    /** Maximum expression complexity score (`tokens + functionCalls×5 + nestingDepth×10`). Protects against deeply nested or combinatorially complex expressions. */
+    readonly maxComplexity: number;
+    /** Maximum parentheses nesting depth. Prevents stack overflow in the recursive-descent parser. */
+    readonly maxNestingDepth: number;
+    /**
+     * Auto-balance unmatched parentheses by appending missing closing parens
+     * or prepending missing opening parens. When disabled, unbalanced expressions
+     * cause parse errors instead of being silently corrected.
+     *
+     * Disabled by default for strict parsing. Enable for forgiving user input
+     * (e.g., chat-style calculators where users often omit closing parens).
+     * Has zero overhead when disabled, the O(n) paren-count scan is skipped.
+     */
+    readonly autoBalanceParens: boolean;
+}
+/**
+ * Worker pool configuration.
+ * Controls the parallel execution workers used for batch evaluation.
+ */
+interface WorkerConfig {
+    /** Maximum number of concurrent Web Workers allowed */
+    readonly maxConcurrentWorkers: number;
+    /** Time (ms) a worker stays alive while idle before being terminated */
+    readonly idleTimeoutMs: number;
+    /** Maximum retry attempts for a failed worker operation */
+    readonly maxRetries: number;
+    /** Base backoff delay (ms) between retries (exponential backoff applied on top) */
+    readonly baseBackoffMs: number;
+} /**
+   * Diagnostic / telemetry configuration.
+   * Controls the diagnostic event pipeline for profiling and debugging.
+   * All diagnostics are disabled by default for maximum production performance.
+   */
+interface DiagnosticConfig {
+    /** Master switch: enable the diagnostic pipeline (collectors receive events for all pipeline stages) */
+    readonly enabled: boolean;
+    /** Enable VM trace mode, emits per-opcode execution events (very verbose; disables some optimizations) */
+    readonly vmTraceEnabled: boolean;
+}
+/**
+ * Virtual Machine configuration.
+ * Controls the internal bytecode VM that executes compiled expressions.
+ */
+interface VMConfig {
+    /** Maximum stack depth (value slots) for VM execution, prevents stack overflow in recursive/pratt-parser generated bytecode */
+    readonly maxStackDepth: number;
+    /** Maximum opcodes executed per expression, halts runaway infinite loops */
+    readonly maxInstructions: number;
+}
+/**
+ * Complete engine configuration.
+ *
+ * Every field has a default in `DEFAULT_CONFIG`. To customize, pass a
+ * `Partial<EngineConfig>` when constructing `ExpressionEngine`. Only the
+ * sections/fields you supply are overridden; all others use their defaults.
+ *
+ * @example
+ * ```typescript
+ * import { ExpressionEngine } from "solve-js";
+ *
+ * const engine = new ExpressionEngine("en", false, {
+ *   validation: {
+ *     maxExpressionLength: 1000,
+ *     maxComplexity: 200,
+ *   },
+ *   // date, dice, performance, vm, worker, diagnostic all use defaults
+ * });
+ * ```
+ */
+interface EngineConfig {
+    /** Date/time expression evaluation bounds and formatting */
+    readonly date: DateConfig;
+    /** Dice roll expression controls */
+    readonly dice: DiceConfig;
+    /** Performance budgets and cache sizing */
+    readonly performance: PerformanceConfig;
+    /** Safety limits for expression complexity */
+    readonly validation: ValidationConfig;
+    /** Internal bytecode VM configuration */
+    readonly vm: VMConfig;
+    /** Parallel worker pool configuration */
+    readonly worker: WorkerConfig;
+    /** Diagnostic pipeline configuration */
+    readonly diagnostic: DiagnosticConfig;
+}
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: EngineConfig;
+/**
+ * Configuration manager for engine settings
+ *
+ * @example
+ * ```typescript
+ * const configManager = new ConfigManager();
+ * configManager.set('performance.defaultCacheSize', 2000);
+ * const cacheSize = configManager.get('performance.defaultCacheSize');
+ * ```
+ */
+declare class ConfigManager {
+    private config;
+    constructor(config?: Partial<EngineConfig>);
+    /**
+     * Get configuration value by path
+     *
+     * @param path - Dot-notation path to config value
+     * @returns Configuration value
+     */
+    get<T>(path: string): T;
+    /**
+     * Set configuration value by path
+     *
+     * @param path - Dot-notation path to config value
+     * @param value - New value
+     */
+    set<T>(path: string, value: T): void;
+    /**
+     * Get complete configuration
+     */
+    getConfig(): EngineConfig;
+    /**
+     * Update multiple configuration values
+     */
+    update(config: Partial<EngineConfig>): void;
+    /**
+     * Reset to default configuration
+     */
+    reset(): void;
+    /**
+     * Validate configuration values
+     */
+    validate(): ValidationResult;
+}
+/**
+ * Result type for {@link ConfigManager.validate}.
+ */
+interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    warnings?: string[];
+}
+
+export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type DiceConfig as c, type ValidationConfig as d, type ValidationResult as e };

package/dist/Configuration-fVpd-HC-.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Configuration Module for solve-js Engine
+ *
+ * This module provides the **single source of truth** for all engine configuration.
+ * Every configurable aspect of the engine, from safety limits and performance
+ * budgets to VM constraints and worker pool sizing, is defined here.
+ *
+ * ### Design principles
+ *
+ * 1. **Engine owns its config.** The engine defines its own config shape and defaults.
+ *    Consumers (e.g., the Obsidian plugin) pass partial overrides; all unspecified
+ *    fields fall back to `DEFAULT_CONFIG`.
+ *
+ * 2. **Self-documenting.** Every interface and field has descriptive JSDoc so the
+ *    config is understandable at a glance, whether you're using the engine as an
+ *    npm package or reading the source.
+ *
+ * 3. **Minimal consumer knowledge.** Consumers only need to pass `Partial<EngineConfig>`.
+ *    They don't need to replicate the full config shape, just the fields they
+ *    want to override.
+ *
+ * @module Configuration
+ */
+/**
+ * Date-related configuration.
+ * Controls the bounds and formatting for date/time expression evaluation
+ * (e.g., `today + 20 days`, `last monday`).
+ */
+interface DateConfig {
+    /** Default offset in days for relative date calculations when no offset is specified */
+    readonly defaultOffsetDays: number;
+    /** Maximum allowed positive offset in years (safety limit) */
+    readonly maxOffsetYears: number;
+    /** Maximum allowed negative offset in years (safety limit) */
+    readonly minOffsetYears: number;
+    /** Default date string format for display (moment.js format string) */
+    readonly defaultFormat: string;
+}
+/**
+ * Dice-related configuration.
+ * Controls dice expression evaluation (e.g., `roll(1, 100)`, `3d6`).
+ */
+interface DiceConfig {
+    /** Default number of sides on a die when not specified */
+    readonly defaultSides: number;
+    /** Maximum allowed sides per die (prevents excessive allocation) */
+    readonly maxSides: number;
+    /** Maximum number of dice in a single roll expression */
+    readonly maxDice: number;
+    /** Default number of dice when not specified */
+    readonly defaultDice: number;
+}
+/**
+ * Performance-related configuration.
+ * Controls caching, timeouts, and processing limits to prevent runaway
+ * resource consumption on large documents.
+ */
+interface PerformanceConfig {
+    /**
+     * Maximum number of entries in {@link ExpressionEngine}'s bytecode cache
+     * (per-instance, keyed by expression text) before the oldest entry is
+     * evicted. Raise this for documents with many distinct expressions if
+     * repeated re-evaluation (e.g. scrolling) is re-parsing instead of
+     * hitting cache, bug fix (release hardening pass): this field used to
+     * be read nowhere; the cache size was a hardcoded, unconfigurable
+     * constant. Note this does NOT bound {@link LineCache}, which has no
+     * size limit of its own.
+     */
+    readonly defaultCacheSize: number;
+    /** Maximum number of document lines processed in a single pass */
+    readonly maxDocumentLines: number;
+    /** Maximum time (ms) allowed for parsing a single expression before timeout */
+    readonly parseTimeoutMs: number;
+    /** Maximum time (ms) allowed for executing a single expression before timeout */
+    readonly executionTimeoutMs: number;
+}
+/**
+ * Validation / safety-limit configuration.
+ * Protects against runaway expressions that could cause excessive memory use
+ * or stack overflow. These limits are checked during lexing and parsing.
+ */
+/** Bounds on untrusted input: expression length and nesting depth. */
+interface ValidationConfig {
+    /** Maximum expression length in characters. Prevents excessively long strings from entering the pipeline. */
+    readonly maxExpressionLength: number;
+    /** Maximum expression complexity score (`tokens + functionCalls×5 + nestingDepth×10`). Protects against deeply nested or combinatorially complex expressions. */
+    readonly maxComplexity: number;
+    /** Maximum parentheses nesting depth. Prevents stack overflow in the recursive-descent parser. */
+    readonly maxNestingDepth: number;
+    /**
+     * Auto-balance unmatched parentheses by appending missing closing parens
+     * or prepending missing opening parens. When disabled, unbalanced expressions
+     * cause parse errors instead of being silently corrected.
+     *
+     * Disabled by default for strict parsing. Enable for forgiving user input
+     * (e.g., chat-style calculators where users often omit closing parens).
+     * Has zero overhead when disabled, the O(n) paren-count scan is skipped.
+     */
+    readonly autoBalanceParens: boolean;
+}
+/**
+ * Worker pool configuration.
+ * Controls the parallel execution workers used for batch evaluation.
+ */
+interface WorkerConfig {
+    /** Maximum number of concurrent Web Workers allowed */
+    readonly maxConcurrentWorkers: number;
+    /** Time (ms) a worker stays alive while idle before being terminated */
+    readonly idleTimeoutMs: number;
+    /** Maximum retry attempts for a failed worker operation */
+    readonly maxRetries: number;
+    /** Base backoff delay (ms) between retries (exponential backoff applied on top) */
+    readonly baseBackoffMs: number;
+} /**
+   * Diagnostic / telemetry configuration.
+   * Controls the diagnostic event pipeline for profiling and debugging.
+   * All diagnostics are disabled by default for maximum production performance.
+   */
+interface DiagnosticConfig {
+    /** Master switch: enable the diagnostic pipeline (collectors receive events for all pipeline stages) */
+    readonly enabled: boolean;
+    /** Enable VM trace mode, emits per-opcode execution events (very verbose; disables some optimizations) */
+    readonly vmTraceEnabled: boolean;
+}
+/**
+ * Virtual Machine configuration.
+ * Controls the internal bytecode VM that executes compiled expressions.
+ */
+interface VMConfig {
+    /** Maximum stack depth (value slots) for VM execution, prevents stack overflow in recursive/pratt-parser generated bytecode */
+    readonly maxStackDepth: number;
+    /** Maximum opcodes executed per expression, halts runaway infinite loops */
+    readonly maxInstructions: number;
+}
+/**
+ * Complete engine configuration.
+ *
+ * Every field has a default in `DEFAULT_CONFIG`. To customize, pass a
+ * `Partial<EngineConfig>` when constructing `ExpressionEngine`. Only the
+ * sections/fields you supply are overridden; all others use their defaults.
+ *
+ * @example
+ * ```typescript
+ * import { ExpressionEngine } from "solve-js";
+ *
+ * const engine = new ExpressionEngine("en", false, {
+ *   validation: {
+ *     maxExpressionLength: 1000,
+ *     maxComplexity: 200,
+ *   },
+ *   // date, dice, performance, vm, worker, diagnostic all use defaults
+ * });
+ * ```
+ */
+interface EngineConfig {
+    /** Date/time expression evaluation bounds and formatting */
+    readonly date: DateConfig;
+    /** Dice roll expression controls */
+    readonly dice: DiceConfig;
+    /** Performance budgets and cache sizing */
+    readonly performance: PerformanceConfig;
+    /** Safety limits for expression complexity */
+    readonly validation: ValidationConfig;
+    /** Internal bytecode VM configuration */
+    readonly vm: VMConfig;
+    /** Parallel worker pool configuration */
+    readonly worker: WorkerConfig;
+    /** Diagnostic pipeline configuration */
+    readonly diagnostic: DiagnosticConfig;
+}
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: EngineConfig;
+/**
+ * Configuration manager for engine settings
+ *
+ * @example
+ * ```typescript
+ * const configManager = new ConfigManager();
+ * configManager.set('performance.defaultCacheSize', 2000);
+ * const cacheSize = configManager.get('performance.defaultCacheSize');
+ * ```
+ */
+declare class ConfigManager {
+    private config;
+    constructor(config?: Partial<EngineConfig>);
+    /**
+     * Get configuration value by path
+     *
+     * @param path - Dot-notation path to config value
+     * @returns Configuration value
+     */
+    get<T>(path: string): T;
+    /**
+     * Set configuration value by path
+     *
+     * @param path - Dot-notation path to config value
+     * @param value - New value
+     */
+    set<T>(path: string, value: T): void;
+    /**
+     * Get complete configuration
+     */
+    getConfig(): EngineConfig;
+    /**
+     * Update multiple configuration values
+     */
+    update(config: Partial<EngineConfig>): void;
+    /**
+     * Reset to default configuration
+     */
+    reset(): void;
+    /**
+     * Validate configuration values
+     */
+    validate(): ValidationResult;
+}
+/**
+ * Result type for {@link ConfigManager.validate}.
+ */
+interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    warnings?: string[];
+}
+
+export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type DiceConfig as c, type ValidationConfig as d, type ValidationResult as e };