@borgar/fx 4.13.0 → 5.0.0

package/docs/AST_format.md

@@ -45,7 +45,7 @@ interface ReferenceIdentifier extends Node {
 }
 ```
 
-An identifier for a range or a named. The 
+An identifier for a range or a name.
 
 
 ## Literal
@@ -140,7 +140,7 @@ interface ArrayExpression extends Node {
 }
 ```
 
-An array expression. Excel does not have empty or sparse arrays and restricts array elements to literals. Google Sheets allows `ReferenceIdentifier`s as elements of arrays, the fx parser as an option for this but it is off by default.
+An array expression. Excel does not have empty or sparse arrays and restricts array elements to literals. Google Sheets allows `ReferenceIdentifier`s as elements of arrays, the fx parser has an option for this but it is off by default.
 
 ## LambdaExpression
 

package/eslint.config.mjs

@@ -0,0 +1,40 @@
+import borgarLint from '@borgar/eslint-config';
+import eslint from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import { defineConfig } from 'eslint/config';
+
+export default defineConfig([
+  {
+    files: [
+      '**/*.js',
+      '**/*.ts',
+      '**/*.mjs'
+    ],
+    ignores: [
+      'dist/*'
+    ],
+    languageOptions: {
+      globals: { ...globals.browser },
+      parserOptions: { projectService: { allowDefaultProject: [] } }
+    }
+  },
+  eslint.configs.recommended,
+  tseslint.configs.recommendedTypeChecked,
+  tseslint.configs.stylisticTypeChecked,
+  borgarLint.config.recommended,
+  borgarLint.config.stylistic({
+    commaDangle: false,
+    singleBlocks: true,
+    lineLength: 120
+  }),
+  {
+    rules: {
+      'no-shadow': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-call': 'off',
+      '@typescript-eslint/prefer-optional-chain': 'off',
+      '@typescript-eslint/no-unused-expressions': 'off',
+    }
+  }
+]);

package/lib/a1.spec.ts

@@ -0,0 +1,32 @@
+/* eslint-disable @stylistic/object-property-newline */
+import { describe, test, expect } from 'vitest';
+import { toRelative, toAbsolute } from './a1.ts';
+import type { RangeA1 } from './types.ts';
+
+describe('A1 utilities', () => {
+  test('toAbsolute and toRelative', () => {
+    const relA1Range = {
+      top: 0, left: 0, bottom: 0, right: 0,
+      $top: false, $left: false, $bottom: false, $right: false
+    };
+    const absA1Range = {
+      top: 0, left: 0, bottom: 0, right: 0,
+      $top: true, $left: true, $bottom: true, $right: true
+    };
+    expect(toAbsolute(relA1Range)).toEqual(absA1Range);
+    expect(toRelative(absA1Range)).toEqual(relA1Range);
+
+    const relA1RangeT: RangeA1 = {
+      top: 0, left: 0, bottom: 0, right: 0,
+      $top: false, $left: false, $bottom: false, $right: false,
+      trim: 'both'
+    };
+    const absA1RangeT: RangeA1 = {
+      top: 0, left: 0, bottom: 0, right: 0,
+      $top: true, $left: true, $bottom: true, $right: true,
+      trim: 'both'
+    };
+    expect(toAbsolute(relA1RangeT)).toEqual(absA1RangeT);
+    expect(toRelative(absA1RangeT)).toEqual(relA1RangeT);
+  });
+});

package/lib/a1.ts

@@ -0,0 +1,26 @@
+import type { RangeA1 } from './types.ts';
+
+export function toRelative (range: RangeA1): RangeA1 {
+  return Object.assign({}, range, { $left: false, $right: false, $top: false, $bottom: false });
+}
+
+export function toAbsolute (range: RangeA1): RangeA1 {
+  return Object.assign({}, range, { $left: true, $right: true, $top: true, $bottom: true });
+}
+
+export function toRow (top: number): string {
+  return String(top + 1);
+}
+
+export function rangeOperator (trim: 'head' | 'tail' | 'both' | null | undefined): string {
+  if (trim === 'both') {
+    return '.:.';
+  }
+  else if (trim === 'head') {
+    return '.:';
+  }
+  else if (trim === 'tail') {
+    return ':.';
+  }
+  return ':';
+}

package/lib/addA1RangeBounds.ts

@@ -0,0 +1,50 @@
+import { MAX_ROWS, MAX_COLS } from './constants.ts';
+import type { RangeA1 } from './types.ts';
+
+/**
+ * Fill the any missing bounds in range objects. Top will be set to 0, bottom to
+ * 1048575, left to 0, and right to 16383, if they are `null` or `undefined`.
+ *
+ * ```js
+ * addA1RangeBounds({
+ *   top: 0,
+ *   left: 0,
+ *   bottom: 1,
+ *   $top: true,
+ *   $left: false,
+ *   $bottom: false,
+ * });
+ * // => {
+ * //   top: 0,
+ * //   left: 0,
+ * //   bottom: 1,
+ * //   right: 16383,  // ← Added
+ * //   $top: true,
+ * //   $left: false,
+ * //   $bottom: false,
+ * //   $right: false  // ← Added
+ * // }
+ * ```
+ *
+ * @param range The range part of a reference object.
+ * @returns The same range with missing bounds filled in.
+ */
+export function addA1RangeBounds (range: RangeA1): RangeA1 {
+  if (range.top == null) {
+    range.top = 0;
+    range.$top = false;
+  }
+  if (range.bottom == null) {
+    range.bottom = MAX_ROWS;
+    range.$bottom = false;
+  }
+  if (range.left == null) {
+    range.left = 0;
+    range.$left = false;
+  }
+  if (range.right == null) {
+    range.right = MAX_COLS;
+    range.$right = false;
+  }
+  return range;
+}

package/lib/addTokenMeta.spec.ts

@@ -0,0 +1,166 @@
+import { describe, test, expect } from 'vitest';
+import { FX_PREFIX, OPERATOR, NUMBER, REF_RANGE, REF_BEAM, FUNCTION, WHITESPACE, REF_STRUCT } from './constants.ts';
+import { addTokenMeta } from './addTokenMeta.ts';
+import { tokenize } from './tokenize.ts';
+
+function isMetaTokens (expr: string, expected: any[], context?: any, opts?: any) {
+  const actual = addTokenMeta(tokenize(expr, opts), context);
+  if (actual.length === expected.length) {
+    actual.forEach((d, i) => {
+      const keys = Object.keys(d).concat(Object.keys(expected[i]));
+      keys.forEach(key => {
+        if (actual[i][key] === expected[i][key]) {
+          delete actual[i][key];
+          delete expected[i][key];
+        }
+      });
+    });
+  }
+  expect(actual).toEqual(expected);
+}
+
+describe('add extra meta to operators', () => {
+  test('parens should be grouped and tagged with depth', () => {
+    isMetaTokens('=((1)+(1))', [
+      { index: 0, depth: 0, type: FX_PREFIX, value: '=' },
+      { index: 1, depth: 1, type: OPERATOR, value: '(', groupId: 'fxg3' },
+      { index: 2, depth: 2, type: OPERATOR, value: '(', groupId: 'fxg1' },
+      { index: 3, depth: 2, type: NUMBER, value: '1' },
+      { index: 4, depth: 2, type: OPERATOR, value: ')', groupId: 'fxg1' },
+      { index: 5, depth: 1, type: OPERATOR, value: '+' },
+      { index: 6, depth: 2, type: OPERATOR, value: '(', groupId: 'fxg2' },
+      { index: 7, depth: 2, type: NUMBER, value: '1' },
+      { index: 8, depth: 2, type: OPERATOR, value: ')', groupId: 'fxg2' },
+      { index: 9, depth: 1, type: OPERATOR, value: ')', groupId: 'fxg3' }
+    ]);
+  });
+
+  test('don\'t be fooled by imbalanced parens', () => {
+    isMetaTokens('=)())', [
+      { index: 0, depth: 0, type: FX_PREFIX, value: '=' },
+      { index: 1, depth: 0, type: OPERATOR, value: ')', error: true },
+      { index: 2, depth: 1, type: OPERATOR, value: '(', groupId: 'fxg1' },
+      { index: 3, depth: 1, type: OPERATOR, value: ')', groupId: 'fxg1' },
+      { index: 4, depth: 0, type: OPERATOR, value: ')', error: true }
+    ]);
+  });
+
+  test('don\'t be fooled by nested curlys', () => {
+    isMetaTokens('={{}}', [
+      { index: 0, depth: 0, type: FX_PREFIX, value: '=' },
+      { index: 1, depth: 1, type: OPERATOR, value: '{', groupId: 'fxg1' },
+      { index: 2, depth: 1, type: OPERATOR, value: '{', error: true },
+      { index: 3, depth: 1, type: OPERATOR, value: '}', groupId: 'fxg1' },
+      { index: 4, depth: 0, type: OPERATOR, value: '}', error: true }
+    ]);
+  });
+
+  test('group ranges if they are equivalent', () => {
+    isMetaTokens("=B11,B11:B12,'Sheet11'!B11,SHEET1!$B11,sheet1!$b$11,A1:B11,[foo]Sheet1!B11,'[foo]Sheet1'!B11", [
+      { index: 0, depth: 0, type: FX_PREFIX, value: '=' },
+      { index: 1, depth: 0, type: REF_RANGE, value: 'B11', groupId: 'fxg1' },
+      { index: 2, depth: 0, type: OPERATOR, value: ',' },
+      { index: 3, depth: 0, type: REF_RANGE, value: 'B11:B12', groupId: 'fxg2' },
+      { index: 4, depth: 0, type: OPERATOR, value: ',' },
+      { index: 5, depth: 0, type: REF_RANGE, value: "'Sheet11'!B11", groupId: 'fxg3' },
+      { index: 6, depth: 0, type: OPERATOR, value: ',' },
+      { index: 7, depth: 0, type: REF_RANGE, value: 'SHEET1!$B11', groupId: 'fxg1' },
+      { index: 8, depth: 0, type: OPERATOR, value: ',' },
+      { index: 9, depth: 0, type: REF_RANGE, value: 'sheet1!$b$11', groupId: 'fxg1' },
+      { index: 10, depth: 0, type: OPERATOR, value: ',' },
+      { index: 11, depth: 0, type: REF_RANGE, value: 'A1:B11', groupId: 'fxg4' },
+      { index: 12, depth: 0, type: OPERATOR, value: ',' },
+      { index: 13, depth: 0, type: REF_RANGE, value: '[foo]Sheet1!B11', groupId: 'fxg1' },
+      { index: 14, depth: 0, type: OPERATOR, value: ',' },
+      { index: 15, depth: 0, type: REF_RANGE, value: "'[foo]Sheet1'!B11", groupId: 'fxg1' }
+    ], { sheetName: 'Sheet1', workbookName: 'foo' });
+  });
+
+  test('group beam references', () => {
+    isMetaTokens('=A:A,1:1,Sheet1!A:A:1:1,[foo]Sheet1!1:1', [
+      { index: 0, depth: 0, type: FX_PREFIX, value: '=' },
+      { index: 1, depth: 0, type: REF_BEAM, value: 'A:A', groupId: 'fxg1' },
+      { index: 2, depth: 0, type: OPERATOR, value: ',' },
+      { index: 3, depth: 0, type: REF_BEAM, value: '1:1', groupId: 'fxg2' },
+      { index: 4, depth: 0, type: OPERATOR, value: ',' },
+      { index: 5, depth: 0, type: REF_BEAM, value: 'Sheet1!A:A', groupId: 'fxg1' },
+      { index: 6, depth: 0, type: OPERATOR, value: ':' },
+      { index: 7, depth: 0, type: REF_BEAM, value: '1:1', groupId: 'fxg2' },
+      { index: 8, depth: 0, type: OPERATOR, value: ',' },
+      { index: 9, depth: 0, type: REF_BEAM, value: '[foo]Sheet1!1:1', groupId: 'fxg2' }
+    ], { sheetName: 'Sheet1', workbookName: 'foo' });
+  });
+
+  test('complex function with nested grouping', () => {
+    isMetaTokens('=SUM((1, 2), {3, 4})', [
+      { index: 0, depth: 0, type: FX_PREFIX, value: '=' },
+      { index: 1, depth: 0, type: FUNCTION, value: 'SUM' },
+      { index: 2, depth: 1, type: OPERATOR, value: '(', groupId: 'fxg3' },
+      { index: 3, depth: 2, type: OPERATOR, value: '(', groupId: 'fxg1' },
+      { index: 4, depth: 2, type: NUMBER, value: '1' },
+      { index: 5, depth: 2, type: OPERATOR, value: ',' },
+      { index: 6, depth: 2, type: WHITESPACE, value: ' ' },
+      { index: 7, depth: 2, type: NUMBER, value: '2' },
+      { index: 8, depth: 2, type: OPERATOR, value: ')', groupId: 'fxg1' },
+      { index: 9, depth: 1, type: OPERATOR, value: ',' },
+      { index: 10, depth: 1, type: WHITESPACE, value: ' ' },
+      { index: 11, depth: 2, type: OPERATOR, value: '{', groupId: 'fxg2' },
+      { index: 12, depth: 2, type: NUMBER, value: '3' },
+      { index: 13, depth: 2, type: OPERATOR, value: ',' },
+      { index: 14, depth: 2, type: WHITESPACE, value: ' ' },
+      { index: 15, depth: 2, type: NUMBER, value: '4' },
+      { index: 16, depth: 2, type: OPERATOR, value: '}', groupId: 'fxg2' },
+      { index: 17, depth: 1, type: OPERATOR, value: ')', groupId: 'fxg3' }
+    ], { sheetName: 'Sheet1', workbookName: 'foo' });
+  });
+
+  test('group structured references', () => {
+    isMetaTokens('=table[#all]+table[foobar]+table[[#All]]', [
+      { index: 0, depth: 0, type: FX_PREFIX, value: '=' },
+      { index: 1, depth: 0, type: REF_STRUCT, value: 'table[#all]', groupId: 'fxg1' },
+      { index: 2, depth: 0, type: OPERATOR, value: '+' },
+      { index: 3, depth: 0, type: REF_STRUCT, value: 'table[foobar]', groupId: 'fxg2' },
+      { index: 4, depth: 0, type: OPERATOR, value: '+' },
+      { index: 5, depth: 0, type: REF_STRUCT, value: 'table[[#All]]', groupId: 'fxg1' }
+    ], { sheetName: 'Sheet1', workbookName: 'foo' });
+  });
+
+  test('group workbook references in xlsx mode', () => {
+    isMetaTokens('=[foo]!A1+[foo]Sheet1!A1+Sheet1!A1+A1', [
+      { index: 0, depth: 0, type: FX_PREFIX, value: '=' },
+      { index: 1, depth: 0, type: REF_RANGE, value: '[foo]!A1', groupId: 'fxg1' },
+      { index: 2, depth: 0, type: OPERATOR, value: '+' },
+      { index: 3, depth: 0, type: REF_RANGE, value: '[foo]Sheet1!A1', groupId: 'fxg1' },
+      { index: 4, depth: 0, type: OPERATOR, value: '+' },
+      { index: 5, depth: 0, type: REF_RANGE, value: 'Sheet1!A1', groupId: 'fxg1' },
+      { index: 6, depth: 0, type: OPERATOR, value: '+' },
+      { index: 7, depth: 0, type: REF_RANGE, value: 'A1', groupId: 'fxg1' }
+    ], { sheetName: 'Sheet1', workbookName: 'foo' }, { xlsx: true });
+  });
+
+  test('group structured references in xlsx mode', () => {
+    isMetaTokens('=[foo]!table[#data]+[foo]Sheet1!table[#data]+Sheet1!table[#data]+table[#data]', [
+      { index: 0, depth: 0, type: FX_PREFIX, value: '=' },
+      { index: 1, depth: 0, type: REF_STRUCT, value: '[foo]!table[#data]', groupId: 'fxg1' },
+      { index: 2, depth: 0, type: OPERATOR, value: '+' },
+      { index: 3, depth: 0, type: REF_STRUCT, value: '[foo]Sheet1!table[#data]', groupId: 'fxg1' },
+      { index: 4, depth: 0, type: OPERATOR, value: '+' },
+      { index: 5, depth: 0, type: REF_STRUCT, value: 'Sheet1!table[#data]', groupId: 'fxg1' },
+      { index: 6, depth: 0, type: OPERATOR, value: '+' },
+      { index: 7, depth: 0, type: REF_STRUCT, value: 'table[#data]', groupId: 'fxg1' }
+    ], { sheetName: 'Sheet1', workbookName: 'foo' }, { xlsx: true });
+  });
+
+  test('trimming should not affect range equivalency', () => {
+    isMetaTokens('=A1:B2*A1.:B2*A1:.B2*A1.:.B2', [
+      { type: FX_PREFIX, value: '=', index: 0, depth: 0 },
+      { type: REF_RANGE, value: 'A1:B2', index: 1, depth: 0, groupId: 'fxg1' },
+      { type: OPERATOR, value: '*', index: 2, depth: 0 },
+      { type: REF_RANGE, value: 'A1.:B2', index: 3, depth: 0, groupId: 'fxg1' },
+      { type: OPERATOR, value: '*', index: 4, depth: 0 },
+      { type: REF_RANGE, value: 'A1:.B2', index: 5, depth: 0, groupId: 'fxg1' },
+      { type: OPERATOR, value: '*', index: 6, depth: 0 },
+      { type: REF_RANGE, value: 'A1.:.B2', index: 7, depth: 0, groupId: 'fxg1' }
+    ], { sheetName: 'Sheet1', workbookName: 'foo' }, { xlsx: true });
+  });
+});

package/lib/{addTokenMeta.js → addTokenMeta.ts}

@@ -1,20 +1,21 @@
-import { REF_RANGE, REF_BEAM, REF_TERNARY, UNKNOWN, REF_STRUCT } from './constants.js';
-import { parseA1Ref } from './a1.js';
-import { parseStructRef } from './parseStructRef.js';
+import { REF_RANGE, REF_BEAM, REF_TERNARY, UNKNOWN, REF_STRUCT } from './constants.ts';
+import { parseA1RefXlsx } from './parseA1Ref.ts';
+import { parseStructRefXlsx } from './parseStructRef.ts';
+import type { ReferenceA1Xlsx, ReferenceStructXlsx, Token, TokenEnhanced } from './types.ts';
 
-function getIDer () {
+function getIDer (): () => string {
   let i = 1;
   return () => 'fxg' + (i++);
 }
 
-function sameValue (a, b) {
+function sameValue (a: unknown, b: unknown): boolean {
   if (a == null && b == null) {
     return true;
   }
   return a === b;
 }
 
-function sameArray (a, b) {
+function sameArray (a: unknown[], b: unknown[]): boolean {
   if ((Array.isArray(a) !== Array.isArray(b)) || a.length !== b.length) {
     return false;
   }
@@ -26,14 +27,14 @@ function sameArray (a, b) {
   return true;
 }
 
-function sameStr (a, b) {
+function sameStr (a: string, b: string): boolean {
   if (!a && !b) {
     return true;
   }
   return String(a).toLowerCase() === String(b).toLowerCase();
 }
 
-function isEquivalent (refA, refB) {
+function isEquivalent (refA, refB): boolean {
   // if named, name must match
   if ((refA.name || refB.name) && refA.name !== refB.name) {
     return false;
@@ -71,7 +72,7 @@ function isEquivalent (refA, refB) {
   return true;
 }
 
-function addContext (ref, sheetName, workbookName) {
+function addContext (ref, sheetName: string, workbookName: string) {
   if (!ref.sheetName) {
     ref.sheetName = sheetName;
   }
@@ -81,6 +82,29 @@ function addContext (ref, sheetName, workbookName) {
   return ref;
 }
 
+type RefWithGroupId = (ReferenceA1Xlsx | ReferenceStructXlsx) & { groupId: string };
+class Reflist {
+  refs: RefWithGroupId[];
+  uid: () => string;
+
+  constructor (uid: () => string) {
+    this.refs = [];
+    this.uid = uid;
+  }
+
+  getGroupId (ref: ReferenceA1Xlsx | ReferenceStructXlsx): string {
+    const known = this.refs.find(d => isEquivalent(d, ref));
+    if (known) {
+      return known.groupId;
+    }
+    else {
+      const r: RefWithGroupId = Object.assign(ref, { groupId: this.uid() });
+      this.refs.push(r);
+      return r.groupId;
+    }
+  }
+}
+
 /**
  * Runs through a list of tokens and adds extra attributes such as matching
  * parens and ranges.
@@ -121,17 +145,17 @@ function addContext (ref, sheetName, workbookName) {
  *
  * All will be tagged with `.error` (boolean `true`).
  *
- * @param {Array<Token>} tokenlist An array of tokens (from `tokenize()`)
- * @param {object} [context={}] A contest used to match `A1` to `Sheet1!A1`.
- * @param {string} [context.sheetName=''] An implied sheet name ('Sheet1')
- * @param {string} [context.workbookName=''] An implied workbook name ('report.xlsx')
- * @returns {Array<TokenEnhanced>} The input array with the enchanced tokens
+ * @param tokenlist An array of tokens (from `tokenize()`)
+ * @param [context={}] A contest used to match `A1` to `Sheet1!A1`.
+ * @param [context.sheetName=''] An implied sheet name ('Sheet1')
+ * @param [context.workbookName=''] An implied workbook name ('report.xlsx')
+ * @returns The input array with the enchanced tokens
  */
-export function addTokenMeta (tokenlist, { sheetName = '', workbookName = '' } = {}) {
+export function addTokenMeta (tokenlist: Token[], { sheetName = '', workbookName = '' } = {}): TokenEnhanced[] {
   const parenStack = [];
   let arrayStart = null;
   const uid = getIDer();
-  const knownRefs = [];
+  const knownRefs = new Reflist(uid);
 
   const getCurrDepth = () => parenStack.length + (arrayStart ? 1 : 0);
 
@@ -178,29 +202,25 @@ export function addTokenMeta (tokenlist, { sheetName = '', workbookName = '' } =
     else if (
       token.type === REF_RANGE ||
       token.type === REF_BEAM ||
-      token.type === REF_TERNARY ||
-      token.type === REF_STRUCT
+      token.type === REF_TERNARY
     ) {
-      const ref = (token.type === REF_STRUCT)
-        ? parseStructRef(token.value, { xlsx: true })
-        : parseA1Ref(token.value, { allowTernary: true, xlsx: true });
-      if (ref && (ref.range || ref.columns)) {
-        ref.source = token.value;
+      const ref = parseA1RefXlsx(token.value, { allowTernary: true });
+      if (ref && 'range' in ref) {
+        addContext(ref, sheetName, workbookName);
+        token.groupId = knownRefs.getGroupId(ref);
+      }
+    }
+    else if (token.type === REF_STRUCT) {
+      const ref = parseStructRefXlsx(token.value);
+      if (ref) {
         addContext(ref, sheetName, workbookName);
-        const known = knownRefs.find(d => isEquivalent(d, ref));
-        if (known) {
-          token.groupId = known.groupId;
-        }
-        else {
-          ref.groupId = uid();
-          token.groupId = ref.groupId;
-          knownRefs.push(ref);
-        }
+        token.groupId = knownRefs.getGroupId(ref);
       }
     }
     else if (token.type === UNKNOWN) {
       token.error = true;
     }
   });
-  return tokenlist;
+
+  return tokenlist as TokenEnhanced[];
 }