@borgar/fx 5.0.1 → 5.0.2

package/lib/constants.ts

@@ -14,6 +14,9 @@ export const REF_BEAM = 'range_beam';
 export const REF_TERNARY = 'range_ternary';
 export const REF_NAMED = 'range_named';
 export const REF_STRUCT = 'structured';
+// TODO: in future, we should type the difference between A1:B1 (REF_RANGE) and
+//       A1 (REF_CELL) but this will require a major version bump.
+export const REF_CELL = 'cell'; // internal only
 export const FX_PREFIX = 'fx_prefix';
 export const UNKNOWN = 'unknown';
 

package/lib/fixRanges.spec.ts

@@ -66,6 +66,20 @@ describe('fixRanges basics', () => {
   });
 });
 
+describe('fixRanges prefixes', () => {
+  test('Quotes prefixes as needed', () => {
+    isFixed('=Sch1!B2', "='Sch1'!B2");
+    isFixed('=[Foo]Ab12x!B2', '=[Foo]Ab12x!B2');
+    isFixed('=[Foo]Ab12!B2', "='[Foo]Ab12'!B2");
+    isFixed('=ABC123!B2', "='ABC123'!B2");
+    isFixed('=abc123!B2', "='abc123'!B2");
+    isFixed('=C!B2', "='C'!B2");
+    isFixed('=R!B2', "='R'!B2");
+    isFixed('=RC!B2', "='RC'!B2");
+    isFixed('=CR!B2', '=CR!B2');
+  });
+});
+
 describe('fixRanges A1', () => {
   const opt = { allowTernary: true };
 

package/lib/lexers/lexRangeA1.ts

@@ -99,7 +99,7 @@ export function lexRangeA1 (
       }
     }
     // LT  : this is A1
-    if (top && canEndRange(str, preOp)) {
+    if (top && canEndRange(str, preOp) && str.charCodeAt(preOp) !== 33) { // 33 = "!"
       return { type: REF_RANGE, value: str.slice(pos, preOp) };
     }
   }

package/lib/lexers/lexRangeR1C1.ts

@@ -11,6 +11,7 @@ const UC_C = 67;
 const LC_C = 99;
 const PLUS = 43;
 const MINUS = 45;
+const EXCL = 33;
 
 // C
 // C\[[+-]?\d+\]
@@ -97,7 +98,7 @@ export function lexRangeR1C1 (
   p += r1;
   const c1 = lexR1C1Part(str, p);
   p += c1;
-  if (c1 || r1) {
+  if ((c1 || r1) && str.charCodeAt(p) !== EXCL) {
     const op = advRangeOp(str, p);
     const preOp = p;
     if (op) {

package/lib/mergeRefTokens.ts

@@ -1,27 +1,29 @@
-import { CONTEXT, CONTEXT_QUOTE, REF_RANGE, REF_NAMED, REF_BEAM, REF_TERNARY, OPERATOR, REF_STRUCT } from './constants.ts';
+import { CONTEXT, CONTEXT_QUOTE, REF_RANGE, REF_NAMED, REF_BEAM, REF_TERNARY, OPERATOR, REF_STRUCT, REF_CELL } from './constants.ts';
 import type { Token } from './types.ts';
 
 const END = '$';
 
 const validRunsMerge = [
-  [ REF_RANGE, ':', REF_RANGE ],
-  [ REF_RANGE, '.:', REF_RANGE ],
-  [ REF_RANGE, ':.', REF_RANGE ],
-  [ REF_RANGE, '.:.', REF_RANGE ],
+  [ REF_CELL, ':', REF_CELL ],
+  [ REF_CELL, '.:', REF_CELL ],
+  [ REF_CELL, ':.', REF_CELL ],
+  [ REF_CELL, '.:.', REF_CELL ],
   [ REF_RANGE ],
   [ REF_BEAM ],
   [ REF_TERNARY ],
-  [ CONTEXT, '!', REF_RANGE, ':', REF_RANGE ],
-  [ CONTEXT, '!', REF_RANGE, '.:', REF_RANGE ],
-  [ CONTEXT, '!', REF_RANGE, ':.', REF_RANGE ],
-  [ CONTEXT, '!', REF_RANGE, '.:.', REF_RANGE ],
+  [ CONTEXT, '!', REF_CELL, ':', REF_CELL ],
+  [ CONTEXT, '!', REF_CELL, '.:', REF_CELL ],
+  [ CONTEXT, '!', REF_CELL, ':.', REF_CELL ],
+  [ CONTEXT, '!', REF_CELL, '.:.', REF_CELL ],
+  [ CONTEXT, '!', REF_CELL ],
   [ CONTEXT, '!', REF_RANGE ],
   [ CONTEXT, '!', REF_BEAM ],
   [ CONTEXT, '!', REF_TERNARY ],
-  [ CONTEXT_QUOTE, '!', REF_RANGE, ':', REF_RANGE ],
-  [ CONTEXT_QUOTE, '!', REF_RANGE, '.:', REF_RANGE ],
-  [ CONTEXT_QUOTE, '!', REF_RANGE, ':.', REF_RANGE ],
-  [ CONTEXT_QUOTE, '!', REF_RANGE, '.:.', REF_RANGE ],
+  [ CONTEXT_QUOTE, '!', REF_CELL, ':', REF_CELL ],
+  [ CONTEXT_QUOTE, '!', REF_CELL, '.:', REF_CELL ],
+  [ CONTEXT_QUOTE, '!', REF_CELL, ':.', REF_CELL ],
+  [ CONTEXT_QUOTE, '!', REF_CELL, '.:.', REF_CELL ],
+  [ CONTEXT_QUOTE, '!', REF_CELL ],
   [ CONTEXT_QUOTE, '!', REF_RANGE ],
   [ CONTEXT_QUOTE, '!', REF_BEAM ],
   [ CONTEXT_QUOTE, '!', REF_TERNARY ],
@@ -62,7 +64,14 @@ const matcher = (tokens: Token[], currNode, anchorIndex, index = 0) => {
   while (i <= max) {
     const token = tokens[anchorIndex - i];
     if (token) {
-      const key = (token.type === OPERATOR) ? token.value : token.type;
+      const value = token.value;
+      let key = (token.type === OPERATOR) ? value : token.type;
+      // we need to prevent merging ["A1:B2" ":" "C3"] as a range is only
+      // allowed to contain a single ":" operator even if "A1:B2:C3" is
+      // valid Excel syntax
+      if (key === REF_RANGE && !value.includes(':')) {
+        key = REF_CELL;
+      }
       if (key in node) {
         node = node[key];
         i += 1;

package/lib/parseA1Ref.spec.ts

@@ -335,3 +335,10 @@ describe('A1 trimmed ranges vs named ranges', () => {
     isA1Equal('foo.:B2', { range: { top: 1, left: 1, right: 4460, trim: 'head' } }, { allowTernary: true });
   });
 });
+
+describe('Sheet name that looks like an A1 ref', () => {
+  test('parse correctly', () => {
+    isA1Equal("'Sch1'!B2", { context: [ 'Sch1' ], range: { top: 1, left: 1, bottom: 1, right: 1 } });
+    isA1Equal('Sch1!B2', { context: [ 'Sch1' ], range: { top: 1, left: 1, bottom: 1, right: 1 } });
+  });
+});

package/lib/stringifyA1Ref.spec.ts

@@ -30,6 +30,12 @@ describe('stringifyA1Ref', () => {
     // @ts-expect-error -- testing invalid input
     expect(stringifyA1Ref({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', name: 'foo' })).toBe('foo');
   });
+
+  test('should quote prefixes that look like A1 ranges', () => {
+    expect(stringifyA1Ref({ context: [ 'Ab12' ], range: rangeA1 })).toBe("'Ab12'!A1");
+    expect(stringifyA1Ref({ context: [ 'Sch1' ], range: rangeA1 })).toBe("'Sch1'!A1");
+    expect(stringifyA1Ref({ context: [ 'Foo12345' ], range: rangeA1 })).toBe("'Foo12345'!A1");
+  });
 });
 
 describe('stringifyA1Ref in XLSX mode', () => {
@@ -61,4 +67,16 @@ describe('stringifyA1Ref in XLSX mode', () => {
     // @ts-expect-error -- testing invalid input
     expect(stringifyA1RefXlsx({ context: [ 'MyFile.xlsx', 'Sheet1' ], name: 'foo' })).toBe('foo');
   });
+
+  test('should quote prefixes that look like ranges', () => {
+    expect(stringifyA1RefXlsx({ sheetName: 'C', range: rangeA1 })).toBe("'C'!A1");
+    expect(stringifyA1RefXlsx({ sheetName: 'R', range: rangeA1 })).toBe("'R'!A1");
+    expect(stringifyA1RefXlsx({ sheetName: 'RC', range: rangeA1 })).toBe("'RC'!A1");
+    expect(stringifyA1RefXlsx({ sheetName: 'Ab12', range: rangeA1 })).toBe("'Ab12'!A1");
+    expect(stringifyA1RefXlsx({ sheetName: 'Sch1', range: rangeA1 })).toBe("'Sch1'!A1");
+    expect(stringifyA1RefXlsx({ sheetName: 'Foo12345', range: rangeA1 })).toBe("'Foo12345'!A1");
+    expect(stringifyA1RefXlsx({ workbookName: 'Ab12', range: rangeA1 })).toBe("'[Ab12]'!A1");
+    expect(stringifyA1RefXlsx({ workbookName: 'Sch1', range: rangeA1 })).toBe("'[Sch1]'!A1");
+    expect(stringifyA1RefXlsx({ workbookName: 'Foo12345', range: rangeA1 })).toBe("'[Foo12345]'!A1");
+  });
 });

package/lib/stringifyPrefix.ts

@@ -10,6 +10,27 @@ import type {
 } from './types.ts';
 
 const reBannedChars = /[^0-9A-Za-z._¡¤§¨ª\u00ad¯-\uffff]/;
+// A1-XFD1048575 | R | C | RC
+const reIsRangelike = /^(R|C|RC|[A-Z]{1,3}\d{1,7})$/i;
+
+export function needQuotes (scope: string, yesItDoes = 0): number {
+  if (yesItDoes) {
+    return 1;
+  }
+  if (scope) {
+    if (reBannedChars.test(scope)) {
+      return 1;
+    }
+    if (reIsRangelike.test(scope)) {
+      return 1;
+    }
+  }
+  return 0;
+}
+
+export function quotePrefix (prefix) {
+  return "'" + prefix.replace(/'/g, "''") + "'";
+}
 
 export function stringifyPrefix (
   ref: ReferenceA1 | ReferenceName | ReferenceStruct | ReferenceR1C1
@@ -23,12 +44,12 @@ export function stringifyPrefix (
     if (scope) {
       const part = (nth % 2) ? '[' + scope + ']' : scope;
       pre = part + pre;
-      quote += +reBannedChars.test(scope);
+      quote += needQuotes(scope, quote);
       nth++;
     }
   }
   if (quote) {
-    pre = "'" + pre.replace(/'/g, "''") + "'";
+    pre = quotePrefix(pre);
   }
   return pre ? pre + '!' : pre;
 }
@@ -41,14 +62,14 @@ export function stringifyPrefixXlsx (
   const { workbookName, sheetName } = ref;
   if (workbookName) {
     pre += '[' + workbookName + ']';
-    quote += +reBannedChars.test(workbookName);
+    quote += needQuotes(workbookName);
   }
   if (sheetName) {
     pre += sheetName;
-    quote += +reBannedChars.test(sheetName);
+    quote += needQuotes(sheetName);
   }
   if (quote) {
-    pre = "'" + pre.replace(/'/g, "''") + "'";
+    pre = quotePrefix(pre);
   }
   return pre ? pre + '!' : pre;
 }

package/lib/tokenize.spec.ts

@@ -1062,6 +1062,13 @@ describe('lexer', () => {
         { type: FX_PREFIX, value: '=' },
         { type: REF_RANGE, value: 'A1:C1' }
       ]);
+
+      isTokens('=A1:C1:D1', [
+        { type: FX_PREFIX, value: '=' },
+        { type: REF_RANGE, value: 'A1:C1' },
+        { type: OPERATOR, value: ':' },
+        { type: REF_RANGE, value: 'D1' }
+      ]);
     });
 
     test('spill range syntax', () => {
@@ -2172,4 +2179,24 @@ describe('lexer', () => {
       { type: OPERATOR, value: ')' }
     ]);
   });
+
+  describe('Sheet name that looks like an A1 ref', () => {
+    test('Sheet name that looks like an A1 ref', () => {
+      expect(tokenize("'Sch1'!B2")).toEqual([
+        { type: REF_RANGE, value: "'Sch1'!B2" }
+      ]);
+      expect(tokenize('Sch1!B2')).toEqual([
+        { type: REF_RANGE, value: 'Sch1!B2' }
+      ]);
+    });
+
+    test('Sheet name that is a R or C ref', () => {
+      expect(tokenize("'C'!R[-9]C[-3]", { r1c1: true })).toEqual([
+        { type: REF_RANGE, value: "'C'!R[-9]C[-3]" }
+      ]);
+      expect(tokenize('C!R[-9]C[-3]', { r1c1: true })).toEqual([
+        { type: REF_RANGE, value: 'C!R[-9]C[-3]' }
+      ]);
+    });
+  });
 });

package/lib/translateToR1C1.ts

@@ -100,8 +100,7 @@ export function translateTokensToR1C1 (
     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);
       if (ref) {
         const d = ref.range;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgar/fx",
-  "version": "5.0.1",
+  "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"
   }
 }