@borgar/fx 4.13.0 → 5.0.0

package/lib/lexers/lexRange.ts

@@ -0,0 +1,15 @@
+import type { Token } from '../types.ts';
+import { lexRangeA1 } from './lexRangeA1.ts';
+import { lexRangeR1C1 } from './lexRangeR1C1.ts';
+
+type LexRangeOptions = {
+  allowTernary: boolean,
+  mergeRefs: boolean,
+  r1c1: boolean
+};
+
+export function lexRange (str: string, pos: number, options: LexRangeOptions): Token | undefined {
+  return options.r1c1
+    ? lexRangeR1C1(str, pos, options)
+    : lexRangeA1(str, pos, options);
+}

package/lib/lexers/{lexRangeA1.js → lexRangeA1.ts}

@@ -1,9 +1,9 @@
-/* eslint-disable no-mixed-operators */
-import { REF_RANGE, REF_BEAM, REF_TERNARY, MAX_COLS, MAX_ROWS } from '../constants.js';
-import { advRangeOp } from './advRangeOp.js';
-import { canEndRange, canEndPartialRange } from './canEndRange.js';
+import { REF_RANGE, REF_BEAM, REF_TERNARY, MAX_COLS, MAX_ROWS } from '../constants.ts';
+import type { Token } from '../types.ts';
+import { advRangeOp } from './advRangeOp.ts';
+import { canEndRange, canEndPartialRange } from './canEndRange.ts';
 
-function advA1Col (str, pos) {
+function advA1Col (str: string, pos: number): number {
   // [A-Z]{1,3}
   const start = pos;
   if (str.charCodeAt(pos) === 36) { // $
@@ -29,7 +29,7 @@ function advA1Col (str, pos) {
   return (col && col <= MAX_COLS + 1) ? pos - start : 0;
 }
 
-function advA1Row (str, pos) {
+function advA1Row (str: string, pos: number): number {
   // [1-9][0-9]{0,6}
   const start = pos;
   if (str.charCodeAt(pos) === 36) { // $
@@ -56,7 +56,11 @@ function advA1Row (str, pos) {
   return (row && row <= MAX_ROWS + 1) ? pos - start : 0;
 }
 
-export function lexRangeA1 (str, pos, options) {
+export function lexRangeA1 (
+  str: string,
+  pos: number,
+  options: { mergeRefs: boolean, allowTernary: boolean }
+): Token | undefined {
   let p = pos;
   const left = advA1Col(str, p);
   let right = 0;

package/lib/lexers/{lexRangeR1C1.js → lexRangeR1C1.ts}

@@ -1,7 +1,7 @@
-/* eslint-disable no-mixed-operators */
-import { REF_RANGE, REF_BEAM, REF_TERNARY, MAX_COLS, MAX_ROWS } from '../constants.js';
-import { advRangeOp } from './advRangeOp.js';
-import { canEndRange } from './canEndRange.js';
+import { REF_RANGE, REF_BEAM, REF_TERNARY, MAX_COLS, MAX_ROWS } from '../constants.ts';
+import type { Token } from '../types.ts';
+import { advRangeOp } from './advRangeOp.ts';
+import { canEndRange } from './canEndRange.ts';
 
 const BR_OPEN = 91; // [
 const BR_CLOSE = 93; // ]
@@ -18,7 +18,7 @@ const MINUS = 45;
 // R
 // R\[[+-]?\d+\]
 // R[1-9][0-9]{0,6}
-function lexR1C1Part (str, pos, isRow = false) {
+function lexR1C1Part (str: string, pos: number, isRow: boolean = false): number {
   const start = pos;
   const c0 = str.charCodeAt(pos);
   if ((isRow ? c0 === UC_R || c0 === LC_R : c0 === UC_C || c0 === LC_C)) {
@@ -78,7 +78,11 @@ function lexR1C1Part (str, pos, isRow = false) {
   return 0;
 }
 
-export function lexRangeR1C1 (str, pos, options) {
+export function lexRangeR1C1 (
+  str: string,
+  pos: number,
+  options: { allowTernary: boolean }
+): Token | undefined {
   let p = pos;
   // C1
   // C1:C1

package/lib/lexers/{lexRangeTrim.js → lexRangeTrim.ts}

@@ -1,9 +1,10 @@
-import { OPERATOR_TRIM } from '../constants.js';
+import { OPERATOR_TRIM } from '../constants.ts';
+import type { Token } from '../types.ts';
 
 const PERIOD = 46;
 const COLON = 58;
 
-export function lexRangeTrim (str, pos) {
+export function lexRangeTrim (str: string, pos: number): Token | undefined {
   const c0 = str.charCodeAt(pos);
   if (c0 === PERIOD || c0 === COLON) {
     const c1 = str.charCodeAt(pos + 1);

package/lib/lexers/{lexRefOp.js → lexRefOp.ts}

@@ -1,9 +1,10 @@
-import { OPERATOR } from '../constants.js';
-import { advRangeOp } from './advRangeOp.js';
+import { OPERATOR } from '../constants.ts';
+import type { Token } from '../types.ts';
+import { advRangeOp } from './advRangeOp.ts';
 
 const EXCL = 33; // !
 
-export function lexRefOp (str, pos, opts) {
+export function lexRefOp (str: string, pos: number, opts: { r1c1: boolean }): Token | undefined {
   // in R1C1 mode we only allow [ '!' ]
   if (str.charCodeAt(pos) === EXCL) {
     return { type: OPERATOR, value: str[pos] };

package/lib/lexers/{lexString.js → lexString.ts}

@@ -1,9 +1,9 @@
-/* eslint-disable no-mixed-operators */
-import { STRING } from '../constants.js';
+import { STRING } from '../constants.ts';
+import type { Token } from '../types.ts';
 
 const QUOT = 34;
 
-export function lexString (str, pos) {
+export function lexString (str: string, pos: number): Token | undefined {
   const start = pos;
   if (str.charCodeAt(pos) === QUOT) {
     pos++;

package/lib/lexers/{lexStructured.js → lexStructured.ts}

@@ -1,11 +1,11 @@
-/* eslint-disable no-mixed-operators */
-import { parseSRange } from '../parseSRange.js';
-import { REF_STRUCT } from '../constants.js';
-import { isWS } from './lexWhitespace.js';
+import { parseSRange } from '../parseSRange.ts';
+import { REF_STRUCT } from '../constants.ts';
+import { isWS } from './lexWhitespace.ts';
+import type { Token } from '../types.ts';
 
 const EXCL = 33; // !
 
-export function lexStructured (str, pos) {
+export function lexStructured (str: string, pos: number): Token | undefined {
   const structData = parseSRange(str, pos);
   if (structData && structData.length) {
     // we have a match for a valid SR

package/lib/lexers/{lexWhitespace.js → lexWhitespace.ts}

@@ -1,4 +1,5 @@
-import { WHITESPACE } from '../constants.js';
+import { WHITESPACE } from '../constants.ts';
+import type { Token } from '../types.ts';
 
 export function isWS (c) {
   return (
@@ -19,7 +20,7 @@ export function isWS (c) {
   );
 }
 
-export function lexWhitespace (str, pos) {
+export function lexWhitespace (str: string, pos: number): Token | undefined {
   const start = pos;
   while (isWS(str.charCodeAt(pos))) {
     pos++;

package/lib/lexers/sets.ts

@@ -0,0 +1,51 @@
+import { lexError } from './lexError.ts';
+import { lexRangeTrim } from './lexRangeTrim.ts';
+import { lexOperator } from './lexOperator.ts';
+import { lexBoolean } from './lexBoolean.ts';
+import { lexNewLine } from './lexNewLine.ts';
+import { lexWhitespace } from './lexWhitespace.ts';
+import { lexString } from './lexString.ts';
+import { lexContextQuoted, lexContextUnquoted } from './lexContext.ts';
+import { lexRange } from './lexRange.ts';
+import { lexStructured } from './lexStructured.ts';
+import { lexNumber } from './lexNumber.ts';
+import { lexNamed } from './lexNamed.ts';
+import { lexRefOp } from './lexRefOp.ts';
+import { lexNameFuncCntx } from './lexNameFuncCntx.ts';
+import type { Token } from '../types.ts';
+
+export type PartLexer = (
+  str: string,
+  pos: number,
+  options?: Partial<{
+    xlsx: boolean,
+    allowTerniary: boolean,
+    allowTernary: boolean,
+    mergeRefs: boolean,
+    r1c1: boolean
+  }>
+) => Token | undefined;
+
+export const lexers: PartLexer[] = [
+  lexError,
+  lexRangeTrim,
+  lexOperator,
+  lexNewLine,
+  lexWhitespace,
+  lexString,
+  lexRange,
+  lexNumber,
+  lexBoolean,
+  lexContextQuoted,
+  lexNameFuncCntx,
+  lexStructured
+];
+
+export const lexersRefs = [
+  lexRefOp,
+  lexContextQuoted,
+  lexContextUnquoted,
+  lexRange,
+  lexStructured,
+  lexNamed
+];

package/lib/mergeRefTokens.spec.ts

@@ -0,0 +1,141 @@
+import { describe, test, expect } from 'vitest';
+import { CONTEXT, FUNCTION, FX_PREFIX, OPERATOR, REF_RANGE, REF_BEAM, REF_NAMED, REF_TERNARY, UNKNOWN } from './constants.ts';
+import { mergeRefTokens } from './mergeRefTokens.ts';
+import { tokenize } from './tokenize.ts';
+
+describe('mergeRefTokens', () => {
+  test('merges reference tokens and preserves metadata', () => {
+    const list = tokenize('=SUM([Wb1]Sheet1!A1:B2)', { mergeRefs: false, withLocation: true });
+
+    expect(list).toEqual([
+      { type: FX_PREFIX, value: '=', loc: [ 0, 1 ] },
+      { type: FUNCTION, value: 'SUM', loc: [ 1, 4 ] },
+      { type: OPERATOR, value: '(', loc: [ 4, 5 ] },
+
+      { type: CONTEXT, value: '[Wb1]Sheet1', loc: [ 5, 16 ] },
+      { type: OPERATOR, value: '!', loc: [ 16, 17 ] },
+      { type: REF_RANGE, value: 'A1', loc: [ 17, 19 ] },
+      { type: OPERATOR, value: ':', loc: [ 19, 20 ] },
+      { type: REF_RANGE, value: 'B2', loc: [ 20, 22 ] },
+
+      { type: OPERATOR, value: ')', loc: [ 22, 23 ] }
+    ]);
+
+    // set IDs on all tokens about to be joined
+    list[3].id = 'id1';
+    list[4].id = 'id2';
+    list[5].id = 'id3';
+    list[6].id = 'id4';
+    list[7].id = 'id5';
+
+    const mergedList = mergeRefTokens(list);
+    expect(mergedList).toEqual([
+      { type: FX_PREFIX, value: '=', loc: [ 0, 1 ] },
+      { type: FUNCTION, value: 'SUM', loc: [ 1, 4 ] },
+      { type: OPERATOR, value: '(', loc: [ 4, 5 ] },
+      { type: REF_RANGE,
+        id: 'id5', // token has the id of the first one
+        value: '[Wb1]Sheet1!A1:B2',
+        loc: [ 5, 22 ] },
+      { type: OPERATOR, value: ')', loc: [ 22, 23 ] }
+    ]);
+  });
+
+  describe('tokenize with mergeRefs enabled', () => {
+    const opts = { mergeRefs: true, allowTernary: true };
+
+    test('basic cell references', () => {
+      expect(tokenize('A1', opts)).toEqual([
+        { type: REF_RANGE, value: 'A1' }
+      ]);
+
+      expect(tokenize('A1:A1', opts)).toEqual([
+        { type: REF_RANGE, value: 'A1:A1' }
+      ]);
+    });
+
+    test('beam references', () => {
+      expect(tokenize('A:A', opts)).toEqual([
+        { type: REF_BEAM, value: 'A:A' }
+      ]);
+    });
+
+    test('ternary references', () => {
+      expect(tokenize('A1:A', opts)).toEqual([
+        { type: REF_TERNARY, value: 'A1:A' }
+      ]);
+    });
+
+    test('quoted sheet references', () => {
+      expect(tokenize('\'Sheet1\'!A1', opts)).toEqual([
+        { type: REF_RANGE, value: '\'Sheet1\'!A1' }
+      ]);
+
+      expect(tokenize('\'Sheet1\'!A:A', opts)).toEqual([
+        { type: REF_BEAM, value: '\'Sheet1\'!A:A' }
+      ]);
+
+      expect(tokenize('\'Sheet1\'!A1:A', opts)).toEqual([
+        { type: REF_TERNARY, value: '\'Sheet1\'!A1:A' }
+      ]);
+    });
+
+    test('unquoted sheet references', () => {
+      expect(tokenize('Sheet1!A1', opts)).toEqual([
+        { type: REF_RANGE, value: 'Sheet1!A1' }
+      ]);
+
+      expect(tokenize('Sheet1!A:A', opts)).toEqual([
+        { type: REF_BEAM, value: 'Sheet1!A:A' }
+      ]);
+
+      expect(tokenize('Sheet1!A1:A', opts)).toEqual([
+        { type: REF_TERNARY, value: 'Sheet1!A1:A' }
+      ]);
+    });
+
+    test('workbook references', () => {
+      expect(tokenize('[WB]Sheet1!A1', opts)).toEqual([
+        { type: REF_RANGE, value: '[WB]Sheet1!A1' }
+      ]);
+
+      expect(tokenize('[WB]Sheet1!A:A', opts)).toEqual([
+        { type: REF_BEAM, value: '[WB]Sheet1!A:A' }
+      ]);
+
+      expect(tokenize('[WB]Sheet1!A1:A', opts)).toEqual([
+        { type: REF_TERNARY, value: '[WB]Sheet1!A1:A' }
+      ]);
+
+      expect(tokenize('[WB]Sheet1!A1.:.C3', opts)).toEqual([
+        { type: REF_RANGE, value: '[WB]Sheet1!A1.:.C3' }
+      ]);
+    });
+
+    test('named references', () => {
+      expect(tokenize('foo', opts)).toEqual([
+        { type: REF_NAMED, value: 'foo' }
+      ]);
+
+      expect(tokenize('\'quoted\'!foo', opts)).toEqual([
+        { type: REF_NAMED, value: '\'quoted\'!foo' }
+      ]);
+
+      expect(tokenize('Sheet1!foo', opts)).toEqual([
+        { type: REF_NAMED, value: 'Sheet1!foo' }
+      ]);
+    });
+
+    test('path references with different formats', () => {
+      expect(tokenize('[path]!foo', opts)).toEqual([
+        { type: UNKNOWN, value: '[path]' },
+        { type: OPERATOR, value: '!' },
+        { type: REF_NAMED, value: 'foo' }
+      ]);
+
+      expect(tokenize('[path]prefix!foo', opts)).toEqual([
+        { type: REF_NAMED, value: '[path]prefix!foo' }
+      ]);
+    });
+  });
+});

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

@@ -1,4 +1,5 @@
-import { CONTEXT, CONTEXT_QUOTE, REF_RANGE, REF_NAMED, REF_BEAM, REF_TERNARY, OPERATOR, REF_STRUCT } from './constants.js';
+import { CONTEXT, CONTEXT_QUOTE, REF_RANGE, REF_NAMED, REF_BEAM, REF_TERNARY, OPERATOR, REF_STRUCT } from './constants.ts';
+import type { Token } from './types.ts';
 
 const END = '$';
 
@@ -33,13 +34,17 @@ const validRunsMerge = [
   [ CONTEXT_QUOTE, '!', REF_NAMED, REF_STRUCT ]
 ];
 
+type TypeNode = {
+  [key: string]: TypeNode | boolean;
+};
+
 // valid token runs are converted to a tree structure
-const refPartsTree = {};
-function packList (f, node) {
+const refPartsTree: TypeNode = {};
+function packList (f: string[], node: TypeNode) {
   if (f.length) {
     const key = f[0];
-    node[key] = node[key] || {};
-    packList(f.slice(1), node[key]);
+    if (!node[key]) { node[key] = {}; }
+    packList(f.slice(1), node[key] as TypeNode);
   }
   else {
     node[END] = true;
@@ -49,7 +54,7 @@ validRunsMerge.forEach(run => packList(run.concat().reverse(), refPartsTree));
 
 // attempt to match a backwards run of tokens from a given point
 // to a path in the tree
-const matcher = (tokens, currNode, anchorIndex, index = 0) => {
+const matcher = (tokens: Token[], currNode, anchorIndex, index = 0) => {
   let i = index;
   let node = currNode;
   const max = tokens.length - index;
@@ -76,10 +81,10 @@ const matcher = (tokens, currNode, anchorIndex, index = 0) => {
  * as whole references (`Sheet1!A1:B2`) rather than separate tokens for each
  * part: (`Sheet1`,`!`,`A1`,`:`,`B2`).
  *
- * @param {Array<Token>} tokenlist An array of tokens (from `tokenize()`)
- * @returns {Array<Token>} A new list of tokens with range parts merged.
+ * @param tokenlist An array of tokens.
+ * @returns A new list of tokens with range parts merged.
  */
-export function mergeRefTokens (tokenlist) {
+export function mergeRefTokens (tokenlist: Token[]): Token[] {
   const finalTokens = [];
   // this seeks backwards because it's really the range part
   // that controls what can be joined.

package/lib/nodeTypes.ts

@@ -0,0 +1,54 @@
+import {
+  // AST types
+  UNARY,
+  BINARY,
+  REFERENCE,
+  LITERAL,
+  ERROR_LITERAL,
+  CALL,
+  ARRAY,
+  IDENTIFIER,
+  LAMBDA,
+  LET,
+  LET_DECL
+} from './constants.ts';
+
+/**
+ * A dictionary of the types used to identify AST node variants.
+ *
+ * @prop UNARY - A unary operation (`10%`)
+ * @prop BINARY - A binary operation (`10+10`)
+ * @prop REFERENCE - A range identifier (`A1`)
+ * @prop LITERAL - A literal (number, string, or boolean) (`123`, `"foo"`, `false`)
+ * @prop ERROR - An error literal (`#VALUE!`)
+ * @prop CALL - A function call expression (`SUM(1,2)`)
+ * @prop ARRAY - An array expression (`{1,2;3,4}`)
+ * @prop IDENTIFIER - A function name identifier (`SUM`)
+ * @prop LAMBDA - A LAMBDA expression (`LAMBDA(x,y,x*y)``)
+ * @prop LET - A LET expression (`LET(a,A1*10,b,SUM(F:F),a*b)`)
+ * @prop LET_DECL - A LET declaration (LET(`a,A1*10`...)
+ */
+export const nodeTypes = Object.freeze({
+  /** A unary operation (`10%`) */
+  UNARY,
+  /** A binary operation (`10+10`) */
+  BINARY,
+  /** A range identifier (`A1`) */
+  REFERENCE,
+  /** A literal (number, string, or boolean) (`123`, `"foo"`, `false`) */
+  LITERAL,
+  /** An error literal (`#VALUE!`) */
+  ERROR: ERROR_LITERAL,
+  /** A function call expression (`SUM(1,2)`) */
+  CALL,
+  /** An array expression (`{1,2;3,4}`) */
+  ARRAY,
+  /** A function name identifier (`SUM`) */
+  IDENTIFIER,
+  /** A LAMBDA expression (`LAMBDA(x,y,x*y)``) */
+  LAMBDA,
+  /** A LET expression (`LET(a,A1*10,b,SUM(F:F),a*b)`) */
+  LET,
+  /** A LET declaration (LET(`a,A1*10`...)*/
+  LET_DECL
+});