@borgar/fx 3.0.0 → 4.0.0-rc.1

package/docs/AST format.md

@@ -0,0 +1,144 @@
+# Abstract Syntax Tree Format
+
+This document specifies the core AST node types that support the Excel grammar. The format is based on the [ESTree AST](https://github.com/estree/estree) (and so is this document).
+
+## Node objects
+
+All AST nodes are represented by `Node` objects. They may have any prototype inheritance but implement the following basic interface:
+
+```
+interface Node {
+  type: string;
+  loc?: Location | null;
+}
+```
+
+The `type` field is a string representing the AST variant type. Each subtype of Node is documented below with the specific string of its `type` field. You can use this field to determine which interface a node implements.
+
+The `loc` field represents the source location information of the node. If the node contains no information about the source location, the field is `null`; otherwise it is an array consisting of a two numbers: A start offset (the position of the first character of the parsed source region) and an end offset (the position of the first character after the parsed source region):
+
+```
+interface Location extends Array<number> {
+  0: number;
+  1: number;
+}
+```
+
+## Identifier
+
+```
+interface Identifier extends Node {
+  type: "Identifier";
+  name: string;
+}
+```
+
+An identifier. These only appear on `CallExpression` and will always be a static string representing the name of a function call.
+
+## ReferenceIdentifier
+
+```
+interface ReferenceIdentifier extends Node {
+  type: "ReferenceIdentifier";
+  value: string;
+}
+```
+
+A range identifier.
+
+
+## Literal
+
+```
+interface Literal extends Node {
+  type: "Literal";
+  raw: string;
+  value: string | number | boolean;
+}
+```
+
+A literal token. Captures numbers, strings, and booleans. Literal errors have their own variant type.
+
+## ErrorLiteral
+
+```
+interface ErrorLiteral extends Node {
+  type: "ErrorLiteral";
+  raw: string;
+  value: string;
+}
+```
+
+An Error expression.
+
+## UnaryExpression
+
+```
+interface UnaryExpression extends Node {
+  type: "UnaryExpression";
+  operator: UnaryOperator;
+  arguments: Array<[ Node ]>;
+}
+```
+
+A unary operator expression.
+
+### UnaryOperator 
+
+```
+type UnaryOperator = (
+  "+" | "-" | "%" | "#" | "@"
+)
+```
+
+A unary operator token.
+
+## BinaryExpression
+
+```
+interface BinaryExpression extends Node {
+  type: "BinaryExpression";
+  operator: BinaryOperator; 
+  arguments: Array<[ Node, Node ]>;
+}
+```
+
+A binary operator expression.
+
+### BinaryOperator 
+
+```
+type BinaryOperator = (
+  "=" | "<" | ">" | "<=" | ">=" |  "<>" |
+  "-" | "+" | "*" | "/" | "^" |
+  ":" | " " | "," |
+  "&"
+)
+```
+
+A binary operator token. Note that Excels union operator is whitespace so a parser must normalize this to a single space.
+
+## CallExpression
+
+```
+interface CallExpression extends Node {
+  type: "CallExpression";
+  callee: Identifier;
+  arguments: Array<Node>;
+}
+```
+
+A function call expression.
+
+## ArrayExpression
+
+```
+interface ArrayExpression extends Node {
+  type: "ArrayExpression";
+  elements: Array<Array<Literal | Error | ReferenceIdentifier>>;
+}
+```
+
+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.
+
+

package/docs/References.md

@@ -0,0 +1,60 @@
+# References and Ranges
+
+In Excels spreadsheet formula language terminology, a reference is similar to what is in most programming is called a variable. Spreadsheets do not have variables though, they have cells. The cells can be referenced in formulas, either directly (such as `=SUM(A1)`), or through aliases (such as `=SUM(someName)`).
+
+A range is when a cell, or a set of cells, is referenced directly. Ranges in formulas can come in one of two syntax styles: The commonly known A1 style, as well as R1C1 style where both axes are numerical. Only one style can be used at a time in a formula.
+
+## Ranges
+
+This tokenizer considers there to be three "types" of ranges:
+
+### Ranges (`REF_RANGE`)
+
+The basic type of range will be referencing either:
+
+* A single cell, like `A1` or `AF31`.
+* A bounded rectangle of cells, like `A1:B2` or `AF17:AF31`.
+
+### Range ternary (`REF_TERNARY`)
+
+Ternary ranges are rectangles of cells defined by only three of the four possible sides. They are are unbounded in either bottom or right dimension:
+
+* A rectangle of cells that is unbounded to the bottom, like `A1:A` or `C3:D`.
+* A rectangle of cells that is unbounded to the right, like `A1:1` or `F2:5`.
+
+This type of range is not supported in Excel, so it is an opt-in for the tokenizer (see [README.md](./README.md)).
+
+### Range beams (`REF_BEAM`)
+
+Range beams are rectangles of cells that are unbounded in either left and right, or top and bottom dimensions.
+
+* A rectangle of cells that is unbounded to the top and bottom, like `A:A` or `C:D`.
+* A rectangle of cells that is unbounded to the left and right, like `1:1` or `2:5`.
+
+
+## References
+
+As well as ranges, a reference can be either of:
+
+### Named Ranges or Names  (`REF_NAMED`)
+
+[Named Ranges][named], or Names as Excel prefers to call them most of the time, are usually a references to a range or table but may also be references to entire expressions.
+
+### Structured references (`REF_STRUCT`)
+
+[Structured references][srefs] are references into an area or slice of a table. They can include the table name (which is essentially a Name), as well as either or both of a section directive and/or column name or a range of columns.
+
+* A structured reference to a column: `Table1[Column1]`
+* A structured reference to the tables totals: `Table1[#Totals]`
+* A structured reference to a range of columns: `[[Column1]:[Column3]]`
+* A structured reference to a specific column of a tables totals: `Table1[[#Totals],[Column2]]`
+
+---
+
+Spreadsheet applications will normalize all ranges when you enter a formula, flipping the left/right and top/bottom coordinates as needed to keep the range top to bottom and left to right. Structured references will also be normalized as appropriate.
+
+The library has tools to both normalize the ranges, as well as filling in the missing boundaries (see [README.md](./README.md)).
+
+
+[named]: https://support.microsoft.com/en-us/office/define-and-use-names-in-formulas-4d0f13ac-53b7-422e-afd2-abd7ff379c64
+[srefs]: https://support.microsoft.com/en-us/office/using-structured-references-with-excel-tables-f5ed2452-2337-4f71-bed3-c8ae6d2b276e

package/lib/a1.js

@@ -2,8 +2,23 @@ import { MAX_ROWS, MAX_COLS } from './constants.js';
 import { parseRef } from './parseRef.js';
 import { stringifyPrefix } from './stringifyPrefix.js';
 
-export function fromCol (columnId) {
-  const x = (columnId || '');
+const clamp = (min, val, max) => Math.min(Math.max(val, min), max);
+const toColStr = (c, a) => (a ? '$' : '') + toCol(c);
+const toRowStr = (r, a) => (a ? '$' : '') + toRow(r);
+
+/**
+ * Convert a column string representation to a 0 based
+ * offset number (`"C"` = `2`).
+ *
+ * The method expects a valid column identifier made up of _only_
+ * A-Z letters, which may be either upper or lower case. Other input will
+ * return garbage.
+ *
+ * @param {string} columnString  The column string identifier
+ * @return {number}  Zero based column index number
+ */
+export function fromCol (columnString) {
+  const x = (columnString || '');
   const l = x.length;
   let n = 0;
   if (l > 2) {
@@ -24,11 +39,21 @@ export function fromCol (columnId) {
   return n;
 }
 
-export function toCol (left) {
+/**
+ * Convert a 0 based offset number to a column string
+ * representation (`2` = `"C"`).
+ *
+ * The method expects a number between 0 and 16383. Other input will
+ * return garbage.
+ *
+ * @param {number} columnIndex Zero based column index number
+ * @return {string} The column string identifier
+ */
+export function toCol (columnIndex) {
   return (
-    (left >= 702 ? String.fromCharCode((((left - 702) / 676) - 0) % 26 + 65) : '') +
-    (left >= 26 ? String.fromCharCode(Math.floor(((left / 26) - 1) % 26 + 65)) : '') +
-    String.fromCharCode((left % 26 + 65))
+    (columnIndex >= 702 ? String.fromCharCode((((columnIndex - 702) / 676) - 0) % 26 + 65) : '') +
+    (columnIndex >= 26 ? String.fromCharCode(Math.floor(((columnIndex / 26) - 1) % 26 + 65)) : '') +
+    String.fromCharCode((columnIndex % 26 + 65))
   );
 }
 
@@ -50,15 +75,32 @@ export function toAbsolute (range) {
   return { top, left, bottom, right, $left: true, $right: true, $top: true, $bottom: true };
 }
 
-// TODO: add a setting for partials?
-const toColStr = (c, a) => (a ? '$' : '') + toCol(c);
-const toRowStr = (r, a) => (a ? '$' : '') + toRow(r);
+/**
+ * Stringify a range object into A1 syntax.
+ *
+ * @private
+ * @see parseA1Ref
+ * @param {Object} range  A range object
+ * @return {string}  An A1-style string represenation of a range
+ */
 export function toA1 (range) {
-  const { top, left, bottom, right, $left, $right, $top, $bottom } = range;
+  let { top, left, bottom, right } = range;
+  const { $left, $right, $top, $bottom } = range;
   const noLeft = left == null;
   const noRight = right == null;
   const noTop = top == null;
   const noBottom = bottom == null;
+  // allow skipping right and bottom to define a cell
+  top = clamp(0, top | 0, MAX_ROWS);
+  left = clamp(0, left | 0, MAX_COLS);
+  if (!noLeft && !noTop && noRight && noBottom) {
+    bottom = top;
+    right = left;
+  }
+  else {
+    bottom = clamp(0, bottom | 0, MAX_ROWS);
+    right = clamp(0, right | 0, MAX_COLS);
+  }
   // A:A
   if ((top === 0 && bottom >= MAX_ROWS) || (noTop && noBottom)) {
     return toColStr(left, $left) + ':' + toColStr(right, $right);
@@ -84,8 +126,9 @@ export function toA1 (range) {
     return toColStr(right, $right) + toRowStr(top, $top) + ':' + toRowStr(bottom, $bottom);
   }
   // A1:A1
-  else if (right !== left || bottom !== top || $right !== $left || $bottom !== $top) {
-    return toColStr(left, $left) + toRowStr(top, $top) + ':' + toColStr(right, $right) + toRowStr(bottom, $bottom);
+  if (right !== left || bottom !== top || $right !== $left || $bottom !== $top) {
+    return toColStr(left, $left) + toRowStr(top, $top) + ':' +
+           toColStr(right, $right) + toRowStr(bottom, $bottom);
   }
   // A1
   return toColStr(left, $left) + toRowStr(top, $top);
@@ -104,6 +147,15 @@ function splitA1 (str) {
   ];
 }
 
+/**
+ * Parse a simple string reference to an A1 range into a range object.
+ * Will accept `A1`, `A2`, `A:A`, or `1:1`.
+ *
+ * @private
+ * @see parseA1Ref
+ * @param {string} rangeString  A range string
+ * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
+ */
 export function fromA1 (rangeStr) {
   let top = null;
   let left = null;
@@ -165,8 +217,37 @@ export function fromA1 (rangeStr) {
   return { top, left, bottom, right, $top, $left, $bottom, $right };
 }
 
-export function parseA1Ref (ref, { allowNamed = true, allowTernary = false } = {}) {
-  const d = parseRef(ref, { allowNamed, allowTernary, r1c1: false });
+/**
+ * Parse a string reference into an object representing it.
+ *
+ * ```js
+ * parseA1Ref('Sheet1!A$1:$B2');
+ * // => {
+ * //   context: [ 'Sheet1' ],
+ * //   range: {
+ * //     top: 0,
+ * //     left: 0,
+ * //     bottom: 1,
+ * //     right: 1
+ * //     $top: true,
+ * //     $left: false,
+ * //     $bottom: false,
+ * //     $right: true
+ * //   }
+ * // }
+ * ```
+ *
+ * For A:A or A1:A style ranges, `null` will be used for any dimensions that the
+ * syntax does not specify:
+ *
+ * @param {string} refString  An A1-style reference string
+ * @param {Object} [options={}]  Options
+ * @param {boolean} [options.allowNamed=true]  Enable parsing names as well as ranges.
+ * @param {boolean} [options.allowTernary=false]  Enables the recognition of ternary ranges in the style of `A1:A` or `A1:1`. These are supported by Google Sheets but not Excel. See: References.md.
+ * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
+ */
+export function parseA1Ref (refString, { allowNamed = true, allowTernary = false } = {}) {
+  const d = parseRef(refString, { allowNamed, allowTernary, r1c1: false });
   if (d && (d.r0 || d.name)) {
     let range = null;
     if (d.r0) {
@@ -185,13 +266,70 @@ export function parseA1Ref (ref, { allowNamed = true, allowTernary = false } = {
   return null;
 }
 
-export function stringifyA1Ref (ref) {
-  return stringifyPrefix(ref) + (
-    ref.name ? ref.name : toA1(ref.range)
+/**
+ * Get an A1-style string representation of a reference object.
+ *
+ * ```js
+ * stringifyA1Ref({
+ *   context: [ 'Sheet1' ],
+ *   range: {
+ *     top: 0,
+ *     left: 0,
+ *     bottom: 1,
+ *     right: 1,
+ *     $top: true,
+ *     $left: false,
+ *     $bottom: false,
+ *     $right: true
+ *   }
+ * });
+ * // => 'Sheet1!A$1:$B2'
+ * ```
+ *
+ * @param {Object} refObject A reference object
+ * @return {Object} The reference in A1-style string format
+ */
+export function stringifyA1Ref (refObject) {
+  return stringifyPrefix(refObject) + (
+    refObject.name ? refObject.name : toA1(refObject.range)
   );
 }
 
-export function addRangeBounds (range) {
+/**
+ * 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({
+ *   context: [ 'Sheet1' ],
+ *   range: {
+ *     top: 0,
+ *     left: 0,
+ *     bottom: 1,
+ *     $top: true,
+ *     $left: false,
+ *     $bottom: false,
+ *   }
+ * });
+ * // => {
+ * //   context: [ 'Sheet1' ],
+ * //   range: {
+ * //     top: 0,
+ * //     left: 0,
+ * //     bottom: 1,
+ * //     right: 16383,
+ * //     $top: true,
+ * //     $left: false,
+ * //     $bottom: false,
+ * //     $right: false
+ * //   }
+ * // }
+ * ```
+ *
+ * @param {Object} range The range part of a reference object.
+ * @return {Object} same range with missing bounds filled in.
+ */
+export function addA1RangeBounds (range) {
   if (range.top == null) {
     range.top = 0;
     range.$top = false;
@@ -210,15 +348,3 @@ export function addRangeBounds (range) {
   }
   return range;
 }
-
-export default {
-  fromCol,
-  toCol,
-  toRelative,
-  toAbsolute,
-  to: toA1,
-  from: fromA1,
-  parse: parseA1Ref,
-  addBounds: addRangeBounds,
-  stringify: stringifyA1Ref
-};

package/lib/a1.spec.js

@@ -13,7 +13,7 @@ import {
 } from './a1.js';
 import { MAX_COLS, MAX_ROWS } from './constants.js';
 
-Test.prototype.isA1Equal = function isTokens (expr, expect, opts) {
+Test.prototype.isA1Equal = function isA1Equal (expr, expect, opts) {
   if (expect) {
     expect = {
       context: [],
@@ -224,7 +224,14 @@ test('A1 serialization', t => {
   t.is(toA1({ top: 0, right: 3, bottom: 0 }), 'D1:1', '1:D1 → D1:1');
   t.is(toA1({ top: 0, left: 3, bottom: 0, $top: true }), 'D$1:1', 'D$1:1');
   t.is(toA1({ top: 0, left: 3, bottom: 0, $left: true }), '$D1:1', '$D1:1');
-  t.is(toA1({ top: 0, left: 3, bottom: 0, $bottom: true }), 'D1:$1', 'D1:$1');
+  t.is(toA1({ top: 0, left: 3, bottom: 0, $left: true }), '$D1:1', '$D1:1');
+  // allow skipping right/bottom for cells
+  t.is(toA1({ top: 0, left: 0 }), 'A1', 'A1');
+  // clamp the range at min/max dimensions
+  t.is(toA1({ top: -10, bottom: -5, left: -10, right: -5 }), 'A1', 'A1');
+  t.is(toA1({ top: 15e5, bottom: 15e5, left: 20000, right: 20000 }), 'XFD1048576', 'XFD1048576');
+  t.is(toA1({ top: 2, bottom: 2, left: 2.5, right: 2.5 }), 'C3', 'C3');
+  t.is(toA1({ top: 1.5, bottom: 2.5, left: 4.5, right: 8.5 }), 'E2:I3', 'E2:I3');
   t.end();
 });
 

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

@@ -1,4 +1,4 @@
-import { RANGE, RANGE_BEAM, RANGE_TERNARY, UNKNOWN } from './constants.js';
+import { REF_RANGE, REF_BEAM, REF_TERNARY, UNKNOWN } from './constants.js';
 import { parseA1Ref } from './a1.js';
 
 function getIDer () {
@@ -46,8 +46,53 @@ function isEquivalent (refA, refB) {
   return true;
 }
 
-// when context is Sheet1, we should consider Sheet!A1 == A1
-export function addMeta (tokens, { sheetName = '', workbookName = '' } = {}) {
+/**
+ * Runs through a list of tokens and adds extra attributes such as matching
+ * parens and ranges.
+ *
+ * The `context` parameter defines default reference attributes:
+ * `{ workbookName: 'report.xlsx', sheetName: 'Sheet1' }`.
+ * If supplied, these are used to match `A1` to `Sheet1!A1`.
+ *
+ * All tokens will be tagged with a `.depth` number value to indicating the
+ * level of nesting in parentheses as well as an `.index` number indicating
+ * their zero based position in the list.
+ *
+ * The returned output will be the same array of tokens but the following
+ * properties will added to tokens (as applicable):
+ *
+ * #### Parentheses ( )
+ *
+ * Matching parens will be tagged with `.groupId` string identifier as well as
+ * a `.depth` number value (indicating the level of nesting).
+ *
+ * Closing parens without a counterpart will be tagged with `.error`
+ * (boolean true).
+ *
+ * #### Curly brackets { }
+ *
+ * Matching curly brackets will be tagged with `.groupId` string identifier.
+ * These may not be nested in Excel.
+ *
+ * Closing curly brackets without a counterpart will be tagged with `.error`
+ * (boolean `true`).
+ *
+ * #### Ranges (`REF_RANGE` or `REF_BEAM` type tokens)
+ *
+ * All ranges will be tagged with `.groupId` string identifier regardless of
+ * the number of times they occur.
+ *
+ * #### Tokens of type `UNKNOWN`
+ *
+ * All will be tagged with `.error` (boolean `true`).
+ *
+ * @param {Array<Object>} 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')
+ * @return {Array<Object>} The input array with the enchanced tokens
+ */
+export function addTokenMeta (tokens, { sheetName = '', workbookName = '' } = {}) {
   const parenStack = [];
   let arrayStart = null;
   const uid = getIDer();
@@ -95,8 +140,8 @@ export function addMeta (tokens, { sheetName = '', workbookName = '' } = {}) {
       }
       arrayStart = null;
     }
-    else if (token.type === RANGE || token.type === RANGE_BEAM || token.type === RANGE_TERNARY) {
-      const ref = parseA1Ref(token.value, { allowNamed: false, allowTernary: true });
+    else if (token.type === REF_RANGE || token.type === REF_BEAM || token.type === REF_TERNARY) {
+      const ref = parseA1Ref(token.value, { allowTernary: true });
       if (ref && ref.range) {
         ref.source = token.value;
         if (!ref.context.length) {

package/lib/{addMeta.spec.js → addTokenMeta.spec.js}

@@ -1,10 +1,10 @@
 import { test, Test } from 'tape';
-import { FX_PREFIX, OPERATOR, NUMBER, RANGE, RANGE_BEAM, FUNCTION, WHITESPACE } from './constants.js';
-import { addMeta } from './addMeta.js';
+import { FX_PREFIX, OPERATOR, NUMBER, REF_RANGE, REF_BEAM, FUNCTION, WHITESPACE } from './constants.js';
+import { addTokenMeta } from './addTokenMeta.js';
 import { tokenize } from './lexer.js';
 
 Test.prototype.isMetaTokens = function isTokens (expr, expect, opts) {
-  const actual = addMeta(tokenize(expr), opts);
+  const actual = addTokenMeta(tokenize(expr), opts);
   if (actual.length === expect.length) {
     actual.forEach((d, i) => {
       const keys = Object.keys(d).concat(Object.keys(expect[i]));
@@ -55,34 +55,34 @@ test('add extra meta to operators', t => {
   // group ranges if they are equivalent
   t.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: RANGE, value: 'B11', groupId: 'fxg1' },
+    { index: 1, depth: 0, type: REF_RANGE, value: 'B11', groupId: 'fxg1' },
     { index: 2, depth: 0, type: OPERATOR, value: ',' },
-    { index: 3, depth: 0, type: RANGE, value: 'B11:B12', groupId: 'fxg2' },
+    { index: 3, depth: 0, type: REF_RANGE, value: 'B11:B12', groupId: 'fxg2' },
     { index: 4, depth: 0, type: OPERATOR, value: ',' },
-    { index: 5, depth: 0, type: RANGE, value: "'Sheet11'!B11", groupId: 'fxg3' },
+    { index: 5, depth: 0, type: REF_RANGE, value: "'Sheet11'!B11", groupId: 'fxg3' },
     { index: 6, depth: 0, type: OPERATOR, value: ',' },
-    { index: 7, depth: 0, type: RANGE, value: 'SHEET1!$B11', groupId: 'fxg1' },
+    { index: 7, depth: 0, type: REF_RANGE, value: 'SHEET1!$B11', groupId: 'fxg1' },
     { index: 8, depth: 0, type: OPERATOR, value: ',' },
-    { index: 9, depth: 0, type: RANGE, value: 'sheet1!$b$11', groupId: 'fxg1' },
+    { 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: RANGE, value: 'A1:B11', groupId: 'fxg4' },
+    { index: 11, depth: 0, type: REF_RANGE, value: 'A1:B11', groupId: 'fxg4' },
     { index: 12, depth: 0, type: OPERATOR, value: ',' },
-    { index: 13, depth: 0, type: RANGE, value: '[foo]Sheet1!B11', groupId: 'fxg1' },
+    { 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: RANGE, value: "'[foo]Sheet1'!B11", groupId: 'fxg1' }
+    { index: 15, depth: 0, type: REF_RANGE, value: "'[foo]Sheet1'!B11", groupId: 'fxg1' }
   ], { sheetName: 'Sheet1', workbookName: 'foo' });
 
   t.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: RANGE_BEAM, value: 'A:A', groupId: 'fxg1' },
+    { index: 1, depth: 0, type: REF_BEAM, value: 'A:A', groupId: 'fxg1' },
     { index: 2, depth: 0, type: OPERATOR, value: ',' },
-    { index: 3, depth: 0, type: RANGE_BEAM, value: '1:1', groupId: 'fxg2' },
+    { index: 3, depth: 0, type: REF_BEAM, value: '1:1', groupId: 'fxg2' },
     { index: 4, depth: 0, type: OPERATOR, value: ',' },
-    { index: 5, depth: 0, type: RANGE_BEAM, value: 'Sheet1!A:A', groupId: 'fxg1' },
+    { 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: RANGE_BEAM, value: '1:1', groupId: 'fxg2' },
+    { index: 7, depth: 0, type: REF_BEAM, value: '1:1', groupId: 'fxg2' },
     { index: 8, depth: 0, type: OPERATOR, value: ',' },
-    { index: 9, depth: 0, type: RANGE_BEAM, value: '[foo]Sheet1!1:1', groupId: 'fxg2' }
+    { index: 9, depth: 0, type: REF_BEAM, value: '[foo]Sheet1!1:1', groupId: 'fxg2' }
   ], { sheetName: 'Sheet1', workbookName: 'foo' });
 
   t.isMetaTokens('=SUM((1, 2), {3, 4})', [

package/lib/constants.js

@@ -8,12 +8,22 @@ export const WHITESPACE = 'whitespace';
 export const STRING = 'string';
 export const CONTEXT_QUOTE = 'context_quote';
 export const CONTEXT = 'context';
-export const RANGE = 'range';
-export const RANGE_BEAM = 'range_beam';
-export const RANGE_TERNARY = 'range_ternary';
-export const RANGE_NAMED = 'range_named';
+export const REF_RANGE = 'range';
+export const REF_BEAM = 'range_beam';
+export const REF_TERNARY = 'range_ternary';
+export const REF_NAMED = 'range_named';
+export const REF_STRUCT = 'structured';
 export const FX_PREFIX = 'fx_prefix';
 export const UNKNOWN = 'unknown';
 
+export const UNARY = 'UnaryExpression';
+export const BINARY = 'BinaryExpression';
+export const REFERENCE = 'ReferenceIdentifier';
+export const LITERAL = 'Literal';
+export const ERROR_LITERAL = 'ErrorLiteral';
+export const CALL = 'CallExpression';
+export const ARRAY = 'ArrayExpression';
+export const IDENTIFIER = 'Identifier';
+
 export const MAX_COLS = 2 ** 14 - 1; // 16383
 export const MAX_ROWS = 2 ** 20 - 1; // 1048575