solve-engine 1.1.1 → 2.0.0

package/README.md

@@ -44,10 +44,10 @@ npm install solve-engine
 ## Quick start
 
 ```typescript
-import { ExpressionEngine } from "solve-engine";
+import { createEngine } from "solve-engine";
 
-const engine = new ExpressionEngine("en");
-const [value] = engine.evaluateExpression("2 + 2 * 10");
+const engine = createEngine();
+const value = engine.evaluateExpression("2 + 2 * 10");
 
 console.log(value.toNumber()); // 22
 ```
@@ -67,7 +67,7 @@ reachable from the module-level data query service, so a parsed engine stays
 retained until `clear()` releases it.
 
 ```typescript
-const engine = new ExpressionEngine();
+const engine = createEngine();
 engine.parseDocument(text);
 // ... read results ...
 engine.clear();
@@ -93,7 +93,7 @@ call to remember.
 ```typescript
 import { formatValue } from "solve-engine/format";
 
-const [value] = engine.evaluateExpression("10 USD to GBP");
+const value = engine.evaluateExpression("10 USD to GBP");
 console.log(formatValue(value)); // uses DEFAULT_FORMATTING_SETTINGS if no settings passed
 ```
 
@@ -104,8 +104,8 @@ they are:
 
 | Subpath | Purpose |
 |---|---|
-| `solve-engine` | Start here, `ExpressionEngine`, `PackageRegistry`/`packageRegistry`, `IEnginePackage`. |
-| `solve-engine/engine` | `ExpressionEngine` and its supporting types (`LineEvaluation`, `EvalResults`, etc.) directly, without the package-registration wrapper. |
+| `solve-engine` | Start here, `ExpressionEngine`, `createEngine`, `IEnginePackage`. |
+| `solve-engine/engine` | `ExpressionEngine` and its supporting types (`Explanation`, `EngineSnapshot`, etc.) directly, without the package-registration wrapper. |
 | `solve-engine/vm` | The bytecode VM: `Value`/`ValueType`, opcode dispatch, `allocatePluginFunctionIndex`. |
 | `solve-engine/format` | Turning a `Value` into a display string (numbers, dates, units, vectors, ...). |
 | `solve-engine/language` | Editor-agnostic language service: token categories, completions, highlighting. |
@@ -122,7 +122,6 @@ depend on):
 | `solve-engine/lexer` | Tokenizer, `LexerVocabulary` for registering custom keywords/operators/units. |
 | `solve-engine/parser` | Pratt parser, `BytecodeBuilder`, `OpCode`. |
 | `solve-engine/normalizer` | Post-lexer token transforms (phrase fusion, implicit multiply). |
-| `solve-engine/variables` | Variable resolution (`IVariableSource`). |
 | `solve-engine/resolvers` | Async resolvers (`IAsyncResolver`) for data that loads asynchronously. |
 | `solve-engine/errors` | `EngineError` and the error factory. |
 | `solve-engine/utilities` | Small stateless helpers (e.g. `stripQuotes`). |
@@ -136,8 +135,8 @@ minor versions without notice.
 ## Authoring a package
 
 A **package** (`IEnginePackage`) is a plain data descriptor bundling everything needed to
-extend the engine with a new domain: custom tokens, parselets, VM opcode handlers, variable
-sources, and optional async resolvers. See
+extend the engine with a new domain: custom tokens, parselets, VM opcode handlers, and
+optional async resolvers. See
 [`solve-engine/api`'s `IEnginePackage`](https://github.com/LiamRiddell/solve-engine/blob/main/packages/engine/src/api/PackageRegistry.ts) for the full field list
 with inline documentation and examples for each field.
 
@@ -211,17 +210,13 @@ published package, see `files` in `package.json`, only `dist/` ships):
 
 ## Known limitations
 
-**Cross-instance isolation is partial.** Plugin functions, the opcode registry and
-variable sources are now owned per `ExpressionEngine`, so two engines with different
-package sets no longer interfere across those. The lexer and the currency exchange rates
+**Cross-instance isolation is partial.** Plugin functions and the opcode registry are
+now owned per `ExpressionEngine`, so two engines with different package sets no longer
+interfere across those. The lexer and the currency exchange rates
 are still module-level singletons, so full isolation between two engines in one process
 cannot yet be assumed. Tracked as "L1, EngineContext"; three of its five migrations have
 landed and the remaining two are a prerequisite for 1.0.0 proper.
 
-**`variableSources` does nothing.** A package can declare them, the engine registers and
-unregisters them, and no evaluation path ever consults them. Treat the extension point as
-absent until that changes.
-
 **Async results need a host hook.** `AsyncResolutionBatcher.onLineResult` is the only
 mechanism that patches a resolved async value back into the document model, and it is not
 wired inside the package. A host that does not supply it gets async values that never

package/dist/{BytecodeBuilder-Bp9xeTmX.d.cts → BytecodeBuilder-DGGeByAP.d.cts}

@@ -182,6 +182,7 @@ interface UserFunctionDef {
  * - In-place reset for reuse without reallocation
  */
 declare class BytecodeBuilder {
+    private readonly pluginFunctionIndex?;
     private opcodes;
     private numbers;
     private strings;
@@ -189,6 +190,23 @@ declare class BytecodeBuilder {
     private _hasAsync;
     private userFunctionBodies;
     private anonymousBodies;
+    /**
+     * The per-engine `plugin function name -> registry index` map, wired in by
+     * the engine so {@link emitPluginCall} can resolve a name at emit time. The
+     * same object reference is shared with every builder in an engine (the pool
+     * and each ad-hoc nested-body builder), and the engine populates it as
+     * packages register, so a parselet never sees the numeric index.
+     */
+    constructor(pluginFunctionIndex?: ReadonlyMap<string, number> | undefined);
+    /** The name->index map, so a nested-body builder inherits the same resolution. */
+    get pluginIndexMap(): ReadonlyMap<string, number> | undefined;
+    /**
+     * Emit a plugin-function call by NAME. The engine assigns each registered
+     * `pluginFunctions` entry an index at registration; this resolves the name to
+     * that index and emits `CALL_PLUGIN` + index + argCount. Package authors emit
+     * through this rather than a hand-allocated index.
+     */
+    emitPluginCall(name: string, argCount: number): void;
     /** Emit an {@link OpCode} instruction. */
     emitOpcode(op: OpCode): void;
     /**

package/dist/{BytecodeBuilder-Bp9xeTmX.d.ts → BytecodeBuilder-DGGeByAP.d.ts}

@@ -182,6 +182,7 @@ interface UserFunctionDef {
  * - In-place reset for reuse without reallocation
  */
 declare class BytecodeBuilder {
+    private readonly pluginFunctionIndex?;
     private opcodes;
     private numbers;
     private strings;
@@ -189,6 +190,23 @@ declare class BytecodeBuilder {
     private _hasAsync;
     private userFunctionBodies;
     private anonymousBodies;
+    /**
+     * The per-engine `plugin function name -> registry index` map, wired in by
+     * the engine so {@link emitPluginCall} can resolve a name at emit time. The
+     * same object reference is shared with every builder in an engine (the pool
+     * and each ad-hoc nested-body builder), and the engine populates it as
+     * packages register, so a parselet never sees the numeric index.
+     */
+    constructor(pluginFunctionIndex?: ReadonlyMap<string, number> | undefined);
+    /** The name->index map, so a nested-body builder inherits the same resolution. */
+    get pluginIndexMap(): ReadonlyMap<string, number> | undefined;
+    /**
+     * Emit a plugin-function call by NAME. The engine assigns each registered
+     * `pluginFunctions` entry an index at registration; this resolves the name to
+     * that index and emits `CALL_PLUGIN` + index + argCount. Package authors emit
+     * through this rather than a hand-allocated index.
+     */
+    emitPluginCall(name: string, argCount: number): void;
     /** Emit an {@link OpCode} instruction. */
     emitOpcode(op: OpCode): void;
     /**

package/dist/{Configuration-C9W8tJv_.d.cts → Configuration-B6W0-T67.d.cts}

@@ -79,7 +79,7 @@ interface DateConfig {
      *
      * Optional and unset by default: with no calendar, working-day arithmetic
      * skips weekends only. A host that wants holidays excluded too supplies one
-     * here (`new ExpressionEngine("en", false, { date: { holidays } })`), the
+     * here (`new ExpressionEngine({ config: { date: { holidays } } })`), the
      * same way stocks and weather take a host data source. Threaded into the VM
      * by `engine/ExpressionEngine.ts` exactly as {@link maxOffsetYears} is,
      * because working-day math is a VM operation several grammar forms share, so
@@ -261,13 +261,13 @@ interface VMConfig {
  * ```typescript
  * import { ExpressionEngine } from "solve-js";
  *
- * const engine = new ExpressionEngine("en", false, {
+ * const engine = new ExpressionEngine({ config: {
  *   validation: {
  *     maxExpressionLength: 1000,
  *     maxComplexity: 200,
  *   },
  *   // date, performance, vm, worker, diagnostic all use defaults
- * });
+ * } });
  * ```
  */
 interface EngineConfig {
@@ -284,6 +284,19 @@ interface EngineConfig {
     /** Diagnostic pipeline configuration */
     readonly diagnostic: DiagnosticConfig;
 }
+/**
+ * A partial {@link EngineConfig} override, one section at a time.
+ *
+ * Overrides are merged per section over {@link DEFAULT_CONFIG}, so you can set a
+ * single field of one section (`{ validation: { maxExpressionLength: 1000 } }`)
+ * and keep every other default in that section. A plain `Partial<EngineConfig>`
+ * cannot express that, it demands a whole section object, which is why the
+ * documented overrides never typechecked against it. This is the type the
+ * constructor and {@link createEngine} accept.
+ */
+type EngineConfigOverride = {
+    readonly [K in keyof EngineConfig]?: Partial<EngineConfig[K]>;
+};
 /**
  * Default configuration values
  */
@@ -355,4 +368,4 @@ interface ValidationResult {
     warnings?: string[];
 }
 
-export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type HolidayCalendar as H, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type HolidayPredicate as c, type ValidationConfig as d, type ValidationResult as e };
+export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfigOverride as E, type HolidayCalendar as H, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type EngineConfig as a, type DateConfig as b, type DiagnosticConfig as c, type HolidayPredicate as d, type ValidationConfig as e, type ValidationResult as f };

package/dist/{Configuration-C9W8tJv_.d.ts → Configuration-B6W0-T67.d.ts}

@@ -79,7 +79,7 @@ interface DateConfig {
      *
      * Optional and unset by default: with no calendar, working-day arithmetic
      * skips weekends only. A host that wants holidays excluded too supplies one
-     * here (`new ExpressionEngine("en", false, { date: { holidays } })`), the
+     * here (`new ExpressionEngine({ config: { date: { holidays } } })`), the
      * same way stocks and weather take a host data source. Threaded into the VM
      * by `engine/ExpressionEngine.ts` exactly as {@link maxOffsetYears} is,
      * because working-day math is a VM operation several grammar forms share, so
@@ -261,13 +261,13 @@ interface VMConfig {
  * ```typescript
  * import { ExpressionEngine } from "solve-js";
  *
- * const engine = new ExpressionEngine("en", false, {
+ * const engine = new ExpressionEngine({ config: {
  *   validation: {
  *     maxExpressionLength: 1000,
  *     maxComplexity: 200,
  *   },
  *   // date, performance, vm, worker, diagnostic all use defaults
- * });
+ * } });
  * ```
  */
 interface EngineConfig {
@@ -284,6 +284,19 @@ interface EngineConfig {
     /** Diagnostic pipeline configuration */
     readonly diagnostic: DiagnosticConfig;
 }
+/**
+ * A partial {@link EngineConfig} override, one section at a time.
+ *
+ * Overrides are merged per section over {@link DEFAULT_CONFIG}, so you can set a
+ * single field of one section (`{ validation: { maxExpressionLength: 1000 } }`)
+ * and keep every other default in that section. A plain `Partial<EngineConfig>`
+ * cannot express that, it demands a whole section object, which is why the
+ * documented overrides never typechecked against it. This is the type the
+ * constructor and {@link createEngine} accept.
+ */
+type EngineConfigOverride = {
+    readonly [K in keyof EngineConfig]?: Partial<EngineConfig[K]>;
+};
 /**
  * Default configuration values
  */
@@ -355,4 +368,4 @@ interface ValidationResult {
     warnings?: string[];
 }
 
-export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfig as E, type HolidayCalendar as H, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type DateConfig as a, type DiagnosticConfig as b, type HolidayPredicate as c, type ValidationConfig as d, type ValidationResult as e };
+export { ConfigManager as C, DEFAULT_CONFIG as D, type EngineConfigOverride as E, type HolidayCalendar as H, type PerformanceConfig as P, type VMConfig as V, type WorkerConfig as W, type EngineConfig as a, type DateConfig as b, type DiagnosticConfig as c, type HolidayPredicate as d, type ValidationConfig as e, type ValidationResult as f };

package/dist/{EngineError-B61GS1jp.d.cts → EngineError-Ce1lPkjZ.d.cts}

@@ -52,6 +52,8 @@ declare const CoreErrorCodes: {
     readonly TOO_MANY_FUNCTION_DEFINITIONS: "TOO_MANY_FUNCTION_DEFINITIONS";
     /** `BytecodeBuilder`'s `anonymousBodies` side-table (map/reduce inline transform bodies) exceeding its capacity. Same class as `TOO_MANY_FUNCTION_DEFINITIONS` above. */
     readonly TOO_MANY_ANONYMOUS_BODIES: "TOO_MANY_ANONYMOUS_BODIES";
+    /** New with the 2.0 descriptor redesign: a parselet emits a plugin call by NAME (`BytecodeBuilder.emitPluginCall(name, argCount)`) and the engine resolves that name to the index it assigned at registration. This fires when the name is absent from the builder's name->index map: the package used a `pluginFunctions` name it never declared, or the expression was parsed before that package registered. Not a user-input error; a package-authoring/registration fault. See `parser/BytecodeBuilder.ts`'s `emitPluginCall()`. */
+    readonly UNKNOWN_PLUGIN_FUNCTION: "UNKNOWN_PLUGIN_FUNCTION";
     readonly EVALUATION_ERROR: "EVALUATION_ERROR";
     readonly INSTRUCTION_LIMIT_EXCEEDED: "INSTRUCTION_LIMIT_EXCEEDED";
     readonly STACK_LIMIT_EXCEEDED: "STACK_LIMIT_EXCEEDED";
@@ -154,6 +156,12 @@ declare const CoreErrorCodes: {
     readonly THEREFORE_REQUIRES_EXPRESSION: "THEREFORE_REQUIRES_EXPRESSION";
     /** A `"=>"`-triggered expression called an async plugin (weather/stocks/currency). Same v1 scope restriction as user-function/map-reduce bodies. */
     readonly THEREFORE_ASYNC_UNSUPPORTED: "THEREFORE_ASYNC_UNSUPPORTED";
+    /** A compound assignment (`name += expr` / `name -= expr`) with nothing on the right, a line half-typed on the way to `total += 5`. */
+    readonly COMPOUND_ASSIGN_REQUIRES_EXPRESSION: "COMPOUND_ASSIGN_REQUIRES_EXPRESSION";
+    /** A running total (`+= / -=`) whose right-hand side calls an async plugin (weather/stocks/currency). The same v1 scope restriction as the `"=>"` and user-function bodies. */
+    readonly COMPOUND_ASSIGN_ASYNC_UNSUPPORTED: "COMPOUND_ASSIGN_ASYNC_UNSUPPORTED";
+    /** A savings-goal contribution period that is not one of daily/weekly/monthly/yearly (`how long to save $X at $Y <period>`). Names the accepted set. */
+    readonly UNKNOWN_SAVINGS_PERIOD: "UNKNOWN_SAVINGS_PERIOD";
     /** Colon-separated numbers that are not a time any clock can show ("24:00", "9:60", "100:5"). Raised by the labeled-line fallback, which used to answer them with whatever stood after the colon. */
     readonly INVALID_TIME_LITERAL: "INVALID_TIME_LITERAL";
     /** `fromJSON()` handed an object that is not a snapshot at all, or whose serialised-shape version does not match this engine's reader. The versioning gate that refuses an incompatible snapshot clearly rather than restoring it wrongly. See `engine/EngineSnapshot.ts`'s `assertRestorable()`. */

package/dist/{EngineError-B61GS1jp.d.ts → EngineError-Ce1lPkjZ.d.ts}

@@ -52,6 +52,8 @@ declare const CoreErrorCodes: {
     readonly TOO_MANY_FUNCTION_DEFINITIONS: "TOO_MANY_FUNCTION_DEFINITIONS";
     /** `BytecodeBuilder`'s `anonymousBodies` side-table (map/reduce inline transform bodies) exceeding its capacity. Same class as `TOO_MANY_FUNCTION_DEFINITIONS` above. */
     readonly TOO_MANY_ANONYMOUS_BODIES: "TOO_MANY_ANONYMOUS_BODIES";
+    /** New with the 2.0 descriptor redesign: a parselet emits a plugin call by NAME (`BytecodeBuilder.emitPluginCall(name, argCount)`) and the engine resolves that name to the index it assigned at registration. This fires when the name is absent from the builder's name->index map: the package used a `pluginFunctions` name it never declared, or the expression was parsed before that package registered. Not a user-input error; a package-authoring/registration fault. See `parser/BytecodeBuilder.ts`'s `emitPluginCall()`. */
+    readonly UNKNOWN_PLUGIN_FUNCTION: "UNKNOWN_PLUGIN_FUNCTION";
     readonly EVALUATION_ERROR: "EVALUATION_ERROR";
     readonly INSTRUCTION_LIMIT_EXCEEDED: "INSTRUCTION_LIMIT_EXCEEDED";
     readonly STACK_LIMIT_EXCEEDED: "STACK_LIMIT_EXCEEDED";
@@ -154,6 +156,12 @@ declare const CoreErrorCodes: {
     readonly THEREFORE_REQUIRES_EXPRESSION: "THEREFORE_REQUIRES_EXPRESSION";
     /** A `"=>"`-triggered expression called an async plugin (weather/stocks/currency). Same v1 scope restriction as user-function/map-reduce bodies. */
     readonly THEREFORE_ASYNC_UNSUPPORTED: "THEREFORE_ASYNC_UNSUPPORTED";
+    /** A compound assignment (`name += expr` / `name -= expr`) with nothing on the right, a line half-typed on the way to `total += 5`. */
+    readonly COMPOUND_ASSIGN_REQUIRES_EXPRESSION: "COMPOUND_ASSIGN_REQUIRES_EXPRESSION";
+    /** A running total (`+= / -=`) whose right-hand side calls an async plugin (weather/stocks/currency). The same v1 scope restriction as the `"=>"` and user-function bodies. */
+    readonly COMPOUND_ASSIGN_ASYNC_UNSUPPORTED: "COMPOUND_ASSIGN_ASYNC_UNSUPPORTED";
+    /** A savings-goal contribution period that is not one of daily/weekly/monthly/yearly (`how long to save $X at $Y <period>`). Names the accepted set. */
+    readonly UNKNOWN_SAVINGS_PERIOD: "UNKNOWN_SAVINGS_PERIOD";
     /** Colon-separated numbers that are not a time any clock can show ("24:00", "9:60", "100:5"). Raised by the labeled-line fallback, which used to answer them with whatever stood after the colon. */
     readonly INVALID_TIME_LITERAL: "INVALID_TIME_LITERAL";
     /** `fromJSON()` handed an object that is not a snapshot at all, or whose serialised-shape version does not match this engine's reader. The versioning gate that refuses an incompatible snapshot clearly rather than restoring it wrongly. See `engine/EngineSnapshot.ts`'s `assertRestorable()`. */

package/dist/{Lexer-BOs7euZe.d.cts → Lexer-B4C1qHXu.d.cts}

@@ -1,4 +1,4 @@
-import { T as Token } from './Token-B1hdkedD.cjs';
+import { T as Token } from './Token-CbP_OutD.cjs';
 
 /** Trie node for multi-word phrase matching. */
 interface PhraseNode {

package/dist/{Lexer-CSI_lwbW.d.ts → Lexer-DKMlj7Sy.d.ts}

@@ -1,4 +1,4 @@
-import { T as Token } from './Token-B1hdkedD.js';
+import { T as Token } from './Token-CbP_OutD.js';
 
 /** Trie node for multi-word phrase matching. */
 interface PhraseNode {

package/dist/{PackageCompatibility-B-7rK1TD.d.cts → PackageCompatibility-Bn5jnBtA.d.cts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-BHWJP83F.cjs';
+import { I as IEnginePackage } from './PackageRegistry-dpdurBVO.cjs';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping
@@ -41,7 +41,7 @@ import { I as IEnginePackage } from './PackageRegistry-BHWJP83F.cjs';
 /** How serious a detected conflict is. */
 type CompatibilitySeverity = "error" | "warning" | "info";
 /** The category of overlap detected between two packages. */
-type CompatibilityConflictKind = "prefixParseletTokenType" | "infixParseletTokenType" | "phrase" | "converterName" | "pluginFunctionIndex" | "lexerKeyword" | "lexerOperator" | "asyncResolverNamespace" | "tokenCategory";
+type CompatibilityConflictKind = "prefixParseletTokenType" | "infixParseletTokenType" | "phrase" | "converterName" | "pluginFunctionName" | "lexerKeyword" | "lexerOperator" | "asyncResolverNamespace" | "tokenCategory" | "normalizerRuleName";
 /** One way two packages collide, for example claiming the same keyword. */
 interface CompatibilityConflict {
     kind: CompatibilityConflictKind;

package/dist/{PackageCompatibility-Dh59eF-X.d.ts → PackageCompatibility-CIvq2MP5.d.ts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-_8rDlvxI.js';
+import { I as IEnginePackage } from './PackageRegistry-DzeiWcv4.js';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping
@@ -41,7 +41,7 @@ import { I as IEnginePackage } from './PackageRegistry-_8rDlvxI.js';
 /** How serious a detected conflict is. */
 type CompatibilitySeverity = "error" | "warning" | "info";
 /** The category of overlap detected between two packages. */
-type CompatibilityConflictKind = "prefixParseletTokenType" | "infixParseletTokenType" | "phrase" | "converterName" | "pluginFunctionIndex" | "lexerKeyword" | "lexerOperator" | "asyncResolverNamespace" | "tokenCategory";
+type CompatibilityConflictKind = "prefixParseletTokenType" | "infixParseletTokenType" | "phrase" | "converterName" | "pluginFunctionName" | "lexerKeyword" | "lexerOperator" | "asyncResolverNamespace" | "tokenCategory" | "normalizerRuleName";
 /** One way two packages collide, for example claiming the same keyword. */
 interface CompatibilityConflict {
     kind: CompatibilityConflictKind;