solve-engine 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 Liam Riddell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/LiamRiddell/solve-engine/main/static/solve-engine-banner-github.png" alt="Solve, a natural language expression engine" width="100%" />
+
+**A calculator that reads like a sentence.**
+
+[![npm](https://img.shields.io/npm/v/solve-engine?color=%230b7285&label=npm)](https://www.npmjs.com/package/solve-engine)
+[![CI](https://github.com/LiamRiddell/solve-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/LiamRiddell/solve-engine/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/node/v/solve-engine)](https://nodejs.org)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/LiamRiddell/solve-engine/blob/main/packages/engine/LICENSE)
+
+[Documentation](https://liamriddell.github.io/solve-engine/) &nbsp;&#8226;&nbsp;
+[Playground](https://liamriddell.github.io/solve-engine/playground/) &nbsp;&#8226;&nbsp;
+[Syntax reference](https://liamriddell.github.io/solve-engine/syntax/cheatsheet/)
+
+</div>
+
+A lexer, Pratt parser, bytecode VM, and an extensible package system for
+evaluating natural-language-flavoured expressions: `2 + 2 * 10`, `50% of 200`,
+`3 days + 4 hours`, `10 USD to GBP`, `100 cm + 2 m`.
+
+Originally the engine inside
+[Solve for Obsidian](https://github.com/LiamRiddell/obsidian-solve), extracted
+so it can be embedded in any host: an editor plugin, a CLI, a desktop app, a
+server. No dependency on a UI framework, a DOM, or an editor.
+
+See [ARCHITECTURE.md](https://github.com/LiamRiddell/solve-engine/blob/main/packages/engine/ARCHITECTURE.md) for how the pipeline, package system, async
+evaluation model, and caching layers fit together, plus a candid list of known
+architectural debt.
+
+## Installation
+
+```bash
+npm install solve-engine
+```
+
+## Quick start
+
+```typescript
+import { ExpressionEngine } from "solve-engine";
+
+const engine = new ExpressionEngine("en");
+const [value] = engine.evaluateExpression("2 + 2 * 10");
+
+console.log(value.toNumber()); // 22
+```
+
+`evaluateExpression` throws an `EngineError` (see `solve-engine/errors`) on a parse or
+evaluation failure, wrap calls with untrusted input in a `try`/`catch`.
+
+For line-oriented input (e.g. a document made of multiple expressions, some referencing
+variables defined on earlier lines), use `evaluateLine`/`parseDocument` instead, see the
+`engine` subpath below.
+
+## Engine lifecycle
+
+Call `clear()` when you are finished with an engine that has parsed a document.
+Dropping your last reference is not enough on its own: the async batcher is
+reachable from the module-level data query service, so a parsed engine stays
+retained until `clear()` releases it.
+
+```typescript
+const engine = new ExpressionEngine();
+engine.parseDocument(text);
+// ... read results ...
+engine.clear();
+```
+
+Measured per engine after a forced collection:
+
+| Lifecycle | Retained |
+| --- | --- |
+| constructed, never parsed | 8.2KB |
+| constructed and parsed | 128KB |
+| constructed, parsed, cleared | 10KB |
+
+This matters most for hosts that create one engine per document or per tab. Over
+10,000 create-and-drop cycles the uncleared path reaches roughly 1.2GB.
+
+Reusing one engine across documents is also fine. `clear()` resets an engine for
+the next document rather than consuming it, so there is no separate teardown
+call to remember.
+
+## Formatting a result for display
+
+```typescript
+import { formatValue } from "solve-engine/format";
+
+const [value] = engine.evaluateExpression("10 USD to GBP");
+console.log(formatValue(value)); // uses DEFAULT_FORMATTING_SETTINGS if no settings passed
+```
+
+## Package structure
+
+`solve-engine` exposes its API as a set of subpath exports, grouped by how stable/low-level
+they are:
+
+| Subpath | Purpose |
+|---|---|
+| `solve-engine` | Start here, `ExpressionEngine`, `PackageRegistry`/`packageRegistry`, `IEnginePackage`. |
+| `solve-engine/engine` | `ExpressionEngine` and its supporting types (`LineEvaluation`, `EvalResults`, etc.) directly, without the package-registration wrapper. |
+| `solve-engine/vm` | The bytecode VM: `Value`/`ValueType`, opcode dispatch, `allocatePluginFunctionIndex`. |
+| `solve-engine/format` | Turning a `Value` into a display string (numbers, dates, units, vectors, ...). |
+| `solve-engine/language` | Editor-agnostic language service: token categories, completions, highlighting. |
+| `solve-engine/packages` | The built-in packages (arithmetic, datetime, time, dice, uom, currency, vector, conditionals, converters, mathphrases, ...). |
+| `solve-engine/constants` | Engine configuration types and defaults (`EngineConfig`, `VMConfig`, ...). |
+
+The following subpaths are **advanced-public**, everything a third-party package author
+needs to extend the engine, but with a looser stability contract than the tier above (these
+are the pieces the built-in packages and the [OSRS example](https://github.com/LiamRiddell/solve-engine/tree/main/packages/engine/examples/osrs) themselves
+depend on):
+
+| Subpath | Purpose |
+|---|---|
+| `solve-engine/lexer` | Tokenizer, `LexerVocabulary` for registering custom keywords/operators/units. |
+| `solve-engine/parser` | Pratt parser, `BytecodeBuilder`, `OpCode`. |
+| `solve-engine/normalizer` | Post-lexer token transforms (phrase fusion, implicit multiply). |
+| `solve-engine/variables` | Variable resolution (`IVariableSource`). |
+| `solve-engine/resolvers` | Async resolvers (`IAsyncResolver`) for data that loads asynchronously. |
+| `solve-engine/errors` | `EngineError` and the error factory. |
+| `solve-engine/utilities` | Small stateless helpers (e.g. `stripQuotes`). |
+| `solve-engine/uom` | Units-of-measurement conversion tables and currency exchange. |
+| `solve-engine/services` | Supporting services (query client construction, etc). |
+
+Anything not listed above (`telemetry`, `cache`, `diagnostics`, `types`, `workers`) is
+internal and not part of the package's public contract, it may change or disappear between
+minor versions without notice.
+
+## Authoring a package
+
+A **package** (`IEnginePackage`) is a plain data descriptor bundling everything needed to
+extend the engine with a new domain: custom tokens, parselets, VM opcode handlers, variable
+sources, and optional async resolvers. See
+[`solve-engine/api`'s `IEnginePackage`](https://github.com/LiamRiddell/solve-engine/blob/main/packages/engine/src/api/PackageRegistry.ts) for the full field list
+with inline documentation and examples for each field.
+
+Minimal shape:
+
+```typescript
+import { allocatePluginFunctionIndex } from "solve-engine/vm";
+import type { IEnginePackage } from "solve-engine";
+
+const MY_FN_IDX = allocatePluginFunctionIndex();
+
+export const MY_PACKAGE: IEnginePackage = {
+  name: "MyPackage",
+  // engineVersion: "^0.1.0", // optional, see below
+  prefixParselets: [{ tokenType: "MY_FUNC", parselet: new MyParselet() }],
+  pluginFunctions: [{ index: MY_FN_IDX, handler: (args) => /* ... */ }],
+};
+```
+
+Register it either as one of the packages passed to the `ExpressionEngine` constructor, or
+at runtime via `ExpressionEngine.registerPackage()` / `unregisterPackage()`.
+
+### Declaring engine-version compatibility
+
+`IEnginePackage.engineVersion` is an optional semver range (e.g. `"^0.1.0"`) declaring which
+`solve-engine` versions your package is built against. It's checked against the real, running
+engine version at registration time. Omit it and your package always registers, exactly as
+before this field existed, this is the default for every package that predates it. Declare it
+once you want protection against the reverse case: your package being loaded into a much
+newer (or much older) engine whose `IEnginePackage` contract has since changed shape.
+
+Unlike every other compatibility signal in this codebase (see `ARCHITECTURE.md` §5.2's
+sibling-package collision warnings, which always log and proceed), a declared range the
+running engine does **not** satisfy causes `registerPackage()` to **throw**, not warn, see
+`ARCHITECTURE.md` §5.3 for the full reasoning.
+
+### Three more extension points, beyond `pluginFunctions`
+
+- **`solve-engine/parser`'s `definePhrasePattern()`**, build a phrase-grammar parselet
+  (`roll between X and Y`, `average of X, Y, Z`) from a declarative list of
+  `{ slots, emit }` alternatives instead of hand-writing `parser.consume()`/
+  `parseExpression()` calls. See `packages/mathphrases/` for several real examples, and
+  its own JSDoc for the one hard constraint (every alternative must start with a keyword
+  slot) and when a hand-written parselet is the right call instead.
+- **`solve-engine/resolvers`'s `createQueryResolver()`**, a factory for the common
+  "one cached async fetch → one `Value`" shape (weather, stock prices, a game-item price
+  API, see `examples/osrs`), generalizing the caching/staleness plumbing so a package
+  only needs to write the fetch call and the response mapping.
+- **`IEnginePackage.asConverters`**, contribute a custom `as <name>` conversion (e.g.
+  `50% as decimal`) to the built-in `converters` package's grammar: `{ myUnit: (value) =>
+  /* ... */ }`. No lexer keyword registration needed, any bare word after "as" that isn't
+  one of the built-in names resolves against this registry at runtime.
+
+See `ARCHITECTURE.md`'s §5.1 for the full reasoning behind each, including a real
+regression (and its fix pattern) worth reading before picking a keyword for your own
+package: a colon-prefixed variable name (`:name = expr`) can never be a keyword-shaped
+word in this engine, so a common-noun trigger word (like "total") should be phrase-fused
+with its qualifying keyword rather than claimed bare.
+
+Two runnable examples, both under [`examples/`](https://github.com/LiamRiddell/solve-engine/tree/main/packages/engine/examples) (example code, not part of the
+published package, see `files` in `package.json`, only `dist/` ships):
+
+- [`examples/basic`](https://github.com/LiamRiddell/solve-engine/tree/main/packages/engine/examples/basic), the smallest complete package: one custom keyword
+  (`reverse("text")`) dispatched through a plugin function, nothing else. Start here. Its
+  test, [`__tests__/examples/basic/BasicPackage.spec.ts`](https://github.com/LiamRiddell/solve-engine/blob/main/packages/engine/__tests__/examples/basic/BasicPackage.spec.ts),
+  shows the full register-and-evaluate loop end to end.
+- [`examples/osrs`](https://github.com/LiamRiddell/solve-engine/tree/main/packages/engine/examples/osrs), a fuller example covering everything `basic` leaves
+  out: a phrase-fused multi-word item name, an async resolver backed by a real HTTP API, a
+  custom highlight category, and completion items. Prices Old School RuneScape Grand Exchange
+  items (e.g. `ge("Abyssal whip")`).
+
+## Known limitations
+
+**Cross-instance isolation is partial.** Plugin functions, the opcode registry and
+variable sources are now owned per `ExpressionEngine`, so two engines with different
+package sets no longer interfere across those. The lexer and the currency exchange rates
+are still module-level singletons, so full isolation between two engines in one process
+cannot yet be assumed. Tracked as "L1, EngineContext"; three of its five migrations have
+landed and the remaining two are a prerequisite for 1.0.0 proper.
+
+**`variableSources` does nothing.** A package can declare them, the engine registers and
+unregisters them, and no evaluation path ever consults them. Treat the extension point as
+absent until that changes.
+
+**Async results need a host hook.** `AsyncResolutionBatcher.onLineResult` is the only
+mechanism that patches a resolved async value back into the document model, and it is not
+wired inside the package. A host that does not supply it gets async values that never
+resolve, with no error to explain why.
+
+## Development
+
+Developed in the [solve-engine](https://github.com/LiamRiddell/solve-engine) repository as
+an npm workspace (`packages/engine`).
+
+```bash
+npm run build   # tsup, emits ESM + CJS + .d.ts to dist/
+npm run dev     # tsup --watch
+npm test        # standalone jest run, scoped to this package
+```
+
+## License
+
+MIT, see [LICENSE](https://github.com/LiamRiddell/solve-engine/blob/main/packages/engine/LICENSE).

package/package.json

@@ -0,0 +1,225 @@
+{
+  "name": "solve-engine",
+  "version": "1.0.0-beta.0",
+  "description": "The expression evaluation engine behind Solve — lexer, parser, bytecode VM, and an extensible package system.",
+  "keywords": [
+    "expression-evaluator",
+    "calculator",
+    "bytecode-vm",
+    "parser",
+    "lexer",
+    "dsl",
+    "markdown",
+    "obsidian"
+  ],
+  "license": "MIT",
+  "author": "Liam Riddell",
+  "homepage": "https://liamriddell.github.io/solve-engine/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LiamRiddell/solve-engine.git",
+    "directory": "packages/engine"
+  },
+  "bugs": {
+    "url": "https://github.com/LiamRiddell/solve-engine/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./engine": {
+      "import": {
+        "types": "./dist/engine.d.ts",
+        "default": "./dist/engine.js"
+      },
+      "require": {
+        "types": "./dist/engine.d.cts",
+        "default": "./dist/engine.cjs"
+      }
+    },
+    "./vm": {
+      "import": {
+        "types": "./dist/vm.d.ts",
+        "default": "./dist/vm.js"
+      },
+      "require": {
+        "types": "./dist/vm.d.cts",
+        "default": "./dist/vm.cjs"
+      }
+    },
+    "./format": {
+      "import": {
+        "types": "./dist/format.d.ts",
+        "default": "./dist/format.js"
+      },
+      "require": {
+        "types": "./dist/format.d.cts",
+        "default": "./dist/format.cjs"
+      }
+    },
+    "./language": {
+      "import": {
+        "types": "./dist/language.d.ts",
+        "default": "./dist/language.js"
+      },
+      "require": {
+        "types": "./dist/language.d.cts",
+        "default": "./dist/language.cjs"
+      }
+    },
+    "./packages": {
+      "import": {
+        "types": "./dist/packages.d.ts",
+        "default": "./dist/packages.js"
+      },
+      "require": {
+        "types": "./dist/packages.d.cts",
+        "default": "./dist/packages.cjs"
+      }
+    },
+    "./constants": {
+      "import": {
+        "types": "./dist/constants.d.ts",
+        "default": "./dist/constants.js"
+      },
+      "require": {
+        "types": "./dist/constants.d.cts",
+        "default": "./dist/constants.cjs"
+      }
+    },
+    "./lexer": {
+      "import": {
+        "types": "./dist/lexer.d.ts",
+        "default": "./dist/lexer.js"
+      },
+      "require": {
+        "types": "./dist/lexer.d.cts",
+        "default": "./dist/lexer.cjs"
+      }
+    },
+    "./parser": {
+      "import": {
+        "types": "./dist/parser.d.ts",
+        "default": "./dist/parser.js"
+      },
+      "require": {
+        "types": "./dist/parser.d.cts",
+        "default": "./dist/parser.cjs"
+      }
+    },
+    "./normalizer": {
+      "import": {
+        "types": "./dist/normalizer.d.ts",
+        "default": "./dist/normalizer.js"
+      },
+      "require": {
+        "types": "./dist/normalizer.d.cts",
+        "default": "./dist/normalizer.cjs"
+      }
+    },
+    "./variables": {
+      "import": {
+        "types": "./dist/variables.d.ts",
+        "default": "./dist/variables.js"
+      },
+      "require": {
+        "types": "./dist/variables.d.cts",
+        "default": "./dist/variables.cjs"
+      }
+    },
+    "./resolvers": {
+      "import": {
+        "types": "./dist/resolvers.d.ts",
+        "default": "./dist/resolvers.js"
+      },
+      "require": {
+        "types": "./dist/resolvers.d.cts",
+        "default": "./dist/resolvers.cjs"
+      }
+    },
+    "./errors": {
+      "import": {
+        "types": "./dist/errors.d.ts",
+        "default": "./dist/errors.js"
+      },
+      "require": {
+        "types": "./dist/errors.d.cts",
+        "default": "./dist/errors.cjs"
+      }
+    },
+    "./utilities": {
+      "import": {
+        "types": "./dist/utilities.d.ts",
+        "default": "./dist/utilities.js"
+      },
+      "require": {
+        "types": "./dist/utilities.d.cts",
+        "default": "./dist/utilities.cjs"
+      }
+    },
+    "./uom": {
+      "import": {
+        "types": "./dist/uom.d.ts",
+        "default": "./dist/uom.js"
+      },
+      "require": {
+        "types": "./dist/uom.d.cts",
+        "default": "./dist/uom.cjs"
+      }
+    },
+    "./services": {
+      "import": {
+        "types": "./dist/services.d.ts",
+        "default": "./dist/services.js"
+      },
+      "require": {
+        "types": "./dist/services.d.cts",
+        "default": "./dist/services.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "jest --config jest.config.cjs --no-coverage",
+    "typecheck": "tsgo --noEmit --skipLibCheck",
+    "typecheck:tsc": "tsc --noEmit --skipLibCheck"
+  },
+  "dependencies": {
+    "@tanstack/query-core": "^5.100.10",
+    "semver": "^7.6.0",
+    "tslib": "^2.6.1"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.4.1",
+    "@types/node": "^26.1.2",
+    "@types/semver": "^7.5.0",
+    "convert": "^7.0.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.12",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3"
+  },
+  "sideEffects": false
+}