@devmm/puredocs-excel-formula 1.0.7 → 1.0.8

package/dist/index.d.cts

@@ -152,8 +152,11 @@ declare const enum TokenType {
     SpillReference = 24,
     Exclamation = 25,
     AtSign = 26,
-    ErrorLiteral = 27,
-    EOF = 28
+    LeftBrace = 27,
+    RightBrace = 28,
+    Semicolon = 29,
+    ErrorLiteral = 30,
+    EOF = 31
 }
 interface Token {
     readonly type: TokenType;
@@ -170,7 +173,8 @@ interface Token {
  *   - Error literals (#N/A, #REF!, #VALUE!, etc.)
  *   - Quoted sheet references ('My Sheet'!A1)
  *   - Unquoted sheet references (Sheet1!A1)
- *   - _xlfn. prefix stripping
+ *   - _xlfn. / _xlws. / _xlpm. prefix stripping
+ *   - Array constants ({1,2;3,4})
  *   - Cell references ($A$1, A1, AA123)
  *   - Named ranges
  *   - @ implicit intersection operator

package/dist/index.d.ts

@@ -152,8 +152,11 @@ declare const enum TokenType {
     SpillReference = 24,
     Exclamation = 25,
     AtSign = 26,
-    ErrorLiteral = 27,
-    EOF = 28
+    LeftBrace = 27,
+    RightBrace = 28,
+    Semicolon = 29,
+    ErrorLiteral = 30,
+    EOF = 31
 }
 interface Token {
     readonly type: TokenType;
@@ -170,7 +173,8 @@ interface Token {
  *   - Error literals (#N/A, #REF!, #VALUE!, etc.)
  *   - Quoted sheet references ('My Sheet'!A1)
  *   - Unquoted sheet references (Sheet1!A1)
- *   - _xlfn. prefix stripping
+ *   - _xlfn. / _xlws. / _xlpm. prefix stripping
+ *   - Array constants ({1,2;3,4})
  *   - Cell references ($A$1, A1, AA123)
  *   - Named ranges
  *   - @ implicit intersection operator

package/dist/index.js

@@ -446,8 +446,11 @@ var TokenType = /* @__PURE__ */ ((TokenType2) => {
   TokenType2[TokenType2["SpillReference"] = 24] = "SpillReference";
   TokenType2[TokenType2["Exclamation"] = 25] = "Exclamation";
   TokenType2[TokenType2["AtSign"] = 26] = "AtSign";
-  TokenType2[TokenType2["ErrorLiteral"] = 27] = "ErrorLiteral";
-  TokenType2[TokenType2["EOF"] = 28] = "EOF";
+  TokenType2[TokenType2["LeftBrace"] = 27] = "LeftBrace";
+  TokenType2[TokenType2["RightBrace"] = 28] = "RightBrace";
+  TokenType2[TokenType2["Semicolon"] = 29] = "Semicolon";
+  TokenType2[TokenType2["ErrorLiteral"] = 30] = "ErrorLiteral";
+  TokenType2[TokenType2["EOF"] = 31] = "EOF";
   return TokenType2;
 })(TokenType || {});
 function makeToken(type, value2, position) {
@@ -461,6 +464,8 @@ var FormulaException = class extends Error {
     this.name = "FormulaException";
   }
 };
+var UNDERSCORE = 95;
+var RESERVED_PREFIXES = ["_XLFN.", "_XLWS.", "_XLPM."];
 var KNOWN_ERRORS = /* @__PURE__ */ new Set([
   "#NULL!",
   "#DIV/0!",
@@ -472,7 +477,7 @@ var KNOWN_ERRORS = /* @__PURE__ */ new Set([
   "#CALC!",
   "#SPILL!"
 ]);
-var _formula, _pos, _FormulaLexer_instances, readNextToken_fn, readString_fn, readErrorLiteral_fn, readQuotedSheetRef_fn, readNumber_fn, readIdentifier_fn, readCellRefChars_fn, readOperator_fn, skipWhitespace_fn;
+var _formula, _pos, _FormulaLexer_instances, readNextToken_fn, readString_fn, readErrorLiteral_fn, readQuotedSheetRef_fn, readNumber_fn, readIdentifier_fn, stripReservedPrefixes_fn, readCellRefChars_fn, readOperator_fn, skipWhitespace_fn;
 var FormulaLexer = class {
   constructor(formula) {
     __privateAdd(this, _FormulaLexer_instances);
@@ -490,7 +495,7 @@ var FormulaLexer = class {
       const token = __privateMethod(this, _FormulaLexer_instances, readNextToken_fn).call(this);
       if (token) tokens.push(token);
     }
-    tokens.push(makeToken(28 /* EOF */, "", __privateGet(this, _pos)));
+    tokens.push(makeToken(31 /* EOF */, "", __privateGet(this, _pos)));
     return tokens;
   }
 };
@@ -544,7 +549,7 @@ readErrorLiteral_fn = function() {
   if (!KNOWN_ERRORS.has(upper2)) {
     throw new FormulaException(`Unknown error literal "${raw}" at position ${start}.`);
   }
-  return makeToken(27 /* ErrorLiteral */, upper2, start);
+  return makeToken(30 /* ErrorLiteral */, upper2, start);
 };
 readQuotedSheetRef_fn = function() {
   const start = __privateWrapper(this, _pos)._++;
@@ -607,10 +612,8 @@ readIdentifier_fn = function() {
     } else break;
   }
   let upper2 = raw.toUpperCase();
-  if (upper2.startsWith("_XLFN.")) {
-    raw = raw.slice(6);
-    upper2 = upper2.slice(6);
-  }
+  raw = __privateMethod(this, _FormulaLexer_instances, stripReservedPrefixes_fn).call(this, raw, upper2);
+  if (raw.length !== upper2.length) upper2 = upper2.slice(upper2.length - raw.length);
   if (upper2 === "TRUE") return makeToken(2 /* Boolean */, "TRUE", start);
   if (upper2 === "FALSE") return makeToken(2 /* Boolean */, "FALSE", start);
   if (__privateGet(this, _formula)[__privateGet(this, _pos)] === "!") {
@@ -632,6 +635,30 @@ readIdentifier_fn = function() {
   }
   return makeToken(23 /* NamedRange */, raw, start);
 };
+/**
+ * Drops Excel's storage-level name decorations. They carry no semantics — the
+ * writer stamps them so an older reader fails loudly instead of silently
+ * mis-evaluating — and they *stack*: `_xlfn._xlws.FILTER` wears two. Stripping
+ * one prefix once, as this used to, leaves `_XLWS.FILTER` unresolvable.
+ *
+ * Every identifier in every formula passes through here, so the common case is
+ * gated on a single char-code test: a name not starting with '_' returns
+ * untouched without so much as a comparison against the prefix table.
+ */
+stripReservedPrefixes_fn = function(raw, upper2) {
+  if (raw.charCodeAt(0) !== UNDERSCORE) return raw;
+  let cut = 0;
+  outer: for (; ; ) {
+    for (const prefix of RESERVED_PREFIXES) {
+      if (upper2.startsWith(prefix, cut)) {
+        cut += prefix.length;
+        continue outer;
+      }
+    }
+    break;
+  }
+  return cut > 0 && cut < raw.length ? raw.slice(cut) : raw;
+};
 readCellRefChars_fn = function() {
   let ref = "";
   while (__privateGet(this, _pos) < __privateGet(this, _formula).length) {
@@ -675,6 +702,14 @@ readOperator_fn = function() {
       return makeToken(26 /* AtSign */, "@", start);
     case "!":
       return makeToken(25 /* Exclamation */, "!", start);
+    case "{":
+      return makeToken(27 /* LeftBrace */, "{", start);
+    case "}":
+      return makeToken(28 /* RightBrace */, "}", start);
+    // Inside an array constant ';' separates rows. Excel always stores ',' as
+    // the argument separator regardless of locale, so ';' has no other role.
+    case ";":
+      return makeToken(29 /* Semicolon */, ";", start);
     case "<":
       if (__privateGet(this, _formula)[__privateGet(this, _pos)] === ">") {
         __privateWrapper(this, _pos)._++;
@@ -757,6 +792,19 @@ var ErrorNode = class extends FormulaNode {
     return this.errorValue;
   }
 };
+var _value;
+var ArrayLiteralNode = class extends FormulaNode {
+  constructor(array) {
+    super();
+    this.array = array;
+    __privateAdd(this, _value);
+    __privateSet(this, _value, FormulaValue.array(array));
+  }
+  evaluate() {
+    return __privateGet(this, _value);
+  }
+};
+_value = new WeakMap();
 var BlankNode = class extends FormulaNode {
   evaluate() {
     return FormulaValue.blank;
@@ -1034,7 +1082,7 @@ var CallNode = class extends FormulaNode {
 };
 
 // src/formula-parser.ts
-var _tokens, _pos2, _FormulaParser_instances, current_get, advance_fn, expect_fn, parseComparison_fn, parseConcatenation_fn, parseAddSub_fn, parseMulDiv_fn, parseUnary_fn, parsePower_fn, parsePercent_fn, parsePostfix_fn, parsePrimary_fn, tryParseFullRange_fn, parseFunction_fn, parseArgList_fn;
+var _tokens, _pos2, _FormulaParser_instances, current_get, advance_fn, expect_fn, parseComparison_fn, parseConcatenation_fn, parseAddSub_fn, parseMulDiv_fn, parseUnary_fn, parsePower_fn, parsePercent_fn, parsePostfix_fn, parsePrimary_fn, tryParseFullRange_fn, parseArrayLiteral_fn, parseArrayElement_fn, parseFunction_fn, parseArgList_fn;
 var FormulaParser = class {
   constructor(tokens) {
     __privateAdd(this, _FormulaParser_instances);
@@ -1045,7 +1093,7 @@ var FormulaParser = class {
   parse() {
     __privateSet(this, _pos2, 0);
     const node = __privateMethod(this, _FormulaParser_instances, parseComparison_fn).call(this);
-    if (__privateGet(this, _FormulaParser_instances, current_get).type !== 28 /* EOF */) {
+    if (__privateGet(this, _FormulaParser_instances, current_get).type !== 31 /* EOF */) {
       throw new FormulaException(
         `Unexpected token '${__privateGet(this, _FormulaParser_instances, current_get).value}' at position ${__privateGet(this, _FormulaParser_instances, current_get).position}.`
       );
@@ -1057,7 +1105,7 @@ _tokens = new WeakMap();
 _pos2 = new WeakMap();
 _FormulaParser_instances = new WeakSet();
 current_get = function() {
-  return __privateGet(this, _tokens)[__privateGet(this, _pos2)] ?? { type: 28 /* EOF */, value: "", position: -1 };
+  return __privateGet(this, _tokens)[__privateGet(this, _pos2)] ?? { type: 31 /* EOF */, value: "", position: -1 };
 };
 advance_fn = function() {
   const t = __privateGet(this, _FormulaParser_instances, current_get);
@@ -1172,7 +1220,7 @@ parsePrimary_fn = function() {
     case 2 /* Boolean */:
       __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
       return new BooleanNode(token.value === "TRUE");
-    case 27 /* ErrorLiteral */:
+    case 30 /* ErrorLiteral */:
       __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
       return new ErrorNode(FormulaValue.error(FormulaValue.errorFromString(token.value)));
     case 3 /* CellReference */: {
@@ -1211,6 +1259,8 @@ parsePrimary_fn = function() {
       return new SpillReferenceNode(token.value);
     case 5 /* Function */:
       return __privateMethod(this, _FormulaParser_instances, parseFunction_fn).call(this);
+    case 27 /* LeftBrace */:
+      return __privateMethod(this, _FormulaParser_instances, parseArrayLiteral_fn).call(this);
     case 6 /* LeftParen */: {
       __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
       const expr = __privateMethod(this, _FormulaParser_instances, parseComparison_fn).call(this);
@@ -1245,6 +1295,79 @@ tryParseFullRange_fn = function(startText, sheetName) {
   const hi = Math.max(start.index, end.index);
   return start.kind === "col" ? new FullRangeReferenceNode(lo, hi, null, null, sheetName) : new FullRangeReferenceNode(null, null, lo, hi, sheetName);
 };
+/**
+ * Parses an array constant: `{1,2;3,4}` — ',' separates columns, ';' rows.
+ *
+ * Excel permits only literals inside one (no references, no calls, not even
+ * arithmetic beyond a leading sign), so the value is fully determined here and
+ * is materialised once into the node instead of being rebuilt on every eval.
+ *
+ * A ragged constant is rejected rather than padded: Excel refuses to accept
+ * one at entry, so a file cannot legitimately contain it, and silently filling
+ * the gaps would invent data the author never wrote.
+ */
+parseArrayLiteral_fn = function() {
+  const open = __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
+  const rows2 = [];
+  let row2 = [];
+  for (; ; ) {
+    row2.push(__privateMethod(this, _FormulaParser_instances, parseArrayElement_fn).call(this));
+    if (__privateGet(this, _FormulaParser_instances, current_get).type === 8 /* Comma */) {
+      __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
+      continue;
+    }
+    if (__privateGet(this, _FormulaParser_instances, current_get).type === 29 /* Semicolon */) {
+      __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
+      rows2.push(row2);
+      row2 = [];
+      continue;
+    }
+    break;
+  }
+  rows2.push(row2);
+  __privateMethod(this, _FormulaParser_instances, expect_fn).call(this, 28 /* RightBrace */);
+  const cols = rows2[0].length;
+  if (rows2.some((r) => r.length !== cols)) {
+    throw new FormulaException(
+      `Array constant at position ${open.position} has rows of differing lengths.`
+    );
+  }
+  const array = new ArrayValue(rows2.length, cols);
+  for (let r = 0; r < rows2.length; r++) {
+    for (let c = 0; c < cols; c++) array.set(r, c, rows2[r][c]);
+  }
+  return new ArrayLiteralNode(array);
+};
+/** One element of an array constant: a literal, optionally signed. */
+parseArrayElement_fn = function() {
+  let negate = false;
+  let signed = false;
+  while (__privateGet(this, _FormulaParser_instances, current_get).type === 10 /* Minus */ || __privateGet(this, _FormulaParser_instances, current_get).type === 9 /* Plus */) {
+    if (__privateGet(this, _FormulaParser_instances, current_get).type === 10 /* Minus */) negate = !negate;
+    signed = true;
+    __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
+  }
+  const token = __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
+  switch (token.type) {
+    case 0 /* Number */: {
+      const n = parseFloat(token.value);
+      if (isNaN(n)) throw new FormulaException(`Invalid number: ${token.value}`);
+      return FormulaValue.number(negate ? -n : n);
+    }
+    case 1 /* String */:
+      if (signed) break;
+      return FormulaValue.text(token.value);
+    case 2 /* Boolean */:
+      if (signed) break;
+      return FormulaValue.boolean(token.value === "TRUE");
+    case 30 /* ErrorLiteral */:
+      if (signed) break;
+      return FormulaValue.error(FormulaValue.errorFromString(token.value));
+  }
+  throw new FormulaException(
+    `Array constants accept only literal values; got '${token.value}' at position ${token.position}.`
+  );
+};
 parseFunction_fn = function() {
   const nameToken = __privateMethod(this, _FormulaParser_instances, advance_fn).call(this);
   __privateMethod(this, _FormulaParser_instances, expect_fn).call(this, 6 /* LeftParen */);
@@ -4061,22 +4184,46 @@ function unique(a, c) {
   const out = fromRows(result);
   return byCol2 ? FormulaValue.array(out.arrayVal.transpose()) : out;
 }
+var numVector = (a, c, i, dflt) => {
+  if (i >= a.length) return { ok: true, v: [dflt] };
+  const val = a[i].evaluate(c);
+  if (val.isError) return { ok: false, e: val };
+  const out = [];
+  for (const item of val.isArray ? val.arrayVal.values() : [val]) {
+    if (item.isBlank) continue;
+    const d = item.tryAsDouble();
+    if (!d.ok) return { ok: false, e: FormulaValue.errorValue };
+    out.push(d.value);
+  }
+  return out.length > 0 ? { ok: true, v: out } : { ok: true, v: [dflt] };
+};
 function sort(a, c) {
   const v = a[0].evaluate(c);
   if (v.isError) return v;
-  const sortIndex = num4(a, c, 1, 1);
-  if (!sortIndex.ok) return sortIndex.e;
-  const sortOrder = num4(a, c, 2, 1);
-  if (!sortOrder.ok) return sortOrder.e;
+  const indices = numVector(a, c, 1, 1);
+  if (!indices.ok) return indices.e;
+  const orders = numVector(a, c, 2, 1);
+  if (!orders.ok) return orders.e;
   const byCol2 = a.length > 3 ? a[3].evaluate(c).coerceToBool().booleanValue : false;
+  if (orders.v.length !== 1 && orders.v.length !== indices.v.length) {
+    return FormulaValue.errorValue;
+  }
   const base = byCol2 ? asArray2(v).transpose() : asArray2(v);
   const rows2 = toRows(base);
-  const idx = Math.trunc(sortIndex.n) - 1;
-  const dir = sortOrder.n < 0 ? -1 : 1;
-  if (rows2.length > 0 && (idx < 0 || idx >= rows2[0].length)) return FormulaValue.errorValue;
+  const keys = indices.v.map((n, i) => ({
+    col: Math.trunc(n) - 1,
+    dir: (orders.v.length === 1 ? orders.v[0] : orders.v[i]) < 0 ? -1 : 1
+  }));
+  const width = rows2.length > 0 ? rows2[0].length : 0;
+  if (rows2.length > 0 && keys.some((k) => k.col < 0 || k.col >= width)) {
+    return FormulaValue.errorValue;
+  }
   const sorted = rows2.map((r, i) => ({ r, i })).sort((x, y) => {
-    const cmp = FormulaValue.compare(x.r[idx], y.r[idx]) * dir;
-    return cmp !== 0 ? cmp : x.i - y.i;
+    for (const k of keys) {
+      const cmp = FormulaValue.compare(x.r[k.col], y.r[k.col]) * k.dir;
+      if (cmp !== 0) return cmp;
+    }
+    return x.i - y.i;
   }).map((o) => o.r);
   const out = fromRows(sorted);
   return byCol2 ? FormulaValue.array(out.arrayVal.transpose()) : out;