@rowsncolumns/toolkit 24.5.18 → 24.5.19

package/dist/cjs/excel-parser/plugins/xlsb/rgce-parser.js

@@ -1,527 +1,471 @@
+import { __extends, __read } from "tslib";
 import { number2Alpha } from "@rowsncolumns/utils";
+import { FTAB, FTAB_FIXED_ARGC } from "./function-table";
 /**
- * Reader class for parsing Rgce bytes
+ * Decoder for a BIFF12 formula's token stream (`rgce`, [MS-XLSB] 2.2.2 / 2.5.97.88):
+ * reverse-Polish tokens rebuilt into the formula's text.
+ *
+ * Strict by design: a formula decodes completely or not at all. A token it
+ * does not know, a function outside the table, a read past the end of the
+ * stream or a stack that does not end with exactly one expression throws
+ * {@link RgceUnsupportedError}, and the caller keeps the cell's cached value
+ * instead of writing a formula that computes something else.
  */
-var RgceReader = /** @class */ (function () {
-    function RgceReader(bytes) {
-        this.offset = 0;
+/** The formula cannot be decoded exactly; keep the cell's cached value. */
+var RgceUnsupportedError = /** @class */ (function (_super) {
+    __extends(RgceUnsupportedError, _super);
+    function RgceUnsupportedError(message) {
+        var _this = _super.call(this, message) || this;
+        _this.name = "RgceUnsupportedError";
+        return _this;
+    }
+    return RgceUnsupportedError;
+}(Error));
+export { RgceUnsupportedError };
+var MAX_ROW_INDEX = 0xfffff; // 1,048,575: row 1,048,576
+var MAX_COL_INDEX = 0x3fff; // 16,383: column XFD
+var ERROR_CODES = {
+    0x00: "#NULL!",
+    0x07: "#DIV/0!",
+    0x0f: "#VALUE!",
+    0x17: "#REF!",
+    0x1d: "#NAME?",
+    0x24: "#NUM!",
+    0x2a: "#N/A",
+    0x2b: "#GETTING_DATA",
+};
+var BINARY_OPERATORS = {
+    0x03: "+",
+    0x04: "-",
+    0x05: "*",
+    0x06: "/",
+    0x07: "^",
+    0x08: "&",
+    0x09: "<",
+    0x0a: "<=",
+    0x0b: "=",
+    0x0c: ">=",
+    0x0d: ">",
+    0x0e: "<>",
+    0x0f: " ",
+    0x10: ",",
+    0x11: ":",
+};
+/** `PtgAttr` kinds that only steer evaluation or carry whitespace: no stack effect. */
+var ATTR_NO_EFFECT = new Set([0x01, 0x02, 0x08, 0x20, 0x21, 0x40, 0x41]);
+var ATTR_CHOOSE = 0x04;
+var PTG_UNION = 0x10;
+var ATTR_SUM = 0x10;
+var Reader = /** @class */ (function () {
+    function Reader(bytes) {
         this.bytes = bytes;
+        this.offset = 0;
         this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
     }
-    RgceReader.prototype.readUInt8 = function () {
-        var value = this.view.getUint8(this.offset);
-        this.offset += 1;
-        return value;
+    Object.defineProperty(Reader.prototype, "done", {
+        get: function () {
+            return this.offset >= this.bytes.length;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Reader.prototype.take = function (count) {
+        if (this.offset + count > this.bytes.length) {
+            throw new RgceUnsupportedError("token runs past the end of the formula");
+        }
+        var at = this.offset;
+        this.offset += count;
+        return at;
     };
-    RgceReader.prototype.readUInt16LE = function () {
-        var value = this.view.getUint16(this.offset, true);
-        this.offset += 2;
-        return value;
+    Reader.prototype.u8 = function () {
+        return this.view.getUint8(this.take(1));
     };
-    RgceReader.prototype.readUInt32LE = function () {
-        var value = this.view.getUint32(this.offset, true);
-        this.offset += 4;
-        return value;
+    Reader.prototype.u16 = function () {
+        return this.view.getUint16(this.take(2), true);
     };
-    RgceReader.prototype.readInt32LE = function () {
-        var value = this.view.getInt32(this.offset, true);
-        this.offset += 4;
-        return value;
+    Reader.prototype.i16 = function () {
+        return this.view.getInt16(this.take(2), true);
     };
-    RgceReader.prototype.readInt16LE = function () {
-        var value = this.view.getInt16(this.offset, true);
-        this.offset += 2;
-        return value;
+    Reader.prototype.u32 = function () {
+        return this.view.getUint32(this.take(4), true);
     };
-    RgceReader.prototype.readFloat64LE = function () {
-        var value = this.view.getFloat64(this.offset, true);
-        this.offset += 8;
-        return value;
+    Reader.prototype.i32 = function () {
+        return this.view.getInt32(this.take(4), true);
     };
-    RgceReader.prototype.readUtf16Chars = function (charCount) {
-        if (charCount <= 0)
-            return "";
-        var byteCount = charCount * 2;
-        var slice = this.bytes.subarray(this.offset, this.offset + byteCount);
-        this.offset += byteCount;
-        return new TextDecoder("utf-16le").decode(slice);
+    Reader.prototype.f64 = function () {
+        return this.view.getFloat64(this.take(8), true);
+    };
+    Reader.prototype.skip = function (count) {
+        this.take(count);
     };
-    RgceReader.prototype.readXLWideString = function () {
-        var cch = this.readUInt32LE();
-        return cch === 0 ? "" : this.readUtf16Chars(cch);
+    Reader.prototype.utf16 = function (chars) {
+        var at = this.take(chars * 2);
+        return new TextDecoder("utf-16le").decode(this.bytes.subarray(at, at + chars * 2));
     };
-    return RgceReader;
+    return Reader;
 }());
-// Common Excel function names by ID (ftab index)
-var FUNCTION_NAMES = {
-    0: "COUNT", 1: "IF", 2: "ISNA", 3: "ISERROR", 4: "SUM", 5: "AVERAGE",
-    6: "MIN", 7: "MAX", 8: "ROW", 9: "COLUMN", 10: "NA", 11: "NPV",
-    12: "STDEV", 13: "DOLLAR", 14: "FIXED", 15: "SIN", 16: "COS",
-    17: "TAN", 18: "ATAN", 19: "PI", 20: "SQRT", 21: "EXP", 22: "LN",
-    23: "LOG10", 24: "ABS", 25: "INT", 26: "SIGN", 27: "ROUND",
-    28: "LOOKUP", 29: "INDEX", 30: "REPT", 31: "MID", 32: "LEN",
-    33: "VALUE", 34: "TRUE", 35: "FALSE", 36: "AND", 37: "OR",
-    38: "NOT", 39: "MOD", 40: "DCOUNT", 41: "DSUM", 42: "DAVERAGE",
-    43: "DMIN", 44: "DMAX", 45: "DSTDEV", 46: "VAR", 47: "DVAR",
-    48: "TEXT", 49: "LINEST", 50: "TREND", 51: "LOGEST", 52: "GROWTH",
-    61: "MIRR", 62: "IRR", 63: "RAND", 64: "MATCH", 65: "DATE",
-    66: "TIME", 67: "DAY", 68: "MONTH", 69: "YEAR", 70: "WEEKDAY",
-    71: "HOUR", 72: "MINUTE", 73: "SECOND", 74: "NOW", 75: "AREAS",
-    76: "ROWS", 77: "COLUMNS", 78: "OFFSET", 82: "SEARCH", 83: "TRANSPOSE",
-    86: "TYPE", 97: "ATAN2", 98: "ASIN", 99: "ACOS", 100: "CHOOSE",
-    101: "HLOOKUP", 102: "VLOOKUP", 103: "ISREF", 104: "LOG",
-    105: "CHAR", 106: "LOWER", 107: "UPPER", 108: "PROPER", 109: "LEFT",
-    110: "RIGHT", 111: "EXACT", 112: "TRIM", 113: "REPLACE", 114: "SUBSTITUTE",
-    115: "CODE", 116: "NAMES", 117: "DIRECTORY", 118: "FIND", 119: "CELL",
-    120: "ISERR", 121: "ISTEXT", 122: "ISNUMBER", 123: "ISBLANK",
-    124: "T", 125: "N", 127: "ISNONTEXT", 128: "ISODD", 129: "ISEVEN",
-    162: "CLEAN", 163: "MDETERM", 164: "MINVERSE", 165: "MMULT",
-    167: "IPMT", 168: "PPMT", 169: "COUNTA", 183: "PRODUCT",
-    184: "FACT", 189: "DPRODUCT", 190: "ISNONTEXT",
-    193: "STDEVP", 194: "VARP", 195: "DSTDEVP", 196: "DVARP",
-    197: "TRUNC", 198: "ISLOGICAL", 199: "DCOUNTA", 200: "DELETEBAR",
-    216: "RANK", 219: "ADDRESS", 220: "DAYS360", 221: "TODAY",
-    222: "VDB", 227: "MEDIAN", 228: "SUMPRODUCT", 229: "SINH",
-    230: "COSH", 231: "TANH", 232: "ASINH", 233: "ACOSH", 234: "ATANH",
-    235: "DGET", 244: "INFO", 247: "DB", 252: "FREQUENCY",
-    261: "ERROR.TYPE", 269: "AVEDEV", 270: "BETADIST", 271: "GAMMALN",
-    272: "BETAINV", 273: "BINOMDIST", 274: "CHIDIST", 275: "CHIINV",
-    276: "COMBIN", 277: "CONFIDENCE", 278: "CRITBINOM", 279: "EVEN",
-    280: "EXPONDIST", 281: "FDIST", 282: "FINV", 283: "FISHER",
-    284: "FISHERINV", 285: "FLOOR", 286: "GAMMADIST", 287: "GAMMAINV",
-    288: "CEILING", 289: "HYPGEOMDIST", 290: "LOGNORMDIST", 291: "LOGINV",
-    292: "NEGBINOMDIST", 293: "NORMDIST", 294: "NORMSDIST", 295: "NORMINV",
-    296: "NORMSINV", 297: "STANDARDIZE", 298: "ODD", 299: "PERMUT",
-    300: "POISSON", 301: "TDIST", 302: "WEIBULL", 303: "SUMXMY2",
-    304: "SUMX2MY2", 305: "SUMX2PY2", 306: "CHITEST", 307: "CORREL",
-    308: "COVAR", 309: "FORECAST", 310: "FTEST", 311: "INTERCEPT",
-    312: "PEARSON", 313: "RSQ", 314: "STEYX", 315: "SLOPE", 316: "TTEST",
-    317: "PROB", 318: "DEVSQ", 319: "GEOMEAN", 320: "HARMEAN",
-    321: "SUMSQ", 322: "KURT", 323: "SKEW", 324: "ZTEST", 325: "LARGE",
-    326: "SMALL", 327: "QUARTILE", 328: "PERCENTILE", 329: "PERCENTRANK",
-    330: "MODE", 331: "TRIMMEAN", 332: "TINV", 334: "CONCATENATE",
-    335: "POWER", 336: "RADIANS", 337: "DEGREES", 338: "SUBTOTAL",
-    339: "SUMIF", 340: "COUNTIF", 341: "COUNTBLANK", 342: "HYPERLINK",
-    343: "PHONETIC", 344: "AVERAGEA", 345: "MAXA", 346: "MINA",
-    347: "STDEVPA", 348: "VARPA", 349: "STDEVA", 350: "VARA",
-};
 /**
- * Parse Rgce (Reverse Polish Notation Compiled Expression) - binary formula format in XLSB
- * This converts binary Ptg (Parsed Token) tokens into a formula string
- *
- * @param rgceBytes - The binary formula data
- * @returns The formula string (without leading "=")
+ * A sheet name as a reference prefix: quoted unless it is a plain ASCII
+ * identifier no reader could take for a cell (`A1`, `R1C1`, `R`) or a
+ * boolean. Quoting is always valid, so anything else is quoted.
  */
+export var quoteSheetName = function (name) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) &&
+        !/^[A-Za-z]{1,3}\d+$/.test(name) &&
+        !/^(?:[Rr]\d*)?(?:[Cc]\d*)?$/.test(name) &&
+        !/^(?:TRUE|FALSE)$/i.test(name)
+        ? name
+        : "'".concat(name.replace(/'/g, "''"), "'");
+};
+var formatNumber = function (value) {
+    if (!Number.isFinite(value)) {
+        throw new RgceUnsupportedError("non-finite number constant");
+    }
+    return String(value).replace("e", "E");
+};
+var cellRef = function (row, col, rowRelative, colRelative) {
+    return "".concat(colRelative ? "" : "$").concat(number2Alpha(col)).concat(rowRelative ? "" : "$").concat(row + 1);
+};
+/** An area, written the way Excel writes whole columns (`A:B`) and whole rows (`1:2`). */
+var areaRef = function (first, last) {
+    if (first.row === 0 && last.row === MAX_ROW_INDEX) {
+        return "".concat(first.colRelative ? "" : "$").concat(number2Alpha(first.col), ":").concat(last.colRelative ? "" : "$").concat(number2Alpha(last.col));
+    }
+    if (first.col === 0 && last.col === MAX_COL_INDEX) {
+        return "".concat(first.rowRelative ? "" : "$").concat(first.row + 1, ":").concat(last.rowRelative ? "" : "$").concat(last.row + 1);
+    }
+    return "".concat(cellRef(first.row, first.col, first.rowRelative, first.colRelative), ":").concat(cellRef(last.row, last.col, last.rowRelative, last.colRelative));
+};
+/** `RgceLoc` / `RgceArea` corner: a 20-bit row (u32) and a 14-bit column with its relative flags (u16). */
+var corner = function (row, colField) { return ({
+    row: row & MAX_ROW_INDEX,
+    col: colField & MAX_COL_INDEX,
+    rowRelative: (colField & 0x8000) !== 0,
+    colRelative: (colField & 0x4000) !== 0,
+}); };
+/** A `RgceLocRel` corner of a shared formula or name: relative parts are offsets from the base cell. */
+var relativeCorner = function (rowField, colField, base) {
+    var _a, _b;
+    var rowRelative = (colField & 0x8000) !== 0;
+    var colRelative = (colField & 0x4000) !== 0;
+    if ((rowRelative || colRelative) && !base) {
+        throw new RgceUnsupportedError("relative reference without a base cell");
+    }
+    var baseRow = ((_a = base === null || base === void 0 ? void 0 : base.row) !== null && _a !== void 0 ? _a : 1) - 1;
+    var baseCol = ((_b = base === null || base === void 0 ? void 0 : base.col) !== null && _b !== void 0 ? _b : 1) - 1;
+    // A relative column is a signed 14-bit offset; a relative row a signed 32-bit one.
+    var colOffset = ((colField & MAX_COL_INDEX) << 18) >> 18;
+    var row = rowRelative ? baseRow + rowField : rowField;
+    var col = colRelative ? baseCol + colOffset : colField & MAX_COL_INDEX;
+    // Offsets wrap around the sheet, as Excel's do.
+    return {
+        row: ((row % (MAX_ROW_INDEX + 1)) + MAX_ROW_INDEX + 1) % (MAX_ROW_INDEX + 1),
+        col: ((col % (MAX_COL_INDEX + 1)) + MAX_COL_INDEX + 1) % (MAX_COL_INDEX + 1),
+        rowRelative: rowRelative,
+        colRelative: colRelative,
+    };
+};
 /**
- * Parse Rgce with sheet names for cross-sheet references
- * @param rgceBytes - The binary formula data
- * @param sheetNames - Array of sheet names for resolving external references
- * @returns The formula string (without leading "=")
+ * Decode a formula's tokens into its text, without the leading `=`.
+ *
+ * Throws {@link RgceUnsupportedError} when any part of the formula cannot be
+ * decoded exactly.
  */
-export function parseRgce(rgceBytes, sheetRefResolver, baseCell, debug) {
-    if (debug === void 0) { debug = false; }
-    if (!rgceBytes || rgceBytes.length === 0)
-        return "";
-    var reader = new RgceReader(rgceBytes);
-    var stack = [];
-    if (debug) {
-        console.log("[Rgce] Parsing", rgceBytes.length, "bytes:", Array.from(rgceBytes.slice(0, Math.min(30, rgceBytes.length)))
-            .map(function (b) { return "0x".concat(b.toString(16).padStart(2, '0')); })
-            .join(' '));
+export function decodeRgce(rgce, context) {
+    var _a, _b;
+    if (context === void 0) { context = {}; }
+    if (rgce.length === 0) {
+        throw new RgceUnsupportedError("empty formula");
     }
-    var fixedArgCounts = {
-        15: 1, // SIN
-        16: 1, // COS
-        17: 1, // TAN
-        19: 0, // PI
-        20: 1, // SQRT
-        21: 1, // EXP
-        22: 1, // LN
-        24: 1, // ABS
-        25: 1, // INT
-        27: 2, // ROUND
-        31: 3, // MID
-        32: 1, // LEN
-        34: 0, // TRUE
-        35: 0, // FALSE
-        39: 2, // MOD
-        65: 3, // DATE
-        66: 3, // TIME
-        67: 1, // DAY
-        68: 1, // MONTH
-        69: 1, // YEAR
-        71: 1, // HOUR
-        72: 1, // MINUTE
-        73: 1, // SECOND
-        74: 0, // NOW
-        105: 1, // CHAR
-        106: 1, // LOWER
-        107: 1, // UPPER
-        109: 2, // LEFT
-        110: 2, // RIGHT
-        111: 2, // EXACT
-        112: 1, // TRIM
-        115: 1, // CODE
-        183: 1, // PRODUCT
-        197: 2, // TRUNC
-        221: 0, // TODAY
-        335: 2, // POWER
-        336: 1, // RADIANS
-        337: 1, // DEGREES
-    };
-    var canRead = function (n) { return reader.offset + n <= rgceBytes.length; };
-    var quoteSheetName = function (name) {
-        return /[\s!'[\]]/.test(name) ? "'".concat(name.replace(/'/g, "''"), "'") : name;
-    };
-    var resolveSheetName = function (ixti) {
-        if (typeof sheetRefResolver === "function") {
-            return sheetRefResolver(ixti);
+    var reader = new Reader(rgce);
+    var stack = [];
+    // Stack slots holding a union without its parentheses: fine as a whole
+    // formula (`A1,C3`), but an argument must say it is one (`SUM((A1,C3))`).
+    var bareUnions = new Set();
+    var pop = function () {
+        var value = stack.pop();
+        if (value === undefined) {
+            throw new RgceUnsupportedError("operator without an operand");
         }
-        return sheetRefResolver === null || sheetRefResolver === void 0 ? void 0 : sheetRefResolver[ixti];
+        bareUnions.delete(stack.length);
+        return value;
     };
     var popArgs = function (count) {
-        var args = [];
-        for (var i = 0; i < count; i++)
-            args.unshift(stack.pop() || "");
-        return args;
+        if (count > stack.length) {
+            throw new RgceUnsupportedError("function without all its arguments");
+        }
+        var first = stack.length - count;
+        return stack.splice(first, count).map(function (arg, at) {
+            var isBareUnion = bareUnions.delete(first + at);
+            return isBareUnion ? "(".concat(arg, ")") : arg;
+        });
     };
-    var pushFixedFunction = function (ftabIndex) {
+    var sheet = function (ixti) {
         var _a;
-        var funcName = FUNCTION_NAMES[ftabIndex] || "FUNC".concat(ftabIndex);
-        var cargs = (_a = fixedArgCounts[ftabIndex]) !== null && _a !== void 0 ? _a : 0;
-        stack.push("".concat(funcName, "(").concat(popArgs(cargs).join(","), ")"));
-    };
-    var pushVariableFunction = function (cargs, ftabIndex) {
-        var funcName = FUNCTION_NAMES[ftabIndex] || "FUNC".concat(ftabIndex);
-        stack.push("".concat(funcName, "(").concat(popArgs(cargs).join(","), ")"));
-    };
-    var formatRef = function (rowZero, colZero, rowRel, colRel) {
-        var row = Math.max(0, rowZero);
-        var col = Math.max(0, colZero);
-        return "".concat(colRel ? "" : "$").concat(number2Alpha(col)).concat(rowRel ? "" : "$").concat(row + 1);
-    };
-    var readShortRef = function () {
-        var row = reader.readUInt32LE();
-        var col = reader.readUInt16LE();
-        var rowRel = (col & 0x8000) !== 0;
-        var colRel = (col & 0x4000) !== 0;
-        return formatRef(row & 0x000fffff, col & 0x3fff, rowRel, colRel);
-    };
-    var readShortArea = function () {
-        var rowFirst = reader.readUInt32LE();
-        var rowLast = reader.readUInt32LE();
-        var colFirst = reader.readUInt16LE();
-        var colLast = reader.readUInt16LE();
-        var refFirst = formatRef(rowFirst & 0x000fffff, colFirst & 0x3fff, (colFirst & 0x8000) !== 0, (colFirst & 0x4000) !== 0);
-        var refLast = formatRef(rowLast & 0x000fffff, colLast & 0x3fff, (colLast & 0x8000) !== 0, (colLast & 0x4000) !== 0);
-        return "".concat(refFirst, ":").concat(refLast);
-    };
-    var readRelShortRef = function () {
-        var _a, _b;
-        var rowOffset = reader.readInt32LE();
-        var colRaw = reader.readInt16LE();
-        var colOffset14 = colRaw & 0x3fff;
-        var colOffset = (colOffset14 << 18) >> 18;
-        var baseRowZero = Math.max(0, ((_a = baseCell === null || baseCell === void 0 ? void 0 : baseCell.row) !== null && _a !== void 0 ? _a : 1) - 1);
-        var baseColZero = Math.max(0, ((_b = baseCell === null || baseCell === void 0 ? void 0 : baseCell.col) !== null && _b !== void 0 ? _b : 1) - 1);
-        return formatRef(baseRowZero + rowOffset, baseColZero + colOffset, true, true);
+        var name = (_a = context.sheetName) === null || _a === void 0 ? void 0 : _a.call(context, ixti);
+        if (name === undefined) {
+            throw new RgceUnsupportedError("unknown sheet reference ".concat(ixti));
+        }
+        return quoteSheetName(name);
     };
-    var readRelShortArea = function () {
-        var _a, _b;
-        var rowFirstOffset = reader.readInt32LE();
-        var rowLastOffset = reader.readInt32LE();
-        var colFirstRaw = reader.readInt16LE();
-        var colLastRaw = reader.readInt16LE();
-        var colFirstOffset = ((colFirstRaw & 0x3fff) << 18) >> 18;
-        var colLastOffset = ((colLastRaw & 0x3fff) << 18) >> 18;
-        var baseRowZero = Math.max(0, ((_a = baseCell === null || baseCell === void 0 ? void 0 : baseCell.row) !== null && _a !== void 0 ? _a : 1) - 1);
-        var baseColZero = Math.max(0, ((_b = baseCell === null || baseCell === void 0 ? void 0 : baseCell.col) !== null && _b !== void 0 ? _b : 1) - 1);
-        var refFirst = formatRef(baseRowZero + rowFirstOffset, baseColZero + colFirstOffset, true, true);
-        var refLast = formatRef(baseRowZero + rowLastOffset, baseColZero + colLastOffset, true, true);
-        return "".concat(refFirst, ":").concat(refLast);
+    var callFunction = function (iftab, args) {
+        var name = FTAB[iftab];
+        if (!name) {
+            throw new RgceUnsupportedError("unknown function ".concat(iftab));
+        }
+        return "".concat(name, "(").concat(args.join(","), ")");
     };
-    try {
-        while (reader.offset < rgceBytes.length) {
-            var ptgOffset = reader.offset;
-            var ptg = reader.readUInt8();
-            if (debug) {
-                console.log("[Rgce] @".concat(ptgOffset, ": ptg=0x").concat(ptg.toString(16).padStart(2, '0'), " stack=[").concat(stack.join(', '), "]"));
-            }
-            // Handle token based on value
-            // Operators are 0x00-0x1f (no class bits)
-            // References/functions are 0x20-0x7f (have class bits in bits 5-6)
-            if (ptg === 0x03) {
-                // PtgAdd
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, "+").concat(right));
-            }
-            else if (ptg === 0x04) {
-                // PtgSub - subtraction operator
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, "-").concat(right));
-            }
-            else if (ptg === 0x05) {
-                // PtgMul - multiplication operator
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, "*").concat(right));
-            }
-            else if (ptg === 0x06) {
-                // PtgDiv
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, "/").concat(right));
-            }
-            else if (ptg === 0x07) {
-                // PtgPower
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, "^").concat(right));
-            }
-            else if (ptg === 0x08) {
-                // PtgConcat
-                var right = stack.pop() || '""';
-                var left = stack.pop() || '""';
-                stack.push("".concat(left, "&").concat(right));
-            }
-            else if (ptg === 0x09) {
-                // PtgLT
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, "<").concat(right));
-            }
-            else if (ptg === 0x0a) {
-                // PtgLE
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, "<=").concat(right));
-            }
-            else if (ptg === 0x0b) {
-                // PtgEQ
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, "=").concat(right));
-            }
-            else if (ptg === 0x0c) {
-                // PtgGE
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, ">=").concat(right));
-            }
-            else if (ptg === 0x0d) {
-                // PtgGT
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, ">").concat(right));
-            }
-            else if (ptg === 0x0e) {
-                // PtgNE
-                var right = stack.pop() || "0";
-                var left = stack.pop() || "0";
-                stack.push("".concat(left, "<>").concat(right));
-            }
-            else if (ptg === 0x12) {
-                // PtgUPlus
-                var operand = stack.pop() || "0";
-                stack.push("+".concat(operand));
-            }
-            else if (ptg === 0x13) {
-                // PtgUMinus
-                var operand = stack.pop() || "0";
-                stack.push("-".concat(operand));
-            }
-            else if (ptg === 0x14) {
-                // PtgPercent
-                var operand = stack.pop() || "0";
-                stack.push("".concat(operand, "%"));
-            }
-            else if (ptg === 0x15) {
-                // PtgParen
-                var operand = stack.pop() || "";
-                stack.push("(".concat(operand, ")"));
-            }
-            else if (ptg === 0x16) {
-                // PtgMissArg - missing argument (empty between commas)
+    while (!reader.done) {
+        var ptg = reader.u8();
+        var binary = BINARY_OPERATORS[ptg];
+        if (binary !== undefined) {
+            var right = pop();
+            var left = pop();
+            if (ptg === PTG_UNION)
+                bareUnions.add(stack.length);
+            stack.push("".concat(left).concat(binary).concat(right));
+            continue;
+        }
+        switch (ptg) {
+            case 0x12: // PtgUplus
+                stack.push("+".concat(pop()));
+                continue;
+            case 0x13: // PtgUminus
+                stack.push("-".concat(pop()));
+                continue;
+            case 0x14: // PtgPercent
+                stack.push("".concat(pop(), "%"));
+                continue;
+            case 0x15: // PtgParen
+                stack.push("(".concat(pop(), ")"));
+                continue;
+            case 0x16: // PtgMissArg
                 stack.push("");
+                continue;
+            case 0x17: {
+                // PtgStr: a 16-bit character count, then UTF-16LE.
+                var text = reader.utf16(reader.u16());
+                stack.push("\"".concat(text.replace(/"/g, '""'), "\""));
+                continue;
             }
-            else if (ptg === 0x17) {
-                // PtgStr - string constant
-                var str = reader.readXLWideString();
-                stack.push("\"".concat(str.replace(/"/g, '""'), "\""));
-            }
-            else if (ptg === 0x1d) {
-                // PtgBool - boolean constant
-                var value = reader.readUInt8();
-                stack.push(value ? "TRUE" : "FALSE");
-            }
-            else if (ptg === 0x1e) {
-                // PtgInt - integer constant
-                var value = reader.readUInt16LE();
-                stack.push(String(value));
-            }
-            else if (ptg === 0x1f) {
-                // PtgNum - float constant
-                var value = reader.readFloat64LE();
-                stack.push(String(value));
-            }
-            else if (ptg === 0x18) {
-                // PtgErr - error constant
-                if (!canRead(1))
-                    break;
-                var code = reader.readUInt8();
-                var errorValues = {
-                    0x00: "#NULL!",
-                    0x07: "#DIV/0!",
-                    0x0f: "#VALUE!",
-                    0x17: "#REF!",
-                    0x1d: "#NAME?",
-                    0x24: "#NUM!",
-                    0x2a: "#N/A",
-                    0x2b: "#GETTING_DATA",
-                };
-                stack.push(errorValues[code] || "#VALUE!");
-            }
-            else if (ptg === 0x19) {
-                // PtgAttr: 1 byte flags + 2 bytes data
-                if (!canRead(3))
-                    break;
-                var flags = reader.readUInt8();
-                var data = reader.readUInt16LE();
-                // Handle various PtgAttr flags
-                if ((flags & 0x10) !== 0) {
-                    // fSum: treat previous operand as SUM(operand)
-                    var operand = stack.pop() || "";
-                    stack.push("SUM(".concat(operand, ")"));
-                }
-                // Note: Other flags (fIf=0x02, fChoose=0x04, fSkip=0x08, fGoto=0x01)
-                // are for control flow and typically don't affect the formula string
-                // They just affect how bytes are skipped during parsing
-            }
-            else if (ptg === 0x01) {
-                // Ambiguous in some XLSB streams:
-                // - PtgExp (4-byte payload)
-                // - PtgFunc ref-class variant (2-byte payload)
-                if (canRead(4)) {
-                    var srcRow = reader.readUInt16LE() + 1;
-                    var srcCol = reader.readUInt16LE() + 1;
-                    stack.push("__PTGEXP__:".concat(srcRow, ":").concat(srcCol));
+            case 0x19: {
+                // PtgAttr: a kind byte and 16 bits of data.
+                var kind = reader.u8();
+                var data = reader.u16();
+                if (kind === ATTR_SUM) {
+                    stack.push("SUM(".concat(popArgs(1)[0], ")"));
                 }
-                else if (canRead(2)) {
-                    pushFixedFunction(reader.readUInt16LE());
+                else if (kind === ATTR_CHOOSE) {
+                    reader.skip((data + 1) * 2); // CHOOSE's jump table
                 }
-                else {
-                    break;
-                }
-            }
-            else if (ptg === 0x02) {
-                // PtgFuncVar reference-class variant (0x02)
-                // In practice, 0x02 is PtgFuncVar, not PtgTbl
-                if (canRead(3)) {
-                    var cargs = reader.readUInt8();
-                    pushVariableFunction(cargs, reader.readUInt16LE());
-                }
-                else {
-                    break;
+                else if (!ATTR_NO_EFFECT.has(kind)) {
+                    throw new RgceUnsupportedError("attribute 0x".concat(kind.toString(16)));
                 }
+                continue;
             }
-            else if (ptg === 0x1a || ptg === 0x3a || ptg === 0x5a || ptg === 0x7a) {
-                // PtgRef3d - cross-sheet cell reference
-                if (!canRead(8))
-                    break;
-                var ixti = reader.readUInt16LE(); // External sheet index
-                var cellRef = readShortRef();
-                // Get sheet name if available
-                var sheetName = resolveSheetName(ixti);
-                if (sheetName) {
-                    var quotedName = quoteSheetName(sheetName);
-                    stack.push("".concat(quotedName, "!").concat(cellRef));
-                }
-                else {
-                    stack.push(cellRef);
+            case 0x1c: {
+                // PtgErr
+                var text = ERROR_CODES[reader.u8()];
+                if (text === undefined) {
+                    throw new RgceUnsupportedError("unknown error constant");
                 }
+                stack.push(text);
+                continue;
             }
-            else if (ptg === 0x1b || ptg === 0x3b || ptg === 0x5b || ptg === 0x7b) {
-                // PtgArea3d - cross-sheet range reference
-                if (!canRead(14))
-                    break;
-                var ixti = reader.readUInt16LE(); // External sheet index
-                var rangeRef = readShortArea();
-                // Get sheet name if available
-                var sheetName = resolveSheetName(ixti);
-                if (sheetName) {
-                    var quotedName = quoteSheetName(sheetName);
-                    stack.push("".concat(quotedName, "!").concat(rangeRef));
-                }
-                else {
-                    stack.push(rangeRef);
+            case 0x1d: // PtgBool
+                stack.push(reader.u8() !== 0 ? "TRUE" : "FALSE");
+                continue;
+            case 0x1e: // PtgInt
+                stack.push(String(reader.u16()));
+                continue;
+            case 0x1f: // PtgNum
+                stack.push(formatNumber(reader.f64()));
+                continue;
+        }
+        // Operand and function tokens carry a value class in bits 5-6.
+        switch (ptg) {
+            case 0x21:
+            case 0x41:
+            case 0x61: {
+                // PtgFunc: a fixed-arity function.
+                var iftab = reader.u16();
+                var argc = FTAB_FIXED_ARGC[iftab];
+                if (argc === undefined || argc < 0) {
+                    throw new RgceUnsupportedError("function ".concat(iftab, " is not fixed-arity"));
                 }
+                stack.push(callFunction(iftab, popArgs(argc)));
+                continue;
             }
-            // References and functions have class bits
-            else if (ptg >= 0x20) {
-                var basePtg = ptg & 0x1f;
-                if (basePtg === 0x01) {
-                    // PtgFunc - function with fixed args
-                    if (!canRead(2))
-                        break;
-                    pushFixedFunction(reader.readUInt16LE());
-                }
-                else if (basePtg === 0x02) {
-                    // PtgFuncVar - function with variable args
-                    if (!canRead(3))
-                        break;
-                    var cargs = reader.readUInt8();
-                    pushVariableFunction(cargs, reader.readUInt16LE());
-                }
-                else if (basePtg === 0x04) {
-                    // PtgRef - cell reference
-                    if (!canRead(6))
-                        break;
-                    stack.push(readShortRef());
-                }
-                else if (basePtg === 0x05) {
-                    // PtgArea - range reference
-                    if (!canRead(12))
-                        break;
-                    stack.push(readShortArea());
+            case 0x22:
+            case 0x42:
+            case 0x62: {
+                // PtgFuncVar: the argument count (up to 255), then the function (bit 15: a command).
+                var argc = reader.u8();
+                var field = reader.u16();
+                if (field & 0x8000) {
+                    throw new RgceUnsupportedError("command-equivalent function");
                 }
-                else if (basePtg === 0x0c) {
-                    // PtgRefN - relative cell reference (commonly used in shared formulas)
-                    if (!canRead(6))
-                        break;
-                    stack.push(readRelShortRef());
-                }
-                else if (basePtg === 0x0d) {
-                    // PtgAreaN - relative range reference
-                    if (!canRead(12))
-                        break;
-                    stack.push(readRelShortArea());
+                var iftab = field & 0x7fff;
+                var args = popArgs(argc);
+                if (iftab === 0xff) {
+                    // A user-defined or add-in function: its name is the first argument.
+                    var _c = __read(args), name_1 = _c[0], rest = _c.slice(1);
+                    if (!name_1) {
+                        throw new RgceUnsupportedError("user-defined function without a name");
+                    }
+                    stack.push("".concat(name_1, "(").concat(rest.join(","), ")"));
                 }
                 else {
-                    // Unknown class token: break to avoid stream desync.
-                    break;
+                    stack.push(callFunction(iftab, args));
                 }
+                continue;
             }
-            else {
-                // Unknown non-class token: break to avoid stream desync.
-                if (debug) {
-                    console.log("[Rgce] Unknown token 0x".concat(ptg.toString(16), ", stopping parse"));
+            case 0x23:
+            case 0x43:
+            case 0x63: {
+                // PtgName: a 1-based index into the workbook's names.
+                var index = reader.u32();
+                var name_2 = (_a = context.definedName) === null || _a === void 0 ? void 0 : _a.call(context, index);
+                if (name_2 === undefined) {
+                    throw new RgceUnsupportedError("unknown defined name ".concat(index));
                 }
-                break;
+                stack.push(name_2);
+                continue;
+            }
+            case 0x24:
+            case 0x44:
+            case 0x64: {
+                // PtgRef
+                var row = reader.u32();
+                var c = corner(row, reader.u16());
+                stack.push(cellRef(c.row, c.col, c.rowRelative, c.colRelative));
+                continue;
+            }
+            case 0x25:
+            case 0x45:
+            case 0x65: {
+                // PtgArea
+                var rowFirst = reader.u32();
+                var rowLast = reader.u32();
+                var colFirst = reader.u16();
+                var colLast = reader.u16();
+                stack.push(areaRef(corner(rowFirst, colFirst), corner(rowLast, colLast)));
+                continue;
+            }
+            case 0x26:
+            case 0x46:
+            case 0x66: // PtgMemArea
+            case 0x27:
+            case 0x47:
+            case 0x67: // PtgMemErr
+            case 0x28:
+            case 0x48:
+            case 0x68: // PtgMemNoMem
+                // A precomputed reference: the tokens that follow compute it.
+                reader.skip(4);
+                reader.u16(); // cce
+                continue;
+            case 0x29:
+            case 0x49:
+            case 0x69: // PtgMemFunc
+                reader.u16(); // cce
+                continue;
+            case 0x2a:
+            case 0x4a:
+            case 0x6a: // PtgRefErr
+                reader.skip(6);
+                stack.push("#REF!");
+                continue;
+            case 0x2b:
+            case 0x4b:
+            case 0x6b: // PtgAreaErr
+                reader.skip(12);
+                stack.push("#REF!");
+                continue;
+            case 0x2c:
+            case 0x4c:
+            case 0x6c: {
+                // PtgRefN: relative to the base cell.
+                var row = reader.i32();
+                var c = relativeCorner(row, reader.u16(), context.baseCell);
+                stack.push(cellRef(c.row, c.col, c.rowRelative, c.colRelative));
+                continue;
+            }
+            case 0x2d:
+            case 0x4d:
+            case 0x6d: {
+                // PtgAreaN
+                var rowFirst = reader.i32();
+                var rowLast = reader.i32();
+                var colFirst = reader.u16();
+                var colLast = reader.u16();
+                stack.push(areaRef(relativeCorner(rowFirst, colFirst, context.baseCell), relativeCorner(rowLast, colLast, context.baseCell)));
+                continue;
+            }
+            case 0x3a:
+            case 0x5a:
+            case 0x7a: {
+                // PtgRef3d
+                var prefix = sheet(reader.u16());
+                var row = reader.u32();
+                var c = corner(row, reader.u16());
+                stack.push("".concat(prefix, "!").concat(cellRef(c.row, c.col, c.rowRelative, c.colRelative)));
+                continue;
+            }
+            case 0x3b:
+            case 0x5b:
+            case 0x7b: {
+                // PtgArea3d
+                var prefix = sheet(reader.u16());
+                var rowFirst = reader.u32();
+                var rowLast = reader.u32();
+                var colFirst = reader.u16();
+                var colLast = reader.u16();
+                stack.push("".concat(prefix, "!").concat(areaRef(corner(rowFirst, colFirst), corner(rowLast, colLast))));
+                continue;
+            }
+            case 0x3c:
+            case 0x5c:
+            case 0x7c: // PtgRefErr3d
+            case 0x3d:
+            case 0x5d:
+            case 0x7d: {
+                // PtgAreaErr3d. Excel keeps the sheet a deleted reference was on
+                // (`Sheet1!#REF!`); on a sheet it cannot name, the error alone.
+                var ixti = reader.u16();
+                var name_3 = (_b = context.sheetName) === null || _b === void 0 ? void 0 : _b.call(context, ixti);
+                reader.skip((ptg & 0x1f) === 0x1c ? 6 : 12);
+                stack.push(name_3 === undefined ? "#REF!" : "".concat(quoteSheetName(name_3), "!#REF!"));
+                continue;
             }
         }
+        // PtgExp / PtgTbl (shared, array or data-table formulas), PtgArray,
+        // PtgNameX, the extended tokens (structured references) and anything else.
+        throw new RgceUnsupportedError("token 0x".concat(ptg.toString(16)));
     }
-    catch (err) {
-        // Parse error - return what we have so far
-        if (debug) {
-            console.error("[Rgce] Parse error:", err);
-        }
-        return stack.length > 0 ? stack[stack.length - 1] : "";
+    if (stack.length !== 1) {
+        throw new RgceUnsupportedError("formula leaves ".concat(stack.length, " expressions"));
+    }
+    return stack[0];
+}
+/**
+ * A formula's text, or `""` when it cannot be decoded exactly — never a part of
+ * one. Prefer {@link decodeRgce}, which says why.
+ *
+ * @deprecated the lenient form of {@link decodeRgce}.
+ */
+export function parseRgce(rgceBytes, sheetRefResolver, baseCell) {
+    if (!rgceBytes || rgceBytes.length === 0)
+        return "";
+    var sheetName = typeof sheetRefResolver === "function"
+        ? sheetRefResolver
+        : function (ixti) { return sheetRefResolver === null || sheetRefResolver === void 0 ? void 0 : sheetRefResolver[ixti]; };
+    try {
+        return decodeRgce(rgceBytes, { sheetName: sheetName, baseCell: baseCell });
     }
-    var result = stack.length > 0 ? stack[stack.length - 1] : "";
-    if (debug) {
-        console.log("[Rgce] Final result:", result);
+    catch (error) {
+        if (error instanceof RgceUnsupportedError)
+            return "";
+        throw error;
     }
-    return result;
 }