@borgar/fx 4.13.0 → 5.0.0

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
+});