solve-engine 1.2.0 → 2.1.0

package/dist/{PackageRegistry-DrCPQNyy.d.ts → PackageRegistry-DzeiWcv4.d.ts}

@@ -1,16 +1,15 @@
-import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-Bhf7d0_W.js';
-import { V as Value, b as ValueType } from './Value-DZNQ_PU7.js';
-import { IVariableSource } from './variables.js';
+import { a as PrecedenceParser, b as PrefixParselet, I as InfixParselet } from './Parselet-B-zoPrTa.js';
+import { V as Value, b as ValueType } from './Value-CCi_Eecs.js';
 import { M as MarkdownLineType, L as Lexer, e as TokenCategory, c as LexerVocabulary } from './Lexer-DKMlj7Sy.js';
 import { IAsyncResolver } from './resolvers.js';
 import { T as TokenFusion, c as TokenNormalizer, a as NormalizerRule } from './TokenNormalizer-DCWdZjGz.js';
-import { a as DependencyGraph, V as VM, D as DagSnapshot, b as EngineContext, S as ScopeManager, L as LineExecutionContext } from './ScopeManager-Bzq87GfA.js';
-import { a as BytecodeProgram } from './BytecodeBuilder-Bp9xeTmX.js';
+import { a as DependencyGraph, V as VM, D as DagSnapshot, b as EngineContext, S as ScopeManager, P as PluginFunctionHandler } from './ScopeManager-C2LDOrDx.js';
+import { a as BytecodeProgram } from './BytecodeBuilder-DGGeByAP.js';
 import { QueryClient } from '@tanstack/query-core';
-import { E as EngineError } from './EngineError-CNA_rHY-.js';
-import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-D-PS9gVw.js';
+import { E as EngineError } from './EngineError-Ce1lPkjZ.js';
+import { a as DiagnosticReportJSON, D as DiagnosticPipeline } from './pipeline-72QmQlGx.js';
 import { T as Token } from './Token-CbP_OutD.js';
-import { D as DEFAULT_CONFIG, E as EngineConfig } from './Configuration-C9W8tJv_.js';
+import { E as EngineConfigOverride, a as EngineConfig } from './Configuration-B6W0-T67.js';
 
 /**
  * One line's compiled bytecode, plus the variables it reads and writes.
@@ -1444,15 +1443,16 @@ interface EngineRestoreOptions {
      * Packages to register on the restored engine. This MUST be the same set
      * the snapshot was taken with: a snapshot carries compiled bytecode whose
      * plugin-function indices and parselet-produced opcodes only line up
-     * against the packages that were present when it was written. Defaults to
-     * {@link BUILTIN_PACKAGES}, exactly like the constructor's own `packages`
-     * parameter, so a host using the default package set needs to pass nothing.
+     * against the packages that were present when it was written. Registers no
+     * packages when omitted, exactly like the constructor's own `packages`
+     * parameter, so a host that snapshotted a full engine passes the same
+     * `BUILTIN_PACKAGES` here that it constructed with.
      */
     packages?: IEnginePackage[];
     /** Config overrides, merged over `DEFAULT_CONFIG`, as in the constructor. */
-    config?: Partial<typeof DEFAULT_CONFIG>;
-    /** Turn on the diagnostic pipeline, as in the constructor's `diagnosticMode`. */
-    diagnosticMode?: boolean;
+    config?: EngineConfigOverride;
+    /** Turn on the diagnostic pipeline, as in the constructor's `diagnostics`. */
+    diagnostics?: boolean;
     /**
      * Override the locale the snapshot recorded. Rarely needed: the snapshot's
      * own {@link EngineSnapshot.locale} is used by default, so a restored engine
@@ -1461,17 +1461,23 @@ interface EngineRestoreOptions {
     locale?: string;
 }
 /**
- * Return type of {@link evaluateLine} and {@link evaluateExpression}.
+ * Options for constructing an {@link ExpressionEngine}. Every field is optional.
  *
- * A single-element `Value[]`, kept as an array (rather than a bare
- * `Value`) for API stability.
+ * An engine registers exactly the {@link EngineOptions.packages} it is given, so
+ * a bundler can tree-shake away every built-in a consumer never imports; pass
+ * `BUILTIN_PACKAGES` (from `solve-engine/packages`) for the full set, a subset
+ * for a slimmer engine, or use {@link createEngine} for the batteries-included
+ * convenience.
  */
-interface EvalResults extends Array<Value> {
-}
-/** Explicit result of {@link ExpressionEngine.evaluateLineDetailed}. */
-interface LineEvaluation {
-    /** The evaluated value, wrapped in a single-element array. */
-    values: Value[];
+interface EngineOptions {
+    /** BCP-47 locale. Defaults to `"en"`. */
+    locale?: string;
+    /** Packages to register. None when omitted, so nothing but what you pass is bundled. */
+    packages?: IEnginePackage[];
+    /** Config overrides, merged per section over {@link DEFAULT_CONFIG}. */
+    config?: EngineConfigOverride;
+    /** Turn on the diagnostic pipeline (per-stage timing and detail). Defaults to `false`. */
+    diagnostics?: boolean;
 }
 /**
  * Core expression evaluation engine, the top-level orchestrator.
@@ -1511,13 +1517,26 @@ interface LineEvaluation {
  * is the intended usage. Reusing a single engine across documents is also fine:
  * `clear()` resets it for the next one rather than consuming it.
  *
+ * The constructor registers only the packages it is given, so a consumer's
+ * bundler can tree-shake away every built-in they do not use. For the common
+ * "I want everything" case, {@link createEngine} registers the full built-in
+ * set in one call; pass an explicit package list to the constructor when
+ * bundle size matters.
+ *
  * @example
  * ```typescript
- * import { ExpressionEngine } from "solve-engine";
- * const engine = new ExpressionEngine("en");
- * const [value] = engine.evaluateExpression("2 + 2 * 10");
+ * import { createEngine } from "solve-engine";
+ * const engine = createEngine(); // every built-in package
+ * const value = engine.evaluateExpression("2 + 2 * 10");
  * console.log(value.toNumber()); // 22
  * ```
+ * @example
+ * ```typescript
+ * // A slimmer engine: only arithmetic and units reach the bundle.
+ * import { ExpressionEngine } from "solve-engine";
+ * import { ARITHMETIC_PACKAGE, UOM_PACKAGE } from "solve-engine/packages";
+ * const engine = new ExpressionEngine({ packages: [ARITHMETIC_PACKAGE, UOM_PACKAGE] });
+ * ```
  */
 declare class ExpressionEngine {
     private dag;
@@ -1557,8 +1576,8 @@ declare class ExpressionEngine {
     /** Registry of async resolvers from registered packages. */
     private resolverRegistry;
     /**
-     * Per-package record of contributions made to the SHARED registries
-     * (this engine's variable resolver / resolver namespaces), so
+     * Per-package record of contributions made to the engine's registries
+     * (plugin functions, resolver namespaces, token categories), so
      * {@link unregisterPackage} can reverse them. Keyed by package name.
      */
     private packageContributions;
@@ -1689,10 +1708,11 @@ declare class ExpressionEngine {
      * the bytecode-cache benefit on re-evaluation regardless of config.
      */
     private cacheBytecode;
+    private pluginFunctionIndexByName;
     private builderPool;
     private builderPoolIndex;
     private lastTelemetry;
-    constructor(localeCode?: string, diagnosticMode?: boolean, config?: Partial<typeof DEFAULT_CONFIG>, diagnosticPipeline?: DiagnosticPipeline, packages?: IEnginePackage[]);
+    constructor(options?: EngineOptions);
     /**
      * Get the native event stream from the batcher for stream-based consumers.
      *
@@ -1724,7 +1744,6 @@ declare class ExpressionEngine {
      * - `lexerVocabulary` → engine's isolated lexer (via this.lexer.registerVocabulary)
      * - `prefixParselets` → engine's isolated ParseletRegistry
      * - `infixParselets` → engine's isolated ParseletRegistry
-     * - `variableSources` → this engine's own variable resolver
      *
      * Built-in packages (ARITHMETIC, FUNCTION, UOM, etc.) are registered
      * via this method during construction. External user packages can also
@@ -2197,8 +2216,8 @@ declare class ExpressionEngine {
      * compile-only callers. NOT used by `evaluateLine()`/
      * `evaluateExpression()`, those route through
      * {@link evaluateExpressionWithDiagnostic} instead (evaluateLine ->
-     * evaluateLineDetailed -> evaluateLineWithDebug ->
-     * evaluateExpressionWithDiagnostic), which does its own lexing and its
+     * evaluateLineWithDebug -> evaluateExpressionWithDiagnostic), which does
+     * its own lexing and its
      * own diagnostic-instrumented front-half, delegating to the SAME
      * {@link prepareExpression} this method calls. Delegates the front-half
      * to {@link prepareExpression}, then runs async preflight (via
@@ -2210,16 +2229,10 @@ declare class ExpressionEngine {
      *
      * @param lineNumber - 1-based line position in the document.
      * @param lineText - The raw line text.
-     * @returns The evaluated Value, wrapped in a single-element array.
-     * @throws {EngineError} On evaluation failure.
-     */
-    evaluateLine(lineNumber: number, lineText: string): EvalResults;
-    /**
-     * Evaluate a line and return an explicit `{ values }` object.
-     *
+     * @returns The evaluated {@link Value}.
      * @throws {EngineError} On evaluation failure.
      */
-    evaluateLineDetailed(lineNumber: number, lineText: string): LineEvaluation;
+    evaluateLine(lineNumber: number, lineText: string): Value;
     /**
      * Evaluate a line with diagnostic information, supporting both regular expressions and inline solves.
      *
@@ -2489,9 +2502,9 @@ declare class ExpressionEngine {
     getLastTelemetry(): PipelineTelemetry | null;
     /**
      * Evaluate a raw expression string without line-number context.
-     * Returns the Value result. Throws on error.
+     * Returns the {@link Value} result. Throws on error.
      */
-    evaluateExpression(expression: string): EvalResults;
+    evaluateExpression(expression: string): Value;
     /**
      * Explain how a line reached its answer, as a readable derivation.
      *
@@ -2609,15 +2622,25 @@ declare class ExpressionEngine {
      * Fast path: evaluate an expression and return a number directly.
      *
      * Skips Value object allocation when only a numeric result is needed.
-     * Returns NaN on error or for bare undefined variable references.
+     * Returns NaN whenever the expression has no numeric answer: a thrown
+     * error, a bare undefined variable reference, or a faulted result (an
+     * Error or a Pending value).
      *
      * Performs a pre-check for bare identifiers (single-token variable
      * references). If the identifier is not a known variable, returns NaN
      * immediately without attempting evaluation, avoids the ambiguity of
      * "result === 0" when a variable might legitimately store the value 0.
      *
+     * A faulted result is treated the same way, and for the same reason: an
+     * Error or Pending reads as 0 through {@link Value.toNumber}, so returning
+     * that 0 would be indistinguishable from a real zero. NaN is this fast
+     * path's established "no value" signal, so `evaluateNumber("5 kg to m")`
+     * (an impossible conversion) is NaN rather than a silent `0`. A caller that
+     * needs the fault's detail should use {@link evaluateExpression} and read
+     * {@link Value.errorCode}/{@link Value.isPending} off the result.
+     *
      * @param expression - The raw expression string to evaluate.
-     * @returns The numeric result, or NaN on error/undefined variable.
+     * @returns The numeric result, or NaN on error / undefined variable / fault.
      */
     evaluateNumber(expression: string): number;
     clear(): void;
@@ -2903,50 +2926,25 @@ declare class LanguageService {
     invalidateCache(): void;
 }
 
-/**
- * Public API for registering plugins with the solve-js engine.
- *
- * All registration goes through this interface, parselets, variable
- * sources, and full packages. The default implementation is
- * {@link PackageRegistry} (singleton via {@link packageRegistry}).
- *
- * @example
- * ```typescript
- * import { packageRegistry } from "solve-engine";
- * packageRegistry.registerPackage(myCustomPackage);
- * ```
- */
-interface IPackageRegistry {
-    /** Register a prefix parselet (e.g., `GE`, `NOW`, `floor`). */
-    registerPrefixParselet(tokenType: string, parselet: PrefixParselet): void;
-    /** Register an infix parselet (e.g., `+`, `in`, `to`). */
-    registerInfixParselet(tokenType: string, parselet: InfixParselet): void;
-    /** @deprecated Has no effect. See {@link IEnginePackage.variableSources}. */
-    registerVariableSource(source: IVariableSource): void;
-    /** Register a complete package (parselets + variable sources). */
-    registerPackage(pkg: IEnginePackage): void;
-    /** Convenience reference to the Value class for creating typed values. */
-    Value: typeof Value;
-}
 /**
  * Package descriptor for registering a complete provider with the engine.
  *
  * A package bundles all the pieces needed for a domain-specific provider:
  * lexer plugins for custom token recognition, parselets for Pratt parsing,
- * plugin functions dispatched via CALL_PLUGIN bytecode, variable sources,
- * and optional async resolvers for data that loads asynchronously (e.g.,
- * exchange rates, game prices).
+ * plugin functions dispatched via CALL_PLUGIN bytecode, and optional async
+ * resolvers for data that loads asynchronously (e.g., exchange rates, game
+ * prices).
  *
  * @example
  * ```typescript
  * const myPackage: IEnginePackage = {
  *   name: "MyProvider",
  *   lexerVocabulary: myLexerVocabulary,
- *   prefixParselets: [{ tokenType: "MY_FUNC", parselet: new MyParselet() }],
- *   pluginFunctions: [{ index: MY_FN_IDX, handler: myHandler }],
+ *   prefixParselets: { MY_FUNC: new MyParselet() },
+ *   pluginFunctions: { myFn: myHandler },
  *   asyncResolvers: [myAsyncResolver],
  * };
- * packageRegistry.registerPackage(myPackage);
+ * const engine = createEngine({ extraPackages: [myPackage] });
  * ```
  */
 interface IEnginePackage {
@@ -2973,59 +2971,30 @@ interface IEnginePackage {
     engineVersion?: string;
     /** Optional lexer vocabulary (keywords/operators/units) for recognizing custom tokens (e.g., `GE`, `£`). */
     lexerVocabulary?: LexerVocabulary;
-    /** Prefix parselets for this package's custom functions/operators. */
-    prefixParselets?: Array<{
-        tokenType: string;
-        parselet: PrefixParselet;
-    }>;
-    /** Infix parselets for this package's custom binary operators. */
-    infixParselets?: Array<{
-        tokenType: string;
-        parselet: InfixParselet;
-    }>;
-    /**
-     * Functions dispatched via CALL_PLUGIN bytecode (emitted by this package's
-     * parselets with `builder.emitIndex(index)`).
-     *
-     * Each entry's `index` MUST come from {@link allocatePluginFunctionIndex}
-     * (`@solve-js/vm/VMBuiltins`), never hardcode a number. Two packages
-     * independently picking the same index would silently overwrite each
-     * other's handler in the shared registry.
-     *
-     * The handler's optional second parameter, `context`, carries the
-     * current line's {@link LineExecutionContext} (line number, and, only
-     * inside a real document, never `evaluateExpression()`'s single-shot
-     * path, closures for reading another line's cached result). Every
-     * handler that doesn't need cross-line data can ignore it entirely.
+    /** Prefix parselets for this package's custom functions/operators, keyed by token type. */
+    prefixParselets?: Record<string, PrefixParselet>;
+    /** Infix parselets for this package's custom binary operators, keyed by token type. */
+    infixParselets?: Record<string, InfixParselet>;
+    /**
+     * Functions dispatched via `CALL_PLUGIN` bytecode, keyed by a package-local
+     * name. The engine assigns each a registry index at registration, so a
+     * parselet emits the call by that name (`builder.emitPluginCall(name, argCount)`)
+     * and never touches a numeric index. Two packages naming a function the same
+     * is a `checkPackageCompatibility` warning, the later registration wins.
+     *
+     * The handler's optional second parameter, `context`, carries the current
+     * line's `LineExecutionContext` (line number, and, only inside a real
+     * document, never `evaluateExpression()`'s single-shot path, closures for
+     * reading another line's cached result). Every handler that doesn't need
+     * cross-line data can ignore it entirely.
      *
      * @example
      * ```ts
-     * const MY_FN_IDX = allocatePluginFunctionIndex();
-     * // In a parselet's parse(): builder.emitOpcode(OpCode.CALL_PLUGIN); builder.emitIndex(MY_FN_IDX); builder.emitIndex(argCount);
-     * pluginFunctions: [{ index: MY_FN_IDX, handler: myHandler }]
+     * // In a parselet's parse(): builder.emitPluginCall("myFn", argCount);
+     * pluginFunctions: { myFn: myHandler }
      * ```
      */
-    pluginFunctions?: Array<{
-        index: number;
-        handler: (args: Value[], context?: LineExecutionContext) => Value | Promise<Value>;
-    }>;
-    /**
-     * Named-variable sources.
-     *
-     * @deprecated Currently has no effect. Sources declared here are registered
-     * into the engine's {@link EngineContext} and unregistered again on package
-     * removal, but no evaluation path ever calls `VariableResolver.resolve()`, so
-     * a variable a source provides is never found. Verified by searching every
-     * use of `IVariableSource` outside its own declaration: they are all
-     * registration bookkeeping.
-     *
-     * Declared here rather than deleted because removing a public field is a
-     * breaking change and the intended behaviour is worth keeping. Documented as
-     * dead so a package author does not spend an afternoon working out why their
-     * variables resolve to nothing. To expose a value today, contribute a plugin
-     * function through {@link IEnginePackage.pluginFunctions}.
-     */
-    variableSources?: IVariableSource[];
+    pluginFunctions?: Record<string, PluginFunctionHandler>;
     /**
      * Async resolvers for this package's domain.
      * When set, the ExpressionEngine runs preflight() before VM execution
@@ -3117,53 +3086,5 @@ interface IEnginePackage {
      */
     asConverters?: Record<string, (value: Value) => Value>;
 }
-/**
- * Default implementation of {@link IPackageRegistry}, the plugin registration API.
- *
- * All registrations delegate to shared singletons (parselet registry,
- * variable resolver, lexer). This ensures that packages registered through
- * any PackageRegistry instance are visible engine-wide.
- *
- * @example
- * ```typescript
- * import { packageRegistry } from "solve-engine";
- *
- * // Register a complete provider package
- * packageRegistry.registerPackage({
- *   name: "MyProvider",
- *   prefixParselets: [{ tokenType: "MY_FUNC", parselet: new MyParselet() }],
- * });
- * ```
- *
- * @deprecated Register on an engine instead:
- * `engine.registerPackage(pkg)`.
- *
- * This class writes into process-wide singletons, which is incompatible with an
- * engine owning its own registries. Since the introduction of
- * {@link EngineContext}, an engine reads plugin functions, opcode handlers and
- * variable sources from its own context, so a package registered here is not
- * visible to any engine. Parselets and lexer vocabulary registered here reach
- * the shared registries, which an engine also does not read: it builds its own
- * `ParseletRegistry` and its own `Lexer`.
- *
- * In other words this path registers into state nothing evaluates against. It
- * remains exported because removing it is a breaking change, and it is where
- * the singletons that survive are still written from, but it should not be used
- * in new code and will be removed before 1.0 proper.
- */
-declare class PackageRegistry implements IPackageRegistry {
-    Value: typeof Value;
-    registerPrefixParselet(tokenType: string, parselet: PrefixParselet): void;
-    registerInfixParselet(tokenType: string, parselet: InfixParselet): void;
-    registerVariableSource(source: IVariableSource): void;
-    registerPackage(pkg: IEnginePackage): void;
-}
-/**
- * Singleton PackageRegistry instance, the default plugin registration API.
- *
- * All packages should register through this instance. The underlying registries
- * are shared singletons, so multiple PackageRegistry instances would be redundant.
- */
-declare const packageRegistry: PackageRegistry;
 
-export { type ApplyChangesResult as A, type BatcherMetrics as B, type CacheSnapshot as C, DocumentModel as D, ExpressionEngine as E, type LineState as F, type LinesUpdatedEvent as G, type CompletionItem as H, type IEnginePackage as I, LanguageService as J, type LanguageServiceOptions as K, type LineEvaluation as L, type SemanticToken as M, type ParsedLine as N, type ParsingResult as O, PackageRegistry as P, SNAPSHOT_FORMAT as S, type UnifiedParsingOptions as U, type ViewportRange as V, type EngineRestoreOptions as a, type EngineSnapshot as b, type EvalResults as c, type Explanation as d, type ExplanationStep as e, type IPackageRegistry as f, SNAPSHOT_VERSION as g, type SerializedAnonymousBody as h, type SerializedBytecode as i, type SerializedDecimal as j, type SerializedLineCacheEntry as k, type SerializedNumber as l, type SerializedRational as m, type SerializedUserFunction as n, type SerializedValue as o, SnapshotErrorCodes as p, packageRegistry as q, type LineChange as r, type InlineSolvePosition as s, type AsyncCachePackageInfo as t, type AsyncErrorEvent as u, AsyncResolutionBatcher as v, type AsyncResolutionEvent as w, type BytecodeCacheEntry as x, type CheckpointSnapshot as y, type LineCacheEntryInfo as z };
+export { type ApplyChangesResult as A, type BatcherMetrics as B, type CacheSnapshot as C, DocumentModel as D, ExpressionEngine as E, LanguageService as F, type LanguageServiceOptions as G, type SemanticToken as H, type IEnginePackage as I, type ParsingResult as J, type LineChange as L, type ParsedLine as P, SNAPSHOT_FORMAT as S, type UnifiedParsingOptions as U, type ViewportRange as V, type EngineOptions as a, type EngineRestoreOptions as b, type EngineSnapshot as c, type Explanation as d, type ExplanationStep as e, SNAPSHOT_VERSION as f, type SerializedAnonymousBody as g, type SerializedBytecode as h, type SerializedDecimal as i, type SerializedLineCacheEntry as j, type SerializedNumber as k, type SerializedRational as l, type SerializedUserFunction as m, type SerializedValue as n, SnapshotErrorCodes as o, type InlineSolvePosition as p, type AsyncCachePackageInfo as q, type AsyncErrorEvent as r, AsyncResolutionBatcher as s, type AsyncResolutionEvent as t, type BytecodeCacheEntry as u, type CheckpointSnapshot as v, type LineCacheEntryInfo as w, type LineState as x, type LinesUpdatedEvent as y, type CompletionItem as z };