@borgar/fx 4.12.0 → 5.0.0

package/lib/stringifyR1C1Range.ts

@@ -0,0 +1,73 @@
+import { rangeOperator } from './a1.ts';
+import { MAX_ROWS, MAX_COLS } from './constants.ts';
+import type { RangeR1C1 } from './types.ts';
+
+const clamp = (min: number, val: number, max: number) => Math.min(Math.max(val, min), max);
+
+function toCoord (value: number, isAbs: boolean): string {
+  if (isAbs) {
+    return String(value + 1);
+  }
+  return value ? '[' + value + ']' : '';
+}
+
+/**
+ * Stringify a range object into R1C1 syntax.
+ * @internal
+ */
+export function stringifyR1C1Range (range: RangeR1C1): string {
+  let { r0, c0, r1, c1 } = range;
+  const { $c0, $c1, $r0, $r1 } = range;
+  const nullR0 = r0 == null;
+  const nullC0 = c0 == null;
+  let nullR1 = r1 == null;
+  let nullC1 = c1 == null;
+  const op = rangeOperator(range.trim);
+  const hasTrim = !!range.trim;
+  r0 = clamp($r0 ? 0 : -MAX_ROWS, r0 | 0, MAX_ROWS);
+  c0 = clamp($c0 ? 0 : -MAX_COLS, c0 | 0, MAX_COLS);
+  if (!nullR0 && nullR1 && !nullC0 && nullC1) {
+    r1 = r0;
+    nullR1 = false;
+    c1 = c0;
+    nullC1 = false;
+  }
+  else {
+    r1 = clamp($r1 ? 0 : -MAX_ROWS, r1 | 0, MAX_ROWS);
+    c1 = clamp($c1 ? 0 : -MAX_COLS, c1 | 0, MAX_COLS);
+  }
+  // C:C
+  const allRows = r0 === 0 && r1 >= MAX_ROWS;
+  if ((allRows && !nullC0 && !nullC1) || (nullR0 && nullR1)) {
+    const a = toCoord(c0, $c0);
+    const b = toCoord(c1, $c1);
+    return 'C' + (a === b && !hasTrim ? a : a + op + 'C' + b);
+  }
+  // R:R
+  const allCols = c0 === 0 && c1 >= MAX_COLS;
+  if ((allCols && !nullR0 && !nullR1) || (nullC0 && nullC1)) {
+    const a = toCoord(r0, $r0);
+    const b = toCoord(r1, $r1);
+    return 'R' + (a === b && !hasTrim ? a : a + op + 'R' + b);
+  }
+  const s_r0 = toCoord(r0, $r0);
+  const s_r1 = toCoord(r1, $r1);
+  const s_c0 = toCoord(c0, $c0);
+  const s_c1 = toCoord(c1, $c1);
+  // RC:R, RC:C
+  if (nullR0 || nullR1 || nullC0 || nullC1) {
+    return (
+      (nullR0 ? '' : 'R' + s_r0) +
+      (nullC0 ? '' : 'C' + s_c0) +
+      op +
+      (nullR1 ? '' : 'R' + s_r1) +
+      (nullC1 ? '' : 'C' + s_c1)
+    );
+  }
+  // RC:RC
+  if (s_r0 !== s_r1 || s_c0 !== s_c1) {
+    return 'R' + s_r0 + 'C' + s_c0 + op + 'R' + s_r1 + 'C' + s_c1;
+  }
+  // RC
+  return 'R' + s_r0 + 'C' + s_c0;
+}

package/lib/stringifyR1C1Ref.spec.ts

@@ -0,0 +1,63 @@
+import { describe, test, expect } from 'vitest';
+import { stringifyR1C1Ref, stringifyR1C1RefXlsx } from './stringifyR1C1Ref.ts';
+
+describe('stringifyR1C1Ref', () => {
+  const rangeA1 = { r0: 2, c0: 4, r1: 2, c1: 4 };
+
+  function testRef (ref: any, expected: string) {
+    expect(stringifyR1C1Ref(ref)).toBe(expected);
+  }
+
+  test('basic stringification', () => {
+    testRef({ range: rangeA1 }, 'R[2]C[4]');
+    testRef({ context: [ 'Sheet1' ], range: rangeA1 }, 'Sheet1!R[2]C[4]');
+    testRef({ context: [ 'Sheet 1' ], range: rangeA1 }, "'Sheet 1'!R[2]C[4]");
+    testRef({ context: [ 'MyFile.xlsx', 'Sheet1' ], range: rangeA1 }, '[MyFile.xlsx]Sheet1!R[2]C[4]');
+    testRef({ context: [ 'My File.xlsx', 'Sheet1' ], range: rangeA1 }, "'[My File.xlsx]Sheet1'!R[2]C[4]");
+    testRef({ context: [ 'MyFile.xlsx' ], range: rangeA1 }, 'MyFile.xlsx!R[2]C[4]');
+    testRef({ context: [ 'My File.xlsx' ], range: rangeA1 }, "'My File.xlsx'!R[2]C[4]");
+  });
+
+  test('named ranges', () => {
+    testRef({ name: 'foo' }, 'foo');
+    testRef({ context: [ 'Sheet1' ], name: 'foo' }, 'Sheet1!foo');
+    testRef({ context: [ 'Sheet 1' ], name: 'foo' }, "'Sheet 1'!foo");
+    testRef({ context: [ 'MyFile.xlsx', 'Sheet1' ], name: 'foo' }, '[MyFile.xlsx]Sheet1!foo');
+    testRef({ context: [ 'My File.xlsx', 'Sheet1' ], name: 'foo' }, "'[My File.xlsx]Sheet1'!foo");
+    testRef({ context: [ 'MyFile.xlsx' ], name: 'foo' }, 'MyFile.xlsx!foo');
+    testRef({ context: [ 'My File.xlsx' ], name: 'foo' }, "'My File.xlsx'!foo");
+  });
+});
+
+describe('stringifyR1C1Ref in XLSX mode', () => {
+  const rangeA1 = { r0: 2, c0: 4, r1: 2, c1: 4 };
+
+  function testRef (ref: any, expected: string) {
+    expect(stringifyR1C1RefXlsx(ref)).toBe(expected);
+  }
+
+  test('basic stringification', () => {
+    testRef({ range: rangeA1 }, 'R[2]C[4]');
+    testRef({ sheetName: 'Sheet1', range: rangeA1 }, 'Sheet1!R[2]C[4]');
+    testRef({ sheetName: 'Sheet 1', range: rangeA1 }, "'Sheet 1'!R[2]C[4]");
+    testRef({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', range: rangeA1 }, '[MyFile.xlsx]Sheet1!R[2]C[4]');
+    testRef({ workbookName: 'My File.xlsx', sheetName: 'Sheet1', range: rangeA1 }, "'[My File.xlsx]Sheet1'!R[2]C[4]");
+    testRef({ workbookName: 'MyFile.xlsx', range: rangeA1 }, '[MyFile.xlsx]!R[2]C[4]');
+    testRef({ workbookName: 'My File.xlsx', range: rangeA1 }, "'[My File.xlsx]'!R[2]C[4]");
+  });
+
+  test('named ranges', () => {
+    testRef({ name: 'foo' }, 'foo');
+    testRef({ sheetName: 'Sheet1', name: 'foo' }, 'Sheet1!foo');
+    testRef({ sheetName: 'Sheet 1', name: 'foo' }, "'Sheet 1'!foo");
+    testRef({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', name: 'foo' }, '[MyFile.xlsx]Sheet1!foo');
+    testRef({ workbookName: 'My File.xlsx', sheetName: 'Sheet1', name: 'foo' }, "'[My File.xlsx]Sheet1'!foo");
+    testRef({ workbookName: 'MyFile.xlsx', name: 'foo' }, '[MyFile.xlsx]!foo');
+    testRef({ workbookName: 'My File.xlsx', name: 'foo' }, "'[My File.xlsx]'!foo");
+  });
+
+  test('ignores context in XLSX mode', () => {
+    testRef({ context: [ 'MyFile.xlsx', 'Sheet1' ], range: rangeA1 }, 'R[2]C[4]');
+    testRef({ context: [ 'MyFile.xlsx', 'Sheet1' ], name: 'foo' }, 'foo');
+  });
+});

package/lib/stringifyR1C1Ref.ts

@@ -0,0 +1,67 @@
+/*
+** RC notation works differently from A1 in that we can't merge static
+** references joined by `:`. Merging can only work between references
+** that are relative/absolute on the same axes, so:
+** - R1C1:R2C2 will work,
+** - R[1]C1:R[2]C2 will also work, but
+** - R[1]C[1]:R2C2 doesn't have a direct rectangle represention without context.
+*/
+import type { ReferenceName, ReferenceNameXlsx, ReferenceR1C1, ReferenceR1C1Xlsx } from './types.ts';
+import { stringifyPrefix, stringifyPrefixXlsx } from './stringifyPrefix.ts';
+import { stringifyR1C1Range } from './stringifyR1C1Range.ts';
+
+/**
+ * Get an R1C1-style string representation of a reference object.
+ *
+ * ```js
+ * stringifyR1C1Ref({
+ *   context: [ 'Sheet1' ],
+ *   range: {
+ *     r0: 9,
+ *     c0: 8,
+ *     r1: 9,
+ *     c1: 8,
+ *     $c0: true,
+ *     $c1: true
+ *     $r0: false,
+ *     $r1: false
+ *   }
+ * });
+ * // => 'Sheet1!R[9]C9:R[9]C9'
+ * ```
+ *
+ * @param refObject A reference object.
+ * @returns The reference in R1C1-style string format.
+ */
+export function stringifyR1C1Ref (refObject: ReferenceR1C1 | ReferenceName): string {
+  const prefix = stringifyPrefix(refObject);
+  return prefix + ('name' in refObject ? refObject.name : stringifyR1C1Range(refObject.range));
+}
+
+/**
+ * Get an R1C1-style string representation of a reference object.
+ *
+ * ```js
+ * stringifyR1C1Ref({
+ *   sheetName: 'Sheet1',
+ *   range: {
+ *     r0: 9,
+ *     c0: 8,
+ *     r1: 9,
+ *     c1: 8,
+ *     $c0: true,
+ *     $c1: true
+ *     $r0: false,
+ *     $r1: false
+ *   }
+ * });
+ * // => 'Sheet1!R[9]C9:R[9]C9'
+ * ```
+ *
+ * @param refObject A reference object.
+ * @returns The reference in R1C1-style string format.
+ */
+export function stringifyR1C1RefXlsx (refObject: ReferenceR1C1Xlsx | ReferenceNameXlsx): string {
+  const prefix = stringifyPrefixXlsx(refObject);
+  return prefix + ('name' in refObject ? refObject.name : stringifyR1C1Range(refObject.range));
+}

package/lib/stringifyStructRef.spec.ts

@@ -0,0 +1,124 @@
+import { describe, test, expect } from 'vitest';
+import { stringifyStructRef, stringifyStructRefXlsx } from './stringifyStructRef.ts';
+
+describe('serialize structured references', () => {
+  test('simple column references', () => {
+    expect(stringifyStructRef({
+      columns: [ 'foo' ]
+    })).toBe('[foo]');
+
+    expect(stringifyStructRef({
+      columns: [ 'foo' ],
+      table: 'tableName'
+    })).toBe('tableName[foo]');
+
+    expect(stringifyStructRef({
+      columns: [ 'lorem ipsum' ],
+      table: 'tableName'
+    })).toBe('tableName[lorem ipsum]');
+  });
+
+  test('column range references', () => {
+    expect(stringifyStructRef({
+      columns: [ 'foo', 'sævör' ],
+      table: 'tableName'
+    })).toBe('tableName[[foo]:[sævör]]');
+
+    expect(stringifyStructRef({
+      columns: [ 'lorem ipsum', 'sævör' ],
+      table: 'tableName'
+    })).toBe('tableName[[lorem ipsum]:[sævör]]');
+  });
+
+  test('section references', () => {
+    expect(stringifyStructRef({
+      sections: [ 'data' ],
+      table: 'tableName'
+    })).toBe('tableName[#Data]');
+
+    expect(stringifyStructRef({
+      sections: [ 'data', 'headers' ],
+      table: 'table'
+    })).toBe('table[[#Data],[#Headers]]');
+  });
+
+  test('complex references with context', () => {
+    expect(stringifyStructRef({
+      columns: [ 'my column', 'fo@o' ],
+      sections: [ 'data' ],
+      table: 'tableName',
+      context: [ 'workbook.xlsx' ]
+    })).toBe('workbook.xlsx!tableName[[#Data],[my column]:[fo\'@o]]');
+  });
+
+  test('this row references', () => {
+    expect(stringifyStructRef({
+      columns: [ 'bar' ],
+      sections: [ 'this row' ],
+      table: 'foo'
+    })).toBe('foo[@bar]');
+
+    expect(stringifyStructRef({
+      columns: [ 'bar', 'baz' ],
+      sections: [ 'this row' ],
+      table: 'foo'
+    })).toBe('foo[@[bar]:[baz]]');
+
+    expect(stringifyStructRef({
+      columns: [ 'lorem ipsum', 'baz' ],
+      sections: [ 'this row' ],
+      table: 'foo'
+    })).toBe('foo[@[lorem ipsum]:[baz]]');
+  });
+});
+
+describe('structured references serialize in xlsx mode', () => {
+  test('context vs workbookName/sheetName handling', () => {
+    expect(stringifyStructRefXlsx({
+      // @ts-expect-error -- this is testing invalid input
+      context: [ 'Lorem', 'Ipsum' ],
+      columns: [ 'foo' ]
+    })).toBe('[foo]');
+
+    expect(stringifyStructRef({
+      // @ts-expect-error -- this is testing invalid input
+      workbookName: 'Lorem',
+      sheetName: 'Ipsum',
+      columns: [ 'foo' ]
+    })).toBe('[foo]');
+
+    expect(stringifyStructRefXlsx({
+      workbookName: 'Lorem',
+      sheetName: 'Ipsum',
+      columns: [ 'foo' ]
+    })).toBe('[Lorem]Ipsum![foo]');
+  });
+
+  test('workbook and sheet name handling', () => {
+    expect(stringifyStructRefXlsx({
+      workbookName: 'Lorem',
+      columns: [ 'foo' ]
+    })).toBe('[Lorem]![foo]');
+
+    expect(stringifyStructRefXlsx({
+      sheetName: 'Ipsum',
+      columns: [ 'foo' ]
+    })).toBe('Ipsum![foo]');
+  });
+});
+
+describe('longform serialize (in xlsx mode)', () => {
+  test('thisRow option affects output format', () => {
+    expect(stringifyStructRefXlsx({
+      table: 'Table2',
+      columns: [ 'col1' ],
+      sections: [ 'this row' ]
+    }, { thisRow: true })).toBe('Table2[[#This row],[col1]]');
+
+    expect(stringifyStructRef({
+      table: 'Table2',
+      columns: [ 'col1' ],
+      sections: [ 'this row' ]
+    }, { thisRow: true })).toBe('Table2[[#This row],[col1]]');
+  });
+});

package/lib/stringifyStructRef.ts

@@ -0,0 +1,113 @@
+import type { ReferenceStruct, ReferenceStructXlsx } from './types.ts';
+import { stringifyPrefix, stringifyPrefixXlsx } from './stringifyPrefix.ts';
+
+function quoteColname (str: string): string {
+  return str.replace(/([[\]#'@])/g, '\'$1');
+}
+
+function needsBraces (str: string): boolean {
+  return /[^a-zA-Z0-9\u00a1-\uffff]/.test(str);
+}
+
+function toSentenceCase (str: string): string {
+  return str[0].toUpperCase() + str.slice(1).toLowerCase();
+}
+
+export function stringifySRef (refObject: ReferenceStruct, thisRow = false) {
+  let s = '';
+  if (refObject.table) {
+    s += refObject.table;
+  }
+  const numColumns = refObject.columns?.length ?? 0;
+  const numSections = refObject.sections?.length ?? 0;
+  // single section
+  if (numSections === 1 && !numColumns) {
+    s += `[#${toSentenceCase(refObject.sections[0])}]`;
+  }
+  // single column
+  else if (!numSections && numColumns === 1) {
+    s += `[${quoteColname(refObject.columns[0])}]`;
+  }
+  else {
+    s += '[';
+    // single [#this row] sections get normalized to an @ by default
+    const singleAt = !thisRow && numSections === 1 && refObject.sections[0].toLowerCase() === 'this row';
+    if (singleAt) {
+      s += '@';
+    }
+    else if (numSections) {
+      s += refObject.sections
+        .map(d => `[#${toSentenceCase(d)}]`)
+        .join(',');
+      if (numColumns) {
+        s += ',';
+      }
+    }
+    // a case of a single alphanumberic column with a [#this row] becomes [@col]
+    if (singleAt && refObject.columns.length === 1 && !needsBraces(refObject.columns[0])) {
+      s += quoteColname(refObject.columns[0]);
+    }
+    else if (numColumns) {
+      s += refObject.columns.slice(0, 2)
+        .map(d => (`[${quoteColname(d)}]`))
+        .join(':');
+    }
+    s += ']';
+  }
+  return s;
+}
+
+/**
+ * Options for {@link stringifyStructRef}
+ */
+export type OptsStringifyStructRef = {
+  /**
+   * Enforces using the `[#This Row]` instead of the `@` shorthand when serializing structured ranges.
+   * @defaultValue false
+   */
+  thisRow?: boolean;
+};
+
+/**
+ * Returns a string representation of a structured reference object.
+ *
+ * ```js
+ * stringifyStructRef({
+ *   context: [ 'workbook.xlsx' ],
+ *   sections: [ 'data' ],
+ *   columns: [ 'my column', '@foo' ],
+ *   table: 'tableName',
+ * });
+ * // => 'workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]'
+ * ```
+ *
+ * @see {@link OptsStringifyStructRef}
+ * @param refObject A structured reference object.
+ * @param [options={}] Options.
+ * @returns The given structured reference in string format.
+ */
+export function stringifyStructRef (refObject: ReferenceStruct, options: OptsStringifyStructRef = {}): string {
+  return stringifyPrefix(refObject) + stringifySRef(refObject, !!options.thisRow);
+}
+
+/**
+ * Returns a string representation of a structured reference object.
+ *
+ * ```js
+ * stringifyStructRef({
+ *   workbookName: 'workbook.xlsx',
+ *   sheetName: '',
+ *   sections: [ 'data' ],
+ *   columns: [ 'my column', '@foo' ],
+ *   table: 'tableName',
+ * });
+ * // => 'workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]'
+ * ```
+ *
+ * @param refObject A structured reference object.
+ * @param [options] Options.
+ * @returns The given structured reference in string format.
+ */
+export function stringifyStructRefXlsx (refObject: ReferenceStructXlsx, options: OptsStringifyStructRef = {}): string {
+  return stringifyPrefixXlsx(refObject) + stringifySRef(refObject, !!options.thisRow);
+}

package/lib/stringifyTokens.ts

@@ -0,0 +1,15 @@
+import type { Token } from './types.ts';
+
+/**
+ * Collapses a list of tokens into a formula string.
+ *
+ * @param tokens A list of tokens.
+ * @returns A formula string.
+ */
+export function stringifyTokens (tokens: Token[]): string {
+  let s = '';
+  for (const token of tokens) {
+    s += token.value;
+  }
+  return s;
+}

package/lib/toCol.spec.ts

@@ -0,0 +1,11 @@
+import { describe, it, expect } from 'vitest';
+import { toCol } from './toCol.ts';
+
+describe('toCol', () => {
+  it('toCol converts integers to column ids', () => {
+    expect(toCol(0)).toBe('A');
+    expect(toCol(26)).toBe('AA');
+    expect(toCol(701)).toBe('ZZ');
+    expect(toCol(18277)).toBe('ZZZ');
+  });
+});

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

@@ -2,15 +2,15 @@ const charFrom = String.fromCharCode;
 
 /**
  * Convert a 0 based offset number to a column string
- * representation (`2` = `"C"`).
+ * representation (`0` = `"A"`, `2` = `"C"`).
  *
  * The method expects a number between 0 and 16383. Other input will
  * return garbage.
  *
- * @param {number} columnIndex Zero based column index number
- * @returns {string} The column string identifier
+ * @param columnIndex Zero based column index number
+ * @returns The column string identifier
  */
-export function toCol (columnIndex) {
+export function toCol (columnIndex: number): string {
   return (
     (columnIndex >= 702
       ? charFrom(((((columnIndex - 702) / 676) - 0) % 26) + 65)

package/lib/tokenTypes.ts

@@ -0,0 +1,76 @@
+import {
+  OPERATOR,
+  BOOLEAN,
+  ERROR,
+  NUMBER,
+  FUNCTION,
+  NEWLINE,
+  WHITESPACE,
+  STRING,
+  CONTEXT,
+  CONTEXT_QUOTE,
+  REF_RANGE,
+  REF_BEAM,
+  REF_TERNARY,
+  REF_NAMED,
+  REF_STRUCT,
+  FX_PREFIX,
+  UNKNOWN
+} from './constants.ts';
+
+/**
+ * A dictionary of the types used to identify token variants.
+ * @prop OPERATOR - Unary or binary operator (`+`, `%`)
+ * @prop BOOLEAN - Boolean literal (`TRUE`)
+ * @prop ERROR - Error literal (`#VALUE!`)
+ * @prop NUMBER - Number literal (`123.4`, `-1.5e+2`)
+ * @prop FUNCTION - Function name (`SUM`)
+ * @prop NEWLINE - Newline character (`\n`)
+ * @prop WHITESPACE - Whitespace character sequence (` `)
+ * @prop STRING - String literal (`"Lorem ipsum"`)
+ * @prop CONTEXT - Reference context ([Workbook.xlsx]Sheet1)
+ * @prop CONTEXT_QUOTE - Quoted reference context (`'[My workbook.xlsx]Sheet1'`)
+ * @prop REF_RANGE - A range identifier (`A1`)
+ * @prop REF_BEAM - A range "beam" identifier (`A:A` or `1:1`)
+ * @prop REF_TERNARY - A ternary range identifier (`B2:B`)
+ * @prop REF_NAMED - A name / named range identifier (`income`)
+ * @prop REF_STRUCT - A structured reference identifier (`table[[Column1]:[Column2]]`)
+ * @prop FX_PREFIX - A leading equals sign at the start of a formula (`=`)
+ * @prop UNKNOWN - Any unidentifiable range of characters.
+ */
+export const tokenTypes = Object.freeze({
+  /** Unary or binary operator (`+`, `%`) */
+  OPERATOR: OPERATOR,
+  /** Boolean literal (`TRUE`) */
+  BOOLEAN: BOOLEAN,
+  /** Error literal (`#VALUE!`) */
+  ERROR: ERROR,
+  /** Number literal (`123.4`, `-1.5e+2`) */
+  NUMBER: NUMBER,
+  /** Function name (`SUM`) */
+  FUNCTION: FUNCTION,
+  /** Newline character (`\n`) */
+  NEWLINE: NEWLINE,
+  /** Whitespace character sequence (` `) */
+  WHITESPACE: WHITESPACE,
+  /** String literal (`"Lorem ipsum"`) */
+  STRING: STRING,
+  /** Reference context ([Workbook.xlsx]Sheet1) */
+  CONTEXT: CONTEXT,
+  /** Quoted reference context (`'[My workbook.xlsx]Sheet1'`) */
+  CONTEXT_QUOTE: CONTEXT_QUOTE,
+  /** A range identifier (`A1`) */
+  REF_RANGE: REF_RANGE,
+  /** A range "beam" identifier (`A:A` or `1:1`) */
+  REF_BEAM: REF_BEAM,
+  /** A ternary range identifier (`B2:B`) */
+  REF_TERNARY: REF_TERNARY,
+  /** A name / named range identifier (`income`) */
+  REF_NAMED: REF_NAMED,
+  /** A structured reference identifier (`table[[Column1]:[Column2]]`) */
+  REF_STRUCT: REF_STRUCT,
+  /** A leading equals sign at the start of a formula (`=`) */
+  FX_PREFIX: FX_PREFIX,
+  /** Any unidentifiable range of characters. */
+  UNKNOWN: UNKNOWN
+});