@hestia-earth/engine-models 0.81.6 → 0.82.1

package/README.md

@@ -142,3 +142,22 @@ The `ecoinventV3` model requires a valid [license](https://ecoinvent.org/offerin
 
 To amortise the impacts of land use change using linear discounting across IPCC (2019) models:
 1. Set the env variable `USE_LINEAR_DISCOUNTING` to `true`
+
+## TypeScript / JavaScript package
+
+The model metadata is also published to npm as [`@hestia-earth/engine-models`](https://www.npmjs.com/package/@hestia-earth/engine-models):
+
+```bash
+npm install @hestia-earth/engine-models
+```
+
+It exposes the links between models, terms and their documentation (`model-links.json`), and the KaTeX **formulas** extracted from each model, with bindings that map every symbol to a value logged at runtime (the "jlog"):
+
+```ts
+import { getFormulas } from '@hestia-earth/engine-models';
+
+getFormulas({ model: 'ipcc2019', term: 'ch4ToAirEntericFermentation' });
+// => [ { formula: 'E_{CH4} = (GE \\times Y_m) / 55.65', bindings: [...] } ]
+```
+
+See [`formulas/README.md`](./formulas/README.md) for the full guide on getting a model's formulas, rendering them with KaTeX, and substituting the symbols with the values from a given execution.

package/cjs/formulas.d.ts

@@ -0,0 +1,99 @@
+import { IModel } from './models';
+/**
+ * A single symbol in a formula, optionally bound to a value logged in the jlog.
+ */
+export interface IFormulaBinding {
+    /**
+     * The KaTeX symbol as written in the formula, e.g. `E_{CH4}`, `GE`.
+     */
+    symbol: string;
+    /**
+     * Human-readable description from the formula's "Where:" list.
+     */
+    description?: string;
+    /**
+     * The jlog field this symbol resolves to. `value` is the result (left-hand
+     * side); any other key is looked up on the model's jlog entry. Absent for
+     * constants / display-only symbols. When `column` is set, this is the log key
+     * of a packed `log_as_table` string rather than a scalar.
+     */
+    key?: string;
+    /**
+     * A value inside a packed `log_as_table` string: the column to read.
+     * - with no `match`, the symbol sits under a `\sum` and is expanded once per
+     *   row (e.g. `\sum_i M_i \times EF_i` → `(32 × 0.166) + (13 × 0.495)`);
+     * - with `match`, it resolves to a single row (row selection, see `match`).
+     */
+    column?: string;
+    /**
+     * Row selection: pick the one row of the `key` table whose id (first column)
+     * starts with this value, then read `column` from it. Resolves to a single
+     * value, e.g. `NH_3\text{-}N` → the `emission-value` of the row `nh3…`.
+     */
+    match?: string;
+    /**
+     * A fixed constant (not logged): the symbol always substitutes to this literal
+     * (e.g. `ER` → `2`) and is excluded from coverage. Empty string marks a
+     * constant with no display value.
+     */
+    constant?: string;
+}
+/**
+ * A KaTeX formula extracted from a model's documentation, with the bindings
+ * needed to substitute its symbols with values logged at runtime.
+ */
+export interface IFormula {
+    /**
+     * The KaTeX source (without the `$$` delimiters).
+     */
+    formula: string;
+    /**
+     * The symbols in the formula, in "Where:" list order.
+     */
+    bindings: IFormulaBinding[];
+}
+/**
+ * Get the formulas (if any) for a model-links entry. A documentation file may
+ * define several formulas, so this always returns an array (empty when none).
+ */
+export declare const getFormulasForLink: (link: Pick<IModel, "docPath">) => IFormula[];
+/**
+ * Get the formulas for a model, addressed by the same parameters used to look
+ * up a model in model-links.json (e.g. `{ model, term }` or `{ model, modelKey }`).
+ * Returns an empty array when the model is unknown or has no formulas.
+ */
+export declare const getFormulas: (model: Partial<IModel>) => IFormula[];
+/**
+ * The result of rendering a formula against a set of values, as KaTeX source
+ * strings (without the `$$` delimiters). Feed these to `katex.render`.
+ */
+export interface IRenderedFormula {
+    /**
+     * The formula as authored, e.g. `E_{CH4} = (GE \times Y_m) / 55.65`.
+     */
+    symbolic: string;
+    /**
+     * Symbols replaced by their values, e.g. `59.24 = (52340 \times 0.063) / 55.65`.
+     * A symbol with no value is left as the symbol.
+     */
+    substituted: string;
+    /**
+     * Symbols kept, each wrapped in `\htmlData{key=..., value=...}{symbol}` so the
+     * rendered DOM node carries `data-key` / `data-value` for tooltips or toggling.
+     * Requires `trust: (ctx) => ctx.command === '\\htmlData'` in the KaTeX options.
+     */
+    annotated: string;
+}
+/**
+ * Render a formula against a set of values, producing the KaTeX strings needed
+ * to display it symbolically, with substituted values, or annotated for
+ * interaction. `values` maps each binding `key` to its value for one execution
+ * (typically pulled from the model's jlog entry, plus `value` for the result);
+ * the caller decides where those values come from, so this stays agnostic.
+ * Symbols without a value in `values` are left symbolic.
+ *
+ * A `\sum` whose summand symbols are bound to table columns (`key`+`column`) is
+ * expanded once per row, provided `values[key]` holds the packed table string
+ * (or an array of row objects). Without the table it stays symbolic.
+ */
+export declare const renderFormula: (formula: IFormula, values: Record<string, unknown>) => IRenderedFormula;

package/cjs/formulas.js

@@ -0,0 +1,209 @@
+"use strict";
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderFormula = exports.getFormulas = exports.getFormulasForLink = void 0;
+var data = require("../formulas/index.json");
+var utils_1 = require("./utils");
+// keyed by the same `docPath` found on model-links.json entries
+var formulas = data;
+/**
+ * Get the formulas (if any) for a model-links entry. A documentation file may
+ * define several formulas, so this always returns an array (empty when none).
+ */
+var getFormulasForLink = function (link) {
+    return (link && formulas[link.docPath]) || [];
+};
+exports.getFormulasForLink = getFormulasForLink;
+/**
+ * Get the formulas for a model, addressed by the same parameters used to look
+ * up a model in model-links.json (e.g. `{ model, term }` or `{ model, modelKey }`).
+ * Returns an empty array when the model is unknown or has no formulas.
+ */
+var getFormulas = function (model) {
+    var link = (0, utils_1.findMatchingModel)(model);
+    return link ? (0, exports.getFormulasForLink)(link) : [];
+};
+exports.getFormulas = getFormulas;
+var isAlpha = function (char) { return /[a-zA-Z]/.test(char || ''); };
+// Split a KaTeX string on the declared symbols only (longest-first), so
+// `\times`, subscripts and constants are never touched.
+var splitOnSymbols = function (formula, symbols) {
+    var ordered = __spreadArray([], __read(symbols), false).sort(function (a, b) { return b.length - a.length; });
+    var segments = [];
+    var i = 0;
+    var _loop_1 = function () {
+        var symbol = ordered.find(function (s) {
+            return formula.startsWith(s, i) &&
+                !isAlpha(formula[i - 1]) &&
+                !isAlpha(formula[i + s.length]) &&
+                formula[i - 1] !== '\\';
+        });
+        if (symbol) {
+            segments.push({ symbol: symbol });
+            i += symbol.length;
+        }
+        else {
+            var j_1 = i + 1;
+            while (j_1 < formula.length && !ordered.some(function (s) { return formula.startsWith(s, j_1); }))
+                j_1++;
+            segments.push({ text: formula.slice(i, j_1) });
+            i = j_1;
+        }
+    };
+    while (i < formula.length) {
+        _loop_1();
+    }
+    return segments;
+};
+var round4 = function (n) { return String(+n.toPrecision(4)); };
+// Round numeric-looking strings, leave everything else (e.g. "kg FPCM") as-is.
+var formatNumericString = function (value) {
+    var asNumber = Number(value);
+    return value !== '' && Number.isFinite(asNumber) ? round4(asNumber) : value;
+};
+var formatValue = function (value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'number')
+        return round4(value);
+    return formatNumericString(String(value));
+};
+// `\sum` with an optional index subscript (`_i`, `_{s=1}`, ...) and upper bound
+// superscript (`^S`, `^{S}`), and trailing space.
+var SUM_RE = /\\sum(?:_\{[^}]*\}|_[^\s{])?(?:\^\{[^}]*\}|\^[^\s{])?\s*/;
+// Parse a packed `log_as_table` string into rows: rows split on `;`, columns on
+// `_`, each column a `key:value` pair (values never contain `_` or `:`).
+var parseTable = function (packed) {
+    return packed
+        .split(';')
+        .filter(Boolean)
+        .map(function (row) {
+        return row.split('_').reduce(function (cols, pair) {
+            var at = pair.indexOf(':');
+            if (at !== -1)
+                cols[pair.slice(0, at)] = pair.slice(at + 1);
+            return cols;
+        }, {});
+    });
+};
+/**
+ * Render a formula against a set of values, producing the KaTeX strings needed
+ * to display it symbolically, with substituted values, or annotated for
+ * interaction. `values` maps each binding `key` to its value for one execution
+ * (typically pulled from the model's jlog entry, plus `value` for the result);
+ * the caller decides where those values come from, so this stays agnostic.
+ * Symbols without a value in `values` are left symbolic.
+ *
+ * A `\sum` whose summand symbols are bound to table columns (`key`+`column`) is
+ * expanded once per row, provided `values[key]` holds the packed table string
+ * (or an array of row objects). Without the table it stays symbolic.
+ */
+var renderFormula = function (formula, values) {
+    // sum: a per-row column under a \sum. point: a single value — a scalar, a row
+    // selection (`match` + `column`), or a fixed constant.
+    var sumBindings = formula.bindings.filter(function (b) { return b.key && b.column && !b.match; });
+    var pointBindings = formula.bindings.filter(function (b) { return (b.key && !(b.column && !b.match)) || b.constant; });
+    var toRows = function (source) {
+        return Array.isArray(source)
+            ? source
+            : typeof source === 'string'
+                ? parseTable(source)
+                : [];
+    };
+    var sumMatch = sumBindings.length ? SUM_RE.exec(formula.formula) : null;
+    // The summand may draw from several parallel tables (e.g. one for values, one
+    // for factors); parse each once and align them by row index.
+    var tableRows = {};
+    if (sumMatch) {
+        sumBindings.forEach(function (b) {
+            var key = b.key;
+            if (!(key in tableRows))
+                tableRows[key] = toRows(values[key]);
+        });
+    }
+    var rowCount = sumMatch
+        ? Math.max.apply(Math, __spreadArray([0], __read(sumBindings.map(function (b) { return tableRows[b.key].length; })), false)) : 0;
+    // Resolve a point binding to a single value: a fixed constant, a scalar lookup,
+    // or the selected row's column for a row selection (`match` = id prefix).
+    var pointValue = function (b) {
+        if (b.constant !== undefined)
+            return b.constant || undefined;
+        if (!b.match)
+            return values[b.key];
+        var row = toRows(values[b.key]).find(function (r) { var _a; return String((_a = Object.values(r)[0]) !== null && _a !== void 0 ? _a : '').startsWith(b.match); });
+        return row ? row[b.column] : undefined;
+    };
+    // How a binding is referenced in the `data-key` attribute.
+    var ref = function (b) {
+        return b.constant !== undefined
+            ? 'const'
+            : "".concat(b.key).concat(b.match ? '@' + b.match : '').concat(b.column ? ':' + b.column : '');
+    };
+    // Expand the `\sum` inline, wrapping each row value with `wrapRow`. Returns the
+    // original formula when there is no table to expand over.
+    var expand = function (wrapRow) {
+        if (!sumMatch || !rowCount)
+            return formula.formula;
+        var before = formula.formula.slice(0, sumMatch.index);
+        var summand = formula.formula.slice(sumMatch.index + sumMatch[0].length);
+        var symbols = sumBindings.map(function (b) { return b.symbol; });
+        var terms = Array.from({ length: rowCount }, function (_, i) {
+            return '(' +
+                splitOnSymbols(summand, symbols)
+                    .map(function (seg) {
+                    if (seg.text !== undefined)
+                        return seg.text;
+                    var b = sumBindings.find(function (x) { return x.symbol === seg.symbol; });
+                    var row = tableRows[b.key][i];
+                    var value = row ? formatValue(row[b.column]) : null;
+                    return value === null ? seg.symbol : wrapRow(b, value);
+                })
+                    .join('') +
+                ')';
+        });
+        return before + terms.join(' + ');
+    };
+    // Substitute the point (single-value) symbols over a working string.
+    var substitutePoints = function (working, wrap) {
+        return splitOnSymbols(working, pointBindings.map(function (b) { return b.symbol; }))
+            .map(function (seg) {
+            if (seg.text !== undefined)
+                return seg.text;
+            var b = pointBindings.find(function (x) { return x.symbol === seg.symbol; });
+            return wrap(b, seg.symbol, formatValue(pointValue(b)));
+        })
+            .join('');
+    };
+    var substituted = substitutePoints(expand(function (b, v) { return "\\htmlData{key=".concat(ref(b), "}{").concat(v, "}"); }), function (b, symbol, value) {
+        return value === null ? symbol : "\\htmlData{key=".concat(ref(b), "}{").concat(value, "}");
+    });
+    var annotated = substitutePoints(expand(function (b, v) { return "\\htmlData{key=".concat(ref(b), ", value=").concat(v, "}{").concat(v, "}"); }), function (b, symbol, value) {
+        return "\\htmlData{key=".concat(ref(b), ", value=").concat(value === null ? 'na' : value, "}{").concat(symbol, "}");
+    });
+    return { symbolic: formula.formula, substituted: substituted, annotated: annotated };
+};
+exports.renderFormula = renderFormula;

package/cjs/index.d.ts

@@ -1,4 +1,5 @@
 export * from './config';
+export * from './formulas';
 export * from './models';
 export * from './utils';
 export * from './validate-config';

package/cjs/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./config"), exports);
+__exportStar(require("./formulas"), exports);
 __exportStar(require("./models"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./validate-config"), exports);

package/cjs/version.d.ts

@@ -1 +1 @@
-export declare const ENGINE_VERSION = "0.81.6";
+export declare const ENGINE_VERSION = "0.82.1";

package/cjs/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ENGINE_VERSION = void 0;
-exports.ENGINE_VERSION = '0.81.6';
+exports.ENGINE_VERSION = '0.82.1';

package/esm/formulas.d.ts

@@ -0,0 +1,99 @@
+import { IModel } from './models';
+/**
+ * A single symbol in a formula, optionally bound to a value logged in the jlog.
+ */
+export interface IFormulaBinding {
+    /**
+     * The KaTeX symbol as written in the formula, e.g. `E_{CH4}`, `GE`.
+     */
+    symbol: string;
+    /**
+     * Human-readable description from the formula's "Where:" list.
+     */
+    description?: string;
+    /**
+     * The jlog field this symbol resolves to. `value` is the result (left-hand
+     * side); any other key is looked up on the model's jlog entry. Absent for
+     * constants / display-only symbols. When `column` is set, this is the log key
+     * of a packed `log_as_table` string rather than a scalar.
+     */
+    key?: string;
+    /**
+     * A value inside a packed `log_as_table` string: the column to read.
+     * - with no `match`, the symbol sits under a `\sum` and is expanded once per
+     *   row (e.g. `\sum_i M_i \times EF_i` → `(32 × 0.166) + (13 × 0.495)`);
+     * - with `match`, it resolves to a single row (row selection, see `match`).
+     */
+    column?: string;
+    /**
+     * Row selection: pick the one row of the `key` table whose id (first column)
+     * starts with this value, then read `column` from it. Resolves to a single
+     * value, e.g. `NH_3\text{-}N` → the `emission-value` of the row `nh3…`.
+     */
+    match?: string;
+    /**
+     * A fixed constant (not logged): the symbol always substitutes to this literal
+     * (e.g. `ER` → `2`) and is excluded from coverage. Empty string marks a
+     * constant with no display value.
+     */
+    constant?: string;
+}
+/**
+ * A KaTeX formula extracted from a model's documentation, with the bindings
+ * needed to substitute its symbols with values logged at runtime.
+ */
+export interface IFormula {
+    /**
+     * The KaTeX source (without the `$$` delimiters).
+     */
+    formula: string;
+    /**
+     * The symbols in the formula, in "Where:" list order.
+     */
+    bindings: IFormulaBinding[];
+}
+/**
+ * Get the formulas (if any) for a model-links entry. A documentation file may
+ * define several formulas, so this always returns an array (empty when none).
+ */
+export declare const getFormulasForLink: (link: Pick<IModel, "docPath">) => IFormula[];
+/**
+ * Get the formulas for a model, addressed by the same parameters used to look
+ * up a model in model-links.json (e.g. `{ model, term }` or `{ model, modelKey }`).
+ * Returns an empty array when the model is unknown or has no formulas.
+ */
+export declare const getFormulas: (model: Partial<IModel>) => IFormula[];
+/**
+ * The result of rendering a formula against a set of values, as KaTeX source
+ * strings (without the `$$` delimiters). Feed these to `katex.render`.
+ */
+export interface IRenderedFormula {
+    /**
+     * The formula as authored, e.g. `E_{CH4} = (GE \times Y_m) / 55.65`.
+     */
+    symbolic: string;
+    /**
+     * Symbols replaced by their values, e.g. `59.24 = (52340 \times 0.063) / 55.65`.
+     * A symbol with no value is left as the symbol.
+     */
+    substituted: string;
+    /**
+     * Symbols kept, each wrapped in `\htmlData{key=..., value=...}{symbol}` so the
+     * rendered DOM node carries `data-key` / `data-value` for tooltips or toggling.
+     * Requires `trust: (ctx) => ctx.command === '\\htmlData'` in the KaTeX options.
+     */
+    annotated: string;
+}
+/**
+ * Render a formula against a set of values, producing the KaTeX strings needed
+ * to display it symbolically, with substituted values, or annotated for
+ * interaction. `values` maps each binding `key` to its value for one execution
+ * (typically pulled from the model's jlog entry, plus `value` for the result);
+ * the caller decides where those values come from, so this stays agnostic.
+ * Symbols without a value in `values` are left symbolic.
+ *
+ * A `\sum` whose summand symbols are bound to table columns (`key`+`column`) is
+ * expanded once per row, provided `values[key]` holds the packed table string
+ * (or an array of row objects). Without the table it stays symbolic.
+ */
+export declare const renderFormula: (formula: IFormula, values: Record<string, unknown>) => IRenderedFormula;

package/esm/formulas.js

@@ -0,0 +1,156 @@
+import * as data from '../formulas/index.json';
+import { findMatchingModel } from './utils';
+// keyed by the same `docPath` found on model-links.json entries
+const formulas = data;
+/**
+ * Get the formulas (if any) for a model-links entry. A documentation file may
+ * define several formulas, so this always returns an array (empty when none).
+ */
+export const getFormulasForLink = (link) => (link && formulas[link.docPath]) || [];
+/**
+ * Get the formulas for a model, addressed by the same parameters used to look
+ * up a model in model-links.json (e.g. `{ model, term }` or `{ model, modelKey }`).
+ * Returns an empty array when the model is unknown or has no formulas.
+ */
+export const getFormulas = (model) => {
+    const link = findMatchingModel(model);
+    return link ? getFormulasForLink(link) : [];
+};
+const isAlpha = (char) => /[a-zA-Z]/.test(char || '');
+// Split a KaTeX string on the declared symbols only (longest-first), so
+// `\times`, subscripts and constants are never touched.
+const splitOnSymbols = (formula, symbols) => {
+    const ordered = [...symbols].sort((a, b) => b.length - a.length);
+    const segments = [];
+    let i = 0;
+    while (i < formula.length) {
+        const symbol = ordered.find((s) => formula.startsWith(s, i) &&
+            !isAlpha(formula[i - 1]) &&
+            !isAlpha(formula[i + s.length]) &&
+            formula[i - 1] !== '\\');
+        if (symbol) {
+            segments.push({ symbol });
+            i += symbol.length;
+        }
+        else {
+            let j = i + 1;
+            while (j < formula.length && !ordered.some((s) => formula.startsWith(s, j)))
+                j++;
+            segments.push({ text: formula.slice(i, j) });
+            i = j;
+        }
+    }
+    return segments;
+};
+const round4 = (n) => String(+n.toPrecision(4));
+// Round numeric-looking strings, leave everything else (e.g. "kg FPCM") as-is.
+const formatNumericString = (value) => {
+    const asNumber = Number(value);
+    return value !== '' && Number.isFinite(asNumber) ? round4(asNumber) : value;
+};
+const formatValue = (value) => {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'number')
+        return round4(value);
+    return formatNumericString(String(value));
+};
+// `\sum` with an optional index subscript (`_i`, `_{s=1}`, ...) and upper bound
+// superscript (`^S`, `^{S}`), and trailing space.
+const SUM_RE = /\\sum(?:_\{[^}]*\}|_[^\s{])?(?:\^\{[^}]*\}|\^[^\s{])?\s*/;
+// Parse a packed `log_as_table` string into rows: rows split on `;`, columns on
+// `_`, each column a `key:value` pair (values never contain `_` or `:`).
+const parseTable = (packed) => packed
+    .split(';')
+    .filter(Boolean)
+    .map((row) => row.split('_').reduce((cols, pair) => {
+    const at = pair.indexOf(':');
+    if (at !== -1)
+        cols[pair.slice(0, at)] = pair.slice(at + 1);
+    return cols;
+}, {}));
+/**
+ * Render a formula against a set of values, producing the KaTeX strings needed
+ * to display it symbolically, with substituted values, or annotated for
+ * interaction. `values` maps each binding `key` to its value for one execution
+ * (typically pulled from the model's jlog entry, plus `value` for the result);
+ * the caller decides where those values come from, so this stays agnostic.
+ * Symbols without a value in `values` are left symbolic.
+ *
+ * A `\sum` whose summand symbols are bound to table columns (`key`+`column`) is
+ * expanded once per row, provided `values[key]` holds the packed table string
+ * (or an array of row objects). Without the table it stays symbolic.
+ */
+export const renderFormula = (formula, values) => {
+    // sum: a per-row column under a \sum. point: a single value — a scalar, a row
+    // selection (`match` + `column`), or a fixed constant.
+    const sumBindings = formula.bindings.filter((b) => b.key && b.column && !b.match);
+    const pointBindings = formula.bindings.filter((b) => (b.key && !(b.column && !b.match)) || b.constant);
+    const toRows = (source) => Array.isArray(source)
+        ? source
+        : typeof source === 'string'
+            ? parseTable(source)
+            : [];
+    const sumMatch = sumBindings.length ? SUM_RE.exec(formula.formula) : null;
+    // The summand may draw from several parallel tables (e.g. one for values, one
+    // for factors); parse each once and align them by row index.
+    const tableRows = {};
+    if (sumMatch) {
+        sumBindings.forEach((b) => {
+            const key = b.key;
+            if (!(key in tableRows))
+                tableRows[key] = toRows(values[key]);
+        });
+    }
+    const rowCount = sumMatch
+        ? Math.max(0, ...sumBindings.map((b) => tableRows[b.key].length))
+        : 0;
+    // Resolve a point binding to a single value: a fixed constant, a scalar lookup,
+    // or the selected row's column for a row selection (`match` = id prefix).
+    const pointValue = (b) => {
+        if (b.constant !== undefined)
+            return b.constant || undefined;
+        if (!b.match)
+            return values[b.key];
+        const row = toRows(values[b.key]).find((r) => { var _a; return String((_a = Object.values(r)[0]) !== null && _a !== void 0 ? _a : '').startsWith(b.match); });
+        return row ? row[b.column] : undefined;
+    };
+    // How a binding is referenced in the `data-key` attribute.
+    const ref = (b) => b.constant !== undefined
+        ? 'const'
+        : `${b.key}${b.match ? '@' + b.match : ''}${b.column ? ':' + b.column : ''}`;
+    // Expand the `\sum` inline, wrapping each row value with `wrapRow`. Returns the
+    // original formula when there is no table to expand over.
+    const expand = (wrapRow) => {
+        if (!sumMatch || !rowCount)
+            return formula.formula;
+        const before = formula.formula.slice(0, sumMatch.index);
+        const summand = formula.formula.slice(sumMatch.index + sumMatch[0].length);
+        const symbols = sumBindings.map((b) => b.symbol);
+        const terms = Array.from({ length: rowCount }, (_, i) => '(' +
+            splitOnSymbols(summand, symbols)
+                .map((seg) => {
+                if (seg.text !== undefined)
+                    return seg.text;
+                const b = sumBindings.find((x) => x.symbol === seg.symbol);
+                const row = tableRows[b.key][i];
+                const value = row ? formatValue(row[b.column]) : null;
+                return value === null ? seg.symbol : wrapRow(b, value);
+            })
+                .join('') +
+            ')');
+        return before + terms.join(' + ');
+    };
+    // Substitute the point (single-value) symbols over a working string.
+    const substitutePoints = (working, wrap) => splitOnSymbols(working, pointBindings.map((b) => b.symbol))
+        .map((seg) => {
+        if (seg.text !== undefined)
+            return seg.text;
+        const b = pointBindings.find((x) => x.symbol === seg.symbol);
+        return wrap(b, seg.symbol, formatValue(pointValue(b)));
+    })
+        .join('');
+    const substituted = substitutePoints(expand((b, v) => `\\htmlData{key=${ref(b)}}{${v}}`), (b, symbol, value) => value === null ? symbol : `\\htmlData{key=${ref(b)}}{${value}}`);
+    const annotated = substitutePoints(expand((b, v) => `\\htmlData{key=${ref(b)}, value=${v}}{${v}}`), (b, symbol, value) => `\\htmlData{key=${ref(b)}, value=${value === null ? 'na' : value}}{${symbol}}`);
+    return { symbolic: formula.formula, substituted, annotated };
+};

package/esm/index.d.ts

@@ -1,4 +1,5 @@
 export * from './config';
+export * from './formulas';
 export * from './models';
 export * from './utils';
 export * from './validate-config';

package/esm/index.js

@@ -1,4 +1,5 @@
 export * from './config';
+export * from './formulas';
 export * from './models';
 export * from './utils';
 export * from './validate-config';

package/esm/version.d.ts

@@ -1 +1 @@
-export declare const ENGINE_VERSION = "0.81.6";
+export declare const ENGINE_VERSION = "0.82.1";

package/esm/version.js

@@ -1 +1 @@
-export const ENGINE_VERSION = '0.81.6';
+export const ENGINE_VERSION = '0.82.1';