solve-engine 1.1.1 → 2.0.0

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"]}

package/dist/language.cjs

@@ -1,370 +1,2 @@
-'use strict';
-
-var chunkEJ3ILXX6_cjs = require('./chunk-EJ3ILXX6.cjs');
-var chunk536WPM2V_cjs = require('./chunk-536WPM2V.cjs');
-var chunkAQNHHJMJ_cjs = require('./chunk-AQNHHJMJ.cjs');
-require('./chunk-AMOJYLG2.cjs');
-require('./chunk-B7LXJ6LC.cjs');
-
-// src/language/LanguageService.ts
-var MAX_COMPLETIONS = 50;
-var CATEGORY_TIER = {
-  variable: 0,
-  function: 1,
-  keyword: 1,
-  operator: 1,
-  comparison: 1,
-  bitwise: 1,
-  datetime: 1,
-  vector: 1,
-  unit: 2
-};
-var MAX_CACHED_LINES = 2e3;
-var LanguageService = class {
-  constructor(engine, options) {
-    // Bounded cache keyed by line number ALONE, not `${lineNumber}:${lineText}`
-    // as an earlier version of this class did. A line's previous text state is
-    // never useful once it changes, so keying on text too was pure waste:
-    // every keystroke on a line minted a brand-new, never-reclaimed cache
-    // entry (an effective per-keystroke memory leak over a long editing
-    // session). Keying on line number alone makes "same line, new text" a
-    // cheap overwrite instead.
-    //
-    // Eviction is oldest-inserted (Map iteration order) when at capacity
-    // mirroring the same bounded-cache pattern ExpressionEngine's own
-    // bytecodeCache already uses elsewhere in this codebase. Deliberately
-    // NOT an LFU (least-frequently-used) policy: LFU would keep resisting
-    // eviction of old, once-popular lines while punishing a line that just
-    // scrolled into view (frequency 1), the opposite of what a "currently
-    // visible" cache should prioritize.
-    this.cache = /* @__PURE__ */ new Map();
-    // Keyword/unit/package-contributed completion candidates don't depend
-    // on any particular line, built lazily on first getCompletions() call
-    // and reused after that, since a package registration is the only thing
-    // that could ever change this list mid-session (see invalidateCache()).
-    // Variable-name candidates are NOT part of this, they're read fresh on
-    // every call from variableNameSource(), since those genuinely change on
-    // every edit.
-    this.staticCompletionCandidates = null;
-    // The same candidates, bucketed by their lowercased first character with the
-    // lowercased label precomputed. getCompletions() runs on every keystroke and
-    // only ever wants candidates sharing the prefix's first character, so
-    // scanning the whole list and lowercasing each label per call was doing two
-    // avoidable things: touching entries that could not possibly match, and
-    // allocating a string per candidate per keystroke. That was affordable when
-    // the vocabulary was a few hundred entries. Deriving the unit list from the
-    // conversion tables took it past a thousand, and the warm completion
-    // benchmarks regressed roughly 2.9x until this was added.
-    this.staticCompletionIndex = null;
-    this.engine = engine ?? null;
-    this.variableNameSource = options?.variableNameSource ?? (() => this.defaultVariableNames());
-    this.normalizeForHighlighting = options?.normalizeForHighlighting ?? false;
-  }
-  defaultVariableNames() {
-    if (!this.engine) return [];
-    const snapshot = this.engine.getDag().getSnapshot();
-    const names = new Set(Object.keys(snapshot.consumers));
-    for (const written of Object.values(snapshot.writes)) {
-      for (const name of written) names.add(name);
-    }
-    return names;
-  }
-  /**
-   * Lex a line, normalize it, and place every resulting token back in the
-   * source text.
-   *
-   * ## Why placing them back is the hard part
-   *
-   * Normalization produces three kinds of token and only one of them can be
-   * highlighted the obvious way.
-   *
-   * A token the normalizer left alone still describes its own text, so its
-   * span is `offset` to `offset + text.length`, exactly as before.
-   *
-   * A FUSED token does not. `10 frames` becomes a FRAME_COUNT whose value is
-   * `10`, and a timecode becomes a token whose value is a comma-separated
-   * tuple appearing nowhere on the line. Those carry `sourceEnd`, set by
-   * `createFusedToken`, which is the only place that knows where the fusion
-   * ended.
-   *
-   * An INSERTED token has no text at all. Implicit multiplication puts a STAR
-   * at the following token's offset, so `5(3)` gains a `*` sitting exactly
-   * where the `(` is. Painting it would colour a character the reader never
-   * typed as an operator, and would overlap the token that really is there.
-   * These are dropped, detected by the one test that needs no cooperation
-   * from any rule: a token with no recorded fusion span must match the text
-   * at its own offset, and an inserted one does not.
-   *
-   * @param lineText - The raw line.
-   * @returns Spans in the same shape `Lexer.getHighlightTokens` returns.
-   */
-  classifyNormalized(lineText) {
-    const lexer = this.engine.getLexer();
-    const raw = lexer.getHighlightTokenObjects(lineText);
-    if (raw.length === 0) return [];
-    const source = lineText.startsWith("> ") && lexer.classifyLine(lineText).skip ? lineText.slice(2) : lineText;
-    let normalized;
-    try {
-      normalized = this.engine.getNormalizer().normalize(raw);
-    } catch {
-      normalized = raw;
-    }
-    const out = [];
-    for (const token of normalized) {
-      let end;
-      if (token.sourceEnd !== void 0) {
-        end = token.sourceEnd;
-      } else if (source.startsWith(token.text, token.offset)) {
-        end = token.offset + token.text.length;
-      } else {
-        continue;
-      }
-      out.push({
-        type: token.type,
-        value: token.value,
-        offset: token.offset,
-        col: token.col,
-        length: end - token.offset,
-        category: chunk536WPM2V_cjs.getTokenCategory(token.type)
-      });
-    }
-    return out;
-  }
-  /**
-   * Classify every recognized token on one line.
-   *
-   * @param lineText - The raw line text (may be a markdown-structural line
-   *   the engine's classifier skips, that's handled by the underlying
-   *   lexer, which returns no tokens for those).
-   * @param lineNumber - 1-based line number, used purely as a cache key.
-   */
-  getSemanticTokens(lineText, lineNumber) {
-    const cached = this.cache.get(lineNumber);
-    if (cached && cached.text === lineText) {
-      if (cached.bareWordCandidate !== void 0) {
-        return this.isKnownVariable(cached.bareWordCandidate) ? cached.tokens : [];
-      }
-      return cached.tokens;
-    }
-    if (!this.engine) {
-      return [];
-    }
-    const lexer = this.engine.getLexer();
-    const lexed = this.normalizeForHighlighting ? this.classifyNormalized(lineText) : lexer.getHighlightTokens(lineText);
-    if (lexed.length === 0) {
-      this.putCache(lineNumber, lineText, []);
-      return [];
-    }
-    const classification = lexer.classifyLine(lineText);
-    const tokens = [];
-    if (classification.hasInlineSolve) {
-      const validSpans = lexer.findInlineSolves(lineText).filter((span) => this.parsesAsExpression(span.expression)).map((span) => ({ from: span.start, to: span.end }));
-      for (const token of lexed) {
-        if (!token.category) continue;
-        const from = token.offset;
-        const to = token.offset + token.length;
-        if (!validSpans.some((s) => from >= s.from && to <= s.to)) continue;
-        tokens.push({ from, to, category: token.category });
-      }
-    } else {
-      const text = lineText.startsWith("> ") && classification.skip ? lineText.slice(2) : lineText;
-      if (this.parsesAsExpression(text)) {
-        for (const token of lexed) {
-          if (!token.category) continue;
-          tokens.push({ from: token.offset, to: token.offset + token.length, category: token.category });
-        }
-      }
-    }
-    if (tokens.length === 1 && tokens[0].category === "variable") {
-      const name = lineText.slice(tokens[0].from, tokens[0].to);
-      this.putCache(lineNumber, lineText, tokens, name);
-      return this.isKnownVariable(name) ? tokens : [];
-    }
-    this.putCache(lineNumber, lineText, tokens);
-    return tokens;
-  }
-  /**
-   * Completion candidates for the identifier prefix immediately before
-   * `cursorOffset` on `lineText`. Deliberately simple prefix matching, not
-   * parser-driven "what's grammatically valid here" prediction, a
-   * half-typed expression almost never parses, so gating on parse
-   * validity (the way `getSemanticTokens` does) would suppress
-   * completions almost always. This is the safest, fastest option that
-   * still delivers real value.
-   *
-   * Candidates come from three sources: keywords (which already include
-   * function names. See `ExpressionLexer.getKeywords()`'s doc comment)
-   * and units, both static per engine configuration and cached lazily;
-   * package-contributed items (`IEnginePackage.completionItems`), same
-   * cache; and variable names, read fresh from `variableNameSource()` on
-   * every call since those change on every edit.
-   */
-  getCompletions(lineText, cursorOffset) {
-    const prefixMatch = /[A-Za-z0-9_]+$/.exec(lineText.slice(0, cursorOffset));
-    if (!prefixMatch) return [];
-    const prefix = prefixMatch[0].toLowerCase();
-    if (!this.engine) return [];
-    const matches = [];
-    for (const name of this.variableNameSource()) {
-      if (name.toLowerCase().startsWith(prefix)) {
-        matches.push({ label: name, category: "variable" });
-      }
-    }
-    const bucket = this.getStaticCompletionIndex().get(prefix[0]);
-    if (bucket) {
-      for (const candidate of bucket) {
-        if (candidate.lowerLabel.startsWith(prefix)) matches.push(candidate.item);
-      }
-    }
-    matches.sort((a, b) => {
-      const tierDiff = (CATEGORY_TIER[a.category] ?? 3) - (CATEGORY_TIER[b.category] ?? 3);
-      if (tierDiff !== 0) return tierDiff;
-      return a.label.localeCompare(b.label);
-    });
-    return matches.slice(0, MAX_COMPLETIONS);
-  }
-  /** Lazily builds and caches the keyword/unit/package-item candidate list. See `staticCompletionCandidates`. */
-  getStaticCompletionCandidates() {
-    if (this.staticCompletionCandidates) return this.staticCompletionCandidates;
-    const items = [];
-    for (const [word, tokenType] of Object.entries(this.engine.getLexer().getKeywords())) {
-      const category = chunk536WPM2V_cjs.getTokenCategory(tokenType);
-      if (!category) continue;
-      items.push({ label: word, category });
-    }
-    for (const unit of chunkAQNHHJMJ_cjs.knownUnits) {
-      items.push({ label: unit, category: "unit", detail: chunkEJ3ILXX6_cjs.getMeasure(unit) });
-    }
-    items.push(...this.engine.getPackageCompletionItems());
-    this.staticCompletionCandidates = items;
-    return items;
-  }
-  /**
-   * The static candidates bucketed by lowercased first character, built once
-   * from {@link getStaticCompletionCandidates} and invalidated alongside it.
-   */
-  getStaticCompletionIndex() {
-    if (this.staticCompletionIndex) return this.staticCompletionIndex;
-    const index = /* @__PURE__ */ new Map();
-    for (const item of this.getStaticCompletionCandidates()) {
-      const lowerLabel = item.label.toLowerCase();
-      const firstCharacter = lowerLabel[0];
-      if (firstCharacter === void 0) continue;
-      let bucket = index.get(firstCharacter);
-      if (bucket === void 0) {
-        bucket = [];
-        index.set(firstCharacter, bucket);
-      }
-      bucket.push({ item, lowerLabel });
-    }
-    this.staticCompletionIndex = index;
-    return index;
-  }
-  isKnownVariable(name) {
-    for (const known of this.variableNameSource()) {
-      if (known === name) return true;
-    }
-    return false;
-  }
-  /**
-   * Whether the engine's parser actually accepts a piece of text as a
-   * well-formed expression, not merely whether it lexes into individually
-   * recognized token types. See the class doc comment's prose example.
-   * `tryCompileExpression` is compile-only (lex → normalize → parse →
-   * cache bytecode, no VM execution, no network/async side effects) and
-   * reuses the engine's existing bytecode cache, so text that's already
-   * been evaluated (or previously highlight-checked) is a cache hit here
-   * too.
-   *
-   * Deliberately calls the non-throwing `tryCompileExpression` rather than
-   * try/catching `compileExpression`. This runs on every visible line on
-   * every keystroke, and the common case for a real markdown document is
-   * lines that DON'T parse (prose), not lines that do. Throwing there would
-   * mean constructing a EngineError (with V8 stack-trace capture) for the
-   * common case instead of the rare one.
-   */
-  parsesAsExpression(text) {
-    return this.engine.tryCompileExpression(text);
-  }
-  putCache(lineNumber, text, tokens, bareWordCandidate) {
-    if (!this.cache.has(lineNumber) && this.cache.size >= MAX_CACHED_LINES) {
-      const oldestKey = this.cache.keys().next().value;
-      if (oldestKey !== void 0) this.cache.delete(oldestKey);
-    }
-    this.cache.set(lineNumber, { text, tokens, bareWordCandidate });
-  }
-  /**
-   * Evict specific lines (e.g. the lines actually touched by a CodeMirror
-   * change set) instead of the whole cache, the surgical counterpart to
-   * {@link invalidateCache}, letting a single-line edit stay cheap even in
-   * a large document: every other cached line is untouched and still hits
-   * on the next call.
-   */
-  invalidateLines(lineNumbers) {
-    for (const lineNumber of lineNumbers) {
-      this.cache.delete(lineNumber);
-    }
-  }
-  /**
-   * Full cache clear. Reserved for cases with no meaningful "which lines
-   * changed" (e.g. the document was swapped wholesale, or a package was
-   * registered/unregistered mid-session, changing what categories exist).
-   * Prefer {@link invalidateLines} for ordinary edits. Also rebuilds the
-   * lazily-cached keyword/unit/package-item completion candidates on next
-   * use, the only thing that can change that list mid-session.
-   */
-  invalidateCache() {
-    this.cache.clear();
-    this.staticCompletionCandidates = null;
-    this.staticCompletionIndex = null;
-  }
-};
-
-// src/language/tokenClassName.ts
-var DEFAULT_TOKEN_CLASS_PREFIX = "solve-";
-function tokenClassName(category, prefix = DEFAULT_TOKEN_CLASS_PREFIX) {
-  return `${prefix}${category}`;
-}
-function createTokenClassName(prefix) {
-  return (category) => `${prefix}${category}`;
-}
-
-// src/language/adapters/codemirror.ts
-var CATEGORY_TO_COMPLETION_TYPE = {
-  keyword: "keyword",
-  operator: "keyword",
-  comparison: "keyword",
-  bitwise: "keyword",
-  function: "function",
-  variable: "variable",
-  unit: "type",
-  datetime: "keyword",
-  vector: "type"
-};
-function completionItemToOption(item) {
-  return { label: item.label, type: CATEGORY_TO_COMPLETION_TYPE[item.category] ?? "text", detail: item.detail };
-}
-
-Object.defineProperty(exports, "UNCATEGORIZED_TOKEN_TYPES", {
-  enumerable: true,
-  get: function () { return chunk536WPM2V_cjs.UNCATEGORIZED_TOKEN_TYPES; }
-});
-Object.defineProperty(exports, "getTokenCategory", {
-  enumerable: true,
-  get: function () { return chunk536WPM2V_cjs.getTokenCategory; }
-});
-Object.defineProperty(exports, "registerTokenCategory", {
-  enumerable: true,
-  get: function () { return chunk536WPM2V_cjs.registerTokenCategory; }
-});
-Object.defineProperty(exports, "unregisterTokenCategory", {
-  enumerable: true,
-  get: function () { return chunk536WPM2V_cjs.unregisterTokenCategory; }
-});
-exports.DEFAULT_TOKEN_CLASS_PREFIX = DEFAULT_TOKEN_CLASS_PREFIX;
-exports.LanguageService = LanguageService;
-exports.completionItemToOption = completionItemToOption;
-exports.createTokenClassName = createTokenClassName;
-exports.tokenClassName = tokenClassName;
-//# sourceMappingURL=language.cjs.map
+'use strict';var chunkIANAMBJQ_cjs=require('./chunk-IANAMBJQ.cjs'),chunkY7O4D3BJ_cjs=require('./chunk-Y7O4D3BJ.cjs'),chunkFWW3M36J_cjs=require('./chunk-FWW3M36J.cjs');require('./chunk-CIQOK7Q4.cjs');var I=50,C={variable:0,function:1,keyword:1,operator:1,comparison:1,bitwise:1,datetime:1,vector:1,unit:2},T=2e3,p=class{constructor(e,o){this.cache=new Map;this.staticCompletionCandidates=null;this.staticCompletionIndex=null;this.engine=e??null,this.variableNameSource=o?.variableNameSource??(()=>this.defaultVariableNames()),this.normalizeForHighlighting=o?.normalizeForHighlighting??false;}defaultVariableNames(){if(!this.engine)return [];let e=this.engine.getDag().getSnapshot(),o=new Set(Object.keys(e.consumers));for(let n of Object.values(e.writes))for(let i of n)o.add(i);return o}classifyNormalized(e){let o=this.engine.getLexer(),n=o.getHighlightTokenObjects(e);if(n.length===0)return [];let i=e.startsWith("> ")&&o.classifyLine(e).skip?e.slice(2):e,r;try{r=this.engine.getNormalizer().normalize(n);}catch{r=n;}let l=[];for(let t of r){let s;if(t.sourceEnd!==void 0)s=t.sourceEnd;else if(i.startsWith(t.text,t.offset))s=t.offset+t.text.length;else continue;l.push({type:t.type,value:t.value,offset:t.offset,col:t.col,length:s-t.offset,category:chunkY7O4D3BJ_cjs.d(t.type)});}return l}getSemanticTokens(e,o){let n=this.cache.get(o);if(n&&n.text===e)return n.bareWordCandidate!==void 0?this.isKnownVariable(n.bareWordCandidate)?n.tokens:[]:n.tokens;if(!this.engine)return [];let i=this.engine.getLexer(),r=this.normalizeForHighlighting?this.classifyNormalized(e):i.getHighlightTokens(e);if(r.length===0)return this.putCache(o,e,[]),[];let l=i.classifyLine(e),t=[];if(l.hasInlineSolve){let s=i.findInlineSolves(e).filter(a=>this.parsesAsExpression(a.expression)).map(a=>({from:a.start,to:a.end}));for(let a of r){if(!a.category)continue;let m=a.offset,f=a.offset+a.length;s.some(u=>m>=u.from&&f<=u.to)&&t.push({from:m,to:f,category:a.category});}}else {let s=e.startsWith("> ")&&l.skip?e.slice(2):e;if(this.parsesAsExpression(s))for(let a of r)a.category&&t.push({from:a.offset,to:a.offset+a.length,category:a.category});}if(t.length===1&&t[0].category==="variable"){let s=e.slice(t[0].from,t[0].to);return this.putCache(o,e,t,s),this.isKnownVariable(s)?t:[]}return this.putCache(o,e,t),t}getCompletions(e,o){let n=/[A-Za-z0-9_]+$/.exec(e.slice(0,o));if(!n)return [];let i=n[0].toLowerCase();if(!this.engine)return [];let r=[];for(let t of this.variableNameSource())t.toLowerCase().startsWith(i)&&r.push({label:t,category:"variable"});let l=this.getStaticCompletionIndex().get(i[0]);if(l)for(let t of l)t.lowerLabel.startsWith(i)&&r.push(t.item);return r.sort((t,s)=>{let a=(C[t.category]??3)-(C[s.category]??3);return a!==0?a:t.label.localeCompare(s.label)}),r.slice(0,I)}getStaticCompletionCandidates(){if(this.staticCompletionCandidates)return this.staticCompletionCandidates;let e=[];for(let[o,n]of Object.entries(this.engine.getLexer().getKeywords())){let i=chunkY7O4D3BJ_cjs.d(n);i&&e.push({label:o,category:i});}for(let o of chunkFWW3M36J_cjs.a)e.push({label:o,category:"unit",detail:chunkIANAMBJQ_cjs.c(o)});return e.push(...this.engine.getPackageCompletionItems()),this.staticCompletionCandidates=e,e}getStaticCompletionIndex(){if(this.staticCompletionIndex)return this.staticCompletionIndex;let e=new Map;for(let o of this.getStaticCompletionCandidates()){let n=o.label.toLowerCase(),i=n[0];if(i===void 0)continue;let r=e.get(i);r===void 0&&(r=[],e.set(i,r)),r.push({item:o,lowerLabel:n});}return this.staticCompletionIndex=e,e}isKnownVariable(e){for(let o of this.variableNameSource())if(o===e)return  true;return  false}parsesAsExpression(e){return this.engine.tryCompileExpression(e)}putCache(e,o,n,i){if(!this.cache.has(e)&&this.cache.size>=T){let r=this.cache.keys().next().value;r!==void 0&&this.cache.delete(r);}this.cache.set(e,{text:o,tokens:n,bareWordCandidate:i});}invalidateLines(e){for(let o of e)this.cache.delete(o);}invalidateCache(){this.cache.clear(),this.staticCompletionCandidates=null,this.staticCompletionIndex=null;}};var y="solve-";function x(c,e=y){return `${e}${c}`}function E(c){return e=>`${c}${e}`}var S={keyword:"keyword",operator:"keyword",comparison:"keyword",bitwise:"keyword",function:"function",variable:"variable",unit:"type",datetime:"keyword",vector:"type"};function w(c){return {label:c.label,type:S[c.category]??"text",detail:c.detail}}Object.defineProperty(exports,"UNCATEGORIZED_TOKEN_TYPES",{enumerable:true,get:function(){return chunkY7O4D3BJ_cjs.a}});Object.defineProperty(exports,"getTokenCategory",{enumerable:true,get:function(){return chunkY7O4D3BJ_cjs.d}});Object.defineProperty(exports,"registerTokenCategory",{enumerable:true,get:function(){return chunkY7O4D3BJ_cjs.b}});Object.defineProperty(exports,"unregisterTokenCategory",{enumerable:true,get:function(){return chunkY7O4D3BJ_cjs.c}});exports.DEFAULT_TOKEN_CLASS_PREFIX=y;exports.LanguageService=p;exports.completionItemToOption=w;exports.createTokenClassName=E;exports.tokenClassName=x;//# sourceMappingURL=language.cjs.map
 //# sourceMappingURL=language.cjs.map