solve-engine 1.2.0 → 2.0.0

package/dist/index.d.ts

@@ -1,20 +1,19 @@
-import { I as IEnginePackage } from './PackageRegistry-DrCPQNyy.js';
-export { a as EngineRestoreOptions, b as EngineSnapshot, c as EvalResults, d as Explanation, e as ExplanationStep, E as ExpressionEngine, f as IPackageRegistry, L as LineEvaluation, P as PackageRegistry, S as SNAPSHOT_FORMAT, g as SNAPSHOT_VERSION, h as SerializedAnonymousBody, i as SerializedBytecode, j as SerializedDecimal, k as SerializedLineCacheEntry, l as SerializedNumber, m as SerializedRational, n as SerializedUserFunction, o as SerializedValue, p as SnapshotErrorCodes, q as packageRegistry } from './PackageRegistry-DrCPQNyy.js';
-export { a as CompatibilityConflict, b as CompatibilityConflictKind, C as CompatibilityReport, c as CompatibilitySeverity, d as checkPackageCompatibility } from './PackageCompatibility-Ceg5XdAp.js';
+import { I as IEnginePackage, a as EngineOptions, E as ExpressionEngine } from './PackageRegistry-DzeiWcv4.js';
+export { b as EngineRestoreOptions, c as EngineSnapshot, d as Explanation, e as ExplanationStep, S as SNAPSHOT_FORMAT, f as SNAPSHOT_VERSION, g as SerializedAnonymousBody, h as SerializedBytecode, i as SerializedDecimal, j as SerializedLineCacheEntry, k as SerializedNumber, l as SerializedRational, m as SerializedUserFunction, n as SerializedValue, o as SnapshotErrorCodes } from './PackageRegistry-DzeiWcv4.js';
+export { a as CompatibilityConflict, b as CompatibilityConflictKind, C as CompatibilityReport, c as CompatibilitySeverity, d as checkPackageCompatibility } from './PackageCompatibility-CIvq2MP5.js';
+export { E as EngineConfigOverride } from './Configuration-B6W0-T67.js';
 export { ENGINE_VERSION } from './constants.js';
-import './Parselet-Bhf7d0_W.js';
-import './BytecodeBuilder-Bp9xeTmX.js';
+import './Parselet-B-zoPrTa.js';
+import './BytecodeBuilder-DGGeByAP.js';
 import './Token-CbP_OutD.js';
-import './pipeline-D-PS9gVw.js';
-import './Value-DZNQ_PU7.js';
-import './variables.js';
+import './pipeline-72QmQlGx.js';
+import './Value-CCi_Eecs.js';
 import './Lexer-DKMlj7Sy.js';
 import './resolvers.js';
 import '@tanstack/query-core';
 import './TokenNormalizer-DCWdZjGz.js';
-import './ScopeManager-Bzq87GfA.js';
-import './EngineError-CNA_rHY-.js';
-import './Configuration-C9W8tJv_.js';
+import './ScopeManager-C2LDOrDx.js';
+import './EngineError-Ce1lPkjZ.js';
 
 /**
  * A higher-level, declarative way to contribute a single `name(args)`
@@ -88,16 +87,16 @@ declare const DefineFunctionErrorCodes: {
  *
  * This is the higher-level API from issue #102. It derives, from the
  * declaration alone, everything the low-level contract asks an author to write
- * by hand: a plugin function index ({@link allocatePluginFunctionIndex}), a
- * lexer keyword so the name tokenises, a call-syntax parselet emitting
- * `CALL_PLUGIN`, and a handler that checks arity and argument types (yielding
+ * by hand: a named plugin function (the engine assigns its `CALL_PLUGIN`
+ * index), a lexer keyword so the name tokenises, a call-syntax parselet emitting
+ * that call by name, and a handler that checks arity and argument types (yielding
  * the engine's own structured errors) before invoking `call` and wrapping its
  * result. Anything needing custom parsing keeps writing a raw parselet exactly
  * as before, this sits on top of that contract and does not change it.
  *
  * @example
  * ```ts
- * const engine = new ExpressionEngine("en", false, undefined, undefined, [
+ * const engine = new ExpressionEngine({ packages: [
  *   ...BUILTIN_PACKAGES,
  *   defineFunction({
  *     name: "vat",
@@ -105,7 +104,7 @@ declare const DefineFunctionErrorCodes: {
  *     returns: "number",
  *     call: (amount) => amount * 1.2,
  *   }),
- * ]);
+ * ] });
  * engine.evaluateExpression("vat(100)"); // 120
  * ```
  *
@@ -148,9 +147,9 @@ declare function defineFunction<const A extends readonly FunctionArg[], R extend
  * `checkPackageCompatibility()`'s "return a result, caller decides" shape,
  * and this codebase's own testing convention of asserting against plain
  * result objects rather than `toThrow()` for a pure function).
- * `assertEngineVersionCompatible()` is the thin throwing wrapper both
- * `ExpressionEngine.registerPackage()` and the `PackageRegistry` singleton
- * call as the very first thing they do. See `ARCHITECTURE.md` §5.3.
+ * `assertEngineVersionCompatible()` is the thin throwing wrapper
+ * `ExpressionEngine.registerPackage()` calls as the very first thing it
+ * does. See `ARCHITECTURE.md` §5.3.
  */
 type EngineVersionCheckResult = {
     compatible: true;
@@ -185,4 +184,37 @@ declare function checkEngineVersionCompatibility(pkg: IEnginePackage, engineVers
  */
 declare function assertEngineVersionCompatible(pkg: IEnginePackage, engineVersion?: string): void;
 
-export { DefineFunctionErrorCodes, type EngineVersionCheckResult, type FunctionArg, type FunctionSpec, type FunctionValueType, IEnginePackage, assertEngineVersionCompatible, checkEngineVersionCompatibility, defineFunction };
+/** Options for {@link createEngine}: the engine options, minus `packages` (the
+ *  built-in set is always registered), plus `extraPackages` to add your own. */
+interface CreateEngineOptions extends Omit<EngineOptions, "packages"> {
+    /** Packages to register ON TOP of the built-in set (e.g. an OSRS or stocks package). */
+    extraPackages?: IEnginePackage[];
+}
+/**
+ * A batteries-included {@link ExpressionEngine} with every built-in package
+ * registered.
+ *
+ * The constructor registers only the packages it is given, so a consumer's
+ * bundler can tree-shake away the built-ins they never use: an engine built
+ * with `new ExpressionEngine({ packages: [ARITHMETIC_PACKAGE] })` carries no
+ * finance, colour or weather code. This convenience is the opposite trade: it
+ * pulls the FULL built-in set (`BUILTIN_PACKAGES`) for the common "I want
+ * everything" case, so importing it defeats that tree-shaking. Reach for the
+ * constructor with an explicit package list when bundle size matters, and for
+ * `createEngine` when it does not.
+ *
+ * @param options - Engine options ({@link EngineOptions}) minus `packages`, plus
+ *   an optional `extraPackages` to register alongside the built-in set.
+ * @returns An engine with the built-in packages (and any extras) registered.
+ *
+ * @example
+ * ```typescript
+ * import { createEngine } from "solve-engine";
+ * const engine = createEngine();
+ * const value = engine.evaluateExpression("2 + 2 * 10");
+ * console.log(value.toNumber()); // 22
+ * ```
+ */
+declare function createEngine(options?: CreateEngineOptions): ExpressionEngine;
+
+export { type CreateEngineOptions, DefineFunctionErrorCodes, EngineOptions, type EngineVersionCheckResult, ExpressionEngine, type FunctionArg, type FunctionSpec, type FunctionValueType, IEnginePackage, assertEngineVersionCompatible, checkEngineVersionCompatibility, createEngine, defineFunction };

package/dist/index.js

@@ -1,279 +1,2 @@
-import './chunk-7JM3F4KL.js';
-import { assertEngineVersionCompatible } from './chunk-IJGOFP2J.js';
-export { ExpressionEngine, SNAPSHOT_FORMAT, SNAPSHOT_VERSION, SnapshotErrorCodes, assertEngineVersionCompatible, checkEngineVersionCompatibility, checkPackageCompatibility } from './chunk-IJGOFP2J.js';
-import { sharedParseletRegistry } from './chunk-AOH6UR2L.js';
-import './chunk-2RWAXT6O.js';
-import './chunk-3VGDNEE3.js';
-import './chunk-5ON7PUAZ.js';
-import './chunk-FD5ZZHEU.js';
-import './chunk-FE4RC37D.js';
-import './chunk-UF6JG5SG.js';
-import './chunk-YNIWOYW6.js';
-import './chunk-UKQHXPGW.js';
-import './chunk-TPOK3UNI.js';
-import { BindingPower } from './chunk-IQJGDZOP.js';
-import './chunk-L5YHV6BQ.js';
-import './chunk-3BOK2LDK.js';
-import './chunk-F4UB4XIL.js';
-import './chunk-NLNDMWZC.js';
-import { allocatePluginFunctionIndex } from './chunk-WMQRJTAO.js';
-import { sharedVariableResolver } from './chunk-GCM5JHMX.js';
-import './chunk-BSPXMGIS.js';
-import './chunk-BLI4NIQY.js';
-import './chunk-Z4X2RWOF.js';
-import './chunk-5HRB36DK.js';
-import './chunk-ZNFFTYWH.js';
-import { Value, boolValue, stringValue, numberValue } from './chunk-5EFKSKMA.js';
-import './chunk-MVTOCRV2.js';
-export { ENGINE_VERSION } from './chunk-CSDQMDU2.js';
-import { sharedLexer } from './chunk-RNKDIXDV.js';
-import './chunk-LSALB3IN.js';
-import './chunk-ORM7CHYZ.js';
-import './chunk-NAWZATKT.js';
-import './chunk-XBTEO4OB.js';
-import './chunk-SBUFNJVE.js';
-import './chunk-V4XG5QF6.js';
-import { ErrorFactory } from './chunk-N7OA4WPJ.js';
-import './chunk-YLJ4XMA6.js';
-
-// src/api/PackageRegistry.ts
-var PackageRegistry = class {
-  constructor() {
-    this.Value = Value;
-  }
-  registerPrefixParselet(tokenType, parselet) {
-    sharedParseletRegistry.registerPrefix(tokenType, parselet);
-  }
-  registerInfixParselet(tokenType, parselet) {
-    sharedParseletRegistry.registerInfix(tokenType, parselet);
-  }
-  registerVariableSource(source) {
-    sharedVariableResolver.registerSource(source);
-  }
-  registerPackage(pkg) {
-    assertEngineVersionCompatible(pkg);
-    if (pkg.lexerVocabulary) {
-      sharedLexer.registerVocabulary(pkg.lexerVocabulary);
-    }
-    if (pkg.prefixParselets) {
-      for (const pp of pkg.prefixParselets) {
-        this.registerPrefixParselet(pp.tokenType, pp.parselet);
-      }
-    }
-    if (pkg.infixParselets) {
-      for (const ip of pkg.infixParselets) {
-        this.registerInfixParselet(ip.tokenType, ip.parselet);
-      }
-    }
-    if (pkg.variableSources) {
-      for (const vs of pkg.variableSources) {
-        this.registerVariableSource(vs);
-      }
-    }
-  }
-};
-var packageRegistry = new PackageRegistry();
-
-// src/api/defineFunction.ts
-var DefineFunctionErrorCodes = {
-  /** The spec's `name` is not a single identifier. Thrown by `defineFunction`, before any engine sees it. */
-  DEFINE_FUNCTION_INVALID_NAME: "DEFINE_FUNCTION_INVALID_NAME",
-  /** The spec is otherwise malformed (bad `args`, unsupported type, missing `call`). Thrown by `defineFunction`. */
-  DEFINE_FUNCTION_INVALID_SPEC: "DEFINE_FUNCTION_INVALID_SPEC",
-  /** The call site passed the wrong number of arguments. Raised at evaluation time. */
-  DEFINE_FUNCTION_ARITY_MISMATCH: "DEFINE_FUNCTION_ARITY_MISMATCH",
-  /** An argument was the wrong value type. Raised at evaluation time. */
-  DEFINE_FUNCTION_ARGUMENT_TYPE: "DEFINE_FUNCTION_ARGUMENT_TYPE",
-  /** The `call` implementation returned a value that did not match `returns`. Raised at evaluation time, an authoring bug rather than a user one. */
-  DEFINE_FUNCTION_RETURN_TYPE: "DEFINE_FUNCTION_RETURN_TYPE"
-};
-var NAME_PATTERN = /^[a-z_][a-z0-9_]*$/i;
-var SUPPORTED_TYPES = /* @__PURE__ */ new Set(["number", "string", "boolean"]);
-function plural(count) {
-  return count === 1 ? "1 argument" : `${count} arguments`;
-}
-function describeValueType(v) {
-  switch (v.type) {
-    case 0 /* Number */:
-    case 1 /* Hex */:
-      return "a number";
-    case 3 /* String */:
-      return "a string";
-    case 10 /* Boolean */:
-      return "a boolean";
-    case 2 /* BigInt */:
-      return "a big integer";
-    case 5 /* Percentage */:
-      return "a percentage";
-    case 6 /* Uom */:
-      return "a value with a unit";
-    case 4 /* Datetime */:
-      return "a date";
-    case 7 /* Matrix */:
-      return "a matrix";
-    case 8 /* Range */:
-      return "a range";
-    case 9 /* Symbolic */:
-      return "a symbolic expression";
-    default:
-      return "an unsupported value";
-  }
-}
-function coerceArgument(value, arg, fnName) {
-  switch (arg.type) {
-    case "number":
-      if (value.type === 0 /* Number */ || value.type === 1 /* Hex */) {
-        return value.toNumber();
-      }
-      break;
-    case "string":
-      if (value.type === 3 /* String */) return value.value;
-      break;
-    case "boolean":
-      if (value.type === 10 /* Boolean */) return value.value;
-      break;
-  }
-  throw ErrorFactory.execution({
-    code: DefineFunctionErrorCodes.DEFINE_FUNCTION_ARGUMENT_TYPE,
-    message: `${fnName}() expects "${arg.name}" to be a ${arg.type}, but was given ${describeValueType(value)}`,
-    expected: `a ${arg.type}`,
-    found: describeValueType(value),
-    context: { functionName: fnName, argName: arg.name, expectedType: arg.type }
-  });
-}
-function wrapReturn(result, returns, fnName) {
-  switch (returns) {
-    case "number":
-      if (typeof result === "number") return numberValue(result);
-      break;
-    case "string":
-      if (typeof result === "string") return stringValue(result);
-      break;
-    case "boolean":
-      if (typeof result === "boolean") return boolValue(result);
-      break;
-  }
-  throw ErrorFactory.internal({
-    code: DefineFunctionErrorCodes.DEFINE_FUNCTION_RETURN_TYPE,
-    message: `${fnName}() is declared to return a ${returns}, but its implementation returned ${typeof result}`,
-    expected: `a ${returns}`,
-    found: typeof result,
-    context: { functionName: fnName, expectedType: returns }
-  });
-}
-var DefinedFunctionParselet = class {
-  constructor(fnIndex, fnName) {
-    this.fnIndex = fnIndex;
-    this.fnName = fnName;
-    this.category = "Function";
-  }
-  parse(parser, _token, builder) {
-    parser.consume("LPAREN");
-    let argCount = 0;
-    if (parser.peek()?.type !== "RPAREN") {
-      parser.parseExpression(BindingPower.Lowest, builder);
-      argCount++;
-      while (parser.match("COMMA")) {
-        parser.parseExpression(BindingPower.Lowest, builder);
-        argCount++;
-      }
-    }
-    parser.consume("RPAREN");
-    builder.emitOpcode(50 /* CALL_PLUGIN */);
-    builder.emitIndex(this.fnIndex);
-    builder.emitIndex(argCount);
-  }
-};
-function makeHandler(spec) {
-  const arity = spec.args.length;
-  return (args) => {
-    if (args.length !== arity) {
-      throw ErrorFactory.execution({
-        code: DefineFunctionErrorCodes.DEFINE_FUNCTION_ARITY_MISMATCH,
-        message: `${spec.name}() takes ${plural(arity)}, but was given ${args.length === 0 ? "none" : plural(args.length)}`,
-        expected: plural(arity),
-        found: args.length === 0 ? "none" : plural(args.length),
-        context: { functionName: spec.name, expected: arity, actual: args.length }
-      });
-    }
-    const jsArgs = new Array(arity);
-    for (let i = 0; i < arity; i++) {
-      jsArgs[i] = coerceArgument(args[i], spec.args[i], spec.name);
-    }
-    const result = spec.call(...jsArgs);
-    return wrapReturn(result, spec.returns, spec.name);
-  };
-}
-function validateSpec(spec) {
-  if (typeof spec?.name !== "string" || !NAME_PATTERN.test(spec.name)) {
-    throw ErrorFactory.config({
-      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_NAME,
-      message: `defineFunction: name must be a single identifier, got ${JSON.stringify(spec?.name)}`,
-      suggestion: 'e.g. "vat" or "net_price"',
-      context: { name: spec?.name }
-    });
-  }
-  if (!Array.isArray(spec.args)) {
-    throw ErrorFactory.config({
-      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,
-      message: `defineFunction: "${spec.name}" args must be an array`,
-      context: { name: spec.name }
-    });
-  }
-  for (const arg of spec.args) {
-    if (typeof arg?.name !== "string" || arg.name.length === 0) {
-      throw ErrorFactory.config({
-        code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,
-        message: `defineFunction: "${spec.name}" has an argument with no name`,
-        context: { name: spec.name }
-      });
-    }
-    if (!SUPPORTED_TYPES.has(arg.type)) {
-      throw ErrorFactory.config({
-        code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,
-        message: `defineFunction: "${spec.name}" argument "${arg.name}" has unsupported type ${JSON.stringify(arg.type)}`,
-        suggestion: "supported argument types are number, string, boolean",
-        context: { name: spec.name, argName: arg.name, type: arg.type }
-      });
-    }
-  }
-  if (!SUPPORTED_TYPES.has(spec.returns)) {
-    throw ErrorFactory.config({
-      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,
-      message: `defineFunction: "${spec.name}" has unsupported return type ${JSON.stringify(spec.returns)}`,
-      suggestion: "supported return types are number, string, boolean",
-      context: { name: spec.name, returns: spec.returns }
-    });
-  }
-  if (typeof spec.call !== "function") {
-    throw ErrorFactory.config({
-      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,
-      message: `defineFunction: "${spec.name}" is missing a call implementation`,
-      context: { name: spec.name }
-    });
-  }
-}
-function defineFunction(spec) {
-  validateSpec(spec);
-  const name = spec.name;
-  const tokenType = `DEFINE_FN_${name.toUpperCase()}`;
-  const index = allocatePluginFunctionIndex();
-  return {
-    name: `solve-fn-${name}`,
-    lexerVocabulary: {
-      // Lowercased because the lexer lowercases input before lookup, so the
-      // call is matched case-insensitively.
-      keywords: { [name.toLowerCase()]: tokenType }
-    },
-    prefixParselets: [
-      { tokenType, parselet: new DefinedFunctionParselet(index, name) }
-    ],
-    pluginFunctions: [
-      { index, handler: makeHandler(spec) }
-    ]
-  };
-}
-
-export { DefineFunctionErrorCodes, PackageRegistry, defineFunction, packageRegistry };
-//# sourceMappingURL=index.js.map
+import'./chunk-JSPKKNPQ.js';import'./chunk-RAF57WYO.js';import {n}from'./chunk-XR7HEC7B.js';export{n as ExpressionEngine,d as SNAPSHOT_FORMAT,e as SNAPSHOT_VERSION,f as SnapshotErrorCodes,c as assertEngineVersionCompatible,b as checkEngineVersionCompatibility,a as checkPackageCompatibility}from'./chunk-XR7HEC7B.js';import'./chunk-XNIWQHXY.js';import'./chunk-2RWAXT6O.js';import'./chunk-7GK3XEZF.js';import'./chunk-MIQBJGGR.js';import'./chunk-YJ2OPULK.js';import'./chunk-TWC7K3ZX.js';import'./chunk-J4LZD4ZY.js';import'./chunk-XEIDV5JP.js';import {y as y$1}from'./chunk-EYRBENHC.js';import'./chunk-6G3PMEPA.js';import'./chunk-6CY44ZPG.js';import {a}from'./chunk-YVKHEAFT.js';import'./chunk-QXQE7X4S.js';import'./chunk-76F3LCIL.js';import'./chunk-TCZSPH4A.js';import'./chunk-W2JAR233.js';import'./chunk-YAYBVVG2.js';import'./chunk-E6Z4NQAS.js';import'./chunk-HFKDWQUL.js';import'./chunk-R2ENWQ76.js';import'./chunk-RSF25YSJ.js';import {J,t,n as n$1}from'./chunk-EVAOPEO4.js';import'./chunk-WGZ3FNHI.js';export{a as ENGINE_VERSION}from'./chunk-L3FPQSGN.js';import'./chunk-GOIQYUWV.js';import'./chunk-JPFCXLJV.js';import'./chunk-UI6IFGBT.js';import'./chunk-IJMNVBIS.js';import'./chunk-62LMTO4F.js';import'./chunk-TRBXW6HW.js';import'./chunk-2JMFUQZH.js';import {c}from'./chunk-MPB7KUN5.js';var r={DEFINE_FUNCTION_INVALID_NAME:"DEFINE_FUNCTION_INVALID_NAME",DEFINE_FUNCTION_INVALID_SPEC:"DEFINE_FUNCTION_INVALID_SPEC",DEFINE_FUNCTION_ARITY_MISMATCH:"DEFINE_FUNCTION_ARITY_MISMATCH",DEFINE_FUNCTION_ARGUMENT_TYPE:"DEFINE_FUNCTION_ARGUMENT_TYPE",DEFINE_FUNCTION_RETURN_TYPE:"DEFINE_FUNCTION_RETURN_TYPE"},b=/^[a-z_][a-z0-9_]*$/i,y=new Set(["number","string","boolean"]);function u(e){return e===1?"1 argument":`${e} arguments`}function f(e){switch(e.type){case 0:case 1:return "a number";case 3:return "a string";case 10:return "a boolean";case 2:return "a big integer";case 5:return "a percentage";case 6:return "a value with a unit";case 4:return "a date";case 7:return "a matrix";case 8:return "a range";case 9:return "a symbolic expression";default:return "an unsupported value"}}function A(e,n,t){switch(n.type){case "number":if(e.type===0||e.type===1)return e.toNumber();break;case "string":if(e.type===3)return e.value;break;case "boolean":if(e.type===10)return e.value;break}throw c.execution({code:r.DEFINE_FUNCTION_ARGUMENT_TYPE,message:`${t}() expects "${n.name}" to be a ${n.type}, but was given ${f(e)}`,expected:`a ${n.type}`,found:f(e),context:{functionName:t,argName:n.name,expectedType:n.type}})}function S(e,n,t$1){switch(n){case "number":if(typeof e=="number")return n$1(e);break;case "string":if(typeof e=="string")return t(e);break;case "boolean":if(typeof e=="boolean")return J(e);break}throw c.internal({code:r.DEFINE_FUNCTION_RETURN_TYPE,message:`${t$1}() is declared to return a ${n}, but its implementation returned ${typeof e}`,expected:`a ${n}`,found:typeof e,context:{functionName:t$1,expectedType:n}})}var p=class{constructor(n){this.fnName=n;this.category="Function";}parse(n,t,i){n.consume("LPAREN");let a$1=0;if(n.peek()?.type!=="RPAREN")for(n.parseExpression(a.Lowest,i),a$1++;n.match("COMMA");)n.parseExpression(a.Lowest,i),a$1++;n.consume("RPAREN"),i.emitPluginCall(this.fnName,a$1);}};function P(e){let n=e.args.length;return t=>{if(t.length!==n)throw c.execution({code:r.DEFINE_FUNCTION_ARITY_MISMATCH,message:`${e.name}() takes ${u(n)}, but was given ${t.length===0?"none":u(t.length)}`,expected:u(n),found:t.length===0?"none":u(t.length),context:{functionName:e.name,expected:n,actual:t.length}});let i=new Array(n);for(let s=0;s<n;s++)i[s]=A(t[s],e.args[s],e.name);let a=e.call(...i);return S(a,e.returns,e.name)}}function V(e){if(typeof e?.name!="string"||!b.test(e.name))throw c.config({code:r.DEFINE_FUNCTION_INVALID_NAME,message:`defineFunction: name must be a single identifier, got ${JSON.stringify(e?.name)}`,suggestion:'e.g. "vat" or "net_price"',context:{name:e?.name}});if(!Array.isArray(e.args))throw c.config({code:r.DEFINE_FUNCTION_INVALID_SPEC,message:`defineFunction: "${e.name}" args must be an array`,context:{name:e.name}});for(let n of e.args){if(typeof n?.name!="string"||n.name.length===0)throw c.config({code:r.DEFINE_FUNCTION_INVALID_SPEC,message:`defineFunction: "${e.name}" has an argument with no name`,context:{name:e.name}});if(!y.has(n.type))throw c.config({code:r.DEFINE_FUNCTION_INVALID_SPEC,message:`defineFunction: "${e.name}" argument "${n.name}" has unsupported type ${JSON.stringify(n.type)}`,suggestion:"supported argument types are number, string, boolean",context:{name:e.name,argName:n.name,type:n.type}})}if(!y.has(e.returns))throw c.config({code:r.DEFINE_FUNCTION_INVALID_SPEC,message:`defineFunction: "${e.name}" has unsupported return type ${JSON.stringify(e.returns)}`,suggestion:"supported return types are number, string, boolean",context:{name:e.name,returns:e.returns}});if(typeof e.call!="function")throw c.config({code:r.DEFINE_FUNCTION_INVALID_SPEC,message:`defineFunction: "${e.name}" is missing a call implementation`,context:{name:e.name}})}function O(e){V(e);let n=e.name,t=`DEFINE_FN_${n.toUpperCase()}`;return {name:`solve-fn-${n}`,lexerVocabulary:{keywords:{[n.toLowerCase()]:t}},prefixParselets:{[t]:new p(n)},pluginFunctions:{[n]:P(e)}}}function h(e={}){let{extraPackages:n$1=[],...t}=e;return new n({...t,packages:n$1.length>0?[...y$1,...n$1]:y$1})}export{r as DefineFunctionErrorCodes,h as createEngine,O as defineFunction};//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/api/PackageRegistry.ts","../src/api/defineFunction.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { sharedParseletRegistry } from \"@solve-js/parser/registry/ParseletRegistry\";\nimport { PrefixParselet, InfixParselet } from \"@solve-js/parser/Parselet\";\nimport { Value } from \"@solve-js/vm/Value\";\nimport { IVariableSource } from \"@solve-js/variables/IVariableSource\";\nimport { sharedVariableResolver } from \"@solve-js/variables/VariableResolver\";\nimport { sharedLexer } from \"@solve-js/lexer/Lexer\";\nimport type { LexerVocabulary } from \"@solve-js/lexer/ExpressionLexer\";\nimport type { IAsyncResolver } from \"@solve-js/resolvers/ResolverRegistry\";\nimport type { NormalizerRule } from \"@solve-js/normalizer/NormalizerRule\";\nimport type { TokenCategory } from \"@solve-js/language/TokenCategory\";\nimport type { CompletionItem } from \"@solve-js/language/LanguageService\";\nimport type { LineExecutionContext } from \"@solve-js/vm/VM\";\nimport { assertEngineVersionCompatible } from \"./EngineVersionCompatibility\";\n\n/**\n * Public API for registering plugins with the solve-js engine.\n *\n * All registration goes through this interface, parselets, variable\n * sources, and full packages. The default implementation is\n * {@link PackageRegistry} (singleton via {@link packageRegistry}).\n *\n * @example\n * ```typescript\n * import { packageRegistry } from \"solve-engine\";\n * packageRegistry.registerPackage(myCustomPackage);\n * ```\n */\nexport interface IPackageRegistry {\n  /** Register a prefix parselet (e.g., `GE`, `NOW`, `floor`). */\n  registerPrefixParselet(tokenType: string, parselet: PrefixParselet): void;\n  /** Register an infix parselet (e.g., `+`, `in`, `to`). */\n  registerInfixParselet(tokenType: string, parselet: InfixParselet): void;\n  /** @deprecated Has no effect. See {@link IEnginePackage.variableSources}. */\n  registerVariableSource(source: IVariableSource): void;\n  /** Register a complete package (parselets + variable sources). */\n  registerPackage(pkg: IEnginePackage): void;\n  /** Convenience reference to the Value class for creating typed values. */\n  Value: typeof Value;\n}\n\n/**\n * Package descriptor for registering a complete provider with the engine.\n *\n * A package bundles all the pieces needed for a domain-specific provider:\n * lexer plugins for custom token recognition, parselets for Pratt parsing,\n * plugin functions dispatched via CALL_PLUGIN bytecode, variable sources,\n * and optional async resolvers for data that loads asynchronously (e.g.,\n * exchange rates, game prices).\n *\n * @example\n * ```typescript\n * const myPackage: IEnginePackage = {\n *   name: \"MyProvider\",\n *   lexerVocabulary: myLexerVocabulary,\n *   prefixParselets: [{ tokenType: \"MY_FUNC\", parselet: new MyParselet() }],\n *   pluginFunctions: [{ index: MY_FN_IDX, handler: myHandler }],\n *   asyncResolvers: [myAsyncResolver],\n * };\n * packageRegistry.registerPackage(myPackage);\n * ```\n */\nexport interface IEnginePackage {\n  /** Human-readable name for debugging and error attribution. */\n  name: string;\n  /**\n   * Semver range of `solve-engine` versions this package is compatible with\n   * (e.g. `\"^0.1.0\"`, `\">=0.1.0 <0.3.0\"`), checked against the engine's own\n   * running version ({@link ENGINE_VERSION}, `@solve-js/constants/version`)\n   * via `checkEngineVersionCompatibility()`/`assertEngineVersionCompatible()`\n   * (`@solve-js/api/EngineVersionCompatibility`) at registration time.\n   *\n   * Optional, omitted means \"no declared constraint,\" so every package\n   * that predates this field (all built-ins, `examples/osrs`) keeps\n   * registering exactly as before.\n   *\n   * Unlike every other compatibility signal in this codebase (e.g.\n   * `checkPackageCompatibility()`'s sibling-package collision warnings,\n   * which always log and proceed. See `api/PackageCompatibility.ts`), a\n   * declared `engineVersion` range the running engine does NOT satisfy is\n   * a deliberate, hard REJECTION: `registerPackage()` throws rather than\n   * warning. See `ARCHITECTURE.md` §5.3.\n   */\n  engineVersion?: string;\n  /** Optional lexer vocabulary (keywords/operators/units) for recognizing custom tokens (e.g., `GE`, `£`). */\n  lexerVocabulary?: LexerVocabulary;\n  /** Prefix parselets for this package's custom functions/operators. */\n  prefixParselets?: Array<{ tokenType: string; parselet: PrefixParselet }>;\n  /** Infix parselets for this package's custom binary operators. */\n  infixParselets?: Array<{ tokenType: string; parselet: InfixParselet }>;\n  /**\n   * Functions dispatched via CALL_PLUGIN bytecode (emitted by this package's\n   * parselets with `builder.emitIndex(index)`).\n   *\n   * Each entry's `index` MUST come from {@link allocatePluginFunctionIndex}\n   * (`@solve-js/vm/VMBuiltins`), never hardcode a number. Two packages\n   * independently picking the same index would silently overwrite each\n   * other's handler in the shared registry.\n   *\n   * The handler's optional second parameter, `context`, carries the\n   * current line's {@link LineExecutionContext} (line number, and, only\n   * inside a real document, never `evaluateExpression()`'s single-shot\n   * path, closures for reading another line's cached result). Every\n   * handler that doesn't need cross-line data can ignore it entirely.\n   *\n   * @example\n   * ```ts\n   * const MY_FN_IDX = allocatePluginFunctionIndex();\n   * // In a parselet's parse(): builder.emitOpcode(OpCode.CALL_PLUGIN); builder.emitIndex(MY_FN_IDX); builder.emitIndex(argCount);\n   * pluginFunctions: [{ index: MY_FN_IDX, handler: myHandler }]\n   * ```\n   */\n  pluginFunctions?: Array<{ index: number; handler: (args: Value[], context?: LineExecutionContext) => Value | Promise<Value> }>;\n  /**\n   * Named-variable sources.\n   *\n   * @deprecated Currently has no effect. Sources declared here are registered\n   * into the engine's {@link EngineContext} and unregistered again on package\n   * removal, but no evaluation path ever calls `VariableResolver.resolve()`, so\n   * a variable a source provides is never found. Verified by searching every\n   * use of `IVariableSource` outside its own declaration: they are all\n   * registration bookkeeping.\n   *\n   * Declared here rather than deleted because removing a public field is a\n   * breaking change and the intended behaviour is worth keeping. Documented as\n   * dead so a package author does not spend an afternoon working out why their\n   * variables resolve to nothing. To expose a value today, contribute a plugin\n   * function through {@link IEnginePackage.pluginFunctions}.\n   */\n  variableSources?: IVariableSource[];\n  /**\n   * Async resolvers for this package's domain.\n   * When set, the ExpressionEngine runs preflight() before VM execution\n   * for each resolver. If async data is needed, a Pending result is\n   * returned immediately and the line re-evaluates when the data resolves.\n   *\n   * Each resolver must have a unique `namespace`, the ResolverRegistry\n   * is keyed by namespace. Multiple resolvers let a package handle\n   * distinct async operations (e.g., `fetch`, `wait`, `poll`) in\n   * separate, focused classes rather than one monolithic preflight().\n   */\n  asyncResolvers?: IAsyncResolver[];\n  /**\n   * Multi-word phrases to fuse into single compound tokens.\n   * Each key is a space-separated phrase (e.g., \"to the power of\"),\n   * each value is the target token type after fusion (e.g., \"CARET\").\n   *\n   * Registered into the engine's {@link PhraseTrie} for single-pass\n   * O(depth) matching, no separate rule scanning per phrase.\n   *\n   * @example\n   * ```ts\n   * phrases: {\n   *   \"to the power of\": \"CARET\",\n   *   \"abyssal whip\": \"ITEM\",\n   * }\n   * ```\n   */\n  phrases?: Record<string, string>;\n  /**\n   * Normalizer rules for post-lexer token transformation.\n   * Applied by the TokenNormalizer between lexing and parsing.\n   * For phrase fusion, prefer the declarative {@link phrases} field\n   * which uses the faster PhraseTrie. Use this for non-phrase rules\n   * like implicit operator insertion.\n   */\n  normalizerRules?: NormalizerRule[];\n  /**\n   * Semantic highlight categories for this package's custom token types\n   * (introduced via {@link lexerVocabulary} or {@link normalizerRules}), the\n   * plugin-facing half of solve-js's editor-agnostic language service (see\n   * `language/TokenCategoryMap.ts`). Without an entry here, a package's\n   * custom tokens (e.g. a game-item name fused from several identifiers)\n   * are still lexed and parsed correctly, but render with no highlight\n   * category in any editor integration.\n   *\n   * @example\n   * ```ts\n   * tokenCategories: { MY_KEYWORD: \"keyword\", MY_ITEM: \"my-plugin-item\" }\n   * ```\n   */\n  tokenCategories?: Record<string, TokenCategory>;\n  /**\n   * Completion candidates for this package, the plugin-facing half of\n   * solve-js's editor-agnostic completions API\n   * (`LanguageService.getCompletions()`). A package's single-word\n   * keywords (via {@link lexerVocabulary}) already flow into completions\n   * automatically; this field is for candidates that AREN'T lexer\n   * keywords, such as a vocabulary of item/entity names. A plain,\n   * pre-built list, not a callback, completion candidate lists are\n   * meant to be cheap and static within one engine configuration.\n   *\n   * @example\n   * ```ts\n   * completionItems: [{ label: \"Abyssal whip\", category: \"my-plugin-item\", detail: \"Item\" }]\n   * ```\n   */\n  completionItems?: CompletionItem[];\n  /**\n   * Custom `as <name>` converters, the extension point for the\n   * Converters package's general `<expr> as <type>` grammar (e.g.\n   * `50% as decimal`, `255 as hex`). The built-in converter names\n   * (`percent`, `decimal`, `hex`, `fraction`, `multiplier`, `sci`,\n   * `binary`, `octal`, ...) dispatch to dedicated fast opcodes; anything\n   * else, including any name a third-party package registers here\n   * resolves through `OpCode.CALL_AS_CONVERTER` against\n   * `vm/VMBuiltins.ts`'s `asConverterRegistry` at runtime. No lexer\n   * keyword registration is needed for a custom name: the AS parselet\n   * accepts any bare-word token after \"as\" and reads its raw text.\n   *\n   * Each handler is a pure, synchronous `(value: Value) => Value`, for\n   * async conversions (e.g. a live currency-style lookup), use\n   * {@link asyncResolvers} instead.\n   *\n   * @example\n   * ```ts\n   * asConverters: { roman: (v) => stringValue(toRomanNumeral(v.toNumber())) }\n   * ```\n   */\n  asConverters?: Record<string, (value: Value) => Value>;\n}\n\n/**\n * Default implementation of {@link IPackageRegistry}, the plugin registration API.\n *\n * All registrations delegate to shared singletons (parselet registry,\n * variable resolver, lexer). This ensures that packages registered through\n * any PackageRegistry instance are visible engine-wide.\n *\n * @example\n * ```typescript\n * import { packageRegistry } from \"solve-engine\";\n *\n * // Register a complete provider package\n * packageRegistry.registerPackage({\n *   name: \"MyProvider\",\n *   prefixParselets: [{ tokenType: \"MY_FUNC\", parselet: new MyParselet() }],\n * });\n * ```\n *\n * @deprecated Register on an engine instead:\n * `engine.registerPackage(pkg)`.\n *\n * This class writes into process-wide singletons, which is incompatible with an\n * engine owning its own registries. Since the introduction of\n * {@link EngineContext}, an engine reads plugin functions, opcode handlers and\n * variable sources from its own context, so a package registered here is not\n * visible to any engine. Parselets and lexer vocabulary registered here reach\n * the shared registries, which an engine also does not read: it builds its own\n * `ParseletRegistry` and its own `Lexer`.\n *\n * In other words this path registers into state nothing evaluates against. It\n * remains exported because removing it is a breaking change, and it is where\n * the singletons that survive are still written from, but it should not be used\n * in new code and will be removed before 1.0 proper.\n */\nexport class PackageRegistry implements IPackageRegistry {\n  Value = Value;\n\n  registerPrefixParselet(tokenType: string, parselet: PrefixParselet): void {\n    sharedParseletRegistry.registerPrefix(tokenType, parselet);\n  }\n\n  registerInfixParselet(tokenType: string, parselet: InfixParselet): void {\n    sharedParseletRegistry.registerInfix(tokenType, parselet);\n  }\n\n  registerVariableSource(source: IVariableSource): void {\n    sharedVariableResolver.registerSource(source);\n  }\n\n  registerPackage(pkg: IEnginePackage): void {\n    // Same hard engine-version gate ExpressionEngine.registerPackage() uses\n    // (see its own comment and ARCHITECTURE.md §5.3). This weaker\n    // shared-singleton path had no compatibility checking of any kind\n    // before this, so without this call the version gate would be\n    // trivially bypassable through this entry point.\n    assertEngineVersionCompatible(pkg);\n\n    if (pkg.lexerVocabulary) {\n      sharedLexer.registerVocabulary(pkg.lexerVocabulary);\n    }\n    if (pkg.prefixParselets) {\n      for (const pp of pkg.prefixParselets) {\n        this.registerPrefixParselet(pp.tokenType, pp.parselet);\n      }\n    }\n    if (pkg.infixParselets) {\n      for (const ip of pkg.infixParselets) {\n        this.registerInfixParselet(ip.tokenType, ip.parselet);\n      }\n    }\n    if (pkg.variableSources) {\n      for (const vs of pkg.variableSources) {\n        this.registerVariableSource(vs);\n      }\n    }\n    // Note: asyncResolvers are NOT registered here, the shared PackageRegistry singleton\n    // doesn't have a ResolverRegistry (that lives inside ExpressionEngine).\n    // Use ExpressionEngine.registerPackage() directly if you need async resolvers.\n  }\n}\n\n/**\n * Singleton PackageRegistry instance, the default plugin registration API.\n *\n * All packages should register through this instance. The underlying registries\n * are shared singletons, so multiple PackageRegistry instances would be redundant.\n */\nexport const packageRegistry = new PackageRegistry();\n","import type { IEnginePackage } from \"@solve-js/api/PackageRegistry\";\nimport type { PrefixParselet } from \"@solve-js/parser/Parselet\";\nimport type { Parser } from \"@solve-js/parser/Parser\";\nimport type { Token } from \"@solve-js/lexer/Token\";\nimport type { BytecodeBuilder } from \"@solve-js/parser/BytecodeBuilder\";\nimport { OpCode } from \"@solve-js/parser/OpCode\";\nimport { BindingPower } from \"@solve-js/parser/BindingPower\";\nimport { allocatePluginFunctionIndex } from \"@solve-js/vm/VMBuiltins\";\nimport {\n  Value,\n  ValueType,\n  numberValue,\n  stringValue,\n  boolValue,\n} from \"@solve-js/vm/Value\";\nimport { ErrorFactory } from \"@solve-js/errors/UnifiedErrorFramework\";\n\n/**\n * A higher-level, declarative way to contribute a single `name(args)`\n * function, sitting ON TOP OF the package contract rather than replacing it.\n *\n * The low-level contract (allocate a plugin function index, write a parselet,\n * emit `CALL_PLUGIN`) stays exactly as it was and remains the way to add\n * anything that needs custom parsing. This module derives that same wiring\n * from a declaration for the common case, a function called with parenthesised\n * arguments, so adding `vat(x)` costs a spec object rather than an\n * understanding of the parser and the VM. See `defineFunction`.\n */\n\n/** The value types a declared argument or return may take. */\nexport type FunctionValueType = \"number\" | \"string\" | \"boolean\";\n\n/** The JavaScript type a {@link FunctionValueType} maps to at the `call` boundary. */\ntype JsValue<T extends FunctionValueType> = T extends \"number\"\n  ? number\n  : T extends \"string\"\n    ? string\n    : boolean;\n\n/** One declared parameter: a name (for error messages) and a value type. */\nexport interface FunctionArg {\n  /** Parameter name, used only in the generated type-mismatch messages. */\n  name: string;\n  /** The value type this parameter accepts. */\n  type: FunctionValueType;\n}\n\n/** Map a tuple of {@link FunctionArg} specs to the tuple of JS values `call` receives. */\ntype CallArgs<A extends readonly FunctionArg[]> = {\n  [K in keyof A]: JsValue<A[K][\"type\"]>;\n};\n\n/**\n * A declarative function definition.\n *\n * `A` and `R` are inferred from the literal `args`/`returns` (via\n * `defineFunction`'s `const` type parameter), so `call`'s parameters and\n * return are typed from the declaration with no annotations: an\n * `{ type: \"number\" }` argument arrives as a `number`, and a `returns:\n * \"string\"` demands a `string` back.\n */\nexport interface FunctionSpec<\n  A extends readonly FunctionArg[] = readonly FunctionArg[],\n  R extends FunctionValueType = FunctionValueType,\n> {\n  /**\n   * The call name, a single identifier (`/^[a-z_][a-z0-9_]*$/i`). Registered\n   * as a lexer keyword, so it is matched case-insensitively and cannot collide\n   * with a built-in keyword (that collision throws at registration time).\n   */\n  name: string;\n  /** The parameters, in order. A fixed-length list: variadic and optional args are out of scope (see {@link defineFunction}). */\n  args: A;\n  /** The value type the function returns. */\n  returns: R;\n  /** The implementation, receiving plain JS values and returning one. Must be synchronous (see {@link defineFunction}). */\n  call: (...args: CallArgs<A>) => JsValue<R>;\n}\n\n/**\n * Error codes the declarative function API raises. Kept as a co-located const\n * (the convention `errors/ErrorCode.ts` documents for a domain's own codes) so\n * the strings have one source of truth.\n */\nexport const DefineFunctionErrorCodes = {\n  /** The spec's `name` is not a single identifier. Thrown by `defineFunction`, before any engine sees it. */\n  DEFINE_FUNCTION_INVALID_NAME: \"DEFINE_FUNCTION_INVALID_NAME\",\n  /** The spec is otherwise malformed (bad `args`, unsupported type, missing `call`). Thrown by `defineFunction`. */\n  DEFINE_FUNCTION_INVALID_SPEC: \"DEFINE_FUNCTION_INVALID_SPEC\",\n  /** The call site passed the wrong number of arguments. Raised at evaluation time. */\n  DEFINE_FUNCTION_ARITY_MISMATCH: \"DEFINE_FUNCTION_ARITY_MISMATCH\",\n  /** An argument was the wrong value type. Raised at evaluation time. */\n  DEFINE_FUNCTION_ARGUMENT_TYPE: \"DEFINE_FUNCTION_ARGUMENT_TYPE\",\n  /** The `call` implementation returned a value that did not match `returns`. Raised at evaluation time, an authoring bug rather than a user one. */\n  DEFINE_FUNCTION_RETURN_TYPE: \"DEFINE_FUNCTION_RETURN_TYPE\",\n} as const;\n\n/** A single identifier: a letter or underscore, then letters, digits, or underscores. */\nconst NAME_PATTERN = /^[a-z_][a-z0-9_]*$/i;\n\nconst SUPPORTED_TYPES: ReadonlySet<string> = new Set([\"number\", \"string\", \"boolean\"]);\n\n/** \"1 argument\" / \"2 arguments\", so a count reads as English either way. Mirrors `VMBuiltinArity.ts`. */\nfunction plural(count: number): string {\n  return count === 1 ? \"1 argument\" : `${count} arguments`;\n}\n\n/**\n * A human noun for the type a Value actually carries, for the \"was given ...\"\n * half of a mismatch message. Covers the three declarable types by their own\n * names and everything else by a readable category, so the message never reads\n * \"given a 6\".\n */\nfunction describeValueType(v: Value): string {\n  switch (v.type) {\n    case ValueType.Number:\n    case ValueType.Hex:\n      return \"a number\";\n    case ValueType.String:\n      return \"a string\";\n    case ValueType.Boolean:\n      return \"a boolean\";\n    case ValueType.BigInt:\n      return \"a big integer\";\n    case ValueType.Percentage:\n      return \"a percentage\";\n    case ValueType.Uom:\n      return \"a value with a unit\";\n    case ValueType.Datetime:\n      return \"a date\";\n    case ValueType.Matrix:\n      return \"a matrix\";\n    case ValueType.Range:\n      return \"a range\";\n    case ValueType.Symbolic:\n      return \"a symbolic expression\";\n    default:\n      return \"an unsupported value\";\n  }\n}\n\n/**\n * Read one runtime Value as the JS primitive its declared type promises, or\n * raise the engine's structured type error.\n *\n * A \"number\" accepts a plain number or a based literal (`0xFF`), both of which\n * ARE numbers written differently, and reads it with `toNumber()`. Nothing\n * else is coerced: a percentage, a unit-bearing value or a string is a\n * genuinely different kind of value, and silently reinterpreting it is the\n * class of wrong-answer this API exists to avoid.\n */\nfunction coerceArgument(\n  value: Value,\n  arg: FunctionArg,\n  fnName: string,\n): number | string | boolean {\n  switch (arg.type) {\n    case \"number\":\n      // Hex is a number in another base (see `hexValue`), so it reads as one here.\n      if (value.type === ValueType.Number || value.type === ValueType.Hex) {\n        return value.toNumber();\n      }\n      break;\n    case \"string\":\n      if (value.type === ValueType.String) return value.value as string;\n      break;\n    case \"boolean\":\n      if (value.type === ValueType.Boolean) return value.value as boolean;\n      break;\n  }\n  throw ErrorFactory.execution({\n    code: DefineFunctionErrorCodes.DEFINE_FUNCTION_ARGUMENT_TYPE,\n    message: `${fnName}() expects \"${arg.name}\" to be a ${arg.type}, but was given ${describeValueType(value)}`,\n    expected: `a ${arg.type}`,\n    found: describeValueType(value),\n    context: { functionName: fnName, argName: arg.name, expectedType: arg.type },\n  });\n}\n\n/**\n * Wrap the `call` result back into a Value of the declared return type, or\n * raise a structured error if the implementation handed back something else.\n *\n * The type check here catches an authoring mistake (a function declared to\n * return a number that returns `undefined`, or a Promise from an accidental\n * `async`), turning it into a named error rather than a Value that lies about\n * its own type downstream.\n */\nfunction wrapReturn(result: unknown, returns: FunctionValueType, fnName: string): Value {\n  switch (returns) {\n    case \"number\":\n      if (typeof result === \"number\") return numberValue(result);\n      break;\n    case \"string\":\n      if (typeof result === \"string\") return stringValue(result);\n      break;\n    case \"boolean\":\n      if (typeof result === \"boolean\") return boolValue(result);\n      break;\n  }\n  throw ErrorFactory.internal({\n    code: DefineFunctionErrorCodes.DEFINE_FUNCTION_RETURN_TYPE,\n    message: `${fnName}() is declared to return a ${returns}, but its implementation returned ${typeof result}`,\n    expected: `a ${returns}`,\n    found: typeof result,\n    context: { functionName: fnName, expectedType: returns },\n  });\n}\n\n/**\n * The call-syntax parselet generated for one declared function.\n *\n * Identical in shape to the built-in `FunctionCallParselet`: consume the open\n * paren, parse a comma-separated argument list, then emit `CALL_PLUGIN` with\n * the function's index and the argument count. The count is whatever was\n * written, arity is checked at the dispatch point (see {@link makeHandler}),\n * the same place the built-in arity check lives.\n */\nclass DefinedFunctionParselet implements PrefixParselet {\n  readonly category = \"Function\";\n\n  constructor(\n    private readonly fnIndex: number,\n    private readonly fnName: string,\n  ) {}\n\n  parse(parser: Parser, _token: Token, builder: BytecodeBuilder): void {\n    parser.consume(\"LPAREN\");\n\n    let argCount = 0;\n    if (parser.peek()?.type !== \"RPAREN\") {\n      parser.parseExpression(BindingPower.Lowest, builder);\n      argCount++;\n      while (parser.match(\"COMMA\")) {\n        parser.parseExpression(BindingPower.Lowest, builder);\n        argCount++;\n      }\n    }\n\n    parser.consume(\"RPAREN\");\n\n    builder.emitOpcode(OpCode.CALL_PLUGIN);\n    builder.emitIndex(this.fnIndex);\n    builder.emitIndex(argCount);\n  }\n}\n\n/**\n * Build the plugin function that checks arity and argument types, calls the\n * host implementation, and wraps the result.\n *\n * The VM has already screened out faulted arguments (an errored or still\n * pending operand short-circuits before the handler runs, see\n * `VM.ts`'s `CALL_PLUGIN` case), so every Value reaching here carries a real\n * result. Arity is checked first, before any argument is read, so a wrong\n * count is reported as a wrong count rather than as a type error on a missing\n * argument.\n */\nfunction makeHandler(spec: FunctionSpec): (args: Value[]) => Value {\n  const arity = spec.args.length;\n  return (args: Value[]): Value => {\n    if (args.length !== arity) {\n      throw ErrorFactory.execution({\n        code: DefineFunctionErrorCodes.DEFINE_FUNCTION_ARITY_MISMATCH,\n        message: `${spec.name}() takes ${plural(arity)}, but was given ${args.length === 0 ? \"none\" : plural(args.length)}`,\n        expected: plural(arity),\n        found: args.length === 0 ? \"none\" : plural(args.length),\n        context: { functionName: spec.name, expected: arity, actual: args.length },\n      });\n    }\n\n    const jsArgs: (number | string | boolean)[] = new Array(arity);\n    for (let i = 0; i < arity; i++) {\n      jsArgs[i] = coerceArgument(args[i], spec.args[i], spec.name);\n    }\n\n    const result = (spec.call as (...a: (number | string | boolean)[]) => unknown)(...jsArgs);\n    return wrapReturn(result, spec.returns, spec.name);\n  };\n}\n\n/** Reject a spec that could not produce a working function, before any engine sees it. */\nfunction validateSpec(spec: FunctionSpec): void {\n  if (typeof spec?.name !== \"string\" || !NAME_PATTERN.test(spec.name)) {\n    throw ErrorFactory.config({\n      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_NAME,\n      message: `defineFunction: name must be a single identifier, got ${JSON.stringify(spec?.name)}`,\n      suggestion: 'e.g. \"vat\" or \"net_price\"',\n      context: { name: spec?.name },\n    });\n  }\n  if (!Array.isArray(spec.args)) {\n    throw ErrorFactory.config({\n      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,\n      message: `defineFunction: \"${spec.name}\" args must be an array`,\n      context: { name: spec.name },\n    });\n  }\n  for (const arg of spec.args) {\n    if (typeof arg?.name !== \"string\" || arg.name.length === 0) {\n      throw ErrorFactory.config({\n        code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,\n        message: `defineFunction: \"${spec.name}\" has an argument with no name`,\n        context: { name: spec.name },\n      });\n    }\n    if (!SUPPORTED_TYPES.has(arg.type)) {\n      throw ErrorFactory.config({\n        code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,\n        message: `defineFunction: \"${spec.name}\" argument \"${arg.name}\" has unsupported type ${JSON.stringify(arg.type)}`,\n        suggestion: \"supported argument types are number, string, boolean\",\n        context: { name: spec.name, argName: arg.name, type: arg.type },\n      });\n    }\n  }\n  if (!SUPPORTED_TYPES.has(spec.returns)) {\n    throw ErrorFactory.config({\n      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,\n      message: `defineFunction: \"${spec.name}\" has unsupported return type ${JSON.stringify(spec.returns)}`,\n      suggestion: \"supported return types are number, string, boolean\",\n      context: { name: spec.name, returns: spec.returns },\n    });\n  }\n  if (typeof spec.call !== \"function\") {\n    throw ErrorFactory.config({\n      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,\n      message: `defineFunction: \"${spec.name}\" is missing a call implementation`,\n      context: { name: spec.name },\n    });\n  }\n}\n\n/**\n * Turn a declarative {@link FunctionSpec} into a ready-to-register\n * {@link IEnginePackage}.\n *\n * This is the higher-level API from issue #102. It derives, from the\n * declaration alone, everything the low-level contract asks an author to write\n * by hand: a plugin function index ({@link allocatePluginFunctionIndex}), a\n * lexer keyword so the name tokenises, a call-syntax parselet emitting\n * `CALL_PLUGIN`, and a handler that checks arity and argument types (yielding\n * the engine's own structured errors) before invoking `call` and wrapping its\n * result. Anything needing custom parsing keeps writing a raw parselet exactly\n * as before, this sits on top of that contract and does not change it.\n *\n * @example\n * ```ts\n * const engine = new ExpressionEngine(\"en\", false, undefined, undefined, [\n *   ...BUILTIN_PACKAGES,\n *   defineFunction({\n *     name: \"vat\",\n *     args: [{ name: \"amount\", type: \"number\" }],\n *     returns: \"number\",\n *     call: (amount) => amount * 1.2,\n *   }),\n * ]);\n * engine.evaluateExpression(\"vat(100)\"); // 120\n * ```\n *\n * The returned package is self-contained and composes with any others through\n * the engine's `packages` array; register several functions by passing several\n * packages. Its name is `solve-fn-<name>`.\n *\n * Scope: arguments are a fixed-length list of `number`/`string`/`boolean`, and\n * `call` is synchronous. Variadic and optional arguments, other value types\n * (units, percentages, dates, matrices), and async work are deliberately out\n * of scope, a function needing any of those keeps using the low-level\n * contract, whose parselets and async resolvers are unchanged.\n *\n * @throws {EngineError} (category CONFIG) if the spec is malformed, at the\n * point `defineFunction` is called, before the package reaches an engine.\n */\nexport function defineFunction<\n  const A extends readonly FunctionArg[],\n  R extends FunctionValueType,\n>(spec: FunctionSpec<A, R>): IEnginePackage {\n  validateSpec(spec as FunctionSpec);\n\n  const name = spec.name;\n  // Uppercased so the generated type is a valid, collision-resistant token\n  // type; the name pattern guarantees it forms one. Distinct from the\n  // built-in FUNC type, so this never routes through the builtin name map.\n  const tokenType = `DEFINE_FN_${name.toUpperCase()}`;\n  // Allocated at definition time (not module load), so importing this module\n  // consumes no index and the export stays side-effect free.\n  const index = allocatePluginFunctionIndex();\n\n  return {\n    name: `solve-fn-${name}`,\n    lexerVocabulary: {\n      // Lowercased because the lexer lowercases input before lookup, so the\n      // call is matched case-insensitively.\n      keywords: { [name.toLowerCase()]: tokenType },\n    },\n    prefixParselets: [\n      { tokenType, parselet: new DefinedFunctionParselet(index, name) },\n    ],\n    pluginFunctions: [\n      { index, handler: makeHandler(spec as FunctionSpec) },\n    ],\n  };\n}\n"]}
+{"version":3,"sources":["../src/api/defineFunction.ts","../src/api/createEngine.ts"],"names":["DefineFunctionErrorCodes","NAME_PATTERN","SUPPORTED_TYPES","plural","count","describeValueType","v","coerceArgument","value","arg","fnName","ErrorFactory","wrapReturn","result","returns","numberValue","stringValue","boolValue","DefinedFunctionParselet","parser","_token","builder","argCount","BindingPower","makeHandler","spec","arity","args","jsArgs","i","validateSpec","defineFunction","name","tokenType","createEngine","options","extraPackages","engineOptions","ExpressionEngine","BUILTIN_PACKAGES"],"mappings":"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","file":"index.js","sourcesContent":["import type { IEnginePackage } from \"@solve-js/api/PackageRegistry\";\nimport type { PrefixParselet } from \"@solve-js/parser/Parselet\";\nimport type { Parser } from \"@solve-js/parser/Parser\";\nimport type { Token } from \"@solve-js/lexer/Token\";\nimport type { BytecodeBuilder } from \"@solve-js/parser/BytecodeBuilder\";\nimport { BindingPower } from \"@solve-js/parser/BindingPower\";\nimport {\n  Value,\n  ValueType,\n  numberValue,\n  stringValue,\n  boolValue,\n} from \"@solve-js/vm/Value\";\nimport { ErrorFactory } from \"@solve-js/errors/UnifiedErrorFramework\";\n\n/**\n * A higher-level, declarative way to contribute a single `name(args)`\n * function, sitting ON TOP OF the package contract rather than replacing it.\n *\n * The low-level contract (allocate a plugin function index, write a parselet,\n * emit `CALL_PLUGIN`) stays exactly as it was and remains the way to add\n * anything that needs custom parsing. This module derives that same wiring\n * from a declaration for the common case, a function called with parenthesised\n * arguments, so adding `vat(x)` costs a spec object rather than an\n * understanding of the parser and the VM. See `defineFunction`.\n */\n\n/** The value types a declared argument or return may take. */\nexport type FunctionValueType = \"number\" | \"string\" | \"boolean\";\n\n/** The JavaScript type a {@link FunctionValueType} maps to at the `call` boundary. */\ntype JsValue<T extends FunctionValueType> = T extends \"number\"\n  ? number\n  : T extends \"string\"\n    ? string\n    : boolean;\n\n/** One declared parameter: a name (for error messages) and a value type. */\nexport interface FunctionArg {\n  /** Parameter name, used only in the generated type-mismatch messages. */\n  name: string;\n  /** The value type this parameter accepts. */\n  type: FunctionValueType;\n}\n\n/** Map a tuple of {@link FunctionArg} specs to the tuple of JS values `call` receives. */\ntype CallArgs<A extends readonly FunctionArg[]> = {\n  [K in keyof A]: JsValue<A[K][\"type\"]>;\n};\n\n/**\n * A declarative function definition.\n *\n * `A` and `R` are inferred from the literal `args`/`returns` (via\n * `defineFunction`'s `const` type parameter), so `call`'s parameters and\n * return are typed from the declaration with no annotations: an\n * `{ type: \"number\" }` argument arrives as a `number`, and a `returns:\n * \"string\"` demands a `string` back.\n */\nexport interface FunctionSpec<\n  A extends readonly FunctionArg[] = readonly FunctionArg[],\n  R extends FunctionValueType = FunctionValueType,\n> {\n  /**\n   * The call name, a single identifier (`/^[a-z_][a-z0-9_]*$/i`). Registered\n   * as a lexer keyword, so it is matched case-insensitively and cannot collide\n   * with a built-in keyword (that collision throws at registration time).\n   */\n  name: string;\n  /** The parameters, in order. A fixed-length list: variadic and optional args are out of scope (see {@link defineFunction}). */\n  args: A;\n  /** The value type the function returns. */\n  returns: R;\n  /** The implementation, receiving plain JS values and returning one. Must be synchronous (see {@link defineFunction}). */\n  call: (...args: CallArgs<A>) => JsValue<R>;\n}\n\n/**\n * Error codes the declarative function API raises. Kept as a co-located const\n * (the convention `errors/ErrorCode.ts` documents for a domain's own codes) so\n * the strings have one source of truth.\n */\nexport const DefineFunctionErrorCodes = {\n  /** The spec's `name` is not a single identifier. Thrown by `defineFunction`, before any engine sees it. */\n  DEFINE_FUNCTION_INVALID_NAME: \"DEFINE_FUNCTION_INVALID_NAME\",\n  /** The spec is otherwise malformed (bad `args`, unsupported type, missing `call`). Thrown by `defineFunction`. */\n  DEFINE_FUNCTION_INVALID_SPEC: \"DEFINE_FUNCTION_INVALID_SPEC\",\n  /** The call site passed the wrong number of arguments. Raised at evaluation time. */\n  DEFINE_FUNCTION_ARITY_MISMATCH: \"DEFINE_FUNCTION_ARITY_MISMATCH\",\n  /** An argument was the wrong value type. Raised at evaluation time. */\n  DEFINE_FUNCTION_ARGUMENT_TYPE: \"DEFINE_FUNCTION_ARGUMENT_TYPE\",\n  /** The `call` implementation returned a value that did not match `returns`. Raised at evaluation time, an authoring bug rather than a user one. */\n  DEFINE_FUNCTION_RETURN_TYPE: \"DEFINE_FUNCTION_RETURN_TYPE\",\n} as const;\n\n/** A single identifier: a letter or underscore, then letters, digits, or underscores. */\nconst NAME_PATTERN = /^[a-z_][a-z0-9_]*$/i;\n\nconst SUPPORTED_TYPES: ReadonlySet<string> = new Set([\"number\", \"string\", \"boolean\"]);\n\n/** \"1 argument\" / \"2 arguments\", so a count reads as English either way. Mirrors `VMBuiltinArity.ts`. */\nfunction plural(count: number): string {\n  return count === 1 ? \"1 argument\" : `${count} arguments`;\n}\n\n/**\n * A human noun for the type a Value actually carries, for the \"was given ...\"\n * half of a mismatch message. Covers the three declarable types by their own\n * names and everything else by a readable category, so the message never reads\n * \"given a 6\".\n */\nfunction describeValueType(v: Value): string {\n  switch (v.type) {\n    case ValueType.Number:\n    case ValueType.Hex:\n      return \"a number\";\n    case ValueType.String:\n      return \"a string\";\n    case ValueType.Boolean:\n      return \"a boolean\";\n    case ValueType.BigInt:\n      return \"a big integer\";\n    case ValueType.Percentage:\n      return \"a percentage\";\n    case ValueType.Uom:\n      return \"a value with a unit\";\n    case ValueType.Datetime:\n      return \"a date\";\n    case ValueType.Matrix:\n      return \"a matrix\";\n    case ValueType.Range:\n      return \"a range\";\n    case ValueType.Symbolic:\n      return \"a symbolic expression\";\n    default:\n      return \"an unsupported value\";\n  }\n}\n\n/**\n * Read one runtime Value as the JS primitive its declared type promises, or\n * raise the engine's structured type error.\n *\n * A \"number\" accepts a plain number or a based literal (`0xFF`), both of which\n * ARE numbers written differently, and reads it with `toNumber()`. Nothing\n * else is coerced: a percentage, a unit-bearing value or a string is a\n * genuinely different kind of value, and silently reinterpreting it is the\n * class of wrong-answer this API exists to avoid.\n */\nfunction coerceArgument(\n  value: Value,\n  arg: FunctionArg,\n  fnName: string,\n): number | string | boolean {\n  switch (arg.type) {\n    case \"number\":\n      // Hex is a number in another base (see `hexValue`), so it reads as one here.\n      if (value.type === ValueType.Number || value.type === ValueType.Hex) {\n        return value.toNumber();\n      }\n      break;\n    case \"string\":\n      if (value.type === ValueType.String) return value.value as string;\n      break;\n    case \"boolean\":\n      if (value.type === ValueType.Boolean) return value.value as boolean;\n      break;\n  }\n  throw ErrorFactory.execution({\n    code: DefineFunctionErrorCodes.DEFINE_FUNCTION_ARGUMENT_TYPE,\n    message: `${fnName}() expects \"${arg.name}\" to be a ${arg.type}, but was given ${describeValueType(value)}`,\n    expected: `a ${arg.type}`,\n    found: describeValueType(value),\n    context: { functionName: fnName, argName: arg.name, expectedType: arg.type },\n  });\n}\n\n/**\n * Wrap the `call` result back into a Value of the declared return type, or\n * raise a structured error if the implementation handed back something else.\n *\n * The type check here catches an authoring mistake (a function declared to\n * return a number that returns `undefined`, or a Promise from an accidental\n * `async`), turning it into a named error rather than a Value that lies about\n * its own type downstream.\n */\nfunction wrapReturn(result: unknown, returns: FunctionValueType, fnName: string): Value {\n  switch (returns) {\n    case \"number\":\n      if (typeof result === \"number\") return numberValue(result);\n      break;\n    case \"string\":\n      if (typeof result === \"string\") return stringValue(result);\n      break;\n    case \"boolean\":\n      if (typeof result === \"boolean\") return boolValue(result);\n      break;\n  }\n  throw ErrorFactory.internal({\n    code: DefineFunctionErrorCodes.DEFINE_FUNCTION_RETURN_TYPE,\n    message: `${fnName}() is declared to return a ${returns}, but its implementation returned ${typeof result}`,\n    expected: `a ${returns}`,\n    found: typeof result,\n    context: { functionName: fnName, expectedType: returns },\n  });\n}\n\n/**\n * The call-syntax parselet generated for one declared function.\n *\n * Identical in shape to the built-in `FunctionCallParselet`: consume the open\n * paren, parse a comma-separated argument list, then emit `CALL_PLUGIN` with\n * the function's index and the argument count. The count is whatever was\n * written, arity is checked at the dispatch point (see {@link makeHandler}),\n * the same place the built-in arity check lives.\n */\nclass DefinedFunctionParselet implements PrefixParselet {\n  readonly category = \"Function\";\n\n  constructor(\n    private readonly fnName: string,\n  ) {}\n\n  parse(parser: Parser, _token: Token, builder: BytecodeBuilder): void {\n    parser.consume(\"LPAREN\");\n\n    let argCount = 0;\n    if (parser.peek()?.type !== \"RPAREN\") {\n      parser.parseExpression(BindingPower.Lowest, builder);\n      argCount++;\n      while (parser.match(\"COMMA\")) {\n        parser.parseExpression(BindingPower.Lowest, builder);\n        argCount++;\n      }\n    }\n\n    parser.consume(\"RPAREN\");\n\n    builder.emitPluginCall(this.fnName, argCount);\n  }\n}\n\n/**\n * Build the plugin function that checks arity and argument types, calls the\n * host implementation, and wraps the result.\n *\n * The VM has already screened out faulted arguments (an errored or still\n * pending operand short-circuits before the handler runs, see\n * `VM.ts`'s `CALL_PLUGIN` case), so every Value reaching here carries a real\n * result. Arity is checked first, before any argument is read, so a wrong\n * count is reported as a wrong count rather than as a type error on a missing\n * argument.\n */\nfunction makeHandler(spec: FunctionSpec): (args: Value[]) => Value {\n  const arity = spec.args.length;\n  return (args: Value[]): Value => {\n    if (args.length !== arity) {\n      throw ErrorFactory.execution({\n        code: DefineFunctionErrorCodes.DEFINE_FUNCTION_ARITY_MISMATCH,\n        message: `${spec.name}() takes ${plural(arity)}, but was given ${args.length === 0 ? \"none\" : plural(args.length)}`,\n        expected: plural(arity),\n        found: args.length === 0 ? \"none\" : plural(args.length),\n        context: { functionName: spec.name, expected: arity, actual: args.length },\n      });\n    }\n\n    const jsArgs: (number | string | boolean)[] = new Array(arity);\n    for (let i = 0; i < arity; i++) {\n      jsArgs[i] = coerceArgument(args[i], spec.args[i], spec.name);\n    }\n\n    const result = (spec.call as (...a: (number | string | boolean)[]) => unknown)(...jsArgs);\n    return wrapReturn(result, spec.returns, spec.name);\n  };\n}\n\n/** Reject a spec that could not produce a working function, before any engine sees it. */\nfunction validateSpec(spec: FunctionSpec): void {\n  if (typeof spec?.name !== \"string\" || !NAME_PATTERN.test(spec.name)) {\n    throw ErrorFactory.config({\n      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_NAME,\n      message: `defineFunction: name must be a single identifier, got ${JSON.stringify(spec?.name)}`,\n      suggestion: 'e.g. \"vat\" or \"net_price\"',\n      context: { name: spec?.name },\n    });\n  }\n  if (!Array.isArray(spec.args)) {\n    throw ErrorFactory.config({\n      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,\n      message: `defineFunction: \"${spec.name}\" args must be an array`,\n      context: { name: spec.name },\n    });\n  }\n  for (const arg of spec.args) {\n    if (typeof arg?.name !== \"string\" || arg.name.length === 0) {\n      throw ErrorFactory.config({\n        code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,\n        message: `defineFunction: \"${spec.name}\" has an argument with no name`,\n        context: { name: spec.name },\n      });\n    }\n    if (!SUPPORTED_TYPES.has(arg.type)) {\n      throw ErrorFactory.config({\n        code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,\n        message: `defineFunction: \"${spec.name}\" argument \"${arg.name}\" has unsupported type ${JSON.stringify(arg.type)}`,\n        suggestion: \"supported argument types are number, string, boolean\",\n        context: { name: spec.name, argName: arg.name, type: arg.type },\n      });\n    }\n  }\n  if (!SUPPORTED_TYPES.has(spec.returns)) {\n    throw ErrorFactory.config({\n      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,\n      message: `defineFunction: \"${spec.name}\" has unsupported return type ${JSON.stringify(spec.returns)}`,\n      suggestion: \"supported return types are number, string, boolean\",\n      context: { name: spec.name, returns: spec.returns },\n    });\n  }\n  if (typeof spec.call !== \"function\") {\n    throw ErrorFactory.config({\n      code: DefineFunctionErrorCodes.DEFINE_FUNCTION_INVALID_SPEC,\n      message: `defineFunction: \"${spec.name}\" is missing a call implementation`,\n      context: { name: spec.name },\n    });\n  }\n}\n\n/**\n * Turn a declarative {@link FunctionSpec} into a ready-to-register\n * {@link IEnginePackage}.\n *\n * This is the higher-level API from issue #102. It derives, from the\n * declaration alone, everything the low-level contract asks an author to write\n * by hand: a named plugin function (the engine assigns its `CALL_PLUGIN`\n * index), a lexer keyword so the name tokenises, a call-syntax parselet emitting\n * that call by name, and a handler that checks arity and argument types (yielding\n * the engine's own structured errors) before invoking `call` and wrapping its\n * result. Anything needing custom parsing keeps writing a raw parselet exactly\n * as before, this sits on top of that contract and does not change it.\n *\n * @example\n * ```ts\n * const engine = new ExpressionEngine({ packages: [\n *   ...BUILTIN_PACKAGES,\n *   defineFunction({\n *     name: \"vat\",\n *     args: [{ name: \"amount\", type: \"number\" }],\n *     returns: \"number\",\n *     call: (amount) => amount * 1.2,\n *   }),\n * ] });\n * engine.evaluateExpression(\"vat(100)\"); // 120\n * ```\n *\n * The returned package is self-contained and composes with any others through\n * the engine's `packages` array; register several functions by passing several\n * packages. Its name is `solve-fn-<name>`.\n *\n * Scope: arguments are a fixed-length list of `number`/`string`/`boolean`, and\n * `call` is synchronous. Variadic and optional arguments, other value types\n * (units, percentages, dates, matrices), and async work are deliberately out\n * of scope, a function needing any of those keeps using the low-level\n * contract, whose parselets and async resolvers are unchanged.\n *\n * @throws {EngineError} (category CONFIG) if the spec is malformed, at the\n * point `defineFunction` is called, before the package reaches an engine.\n */\nexport function defineFunction<\n  const A extends readonly FunctionArg[],\n  R extends FunctionValueType,\n>(spec: FunctionSpec<A, R>): IEnginePackage {\n  validateSpec(spec as FunctionSpec);\n\n  const name = spec.name;\n  // Uppercased so the generated type is a valid, collision-resistant token\n  // type; the name pattern guarantees it forms one. Distinct from the\n  // built-in FUNC type, so this never routes through the builtin name map.\n  const tokenType = `DEFINE_FN_${name.toUpperCase()}`;\n\n  return {\n    name: `solve-fn-${name}`,\n    lexerVocabulary: {\n      // Lowercased because the lexer lowercases input before lookup, so the\n      // call is matched case-insensitively.\n      keywords: { [name.toLowerCase()]: tokenType },\n    },\n    prefixParselets: {\n      [tokenType]: new DefinedFunctionParselet(name),\n    },\n    pluginFunctions: {\n      [name]: makeHandler(spec as FunctionSpec),\n    },\n  };\n}\n","import { ExpressionEngine, type EngineOptions } from \"@solve-js/engine/ExpressionEngine\";\nimport { BUILTIN_PACKAGES } from \"@solve-js/packages/builtins\";\nimport type { IEnginePackage } from \"@solve-js/api/PackageRegistry\";\n\n/** Options for {@link createEngine}: the engine options, minus `packages` (the\n *  built-in set is always registered), plus `extraPackages` to add your own. */\nexport interface CreateEngineOptions extends Omit<EngineOptions, \"packages\"> {\n\t/** Packages to register ON TOP of the built-in set (e.g. an OSRS or stocks package). */\n\textraPackages?: IEnginePackage[];\n}\n\n/**\n * A batteries-included {@link ExpressionEngine} with every built-in package\n * registered.\n *\n * The constructor registers only the packages it is given, so a consumer's\n * bundler can tree-shake away the built-ins they never use: an engine built\n * with `new ExpressionEngine({ packages: [ARITHMETIC_PACKAGE] })` carries no\n * finance, colour or weather code. This convenience is the opposite trade: it\n * pulls the FULL built-in set (`BUILTIN_PACKAGES`) for the common \"I want\n * everything\" case, so importing it defeats that tree-shaking. Reach for the\n * constructor with an explicit package list when bundle size matters, and for\n * `createEngine` when it does not.\n *\n * @param options - Engine options ({@link EngineOptions}) minus `packages`, plus\n *   an optional `extraPackages` to register alongside the built-in set.\n * @returns An engine with the built-in packages (and any extras) registered.\n *\n * @example\n * ```typescript\n * import { createEngine } from \"solve-engine\";\n * const engine = createEngine();\n * const value = engine.evaluateExpression(\"2 + 2 * 10\");\n * console.log(value.toNumber()); // 22\n * ```\n */\nexport function createEngine(options: CreateEngineOptions = {}): ExpressionEngine {\n\tconst { extraPackages = [], ...engineOptions } = options;\n\treturn new ExpressionEngine({\n\t\t...engineOptions,\n\t\tpackages: extraPackages.length > 0 ? [...BUILTIN_PACKAGES, ...extraPackages] : BUILTIN_PACKAGES,\n\t});\n}\n"]}