@borgar/fx 4.5.0 → 4.7.0

package/lib/a1.js

@@ -16,7 +16,7 @@ const charFrom = String.fromCharCode;
  * return garbage.
  *
  * @param {string} columnString  The column string identifier
- * @return {number}  Zero based column index number
+ * @returns {number}  Zero based column index number
  */
 export function fromCol (columnString) {
   const x = (columnString || '');
@@ -48,7 +48,7 @@ export function fromCol (columnString) {
  * return garbage.
  *
  * @param {number} columnIndex Zero based column index number
- * @return {string} The column string identifier
+ * @returns {string} The column string identifier
  */
 export function toCol (columnIndex) {
   return (
@@ -85,8 +85,8 @@ export function toAbsolute (range) {
  *
  * @private
  * @see parseA1Ref
- * @param {Object} range  A range object
- * @return {string}  An A1-style string represenation of a range
+ * @param {RangeA1} range  A range object
+ * @returns {string}  An A1-style string represenation of a range
  */
 export function toA1 (range) {
   let { top, left, bottom, right } = range;
@@ -163,9 +163,9 @@ function splitA1 (str) {
  * @private
  * @see parseA1Ref
  * @param {string} rangeString  A range string
- * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
+ * @returns {(RangeA1|null)} An object representing a valid range or null if it is invalid.
  */
-export function fromA1 (rangeStr) {
+export function fromA1 (rangeString) {
   let top = null;
   let left = null;
   let bottom = null;
@@ -174,7 +174,7 @@ export function fromA1 (rangeStr) {
   let $left = false;
   let $bottom = false;
   let $right = false;
-  const [ part1, part2, part3 ] = rangeStr.split(':');
+  const [ part1, part2, part3 ] = rangeString.split(':');
   if (part3) {
     return null;
   }
@@ -250,11 +250,11 @@ export function fromA1 (rangeStr) {
  * syntax does not specify:
  *
  * @param {string} refString  An A1-style reference string
- * @param {Object} [options={}]  Options
+ * @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.
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
- * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
+ * @returns {(ReferenceA1|null)} An object representing a valid reference or null if it is invalid.
  */
 export function parseA1Ref (refString, { allowNamed = true, allowTernary = false, xlsx = false } = {}) {
   const d = parseRef(refString, { allowNamed, allowTernary, xlsx, r1c1: false });
@@ -296,10 +296,10 @@ export function parseA1Ref (refString, { allowNamed = true, allowTernary = false
  * // => 'Sheet1!A$1:$B2'
  * ```
  *
- * @param {Object} refObject A reference object
- * @param {Object} [options={}]  Options
+ * @param {ReferenceA1} refObject A reference object
+ * @param {object} [options={}]  Options
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
- * @return {Object} The reference in A1-style string format
+ * @returns {string} The reference in A1-style string format
  */
 export function stringifyA1Ref (refObject, { xlsx = false } = {}) {
   const prefix = xlsx
@@ -341,8 +341,8 @@ export function stringifyA1Ref (refObject, { xlsx = false } = {}) {
  * // }
  * ```
  *
- * @param {Object} range The range part of a reference object.
- * @return {Object} same range with missing bounds filled in.
+ * @param {RangeA1} range The range part of a reference object.
+ * @returns {RangeA1} same range with missing bounds filled in.
  */
 export function addA1RangeBounds (range) {
   if (range.top == null) {

package/lib/addTokenMeta.js

@@ -121,13 +121,13 @@ function addContext (ref, sheetName, workbookName) {
  *
  * 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 {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')
- * @return {Array<Object>} The input array with the enchanced tokens
+ * @returns {Array<TokenEnhanced>} The input array with the enchanced tokens
  */
-export function addTokenMeta (tokens, { sheetName = '', workbookName = '' } = {}) {
+export function addTokenMeta (tokenlist, { sheetName = '', workbookName = '' } = {}) {
   const parenStack = [];
   let arrayStart = null;
   const uid = getIDer();
@@ -135,7 +135,7 @@ export function addTokenMeta (tokens, { sheetName = '', workbookName = '' } = {}
 
   const getCurrDepth = () => parenStack.length + (arrayStart ? 1 : 0);
 
-  tokens.forEach((token, i) => {
+  tokenlist.forEach((token, i) => {
     token.index = i;
     token.depth = getCurrDepth();
     if (token.value === '(') {
@@ -202,5 +202,5 @@ export function addTokenMeta (tokens, { sheetName = '', workbookName = '' } = {}
       token.error = true;
     }
   });
-  return tokens;
+  return tokenlist;
 }

package/lib/extraTypes.js

@@ -0,0 +1,73 @@
+/**
+ * @typedef {object} Token A formula language token.
+ * @augments Record<string,any>
+ * @property {string} type The type of the token
+ * @property {string} value The value of the token
+ * @property {boolean} [unterminated] Signifies an unterminated string token
+ * @property {Array<number>} [loc] Source position offsets to the token
+ */
+
+/**
+ * @typedef {object} TokenEnhanced A token with extra meta data.
+ * @augments Token
+ * @property {number} index A zero based position in a token list
+ * @property {string} [groupId] The ID of a group which this token belongs (e.g. matching parens)
+ * @property {number} [depth] This token's level of nesting inside parentheses
+ * @property {boolean} [error] Token is of unknown type or a paren without a match
+ */
+
+/**
+ * @typedef {Record<string, any>} RangeR1C1 A range in R1C1 style coordinates.
+ * @property {number | null} [r0] Top row of the range
+ * @property {number | null} [r1] Bottom row of the range
+ * @property {number | null} [c0] Left column of the range
+ * @property {number | null} [c1] Right column of the range
+ * @property {boolean | null} [$r0] Signifies that r0 is an absolute value
+ * @property {boolean | null} [$r1] Signifies that r1 is an absolute value
+ * @property {boolean | null} [$c0] Signifies that c0 is an absolute value
+ * @property {boolean | null} [$c1] Signifies that c1 is an absolute value
+ */
+
+/**
+ * @typedef {Record<string, any>} RangeA1 A range in A1 style coordinates.
+ * @property {number | null} [top] Top row of the range
+ * @property {number | null} [bottom] Bottom row of the range
+ * @property {number | null} [left] Left column of the range
+ * @property {number | null} [right] Right column of the range
+ * @property {boolean | null} [$top] Signifies that top is a "locked" value
+ * @property {boolean | null} [$bottom] Signifies that bottom is a "locked" value
+ * @property {boolean | null} [$left] Signifies that left is a "locked" value
+ * @property {boolean | null} [$right] Signifies that right is a "locked" value
+ */
+
+/**
+ * @typedef {Record<string, any>} ReferenceA1
+ *   A reference containing an A1 style range. See [Prefixes.md] for
+ *   documentation on how scopes work in Fx.
+ * @property {Array<string>} [context] A collection of scopes for the reference
+ * @property {string} [workbookName] A context workbook scope
+ * @property {string} [sheetName] A context sheet scope
+ * @property {RangeA1} [range] The reference's range
+ */
+
+/**
+ * @typedef {Record<string, any>} ReferenceR1C1
+ *   A reference containing a R1C1 style range. See [Prefixes.md] for
+ *   documentation on how scopes work in Fx.
+ * @property {Array<string>} [context] A collection of scopes for the reference
+ * @property {string} [workbookName] A context workbook scope
+ * @property {string} [sheetName] A context sheet scope
+ * @property {RangeR1C1} [range] The reference's range
+ */
+
+/**
+ * @typedef {Record<string, any>} ReferenceStruct
+ *   A reference containing a table slice definition. See [Prefixes.md] for
+ *   documentation on how scopes work in Fx.
+ * @property {Array<string>} [context] A collection of scopes for the reference
+ * @property {string} [workbookName] A context workbook scope
+ * @property {string} [sheetName] A context sheet scope
+ * @property {Array<string>} [sections] The sections this reference targets
+ * @property {Array<string>} [columns] The sections this reference targets
+ * @property {string} [table] The table this reference targets
+ */

package/lib/fixRanges.js

@@ -40,19 +40,19 @@ import { REF_STRUCT } from './constants.js';
  * Returns the same formula with the ranges updated. If an array of tokens was
  * supplied, then a new array is returned.
  *
- * @param {(string | Array<Object>)} formula A string (an Excel formula) or a token list that should be adjusted.
- * @param {Object} [options={}]  Options
+ * @param {(string | Array<Token>)} formula A string (an Excel formula) or a token list that should be adjusted.
+ * @param {object} [options={}]  Options
  * @param {boolean} [options.addBounds=false]  Fill in any undefined bounds of range objects. Top to 0, bottom to 1048575, left to 0, and right to 16383.
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
- * @return {(string | Array<Object>)} A formula string or token list (depending on which was input)
+ * @returns {(string | Array<Token>)} A formula string or token list (depending on which was input)
  */
-export function fixRanges (tokens, options = { addBounds: false }) {
-  if (typeof tokens === 'string') {
-    return fixRanges(tokenize(tokens, options), options)
+export function fixRanges (formula, options = { addBounds: false }) {
+  if (typeof formula === 'string') {
+    return fixRanges(tokenize(formula, options), options)
       .map(d => d.value)
       .join('');
   }
-  if (!Array.isArray(tokens)) {
+  if (!Array.isArray(formula)) {
     throw new Error('fixRanges expects an array of tokens');
   }
   const { addBounds, r1c1, xlsx } = options;
@@ -60,7 +60,7 @@ export function fixRanges (tokens, options = { addBounds: false }) {
     throw new Error('fixRanges does not have an R1C1 mode');
   }
   let offsetSkew = 0;
-  return tokens.map(t => {
+  return formula.map(t => {
     const token = { ...t };
     if (t.loc) {
       token.loc = [ ...t.loc ];

package/lib/fixRanges.spec.js

@@ -135,7 +135,15 @@ test('fixRanges structured references', t => {
   t.isFixed('[[#all],[#all],[#all],[#all],[ColumnName]]', '[[#All],[ColumnName]]');
   t.isFixed('[@[foo]:bar]', '[@[foo]:[bar]]');
   t.isFixed('[@foo bar]', '[@[foo bar]]');
-  t.isFixed('[ @foo bar ]', '[@[foo bar]]');
+  // Care must be taken with spaces in column headers.
+  // Excel considers refs only valid if they match the column name
+  // but the parser does not know the names, so it must preserve
+  // leading/trailing whitespace.
+  t.isFixed('[ @[foo bar] ]', '[@[foo bar]]');
+  t.isFixed('[ @[ foo bar ] ]', '[@[ foo bar ]]');
+  t.isFixed('[ @foo bar ]', '[@[foo bar ]]');
+  t.isFixed('[@ foo bar]', '[@[ foo bar]]');
+  t.isFixed('[ @ foo bar ]', '[@[ foo bar ]]');
   t.end();
 });
 

package/lib/isType.js

@@ -12,8 +12,8 @@ import {
  * (`A1` or `A1:B2`), REF_TERNARY (`A1:A`, `A1:1`, `1:A1`, or `A:A1`), or
  * REF_BEAM (`A:A` or `1:1`). In all other cases `false` is returned.
  *
- * @param {Object} token A token
- * @return {boolean} True if the specified token is range, False otherwise.
+ * @param {any} token A token
+ * @returns {boolean} True if the specified token is range, False otherwise.
  */
 export function isRange (token) {
   return !!token && (
@@ -30,8 +30,8 @@ export function isRange (token) {
  * REF_TERNARY (`A1:A`, `A1:1`, `1:A1`, or `A:A1`), REF_BEAM (`A:A` or `1:1`),
  * or REF_NAMED (`myrange`). In all other cases `false` is returned.
  *
- * @param {Object} token The token
- * @return {boolean} True if the specified token is reference, False otherwise.
+ * @param {any} token The token
+ * @returns {boolean} True if the specified token is reference, False otherwise.
  */
 export function isReference (token) {
   return !!token && (
@@ -50,8 +50,8 @@ export function isReference (token) {
  * ERROR (`#VALUE!`), NUMBER (123.4), or STRING (`"lorem ipsum"`). In all other
  * cases `false` is returned.
  *
- * @param {Object} token The token
- * @return {boolean} True if the specified token is literal, False otherwise.
+ * @param {any} token The token
+ * @returns {boolean} True if the specified token is literal, False otherwise.
  */
 export function isLiteral (token) {
   return !!token && (
@@ -68,8 +68,8 @@ export function isLiteral (token) {
  * Returns `true` if the input is a token of type ERROR (`#VALUE!`). In all
  * other cases `false` is returned.
  *
- * @param {Object} token The token
- * @return {boolean} True if the specified token is error, False otherwise.
+ * @param {any} token The token
+ * @returns {boolean} True if the specified token is error, False otherwise.
  */
 export function isError (token) {
   return !!token && token.type === ERROR;
@@ -81,8 +81,8 @@ export function isError (token) {
  * Returns `true` if the input is a token of type WHITESPACE (` `) or
  * NEWLINE (`\n`). In all other cases `false` is returned.
  *
- * @param {Object} token The token
- * @return {boolean} True if the specified token is whitespace, False otherwise.
+ * @param {any} token The token
+ * @returns {boolean} True if the specified token is whitespace, False otherwise.
  */
 export function isWhitespace (token) {
   return !!token && (
@@ -97,8 +97,8 @@ export function isWhitespace (token) {
  * Returns `true` if the input is a token of type FUNCTION.
  * In all other cases `false` is returned.
  *
- * @param {Object} token The token
- * @return {boolean} True if the specified token is function, False otherwise.
+ * @param {any} token The token
+ * @returns {boolean} True if the specified token is function, False otherwise.
  */
 export function isFunction (token) {
   return !!token && token.type === FUNCTION;
@@ -108,8 +108,8 @@ export function isFunction (token) {
  * Returns `true` if the input is a token of type FX_PREFIX (leading `=` in
  * formula). In all other cases `false` is returned.
  *
- * @param {Object} token The token
- * @return {boolean} True if the specified token is effects prefix, False otherwise.
+ * @param {any} token The token
+ * @returns {boolean} True if the specified token is effects prefix, False otherwise.
  */
 export function isFxPrefix (token) {
   return !!token && token.type === FX_PREFIX;
@@ -121,8 +121,8 @@ export function isFxPrefix (token) {
  * Returns `true` if the input is a token of type OPERATOR (`+` or `:`). In all
  * other cases `false` is returned.
  *
- * @param {Object} token The token
- * @return {boolean} True if the specified token is operator, False otherwise.
+ * @param {any} token The token
+ * @returns {boolean} True if the specified token is operator, False otherwise.
  */
 export function isOperator (token) {
   return !!token && token.type === OPERATOR;

package/lib/lexer.js

@@ -196,14 +196,14 @@ export function getTokens (fx, tokenHandlers, options = {}) {
  *
  * @see tokenTypes
  * @param {string} formula An Excel formula string (an Excel expression) or an array of tokens.
- * @param {Object} [options={}]  Options
+ * @param {object} [options={}]  Options
  * @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.
  * @param {boolean} [options.negativeNumbers=true]  Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree).
  * @param {boolean} [options.r1c1=false]  Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
  * @param {boolean} [options.withLocation=true]  Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }`
  * @param {boolean} [options.mergeRefs=true]  Should ranges be returned as whole references (`Sheet1!A1:B2`) or as separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`). This is the same as calling [`mergeRefTokens`](#mergeRefTokens)
  * @param {boolean} [options.xlsx=false]  Enables a `[1]Sheet1!A1` or `[1]!name` syntax form for external workbooks found only in XLSX files.
- * @return {Array<Object>} An AST of nodes
+ * @returns {Array<Token>} An AST of nodes
  */
 export function tokenize (formula, options = {}) {
   return getTokens(formula, lexers, options);

package/lib/mergeRefTokens.js

@@ -63,8 +63,8 @@ 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<Object>} tokenlist An array of tokens (from `tokenize()`)
- * @return {Array} A new list of tokens with range parts merged.
+ * @param {Array<Token>} tokenlist An array of tokens (from `tokenize()`)
+ * @returns {Array<Token>} A new list of tokens with range parts merged.
  */
 export function mergeRefTokens (tokenlist) {
   const finalTokens = [];

package/lib/parser.js

@@ -478,8 +478,8 @@ prefix('{', function () {
  * [AST_format.md](./AST_format.md)
  *
  * @see nodeTypes
- * @param {(string | Array<Object>)} formula An Excel formula string (an Excel expression) or an array of tokens.
- * @param {Object} [options={}]  Options
+ * @param {(string | Array<Token>)} formula An Excel formula string (an Excel expression) or an array of tokens.
+ * @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.
  * @param {boolean} [options.negativeNumbers=true]  Merges unary minuses with their immediately following number tokens (`-`,`1`) => `-1` (alternatively these will be unary operations in the tree).
@@ -488,18 +488,18 @@ prefix('{', function () {
  * @param {boolean} [options.r1c1=false]  Ranges are expected to be in the R1C1 style format rather than the more popular A1 style.
  * @param {boolean} [options.withLocation=false]  Nodes will include source position offsets to the tokens: `{ loc: [ start, end ] }`
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
- * @return {Object} An AST of nodes
+ * @returns {object} An AST of nodes
  */
-export function parse (source, options) {
-  if (typeof source === 'string') {
-    tokens = tokenize(source, {
+export function parse (formula, options) {
+  if (typeof formula === 'string') {
+    tokens = tokenize(formula, {
       withLocation: false,
       ...options,
       mergeRefs: true
     });
   }
-  else if (Array.isArray(source)) {
-    tokens = source;
+  else if (Array.isArray(formula)) {
+    tokens = formula;
   }
   else {
     throw new Error('Parse requires a string or array of tokens.');

package/lib/rc.js

@@ -24,8 +24,8 @@ function toCoord (value, isAbs) {
  *
  * @private
  * @see parseR1C1Ref
- * @param {Object} range  A range object
- * @return {string}  An R1C1-style string represenation of a range
+ * @param {RangeR1C1} range  A range object
+ * @returns {string}  An R1C1-style string represenation of a range
  */
 export function toR1C1 (range) {
   let { r0, c0, r1, c1 } = range;
@@ -134,11 +134,11 @@ function parseR1C1Part (ref) {
  * @private
  * @see parseA1Ref
  * @param {string} rangeString  A range string
- * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
+ * @returns {(RangeR1C1|null)} An object representing a valid reference or null if it is invalid.
  */
-export function fromR1C1 (ref) {
+export function fromR1C1 (rangeString) {
   let final = null;
-  const [ part1, part2 ] = ref.split(':', 2);
+  const [ part1, part2 ] = rangeString.split(':', 2);
   const range = parseR1C1Part(part1);
   if (range) {
     const [ r0, c0, $r0, $c0 ] = range;
@@ -267,11 +267,11 @@ export function fromR1C1 (ref) {
  * ```
  *
  * @param {string} refString An R1C1-style reference string
- * @param {Object} [options={}]  Options
+ * @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.
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
- * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
+ * @returns {(ReferenceR1C1|null)} An object representing a valid reference or null if it is invalid.
  */
 export function parseR1C1Ref (refString, { allowNamed = true, allowTernary = false, xlsx = false } = {}) {
   const d = parseRef(refString, { allowNamed, allowTernary, xlsx, r1c1: true });
@@ -312,10 +312,10 @@ export function parseR1C1Ref (refString, { allowNamed = true, allowTernary = fal
  * // => 'Sheet1!R[9]C9:R[9]C9'
  * ```
  *
- * @param {Object} refObject A reference object
- * @param {Object} [options={}]  Options
+ * @param {ReferenceR1C1} refObject A reference object
+ * @param {object} [options={}]  Options
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
- * @return {Object} The reference in R1C1-style string format
+ * @returns {string} The reference in R1C1-style string format
  */
 export function stringifyR1C1Ref (refObject, { xlsx = false } = {}) {
   const prefix = xlsx

package/lib/sr.js

@@ -71,7 +71,7 @@ export function parseSRange (raw) {
     // [column]
     else if ((m1 = matchColumn(s, false))) {
       pos += m1[0].length;
-      columns.push(m1[1].trim());
+      columns.push(m1[1]);
     }
     // use the "normal" method
     // [[#keyword]]
@@ -126,7 +126,7 @@ export function parseSRange (raw) {
       const leftCol = expect_more ? matchColumn(raw.slice(pos)) : null;
       if (leftCol) {
         pos += leftCol[0].length;
-        columns.push(leftCol[1].trim());
+        columns.push(leftCol[1]);
         s = raw.slice(pos);
         if (s[0] === ':') {
           s = s.slice(1);
@@ -134,7 +134,7 @@ export function parseSRange (raw) {
           const rightCol = matchColumn(s);
           if (rightCol) {
             pos += rightCol[0].length;
-            columns.push(rightCol[1].trim());
+            columns.push(rightCol[1]);
           }
           else {
             return null;
@@ -185,16 +185,16 @@ export function parseSRange (raw) {
  *
  * @tutorial References.md
  * @param {string} ref  A structured reference string
- * @param {Object} [options={}]  Options
+ * @param {object} [options={}]  Options
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
- * @return {(Object|null)} An object representing a valid reference or null if it is invalid.
+ * @returns {(ReferenceStruct|null)} An object representing a valid reference or null if it is invalid.
  */
-export function parseStructRef (ref, opts = { xlsx: false }) {
-  const r = parseRef(ref, opts);
+export function parseStructRef (ref, options = { xlsx: false }) {
+  const r = parseRef(ref, options);
   if (r && r.struct) {
     const structData = parseSRange(r.struct);
     if (structData && structData.length === r.struct.length) {
-      return opts.xlsx
+      return options.xlsx
         ? {
           workbookName: r.workbookName,
           sheetName: r.sheetName,
@@ -238,38 +238,38 @@ function toSentenceCase (str) {
  * // => 'workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]'
  * ```
  *
- * @param {Object} refObject A structured reference object
- * @param {Object} [options={}]  Options
+ * @param {ReferenceStruct} refObject A structured reference object
+ * @param {object} [options={}]  Options
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
- * @return {Object} The structured reference in string format
+ * @returns {string} The structured reference in string format
  */
-export function stringifyStructRef (ref, { xlsx = false } = {}) {
+export function stringifyStructRef (refObject, { xlsx = false } = {}) {
   let s = xlsx
-    ? stringifyPrefixAlt(ref)
-    : stringifyPrefix(ref);
+    ? stringifyPrefixAlt(refObject)
+    : stringifyPrefix(refObject);
 
-  if (ref.table) {
-    s += ref.table;
+  if (refObject.table) {
+    s += refObject.table;
   }
-  const numColumns = ref.columns?.length ?? 0;
-  const numSections = ref.sections?.length ?? 0;
+  const numColumns = refObject.columns?.length ?? 0;
+  const numSections = refObject.sections?.length ?? 0;
   // single section
   if (numSections === 1 && !numColumns) {
-    s += `[#${toSentenceCase(ref.sections[0])}]`;
+    s += `[#${toSentenceCase(refObject.sections[0])}]`;
   }
   // single column
   else if (!numSections && numColumns === 1) {
-    s += `[${quoteColname(ref.columns[0])}]`;
+    s += `[${quoteColname(refObject.columns[0])}]`;
   }
   else {
     s += '[';
     // single [#this row] sections get normalized to an @
-    const singleAt = numSections === 1 && ref.sections[0].toLowerCase() === 'this row';
+    const singleAt = numSections === 1 && refObject.sections[0].toLowerCase() === 'this row';
     if (singleAt) {
       s += '@';
     }
     else if (numSections) {
-      s += ref.sections
+      s += refObject.sections
         .map(d => `[#${toSentenceCase(d)}]`)
         .join(',');
       if (numColumns) {
@@ -277,11 +277,11 @@ export function stringifyStructRef (ref, { xlsx = false } = {}) {
       }
     }
     // a case of a single alphanumberic column with a [#this row] becomes [@col]
-    if (singleAt && ref.columns.length === 1 && !needsBraces(ref.columns[0])) {
-      s += quoteColname(ref.columns[0]);
+    if (singleAt && refObject.columns.length === 1 && !needsBraces(refObject.columns[0])) {
+      s += quoteColname(refObject.columns[0]);
     }
     else if (numColumns) {
-      s += ref.columns.slice(0, 2)
+      s += refObject.columns.slice(0, 2)
         .map(d => (`[${quoteColname(d)}]`))
         .join(':');
     }

package/lib/sr.spec.js

@@ -45,16 +45,24 @@ test('parse structured references', t => {
     columns: [ 'my column' ]
   });
 
-  t.isSREqual('[ [my column]:otherColumn ]', {
+  t.isSREqual('[[my column]:otherColumn]', {
     columns: [ 'my column', 'otherColumn' ]
   });
 
-  t.isSREqual('[ @[my column]:otherColumn ]', {
-    columns: [ 'my column', 'otherColumn' ],
+  t.isSREqual('[ [my column]:otherColumn ]', {
+    columns: [ 'my column', 'otherColumn ' ]
+  });
+
+  t.isSREqual('[ [my column]: otherColumn ]', {
+    columns: [ 'my column', ' otherColumn ' ]
+  });
+
+  t.isSREqual('[ @[ my column ]: otherColumn ]', {
+    columns: [ ' my column ', ' otherColumn ' ],
     sections: [ 'this row' ]
   });
 
-  t.isSREqual('[ [#Data], [my column]:otherColumn ]', {
+  t.isSREqual('[[#Data], [my column]:otherColumn]', {
     columns: [ 'my column', 'otherColumn' ],
     sections: [ 'data' ]
   });

package/lib/translate.js

@@ -30,20 +30,20 @@ const settings = {
  * // => "=SUM(RC[1],R2C5,Sheet!R3C5)");
  * ```
  *
- * @param {(string | Array<Object>)} formula A string (an Excel formula) or a token list that should be adjusted.
+ * @param {(string | Array<Token>)} formula A string (an Excel formula) or a token list that should be adjusted.
  * @param {string} anchorCell A simple string reference to an A1 cell ID (`AF123` or`$C$5`).
- * @param {Object} [options={}] The options
+ * @param {object} [options={}] The options
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
  * @param {boolean} [options.allowTernary=true]  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 {(string | Array<Object>)} A formula string or token list (depending on which was input)
+ * @returns {(string | Array<Token>)} A formula string or token list (depending on which was input)
  */
-export function translateToR1C1 (fx, anchorCell, { xlsx = false, allowTernary = true } = {}) {
+export function translateToR1C1 (formula, anchorCell, { xlsx = false, allowTernary = true } = {}) {
   const { top, left } = fromA1(anchorCell);
-  const isString = typeof fx === 'string';
+  const isString = typeof formula === 'string';
 
   const tokens = isString
-    ? tokenize(fx, { ...settings, xlsx, allowTernary })
-    : fx;
+    ? tokenize(formula, { ...settings, xlsx, allowTernary })
+    : formula;
 
   let offsetSkew = 0;
   const refOpts = { xlsx, allowTernary };
@@ -144,14 +144,14 @@ const defaultOptions = {
  * `=Sheet3!#REF!:F3`. These are valid formulas in the Excel formula language
  * and Excel will accept them, but they are not supported in Google Sheets.
  *
- * @param {(string | Array<Object>)} formula A string (an Excel formula) or a token list that should be adjusted.
+ * @param {(string | Array<Token>)} formula A string (an Excel formula) or a token list that should be adjusted.
  * @param {string} anchorCell A simple string reference to an A1 cell ID (`AF123` or`$C$5`).
- * @param {Object} [options={}] The options
+ * @param {object} [options={}] The options
  * @param {boolean} [options.wrapEdges=true]  Wrap out-of-bounds ranges around sheet edges rather than turning them to #REF! errors
  * @param {boolean} [options.mergeRefs=true]   Should ranges be treated as whole references (`Sheet1!A1:B2`) or as separate tokens for each part: (`Sheet1`,`!`,`A1`,`:`,`B2`).
  * @param {boolean} [options.xlsx=false]  Switches to the `[1]Sheet1!A1` or `[1]!name` prefix syntax form for external workbooks. See: [Prefixes.md](./Prefixes.md)
  * @param {boolean} [options.allowTernary=true]  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 {(string | Array<Object>)} A formula string or token list (depending on which was input)
+ * @returns {(string | Array<Token>)} A formula string or token list (depending on which was input)
  */
 export function translateToA1 (formula, anchorCell, options = defaultOptions) {
   const anchor = fromA1(anchorCell);