@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/core/formula-references.js

@@ -0,0 +1,173 @@
+import { MAX_COLUMN, MAX_ROW, numberToColumn, tryColumnToNumber } from './address.js';
+import { scanFormula, skipOpaque } from './formula-scan.js';
+import { REF_ERROR } from './value.js';
+const SHIFTABLE_REFERENCE = /(?<![A-Za-z0-9_.])(?:(\$?)([A-Z]{1,3}):(\$?)([A-Z]{1,3})|(\$?)([0-9]{1,7}):(\$?)([0-9]{1,7})|(\$?)([A-Z]{1,3})(\$?)([0-9]{1,7}))(?![A-Za-z0-9_.!(])/g;
+export function translateFormula(formula, colDelta, rowDelta) {
+    if (colDelta === 0 && rowDelta === 0)
+        return formula;
+    const column = (anchor, letters) => {
+        const decoded = tryColumnToNumber(letters);
+        if (decoded === undefined)
+            return undefined;
+        const col = anchor === '$' ? decoded : decoded + colDelta;
+        return col < 1 || col > MAX_COLUMN ? undefined : `${anchor}${numberToColumn(col)}`;
+    };
+    const row = (anchor, digits) => {
+        const index = anchor === '$' ? Number(digits) : Number(digits) + rowDelta;
+        return index < 1 || index > MAX_ROW ? undefined : `${anchor}${index}`;
+    };
+    const range = (first, last) => first === undefined || last === undefined ? REF_ERROR : `${first}:${last}`;
+    return scanFormula(formula, (code) => code.replace(SHIFTABLE_REFERENCE, (_match, firstColumnAnchor, firstColumn, lastColumnAnchor, lastColumn, firstRowAnchor, firstRow, lastRowAnchor, lastRow, cellColumnAnchor, cellColumn, cellRowAnchor, cellRow) => {
+        if (firstColumn !== undefined && lastColumn !== undefined) {
+            return range(column(firstColumnAnchor ?? '', firstColumn), column(lastColumnAnchor ?? '', lastColumn));
+        }
+        if (firstRow !== undefined && lastRow !== undefined) {
+            return range(row(firstRowAnchor ?? '', firstRow), row(lastRowAnchor ?? '', lastRow));
+        }
+        const shiftedColumn = column(cellColumnAnchor ?? '', cellColumn ?? '');
+        const shiftedRow = row(cellRowAnchor ?? '', cellRow ?? '');
+        return shiftedColumn === undefined || shiftedRow === undefined
+            ? REF_ERROR
+            : `${shiftedColumn}${shiftedRow}`;
+    }));
+}
+const REFERENCE = /(?:(\$?)([A-Z]{1,3})(\$?)(\d{1,7}):(\$?)([A-Z]{1,3})(\$?)(\d{1,7})|(\$?)([A-Z]{1,3})(\$?)(\d{1,7})|(\$?)([A-Z]{1,3}):(\$?)([A-Z]{1,3})|(\$?)(\d{1,7}):(\$?)(\d{1,7}))(?![\p{L}\p{N}_.(![])/uy;
+const NAME_CHAR = /[\p{L}\p{N}_.\\]/u;
+export function spliceFormula(formula, home, edit) {
+    const target = edit.sheet.toLowerCase();
+    const homeIsTarget = home !== undefined && home.toLowerCase() === target;
+    let out = '';
+    let i = 0;
+    const n = formula.length;
+    const atTokenStart = (index) => index === 0 || !NAME_CHAR.test(formula[index - 1] ?? '');
+    const reference = (moves) => {
+        REFERENCE.lastIndex = i;
+        const match = REFERENCE.exec(formula);
+        if (match === null)
+            return false;
+        out += moves ? moved(match, edit.splice) : match[0];
+        i = REFERENCE.lastIndex;
+        return true;
+    };
+    while (i < n) {
+        const ch = formula[i] ?? '';
+        if (ch === '"') {
+            const end = skipOpaque(formula, i);
+            out += formula.slice(i, end);
+            i = end;
+            continue;
+        }
+        if (ch === '[') {
+            const end = skipOpaque(formula, i);
+            out += formula.slice(i, end);
+            i = end;
+            const name = nameRun(formula, i);
+            if (name > i && formula[name] === '!') {
+                out += formula.slice(i, name + 1);
+                i = name + 1;
+                reference(false);
+            }
+            continue;
+        }
+        if (ch === "'") {
+            const end = skipOpaque(formula, i);
+            const quoted = formula.slice(i + 1, end - 1).replaceAll("''", "'");
+            out += formula.slice(i, end);
+            i = end;
+            if (formula[i] !== '!')
+                continue;
+            out += '!';
+            i += 1;
+            reference(!quoted.includes(':') && !quoted.includes('[') && quoted.toLowerCase() === target);
+            continue;
+        }
+        if (atTokenStart(i) && NAME_CHAR.test(ch)) {
+            const end = nameRun(formula, i);
+            const next = formula[end];
+            if (next === '!') {
+                out += formula.slice(i, end + 1);
+                const name = formula.slice(i, end);
+                i = end + 1;
+                reference(name.toLowerCase() === target);
+                continue;
+            }
+            if (next === ':') {
+                const last = nameRun(formula, end + 1);
+                if (last > end + 1 && formula[last] === '!') {
+                    out += formula.slice(i, last + 1);
+                    i = last + 1;
+                    reference(false);
+                    continue;
+                }
+            }
+            if (reference(homeIsTarget))
+                continue;
+            out += formula.slice(i, end);
+            i = end;
+            continue;
+        }
+        if (atTokenStart(i) && ch === '$' && reference(homeIsTarget))
+            continue;
+        out += ch;
+        i += 1;
+    }
+    return out === formula ? formula : out;
+}
+function nameRun(formula, start) {
+    let j = start;
+    while (j < formula.length && NAME_CHAR.test(formula[j] ?? ''))
+        j += 1;
+    return j;
+}
+function moved(match, splice) {
+    const g = (index) => match[index] ?? '';
+    const ends = match[2] !== undefined
+        ? [
+            [g(1), g(2), g(3), g(4)],
+            [g(5), g(6), g(7), g(8)],
+        ]
+        : match[10] !== undefined
+            ? [[g(9), g(10), g(11), g(12)]]
+            : match[14] !== undefined
+                ? [
+                    [g(13), g(14), '', ''],
+                    [g(15), g(16), '', ''],
+                ]
+                : [
+                    ['', '', g(17), g(18)],
+                    ['', '', g(19), g(20)],
+                ];
+    const rows = splice.axis === 'row';
+    const lines = ends.map(([, letters = '', , digits = '']) => (rows ? digits : letters));
+    if (lines.includes(''))
+        return match[0];
+    const [first = 0, last = first] = lines.map((line) => (rows ? Number(line) : columnOf(line)));
+    const edges = movedEdges(Math.min(first, last), Math.max(first, last), splice, rows ? MAX_ROW : MAX_COLUMN);
+    if (edges === undefined)
+        return REF_ERROR;
+    const placed = first <= last ? edges : [edges[1], edges[0]];
+    return ends
+        .map(([columnAnchor = '', letters = '', rowAnchor = '', digits = ''], i) => {
+        const at = placed[i] ?? 0;
+        return rows
+            ? `${columnAnchor}${letters}${rowAnchor}${at}`
+            : `${columnAnchor}${numberToColumn(at)}${rowAnchor}${digits}`;
+    })
+        .join(':');
+}
+function columnOf(letters) {
+    return tryColumnToNumber(letters) ?? MAX_COLUMN + 1;
+}
+function movedEdges(lo, hi, splice, bound) {
+    if (hi > bound)
+        return [lo, hi];
+    const { start, count, delta } = splice;
+    const end = start + count;
+    if (lo >= start && hi < end)
+        return undefined;
+    const top = lo < start ? lo : lo < end ? end + delta : lo + delta;
+    const bottom = hi < start ? hi : hi < end ? start - 1 : hi + delta;
+    if (top > bound)
+        return undefined;
+    return [top, Math.min(bottom, bound)];
+}

package/dist/core/formula-scan.d.ts

@@ -0,0 +1,2 @@
+export declare function skipOpaque(formula: string, index: number): number;
+export declare function scanFormula(formula: string, transform: (code: string) => string): string;

package/dist/core/formula-scan.js

@@ -0,0 +1,58 @@
+export function skipOpaque(formula, index) {
+    const opener = formula[index];
+    const n = formula.length;
+    if (opener === '"' || opener === "'") {
+        let j = index + 1;
+        while (j < n) {
+            if (formula[j] === opener) {
+                if (formula[j + 1] === opener) {
+                    j += 2;
+                    continue;
+                }
+                return j + 1;
+            }
+            j += 1;
+        }
+        return n;
+    }
+    if (opener === '[') {
+        let depth = 0;
+        let j = index;
+        while (j < n) {
+            const ch = formula[j];
+            if (ch === "'") {
+                j += 2;
+                continue;
+            }
+            if (ch === '[')
+                depth += 1;
+            else if (ch === ']') {
+                depth -= 1;
+                if (depth === 0)
+                    return j + 1;
+            }
+            j += 1;
+        }
+        return n;
+    }
+    return index;
+}
+export function scanFormula(formula, transform) {
+    let out = '';
+    let codeStart = 0;
+    let i = 0;
+    const n = formula.length;
+    while (i < n) {
+        const past = skipOpaque(formula, i);
+        if (past > i) {
+            out += transform(formula.slice(codeStart, i));
+            out += formula.slice(i, past);
+            i = past;
+            codeStart = past;
+        }
+        else {
+            i += 1;
+        }
+    }
+    return out + transform(formula.slice(codeStart));
+}

package/dist/core/formula.d.ts

@@ -1,6 +1,6 @@
 /**
  * Quote a sheet name for use in a reference exactly when Excel would: a name that is not a plain
- * identifier, or that would read as a cell address, is wrapped in single quotes with its internal
+ * identifier, or that would read as a reference, is wrapped in single quotes with its internal
  * quotes doubled, and a simple name is left bare. Shared by everything that *builds* a qualified
  * reference: the `_FilterDatabase` name the writer derives from an autofilter, and the `.xlsb`
  * reader's Ptg decoder, which has only a sheet index to work from and must spell the prefix itself.
@@ -11,7 +11,8 @@
  */
 export declare function quoteSheetName(name: string, last?: string): string;
 /**
- * Prefix every modern function called by its plain name with `_xlfn.` so Excel accepts the stored
+ * Prefix every future function called by its plain name with the prefix Excel stores it under
+ * (`_xlfn.`, or `_xlfn._xlws.` for the worksheet-only FILTER, SORT and PY) so Excel accepts the stored
  * formula. Names already prefixed are left alone (never doubled), unknown/legacy functions pass
  * through untouched, and opaque regions (string literals, sheet names, structured references) are
  * preserved verbatim. No other rewriting occurs: in particular no `@` implicit-intersection operator
@@ -19,31 +20,89 @@ export declare function quoteSheetName(name: string, last?: string): string;
  */
 export declare function mangleFunctions(formula: string): string;
 /**
- * Strip the `_xlfn.` function prefix and the `_xlpm.` LET-parameter prefix back to the plain names,
- * so the model holds the readable form regardless of how a file stored it. Opaque regions (string
- * literals, sheet names, structured references) are left untouched.
+ * Strip the `_xlfn.` function prefix (with the `_xlws.` a worksheet-only function adds after it), the
+ * `_xlpm.` LET-parameter prefix and the `_xleta.` prefix of a function passed as a value back to the
+ * plain names, so the model holds the readable form regardless of how a file stored it. Opaque regions
+ * (string literals, sheet names, structured references) are left untouched.
+ *
+ * `definedNames` is every name the workbook defines, whatever its scope, as {@link definedNameKeys}
+ * spells them. A function passed as a value keeps its prefix when one of them is spelled like it,
+ * since the bare name could then read as that name. Excel's own formula text does the same: with a
+ * `LEN` defined only on another sheet, `Range.Formula` still reports `MAP(A1:A3,_xleta.LEN)`.
  */
-export declare function unmangleFunctions(formula: string): string;
+export declare function unmangleFunctions(formula: string, definedNames: ReadonlySet<string>): string;
 /**
  * Prefix every LET/LAMBDA parameter identifier with `_xlpm.`, at its declaration and at each
  * reference within the binding call's parentheses, so Excel accepts the stored formula. The prefix
  * is lexically scoped: a name is only rewritten inside the call that binds it, opaque regions are
  * copied verbatim, and a lambda-valued parameter used as a call (`f(…)`) is prefixed too. Formulas
- * with no LET/LAMBDA pass through unchanged.
+ * with no LET/LAMBDA pass through unchanged. A parameter matches case-insensitively, as Excel's names
+ * do, and every reference to it is written in the spelling it was declared with, as Excel writes it.
  */
 export declare function mangleParams(formula: string): string;
+/**
+ * Prefix every built-in function a formula passes as a value with `_xleta.`, uppercased as Excel writes
+ * it, so Excel reads the function rather than a defined name spelled like it. A value is any use that
+ * is not a call: the `SUM` in `BYROW(A1:A3,SUM)`, in `LET(f,SUM,f(A1:A3))`, in `SUM+1`.
+ *
+ * `namesInScope` is {@link formulaNamesInScope} for where the formula sits, and a function name among
+ * them stays bare, because there it means the defined name. Run after {@link mangleParams}, so that a
+ * LET or LAMBDA parameter spelled like a function already carries `_xlpm.`.
+ *
+ * A name is not a value where it names a sheet (`SUM!A1`, `SUM:Other!A1`) or a table (`Rate[Amount]`),
+ * where a sheet or workbook qualifies it (`S1!SUM`), or inside an error literal: the `N` of `#N/A` is a
+ * function too.
+ */
+export declare function mangleFunctionValues(formula: string, namesInScope: ReadonlySet<string>): string;
+/**
+ * How a formula compares names: uppercased, as Excel's names are case-insensitive. The reader's form of
+ * the set {@link unmangleFunctions} takes, built from every name the workbook defines.
+ */
+export declare function definedNameKeys(names: readonly {
+    readonly name: string;
+}[]): ReadonlySet<string>;
+/**
+ * The names a bare name in a formula resolves to, as {@link definedNameKeys} spells them: every
+ * workbook-level name, and the names scoped to `sheet`. For a cell formula `sheet` is the cell's own
+ * sheet; for a defined name's formula it is the sheet that name is scoped to, and `undefined` for a
+ * workbook-level name. A sheet is matched case-insensitively, as it is everywhere else.
+ */
+export declare function formulaNamesInScope(names: readonly {
+    readonly name: string;
+    readonly scope?: string | undefined;
+}[], sheet: string | undefined): ReadonlySet<string>;
 /**
  * Mangle a model formula into its on-disk form: LET/LAMBDA parameter names first (`_xlpm.`), then the
- * modern-function prefix (`_xlfn.`). Ordering matters: parameter mangling reads the plain LET/LAMBDA
- * names before the function pass qualifies them. The inverse for both prefixes is unmangleFunctions.
+ * functions it passes as values (`_xleta.`), then the modern-function prefix (`_xlfn.`). Ordering
+ * matters: parameter mangling reads the plain LET/LAMBDA names before the function pass qualifies them,
+ * and a parameter spelled like a function has to carry `_xlpm.` before the value pass looks for
+ * functions. `namesInScope` is {@link formulaNamesInScope} for where the formula sits. The inverse for
+ * every prefix is unmangleFunctions.
+ */
+export declare function mangleFormula(formula: string, namesInScope: ReadonlySet<string>): string;
+/**
+ * A number as it appears *inside formula text*, which is not the same serialisation as an
+ * attribute's.
+ *
+ * Two divergences, both found as drift rather than designed. The exponent's case: Excel writes
+ * `1E+21` where JavaScript writes `1e+21`, so the same literal read back through the two codecs
+ * produced two different formula strings depending on which file it came from -- exactly the
+ * asymmetry `cell-value.ts` and `cell-accumulator.ts` were extracted to prevent. And the finiteness
+ * guard: the BIFF12 decoder had a private copy of this function with none, so a `PtgNum` whose eight
+ * bytes decode to an infinity produced the formula text `INFINITY`, which the writer then escaped as
+ * ordinary text into a package Excel reports as damaged.
+ *
+ * Here rather than in `xml/xml.ts` beside the attribute form, because formula text is not XML: the
+ * BIFF12 codec produces it too, and reaching the XML serialiser for it put the whole write half of
+ * that module into the closure of an entry that has no XML in it.
+ *
+ * @throws {AuthoringError} when the value is not finite.
  */
-export declare function mangleFormula(formula: string): string;
+export declare function formulaNumberLiteral(value: number): string;
 /**
- * Shift every relative cell reference in a formula by `colDelta` columns and `rowDelta` rows, leaving
- * absolute (`$`-anchored) axes fixed. This is how a shared-formula clone recovers its own formula from
- * the master's: a master `A1*2` shared one row down reads back as `A2*2`, and `$A$1*B1` shared one row
- * and one column across as `$A$1*C2`. String literals, single-quoted sheet names, and bracketed
- * structured references are copied verbatim, and a sheet-qualified reference shifts the cell while its
- * sheet name is untouched. Function names and defined names carry no row digits, so they pass through.
+ * Render a formula operand for serialisation: a number becomes its literal, a string is stripped of
+ * the single optional leading '=' an author may write (OOXML stores the expression without it, e.g.
+ * `=A1>0` on disk is `A1>0`). The result is unescaped: the caller escapes it for its target, whether
+ * that is element text or an attribute value.
  */
-export declare function translateFormula(formula: string, colDelta: number, rowDelta: number): string;
+export declare function stripFormulaEquals(value: string | number): string;

package/dist/core/formula.js

@@ -1,77 +1,32 @@
-import { columnToNumber, numberToColumn } from './address.js';
-import { MODERN_FUNCTIONS } from './modern-functions.js';
-const XLFN = '_xlfn.';
+import { assertWritableNumber } from '../errors.js';
+import { nameReadsAsReference } from './address.js';
+import { scanFormula, skipOpaque } from './formula-scan.js';
+import { FUNCTION_VALUE_NAMES } from './function-values.js';
+import { FUTURE_FUNCTION_PREFIXES } from './future-functions.js';
 const XLPM = '_xlpm.';
+const XLETA = '_xleta.';
 export function quoteSheetName(name, last) {
     const names = last === undefined ? [name] : [name, last];
     const joined = names.join(':');
     return names.every(isBareSheetName) ? joined : `'${joined.replace(/'/g, "''")}'`;
 }
 function isBareSheetName(name) {
-    return /^[A-Za-z_][A-Za-z0-9_.]*$/.test(name) && !/^[A-Za-z]{1,3}\d+$/.test(name);
+    return /^[A-Za-z_][A-Za-z0-9_.]*$/.test(name) && !nameReadsAsReference(name);
 }
 const SCOPING_FUNCTIONS = new Set(['LET', 'LAMBDA']);
 const FUNCTION_CALL = /(?<![A-Za-z0-9_.])([A-Za-z_][A-Za-z0-9_.]*)(\s*\()/g;
-const PREFIX = /_xlfn\.|_xlpm\./g;
-function skipOpaque(formula, index) {
-    const opener = formula[index];
-    const n = formula.length;
-    if (opener === '"' || opener === "'") {
-        let j = index + 1;
-        while (j < n) {
-            if (formula[j] === opener) {
-                if (formula[j + 1] === opener) {
-                    j += 2;
-                    continue;
-                }
-                return j + 1;
-            }
-            j += 1;
-        }
-        return n;
-    }
-    if (opener === '[') {
-        let depth = 0;
-        let j = index;
-        while (j < n) {
-            const ch = formula[j];
-            if (ch === '[')
-                depth += 1;
-            else if (ch === ']') {
-                depth -= 1;
-                if (depth === 0)
-                    return j + 1;
-            }
-            j += 1;
-        }
-        return n;
-    }
-    return index;
-}
-function scanFormula(formula, transform) {
-    let out = '';
-    let codeStart = 0;
-    let i = 0;
-    const n = formula.length;
-    while (i < n) {
-        const past = skipOpaque(formula, i);
-        if (past > i) {
-            out += transform(formula.slice(codeStart, i));
-            out += formula.slice(i, past);
-            i = past;
-            codeStart = past;
-        }
-        else {
-            i += 1;
-        }
-    }
-    return out + transform(formula.slice(codeStart));
-}
+const PREFIX = /_xlfn\.(?:_xlws\.)?|_xlpm\./g;
+const FUNCTION_VALUE_PREFIX = /_xleta\.([A-Za-z_][A-Za-z0-9_.]*)/g;
 export function mangleFunctions(formula) {
-    return scanFormula(formula, (code) => code.replace(FUNCTION_CALL, (whole, name, open) => MODERN_FUNCTIONS.has(name.toUpperCase()) ? `${XLFN}${name}${open}` : whole));
+    return scanFormula(formula, (code) => code.replace(FUNCTION_CALL, (whole, name, open) => {
+        const prefix = FUTURE_FUNCTION_PREFIXES.get(name.toUpperCase());
+        return prefix === undefined ? whole : `${prefix}${name}${open}`;
+    }));
 }
-export function unmangleFunctions(formula) {
-    return scanFormula(formula, (code) => code.replace(PREFIX, ''));
+export function unmangleFunctions(formula, definedNames) {
+    return scanFormula(formula, (code) => code
+        .replace(PREFIX, '')
+        .replace(FUNCTION_VALUE_PREFIX, (whole, name) => definedNames.has(name.toUpperCase()) ? whole : name));
 }
 const NAME_START = /[A-Za-z_]/;
 const NAME_CHAR = /[A-Za-z0-9_.]/;
@@ -134,13 +89,13 @@ function boundName(formula, [start, end]) {
     return name.startsWith(XLPM) ? undefined : name;
 }
 function parameterNames(formula, keyword, args) {
-    const names = new Set();
+    const names = new Map();
     const isLambda = keyword === 'LAMBDA';
     for (let a = 0; a < args.length - 1; a += 1) {
         if (isLambda || a % 2 === 0) {
             const name = boundName(formula, args[a]);
-            if (name !== undefined)
-                names.add(name);
+            if (name !== undefined && !names.has(name.toUpperCase()))
+                names.set(name.toUpperCase(), name);
         }
     }
     return names;
@@ -150,7 +105,15 @@ export function mangleParams(formula) {
     let i = 0;
     const n = formula.length;
     const frames = [];
-    const inScope = (name) => frames.some((frame) => frame.names.has(name));
+    const declared = (name) => {
+        const key = name.toUpperCase();
+        for (let f = frames.length - 1; f >= 0; f -= 1) {
+            const spelling = frames[f]?.names.get(key);
+            if (spelling !== undefined)
+                return spelling;
+        }
+        return undefined;
+    };
     while (i < n) {
         const top = frames[frames.length - 1];
         if (top !== undefined && i >= top.end) {
@@ -175,28 +138,72 @@ export function mangleParams(formula) {
         while (k < n && WHITESPACE.test(formula[k] ?? ''))
             k += 1;
         const heads = formula[k] === '(';
-        if (heads && SCOPING_FUNCTIONS.has(name.toUpperCase()) && !inScope(name)) {
+        if (heads && SCOPING_FUNCTIONS.has(name.toUpperCase()) && declared(name) === undefined) {
             const { close, args } = parseCall(formula, k);
             out += formula.slice(i, k + 1);
             frames.push({ end: close, names: parameterNames(formula, name.toUpperCase(), args) });
             i = k + 1;
             continue;
         }
-        out += inScope(name) ? `${XLPM}${name}` : name;
+        const spelling = declared(name);
+        out += spelling === undefined ? name : `${XLPM}${spelling}`;
         i = nameEnd;
     }
     return out;
 }
-export function mangleFormula(formula) {
-    return mangleFunctions(mangleParams(formula));
-}
-const CELL_REFERENCE = /(?<![A-Za-z0-9_.])(\$?)([A-Z]{1,3})(\$?)([0-9]{1,7})(?![A-Za-z0-9_.!(])/g;
-export function translateFormula(formula, colDelta, rowDelta) {
-    if (colDelta === 0 && rowDelta === 0)
-        return formula;
-    return scanFormula(formula, (code) => code.replace(CELL_REFERENCE, (_match, colAbs, colLetters, rowAbs, rowDigits) => {
-        const col = colAbs === '$' ? colLetters : numberToColumn(columnToNumber(colLetters) + colDelta);
-        const row = rowAbs === '$' ? rowDigits : String(Number(rowDigits) + rowDelta);
-        return `${colAbs}${col}${rowAbs}${row}`;
-    }));
+export function mangleFunctionValues(formula, namesInScope) {
+    let out = '';
+    let i = 0;
+    while (i < formula.length) {
+        const past = skipOpaque(formula, i);
+        if (past > i) {
+            out += formula.slice(i, past);
+            i = past;
+            continue;
+        }
+        const end = readName(formula, i);
+        if (end === i) {
+            out += formula.charAt(i);
+            i += 1;
+            continue;
+        }
+        const name = formula.slice(i, end);
+        out += isFunctionValue(formula, i, end, namesInScope) ? `${XLETA}${name.toUpperCase()}` : name;
+        i = end;
+    }
+    return out;
+}
+const QUALIFIES_NAME = /[A-Za-z0-9_.!#\]]/;
+const NAMES_A_CONTAINER = /[!:[]/;
+function isFunctionValue(formula, start, end, namesInScope) {
+    const name = formula.slice(start, end).toUpperCase();
+    if (!FUNCTION_VALUE_NAMES.has(name) || namesInScope.has(name))
+        return false;
+    if (QUALIFIES_NAME.test(formula.charAt(start - 1)))
+        return false;
+    if (NAMES_A_CONTAINER.test(formula.charAt(end)))
+        return false;
+    let next = end;
+    while (WHITESPACE.test(formula.charAt(next)))
+        next += 1;
+    return formula.charAt(next) !== '(';
+}
+export function definedNameKeys(names) {
+    return new Set(names.map(({ name }) => name.toUpperCase()));
+}
+export function formulaNamesInScope(names, sheet) {
+    const wanted = sheet?.toLowerCase();
+    return definedNameKeys(names.filter(({ scope }) => scope === undefined || scope.toLowerCase() === wanted));
+}
+export function mangleFormula(formula, namesInScope) {
+    return mangleFunctions(mangleFunctionValues(mangleParams(formula), namesInScope));
+}
+export function formulaNumberLiteral(value) {
+    assertWritableNumber(value);
+    return String(value).toUpperCase();
+}
+export function stripFormulaEquals(value) {
+    if (typeof value === 'number')
+        return formulaNumberLiteral(value);
+    return value.startsWith('=') ? value.slice(1) : value;
 }

package/dist/core/function-values.d.ts

@@ -0,0 +1,4 @@
+export declare const NOT_VALUES: ReadonlySet<string>;
+export declare const OLDER_FUNCTION_VALUES: readonly string[];
+/** Every built-in function Excel stores under `_xleta.` when a formula passes it as a value. */
+export declare const FUNCTION_VALUE_NAMES: ReadonlySet<string>;

package/dist/core/function-values.js

@@ -0,0 +1,58 @@
+import { FUTURE_FUNCTION_PREFIXES } from './future-functions.js';
+const OLDER_FUNCTIONS = `
+  ABS ACCRINT ACCRINTM ACOS ACOSH ADDRESS AMORDEGRC AMORLINC AND AREAS ASC ASIN ASINH ATAN ATAN2 ATANH
+  AVEDEV AVERAGE AVERAGEA AVERAGEIF AVERAGEIFS
+  BAHTTEXT BESSELI BESSELJ BESSELK BESSELY BETADIST BETAINV BIN2DEC BIN2HEX BIN2OCT BINOMDIST
+  CEILING CELL CHAR CHIDIST CHIINV CHITEST CHOOSE CLEAN CODE COLUMN COLUMNS COMBIN COMPLEX CONCATENATE
+  CONFIDENCE CONVERT CORREL COS COSH COUNT COUNTA COUNTBLANK COUNTIF COUNTIFS COUPDAYBS COUPDAYS
+  COUPDAYSNC COUPNCD COUPNUM COUPPCD COVAR CRITBINOM CUBEKPIMEMBER CUBEMEMBER CUBEMEMBERPROPERTY
+  CUBERANKEDMEMBER CUBESET CUBESETCOUNT CUBEVALUE CUMIPMT CUMPRINC
+  DATE DATEDIF DATESTRING DATEVALUE DAVERAGE DAY DAYS360 DB DBCS DCOUNT DCOUNTA DDB DEC2BIN DEC2HEX
+  DEC2OCT DEGREES DELTA DEVSQ DGET DISC DMAX DMIN DOLLAR DOLLARDE DOLLARFR DPRODUCT DSTDEV DSTDEVP DSUM
+  DURATION DVAR DVARP
+  EDATE EFFECT EOMONTH ERF ERFC ERROR.TYPE EVEN EXACT EXP EXPONDIST
+  FACT FACTDOUBLE FDIST FIND FINDB FINV FISHER FISHERINV FIXED FLOOR FORECAST FREQUENCY FTEST FV
+  FVSCHEDULE
+  GAMMADIST GAMMAINV GAMMALN GCD GEOMEAN GESTEP GETPIVOTDATA GROWTH
+  HARMEAN HEX2BIN HEX2DEC HEX2OCT HLOOKUP HOUR HYPERLINK HYPGEOMDIST
+  IF IFERROR IMABS IMAGINARY IMARGUMENT IMCONJUGATE IMCOS IMDIV IMEXP IMLN IMLOG10 IMLOG2 IMPOWER
+  IMPRODUCT IMREAL IMSIN IMSQRT IMSUB IMSUM INDEX INDIRECT INFO INT INTERCEPT INTRATE IPMT IRR ISBLANK
+  ISERR ISERROR ISEVEN ISLOGICAL ISNA ISNONTEXT ISNUMBER ISODD ISPMT ISREF ISTEXT ISTHAIDIGIT
+  KURT
+  LARGE LCM LEFT LEFTB LEN LENB LINEST LN LOG LOGEST LOGINV LOGNORMDIST LOOKUP LOWER
+  MATCH MAX MAXA MDETERM MDURATION MEDIAN MID MIDB MIN MINA MINUTE MINVERSE MIRR MMULT MOD MODE MONTH
+  MROUND MULTINOMIAL
+  N NA NEGBINOMDIST NETWORKDAYS NOMINAL NORMDIST NORMINV NORMSDIST NORMSINV NOT NOW NPER NPV
+  NUMBERSTRING
+  OCT2BIN OCT2DEC OCT2HEX ODD ODDFPRICE ODDFYIELD ODDLPRICE ODDLYIELD OFFSET OR
+  PEARSON PERCENTILE PERCENTRANK PERMUT PHONETIC PI PMT POISSON POWER PPMT PRICE PRICEDISC PRICEMAT
+  PROB PRODUCT PROPER PV
+  QUARTILE QUOTIENT
+  RADIANS RAND RANDBETWEEN RANK RATE RECEIVED REPLACE REPLACEB REPT RIGHT RIGHTB ROMAN ROUND
+  ROUNDBAHTDOWN ROUNDBAHTUP ROUNDDOWN ROUNDUP ROW ROWS RSQ RTD
+  SEARCH SEARCHB SECOND SERIES SERIESSUM SIGN SIN SINH SKEW SLN SLOPE SMALL SQRT SQRTPI STANDARDIZE
+  STDEV STDEVA STDEVP STDEVPA STEYX SUBSTITUTE SUBTOTAL SUM SUMIF SUMIFS SUMPRODUCT SUMSQ SUMX2MY2
+  SUMX2PY2 SUMXMY2 SYD
+  T TAN TANH TBILLEQ TBILLPRICE TBILLYIELD TDIST TEXT THAIDAYOFWEEK THAIDIGIT THAIMONTHOFYEAR
+  THAINUMSOUND THAINUMSTRING THAISTRINGLENGTH THAIYEAR TIME TIMEVALUE TINV TODAY TRANSPOSE TREND TRIM
+  TRIMMEAN TRUNC TTEST TYPE
+  UPPER USDOLLAR
+  VALUE VAR VARA VARP VARPA VDB VLOOKUP
+  WEEKDAY WEEKNUM WEIBULL WORKDAY
+  XIRR XNPV
+  YEAR YEARFRAC YIELD YIELDDISC YIELDMAT
+  ZTEST
+`;
+export const NOT_VALUES = new Set([
+    'LAMBDA',
+    'LET',
+    'PYTHON_STR',
+    'PYTHON_TYPE',
+    'PYTHON_TYPENAME',
+    'QUERYSTRING',
+]);
+export const OLDER_FUNCTION_VALUES = OLDER_FUNCTIONS.trim().split(/\s+/);
+export const FUNCTION_VALUE_NAMES = new Set([
+    ...OLDER_FUNCTION_VALUES,
+    ...[...FUTURE_FUNCTION_PREFIXES.keys()].filter((name) => !NOT_VALUES.has(name)),
+]);

package/dist/core/future-functions.d.ts

@@ -0,0 +1,3 @@
+/** The prefix a future function carries on disk. */
+export type FutureFunctionPrefix = '_xlfn.' | '_xlfn._xlws.';
+export declare const FUTURE_FUNCTION_PREFIXES: ReadonlyMap<string, FutureFunctionPrefix>;