@borgar/fx 4.13.0 → 5.0.0

package/lib/fixRanges.ts

@@ -0,0 +1,260 @@
+import { isRange } from './isType.ts';
+import { parseA1Ref, parseA1RefXlsx } from './parseA1Ref.ts';
+import { stringifyA1Ref, stringifyA1RefXlsx } from './stringifyA1Ref.ts';
+import { addA1RangeBounds } from './addA1RangeBounds.ts';
+import { parseStructRef, parseStructRefXlsx } from './parseStructRef.ts';
+import { stringifyStructRef, stringifyStructRefXlsx } from './stringifyStructRef.ts';
+import { tokenize, type OptsTokenize, tokenizeXlsx } from './tokenize.ts';
+import { REF_STRUCT } from './constants.ts';
+import type { ReferenceA1, ReferenceA1Xlsx, Token } from './types.ts';
+import { cloneToken } from './cloneToken.ts';
+import { stringifyTokens } from './stringifyTokens.ts';
+
+// There is no R1C1 counterpart to this. This is because without an anchor cell
+// it is impossible to determine if a relative+absolute range (R[1]C[1]:R5C5)
+// needs to be flipped or not. The solution is to convert to A1 first:
+// translateToRC(fixRanges(translateToA1(...)))
+
+/**
+ * Options for {@link fixTokenRanges} and {@link fixFormulaRanges}.
+ */
+export type OptsFixRanges = {
+  /**
+   * Fill in any undefined bounds of range objects. Top to 0, bottom to 1048575, left to 0, and right to 16383.
+   * @defaultValue false
+   */
+  addBounds?: boolean,
+  /**
+   * Enforces using the `[#This Row]` instead of the `@` shorthand when serializing structured ranges.
+   * @defaultValue false
+   */
+  thisRow?: boolean,
+};
+
+/**
+ * Normalizes A1 style ranges and structured references in a list of tokens.
+ *
+ * It ensures that that the top and left coordinates of an A1 range are on the
+ * left-hand side of a colon operator:
+ *
+ * ```
+ * B2:A1 → A1:B2
+ * 1:A1 → A1:1
+ * A:A1 → A1:A
+ * B:A → A:B
+ * 2:1 → 1:2
+ * A1:A1 → A1
+ * ```
+ *
+ * When `{ addBounds }` option is set to true, the missing bounds are also added.
+ * This can be done to ensure Excel compatible ranges. The fixes then additionally include:
+ *
+ * ```
+ * 1:A1 → A1:1 → 1:1
+ * A:A1 → A1:A → A:A
+ * A1:A → A:A
+ * A1:1 → A:1
+ * B2:B → B2:1048576
+ * B2:2 → B2:XFD2
+ * ```
+ *
+ * Structured ranges are normalized to have consistent order and capitalization
+ * of sections as well as removing redundant ones.
+ *
+ * Returns a new array of tokens with values and position data updated.
+ *
+ * @see {@link OptsFixRanges}
+ * @param tokens A list of tokens to be adjusted.
+ * @param [options]  Options.
+ * @returns A token list with ranges adjusted.
+ */
+export function fixTokenRanges (
+  tokens: Token[],
+  options: OptsFixRanges = {}
+): Token[] {
+  if (!Array.isArray(tokens)) {
+    throw new Error('fixRanges expects an array of tokens');
+  }
+  const { addBounds, thisRow } = options;
+  let offsetSkew = 0;
+  const output: Token[] = [];
+  for (const t of tokens) {
+    const token = cloneToken(t);
+    let offsetDelta = 0;
+    if (token.type === REF_STRUCT) {
+      const sref = parseStructRef(token.value);
+      const newValue = stringifyStructRef(sref, { thisRow });
+      offsetDelta = newValue.length - token.value.length;
+      token.value = newValue;
+    }
+    else if (isRange(token)) {
+      const ref = parseA1Ref(token.value, { allowTernary: true }) as ReferenceA1;
+      const range = ref.range;
+      // fill missing dimensions?
+      if (addBounds) {
+        addA1RangeBounds(range);
+      }
+      const newValue = stringifyA1Ref(ref);
+      offsetDelta = newValue.length - token.value.length;
+      token.value = newValue;
+    }
+    // ensure that positioning is still correct
+    if (offsetSkew || offsetDelta) {
+      if (token.loc) {
+        token.loc[0] += offsetSkew;
+      }
+      offsetSkew += offsetDelta;
+      if (token.loc) {
+        token.loc[1] += offsetSkew;
+      }
+    }
+    else {
+      offsetSkew += offsetDelta;
+    }
+    output.push(token);
+  }
+
+  return output;
+}
+
+/**
+ * Normalizes A1 style ranges and structured references in a list of tokens.
+ *
+ * It ensures that that the top and left coordinates of an A1 range are on the
+ * left-hand side of a colon operator:
+ *
+ * ```
+ * B2:A1 → A1:B2
+ * 1:A1 → A1:1
+ * A:A1 → A1:A
+ * B:A → A:B
+ * 2:1 → 1:2
+ * A1:A1 → A1
+ * ```
+ *
+ * When `{ addBounds }` option is set to true, the missing bounds are also added.
+ * This can be done to ensure Excel compatible ranges. The fixes then additionally include:
+ *
+ * ```
+ * 1:A1 → A1:1 → 1:1
+ * A:A1 → A1:A → A:A
+ * A1:A → A:A
+ * A1:1 → A:1
+ * B2:B → B2:1048576
+ * B2:2 → B2:XFD2
+ * ```
+ *
+ * Structured ranges are normalized to have consistent order and capitalization
+ * of sections as well as removing redundant ones.
+ *
+ * Returns a new array of tokens with values and position data updated.
+ *
+ * @see {@link OptsFixRanges}
+ * @param tokens A list of tokens to be adjusted.
+ * @param [options]  Options.
+ * @returns A token list with ranges adjusted.
+ */
+export function fixTokenRangesXlsx (
+  tokens: Token[],
+  options: OptsFixRanges = {}
+): Token[] {
+  if (!Array.isArray(tokens)) {
+    throw new Error('fixRanges expects an array of tokens');
+  }
+  const { addBounds, thisRow } = options;
+  let offsetSkew = 0;
+  const output: Token[] = [];
+  for (const t of tokens) {
+    const token = cloneToken(t);
+    let offsetDelta = 0;
+    if (token.type === REF_STRUCT) {
+      const sref = parseStructRefXlsx(token.value);
+      const newValue = stringifyStructRefXlsx(sref, { thisRow });
+      offsetDelta = newValue.length - token.value.length;
+      token.value = newValue;
+    }
+    else if (isRange(token)) {
+      const ref = parseA1RefXlsx(token.value, { allowTernary: true }) as ReferenceA1Xlsx;
+      const range = ref.range;
+      // fill missing dimensions?
+      if (addBounds) {
+        addA1RangeBounds(range);
+      }
+      const newValue = stringifyA1RefXlsx(ref);
+      offsetDelta = newValue.length - token.value.length;
+      token.value = newValue;
+    }
+    // ensure that positioning is still correct
+    if (offsetSkew || offsetDelta) {
+      if (token.loc) {
+        token.loc[0] += offsetSkew;
+      }
+      offsetSkew += offsetDelta;
+      if (token.loc) {
+        token.loc[1] += offsetSkew;
+      }
+    }
+    else {
+      offsetSkew += offsetDelta;
+    }
+    output.push(token);
+  }
+
+  return output;
+}
+
+/**
+ * Normalizes A1 style ranges and structured references in a formula.
+ *
+ * Internally it uses {@link fixTokenRanges} so see it's documentation for details.
+ *
+ * Returns the same formula with the ranges updated. If an array of tokens was
+ * supplied, then a new array is returned.
+ *
+ * @see {@link OptsFixRanges} & {@link OptsTokenize}
+ * @param formula A string (an Excel formula) or a token list that should be adjusted.
+ * @param [options]  Options
+ * @returns A formula string with ranges adjusted
+ */
+export function fixFormulaRanges (
+  formula: string,
+  options: OptsFixRanges & OptsTokenize = {}
+): string {
+  if (typeof formula !== 'string') {
+    throw new Error('fixFormulaRanges expects a string formula');
+  }
+  return stringifyTokens(
+    fixTokenRanges(
+      tokenize(formula, options),
+      options
+    )
+  );
+}
+
+/**
+ * Normalizes A1 style ranges and structured references in a formula.
+ *
+ * Internally it uses {@link fixTokenRanges} so see it's documentation for details.
+ *
+ * Returns the same formula with the ranges updated. If an array of tokens was
+ * supplied, then a new array is returned.
+ *
+ * @see {@link OptsFixRanges} & {@link OptsTokenize}
+ * @param formula A string (an Excel formula) or a token list that should be adjusted.
+ * @param [options]  Options
+ * @returns A formula string with ranges adjusted
+ */
+export function fixFormulaRangesXlsx (
+  formula: string,
+  options: OptsFixRanges & OptsTokenize = {}
+): string {
+  if (typeof formula !== 'string') {
+    throw new Error('fixFormulaRanges expects a string formula');
+  }
+  return stringifyTokens(
+    fixTokenRangesXlsx(
+      tokenizeXlsx(formula, options),
+      options
+    )
+  );
+}

package/lib/fromCol.spec.ts

@@ -0,0 +1,15 @@
+import { describe, test, expect } from 'vitest';
+import { fromCol } from './fromCol.ts';
+
+describe('fromCol parses column id strings to numbers', () => {
+  test('single letter columns', () => {
+    expect(fromCol('a')).toBe(0);
+    expect(fromCol('A')).toBe(0);
+  });
+
+  test('multi-letter columns', () => {
+    expect(fromCol('AA')).toBe(26);
+    expect(fromCol('zz')).toBe(701);
+    expect(fromCol('ZZZ')).toBe(18277);
+  });
+});

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

@@ -9,7 +9,7 @@
  * @param {string} columnString  The column string identifier
  * @returns {number}  Zero based column index number
  */
-export function fromCol (columnString) {
+export function fromCol (columnString: string): number {
   const x = (columnString || '');
   const l = x.length;
   let n = 0;

package/lib/index.spec.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+import {
+  addA1RangeBounds,
+  fixTokenRanges,
+  fixFormulaRanges,
+  fromCol,
+  isError,
+  isFunction,
+  isFxPrefix,
+  isLiteral,
+  isOperator,
+  isRange,
+  isReference,
+  isWhitespace,
+  mergeRefTokens,
+  nodeTypes,
+  parse,
+  parseA1Ref,
+  parseR1C1Ref,
+  parseStructRef,
+  stringifyA1Ref,
+  stringifyR1C1Ref,
+  stringifyStructRef,
+  toCol,
+  tokenize,
+  tokenTypes,
+  translateFormulaToA1,
+  translateTokensToA1,
+  translateFormulaToR1C1,
+  translateTokensToR1C1
+} from './index.ts';
+
+// What happens when B2:A1 -> should work!
+describe('fx main interface', () => {
+  it('addA1RangeBounds exists', () => {
+    expect(typeof addA1RangeBounds === 'function').toBeTruthy();
+  });
+  it('fixTokenRanges exists', () => {
+    expect(typeof fixTokenRanges === 'function').toBeTruthy();
+  });
+  it('fixFormulaRanges exists', () => {
+    expect(typeof fixFormulaRanges === 'function').toBeTruthy();
+  });
+  it('fromCol exists', () => {
+    expect(typeof fromCol === 'function').toBeTruthy();
+  });
+  it('isError exists', () => {
+    expect(typeof isError === 'function').toBeTruthy();
+  });
+  it('isFunction exists', () => {
+    expect(typeof isFunction === 'function').toBeTruthy();
+  });
+  it('isFxPrefix exists', () => {
+    expect(typeof isFxPrefix === 'function').toBeTruthy();
+  });
+  it('isLiteral exists', () => {
+    expect(typeof isLiteral === 'function').toBeTruthy();
+  });
+  it('isOperator exists', () => {
+    expect(typeof isOperator === 'function').toBeTruthy();
+  });
+  it('isRange exists', () => {
+    expect(typeof isRange === 'function').toBeTruthy();
+  });
+  it('isReference exists', () => {
+    expect(typeof isReference === 'function').toBeTruthy();
+  });
+  it('isWhitespace exists', () => {
+    expect(typeof isWhitespace === 'function').toBeTruthy();
+  });
+  it('mergeRefTokens exists', () => {
+    expect(typeof mergeRefTokens === 'function').toBeTruthy();
+  });
+  it('parse exists', () => {
+    expect(typeof parse === 'function').toBeTruthy();
+  });
+  it('parseA1Ref exists', () => {
+    expect(typeof parseA1Ref === 'function').toBeTruthy();
+  });
+  it('parseR1C1Ref exists', () => {
+    expect(typeof parseR1C1Ref === 'function').toBeTruthy();
+  });
+  it('parseStructRef exists', () => {
+    expect(typeof parseStructRef === 'function').toBeTruthy();
+  });
+  it('stringifyA1Ref exists', () => {
+    expect(typeof stringifyA1Ref === 'function').toBeTruthy();
+  });
+  it('stringifyR1C1Ref exists', () => {
+    expect(typeof stringifyR1C1Ref === 'function').toBeTruthy();
+  });
+  it('stringifyStructRef exists', () => {
+    expect(typeof stringifyStructRef === 'function').toBeTruthy();
+  });
+  it('toCol exists', () => {
+    expect(typeof toCol === 'function').toBeTruthy();
+  });
+  it('tokenize exists', () => {
+    expect(typeof tokenize === 'function').toBeTruthy();
+  });
+  it('translateFormulaToA1 exists', () => {
+    expect(typeof translateFormulaToA1 === 'function').toBeTruthy();
+  });
+  it('translateTokensToA1 exists', () => {
+    expect(typeof translateTokensToA1 === 'function').toBeTruthy();
+  });
+  it('translateFormulaToR1C1 exists', () => {
+    expect(typeof translateFormulaToR1C1 === 'function').toBeTruthy();
+  });
+  it('translateTokensToR1C1 exists', () => {
+    expect(typeof translateTokensToR1C1 === 'function').toBeTruthy();
+  });
+  it('nodeTypes exists', () => {
+    expect(typeof nodeTypes === 'object').toBeTruthy();
+  });
+  it('tokenTypes exists', () => {
+    expect(typeof tokenTypes === 'object').toBeTruthy();
+  });
+});

package/lib/index.ts

@@ -0,0 +1,76 @@
+/**
+ * A tokenizer, parser, and other utilities to work with Excel formula code.
+ *
+ * The base entry-point methods expect and return the variant of references that uses contexts.
+ * If you are using xlsx files or otherwise want to work with the xlsx-file variant of references
+ * you should use the {@link fx/xlsx} variant methods.
+ *
+ * See [Prefixes.md](./Prefixes.md) for documentation on how scopes work in Fx.
+ *
+ * @packageDocumentation
+ * @module fx
+ */
+
+export { tokenize, type OptsTokenize } from './tokenize.ts';
+export { parse, type OptsParse } from './parse.ts';
+export { translateFormulaToR1C1, translateTokensToR1C1, type OptsTranslateToR1C1 } from './translateToR1C1.ts';
+export {
+  translateFormulaToA1, type OptsTranslateFormulaToA1,
+  translateTokensToA1, type OptsTranslateTokensToA1
+} from './translateToA1.ts';
+export { MAX_COLS, MAX_ROWS } from './constants.ts';
+export { mergeRefTokens } from './mergeRefTokens.ts';
+export { fixTokenRanges, fixFormulaRanges, type OptsFixRanges } from './fixRanges.ts';
+export {
+  isError,
+  isFunction,
+  isFxPrefix,
+  isLiteral,
+  isOperator,
+  isRange,
+  isReference,
+  isWhitespace
+} from './isType.ts';
+export {
+  isArrayNode,
+  isBinaryNode,
+  isCallNode,
+  isErrorNode,
+  isExpressionNode,
+  isIdentifierNode,
+  isLambdaNode,
+  isLetDeclaratorNode,
+  isLetNode,
+  isLiteralNode,
+  isReferenceNode,
+  isUnaryNode
+} from './isNodeType.ts';
+export { addA1RangeBounds } from './addA1RangeBounds.ts';
+export { toCol } from './toCol.ts';
+export { fromCol } from './fromCol.ts';
+export { parseA1Range } from './parseA1Range.ts';
+export { parseA1Ref, type OptsParseA1Ref } from './parseA1Ref.ts';
+export { parseR1C1Range } from './parseR1C1Range.ts';
+export { parseR1C1Ref, type OptsParseR1C1Ref } from './parseR1C1Ref.ts';
+export { parseStructRef } from './parseStructRef.ts';
+export { stringifyA1Ref } from './stringifyA1Ref.ts';
+export { stringifyR1C1Ref } from './stringifyR1C1Ref.ts';
+export { stringifyStructRef, type OptsStringifyStructRef } from './stringifyStructRef.ts';
+export { stringifyTokens } from './stringifyTokens.ts';
+export type {
+  RangeA1,
+  RangeR1C1,
+  Token,
+  TokenEnhanced,
+  ReferenceA1,
+  ReferenceA1Xlsx,
+  ReferenceR1C1,
+  ReferenceR1C1Xlsx,
+  ReferenceStruct,
+  ReferenceStructXlsx,
+  ReferenceName,
+  ReferenceNameXlsx
+} from './types.ts';
+export type * from './astTypes.ts';
+export { tokenTypes } from './tokenTypes.ts';
+export { nodeTypes } from './nodeTypes.ts';

package/lib/isNodeType.ts

@@ -0,0 +1,151 @@
+import type {
+  Node,
+  Identifier,
+  ReferenceIdentifier,
+  Literal,
+  ErrorLiteral,
+  UnaryExpression,
+  BinaryExpression,
+  CallExpression,
+  ArrayExpression,
+  LambdaExpression,
+  LetExpression,
+  LetDeclarator,
+  AstExpression
+} from './astTypes.ts';
+import {
+  ARRAY,
+  BINARY,
+  CALL,
+  ERROR,
+  ERROR_LITERAL,
+  IDENTIFIER,
+  LAMBDA,
+  LET,
+  LET_DECL,
+  LITERAL,
+  REFERENCE,
+  UNARY
+} from './constants.ts';
+
+/**
+ * Determines whether the specified node is an Identifier.
+ * @param node An AST node.
+ * @returns True if the specified token is an Identifier, False otherwise.
+ */
+export function isIdentifierNode (node?: Node | null): node is Identifier {
+  return node?.type === IDENTIFIER;
+}
+
+/**
+ * Determines whether the specified node is a ReferenceIdentifier.
+ * @param node An AST node.
+ * @returns True if the specified token is a ReferenceIdentifier, False otherwise.
+ */
+export function isReferenceNode (node?: Node | null): node is ReferenceIdentifier {
+  return node?.type === REFERENCE;
+}
+
+/**
+ * Determines whether the specified node is a Literal.
+ * @param node An AST node.
+ * @returns True if the specified token is a Literal, False otherwise.
+ */
+export function isLiteralNode (node?: Node | null): node is Literal {
+  return node?.type === LITERAL;
+}
+
+/**
+ * Determines whether the specified node is an ErrorLiteral.
+ * @param node An AST node.
+ * @returns True if the specified token is an ErrorLiteral, False otherwise.
+ */
+export function isErrorNode (node?: Node | null): node is ErrorLiteral {
+  return node?.type === ERROR_LITERAL;
+}
+
+/**
+ * Determines whether the specified node is a UnaryExpression.
+ * @param node An AST node.
+ * @returns True if the specified token is a UnaryExpression, False otherwise.
+ */
+export function isUnaryNode (node?: Node | null): node is UnaryExpression {
+  return node?.type === UNARY;
+}
+
+/**
+ * Determines whether the specified node is a BinaryExpression.
+ * @param node An AST node.
+ * @returns True if the specified token is a BinaryExpression, False otherwise.
+ */
+export function isBinaryNode (node?: Node | null): node is BinaryExpression {
+  return node?.type === BINARY;
+}
+
+/**
+ * Determines whether the specified node is a CallExpression.
+ * @param node An AST node.
+ * @returns True if the specified token is a CallExpression, False otherwise.
+ */
+export function isCallNode (node?: Node | null): node is CallExpression {
+  return node?.type === CALL;
+}
+
+/**
+ * Determines whether the specified node is a ArrayExpression.
+ * @param node An AST node.
+ * @returns True if the specified token is a ArrayExpression, False otherwise.
+ */
+export function isArrayNode (node?: Node | null): node is ArrayExpression {
+  return node?.type === ARRAY;
+}
+
+/**
+ * Determines whether the specified node is a LambdaExpression.
+ * @param node An AST node.
+ * @returns True if the specified token is a LambdaExpression, False otherwise.
+ */
+export function isLambdaNode (node?: Node | null): node is LambdaExpression {
+  return node?.type === ARRAY;
+}
+
+/**
+ * Determines whether the specified node is a LetExpression.
+ * @param node An AST node.
+ * @returns True if the specified token is a LetExpression, False otherwise.
+ */
+export function isLetNode (node?: Node | null): node is LetExpression {
+  return node?.type === LET;
+}
+
+/**
+ * Determines whether the specified node is a LetDeclarator.
+ * @param node An AST node.
+ * @returns True if the specified token is a LetDeclarator, False otherwise.
+ */
+export function isLetDeclaratorNode (node?: Node | null): node is LetDeclarator {
+  return node?.type === LET_DECL;
+}
+
+/**
+ * Determines whether the specified node is a AstExpression.
+ * @param node An AST node.
+ * @returns True if the specified token is a AstExpression, False otherwise.
+ */
+export function isExpressionNode (node?: Node | null): node is AstExpression {
+  const type = node?.type;
+  if (type) {
+    return (
+      type === REFERENCE ||
+      type === LITERAL ||
+      type === ERROR ||
+      type === UNARY ||
+      type === BINARY ||
+      type === CALL ||
+      type === ARRAY ||
+      type === LAMBDA ||
+      type === LET
+    );
+  }
+  return false;
+}