@borgar/fx 5.0.0 → 5.0.2

package/lib/translateToR1C1.spec.ts

@@ -2,7 +2,7 @@ import { describe, test, expect } from 'vitest';
 import { translateFormulaToR1C1, translateTokensToR1C1 } from './translateToR1C1.ts';
 import { tokenize } from './tokenize.ts';
 import { addTokenMeta } from './addTokenMeta.ts';
-import { FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_BEAM, REF_STRUCT } from './constants.ts';
+import { FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_BEAM, REF_STRUCT, REF_NAMED, NUMBER } from './constants.ts';
 
 function isA2R (expr: string, anchor: string, result: string) {
   expect(translateFormulaToR1C1(expr, anchor)).toBe(result);
@@ -219,9 +219,73 @@ describe('translate works with trimmed ranges', () => {
 
   test('trimmed range translation', () => {
     testExpr('Sheet!A1.:.B2*Sheet2!AZ.:.ZZ', 'B2', [
-      { type: 'range', value: 'Sheet!R[-1]C[-1].:.RC' },
-      { type: 'operator', value: '*' },
-      { type: 'range_beam', value: 'Sheet2!C[50].:.C[700]' }
+      { type: REF_RANGE, value: 'Sheet!R[-1]C[-1].:.RC' },
+      { type: OPERATOR, value: '*' },
+      { type: REF_BEAM, value: 'Sheet2!C[50].:.C[700]' }
+    ]);
+  });
+});
+
+describe('translate does not create invalid LET arguments', () => {
+  // Unlike in A1, LET(c,1,c) is not valid syntax with the R1C1 notation in Excel.
+  // If you create a cell with this expression in A1 mode and flip to R1C1, Excel
+  // will not change it when expressing it, but will not allow you to re-enter it.
+  //
+  // Excel will always save the formula such as the arguments will have a "_xlpm."
+  // prefix: _xlfn.LET(_xlpm.c,1,_xlpm.c)
+  //
+  // However, that is also invalid syntax in the exposed/common Excel formula syntax.
+  // To counter this, fx does the following:
+  //
+  // tokenize:
+  //    Supports _xlpm.c in both modes.
+  //    Assumes c, C, r and R are names when encountered as tokens within LET functions.
+  // translateTokensToR1C1:
+  //    Tries to be unambiguous by serializing "c" ranges in within LET as C[0].
+  //    Same goes for "r" to R[0]. Prefixed names are left as they are.
+  //    This way round-tripping is possible.
+  function testExpr (expr: string, anchor: string, expected: any[]) {
+    const opts = { mergeRefs: true, xlsx: true, r1c1: false };
+    expect(translateTokensToR1C1(tokenize(expr, opts), anchor)).toEqual(expected);
+  }
+
+  test('preserve C + R argument names', () => {
+    isA2R('=LET(c,1,c)', 'B2', '=LET(c,1,c)');
+    isA2R('=LET(r,1,r)', 'B2', '=LET(r,1,r)');
+    // ensure that we disambiguate C and R ranges
+    isA2R('=LET(c,B:B,c+B:B)', 'B2', '=LET(c,C[0],c+C[0])');
+    isA2R('=LET(r,2:2,r+2:2)', 'B2', '=LET(r,R[0],r+R[0])');
+    // prefixed parameters work too
+    isA2R('=LET(_xlpm.c,1,_xlpm.c)', 'B2', '=LET(_xlpm.c,1,_xlpm.c)');
+    isA2R('=LET(_xlpm.r,1,_xlpm.r)', 'B2', '=LET(_xlpm.r,1,_xlpm.r)');
+
+    testExpr('=LET(c,1,c)', 'B2', [
+      { type: FX_PREFIX, value: '=' },
+      { type: FUNCTION, value: 'LET' },
+      { type: OPERATOR, value: '(' },
+      { type: REF_NAMED, value: 'c' },
+      { type: OPERATOR, value: ',' },
+      { type: NUMBER, value: '1' },
+      { type: OPERATOR, value: ',' },
+      { type: REF_NAMED, value: 'c' },
+      { type: OPERATOR, value: ')' }
+    ]);
+  });
+
+  test('ensure that C + R ranges are unambiguous', () => {
+    isA2R('=LET(c,B:B,c)', 'B2', '=LET(c,C[0],c)');
+    isA2R('=LET(r,2:2,r)', 'B2', '=LET(r,R[0],r)');
+
+    testExpr('=LET(c,B:B,c)', 'B2', [
+      { type: FX_PREFIX, value: '=' },
+      { type: FUNCTION, value: 'LET' },
+      { type: OPERATOR, value: '(' },
+      { type: REF_NAMED, value: 'c' },
+      { type: OPERATOR, value: ',' },
+      { type: REF_BEAM, value: 'C[0]' },
+      { type: OPERATOR, value: ',' },
+      { type: REF_NAMED, value: 'c' },
+      { type: OPERATOR, value: ')' }
     ]);
   });
 });

package/lib/translateToR1C1.ts

@@ -4,8 +4,11 @@ import { parseA1Range } from './parseA1Range.ts';
 import type { RangeR1C1, ReferenceA1Xlsx, Token } from './types.ts';
 import { stringifyTokens } from './stringifyTokens.ts';
 import { cloneToken } from './cloneToken.ts';
-import { REF_BEAM, REF_RANGE, REF_TERNARY } from './constants.ts';
+import { FUNCTION, OPERATOR, REF_BEAM, REF_RANGE, REF_TERNARY } from './constants.ts';
 import { splitContext } from './parseRef.ts';
+import { isRCTokenValue } from './isRCTokenValue.ts';
+
+const reLetLambda = /^l(?:ambda|et)$/i;
 
 const calc = (abs: boolean, vX: number, aX: number): number => {
   if (vX == null) {
@@ -70,33 +73,57 @@ export function translateTokensToR1C1 (
     throw new Error('translateTokensToR1C1 got an invalid anchorCell: ' + anchorCell);
   }
   const { top, left } = anchorRange;
+  let withinCall = 0;
+  let parenDepth = 0;
 
   let offsetSkew = 0;
-  const outTokens = [];
+  const outTokens: Token[] = [];
   for (let token of tokens) {
     const tokenType = token?.type;
+    if (tokenType === OPERATOR) {
+      if (token.value === '(') {
+        parenDepth++;
+        const lastToken = outTokens[outTokens.length - 1];
+        if (lastToken && lastToken.type === FUNCTION) {
+          if (reLetLambda.test(lastToken.value)) {
+            withinCall = parenDepth;
+          }
+        }
+      }
+      else if (token.value === ')') {
+        parenDepth--;
+        if (parenDepth < withinCall) {
+          withinCall = 0;
+        }
+      }
+    }
     if (tokenType === REF_RANGE || tokenType === REF_BEAM || tokenType === REF_TERNARY) {
       token = cloneToken(token);
       const tokenValue = token.value;
-      // We can get away with using the xlsx ref-parser here because it is more permissive
-      // and we will end up with the same prefix after serialization anyway:
+      // We can get away with using the xlsx ref-parser here because it is more permissive:
       const ref = quickParseA1(tokenValue);
-      const d = ref.range;
-      const range: RangeR1C1 = {};
-      range.r0 = calc(d.$top, d.top, top);
-      range.r1 = calc(d.$bottom, d.bottom, top);
-      range.c0 = calc(d.$left, d.left, left);
-      range.c1 = calc(d.$right, d.right, left);
-      range.$r0 = d.$top;
-      range.$r1 = d.$bottom;
-      range.$c0 = d.$left;
-      range.$c1 = d.$right;
-      if (d.trim) {
-        range.trim = d.trim;
+      if (ref) {
+        const d = ref.range;
+        const range: RangeR1C1 = {};
+        range.r0 = calc(d.$top, d.top, top);
+        range.r1 = calc(d.$bottom, d.bottom, top);
+        range.c0 = calc(d.$left, d.left, left);
+        range.c1 = calc(d.$right, d.right, left);
+        range.$r0 = d.$top;
+        range.$r1 = d.$bottom;
+        range.$c0 = d.$left;
+        range.$c1 = d.$right;
+        if (d.trim) {
+          range.trim = d.trim;
+        }
+        // @ts-expect-error -- reusing the object, switching it to R1C1 by swapping the range
+        ref.range = range;
+        let val = stringifyR1C1RefXlsx(ref);
+        if (isRCTokenValue(val) && withinCall) {
+          val += '[0]';
+        }
+        token.value = val;
       }
-      // @ts-expect-error -- reusing the object, switching it to R1C1 by swapping the range
-      ref.range = range;
-      token.value = stringifyR1C1RefXlsx(ref);
       // if token includes offsets, those offsets are now likely wrong!
       if (token.loc) {
         token.loc[0] += offsetSkew;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgar/fx",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Utilities for working with Excel formulas",
   "type": "module",
   "exports": {
@@ -68,11 +68,11 @@
     "benchmark": "~2.1.4",
     "eslint": "~9.39.0",
     "typescript": "~5.9.3",
-    "typescript-eslint": "~8.46.2",
-    "vitest": "~4.0.6",
-    "globals": "~16.5.0",
-    "typedoc": "~0.28.14",
-    "typedoc-plugin-markdown": "~4.9.0",
-    "tsup": "~8.5.0"
+    "typescript-eslint": "~8.55.0",
+    "vitest": "~4.0.18",
+    "globals": "~17.3.0",
+    "typedoc": "~0.28.17",
+    "typedoc-plugin-markdown": "~4.10.0",
+    "tsup": "~8.5.1"
   }
 }