@borgar/fx 4.12.0 → 5.0.0

package/lib/parseStructRef.spec.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect } from 'vitest';
+import { parseStructRef, parseStructRefXlsx } from './parseStructRef.ts';
+
+function isSREqual (expr: string, expected: any, opts?: any) {
+  if (expected) {
+    expected = opts?.xlsx
+      ? {
+        workbookName: '',
+        sheetName: '',
+        table: '',
+        columns: [],
+        sections: [],
+        ...expected
+      }
+      : {
+        context: [],
+        table: '',
+        columns: [],
+        sections: [],
+        ...expected
+      };
+  }
+  expect(opts?.xlsx ? parseStructRefXlsx(expr) : parseStructRef(expr)).toEqual(expected);
+}
+
+describe('parse structured references', () => {
+  test('basic table and column references', () => {
+    isSREqual('table[col]', {
+      table: 'table',
+      columns: [ 'col' ]
+    });
+
+    isSREqual('table[]', {
+      table: 'table'
+    });
+  });
+
+  test('section references', () => {
+    isSREqual('[#All]', {
+      sections: [ 'all' ]
+    });
+  });
+
+  test('column name references', () => {
+    isSREqual('[column name]', {
+      columns: [ 'column name' ]
+    });
+
+    isSREqual('[[my column]]', {
+      columns: [ 'my column' ]
+    });
+  });
+
+  test('invalid references', () => {
+    isSREqual('[column name]!foo', undefined);
+    isSREqual('[foo]bar', undefined);
+  });
+
+  test('column range references', () => {
+    isSREqual('[[my column]:otherColumn]', {
+      columns: [ 'my column', 'otherColumn' ]
+    });
+
+    isSREqual('[ [my column]:otherColumn ]', {
+      columns: [ 'my column', 'otherColumn ' ]
+    });
+
+    isSREqual('[ [my column]: otherColumn ]', {
+      columns: [ 'my column', ' otherColumn ' ]
+    });
+  });
+
+  test('this row references', () => {
+    isSREqual('[ @[ my column ]: otherColumn ]', {
+      columns: [ ' my column ', ' otherColumn ' ],
+      sections: [ 'this row' ]
+    });
+  });
+
+  test('section and column combinations', () => {
+    isSREqual('[[#Data], [my column]:otherColumn]', {
+      columns: [ 'my column', 'otherColumn' ],
+      sections: [ 'data' ]
+    });
+
+    isSREqual('[ [#Data], [my column]:[\'@foo] ]', {
+      columns: [ 'my column', '@foo' ],
+      sections: [ 'data' ]
+    });
+  });
+
+  test('context-qualified references', () => {
+    isSREqual('workbook.xlsx!tableName[ [#Data], [my column]:[\'@foo] ]', {
+      columns: [ 'my column', '@foo' ],
+      sections: [ 'data' ],
+      table: 'tableName',
+      context: [ 'workbook.xlsx' ]
+    });
+
+    isSREqual("'Sheet'!Table[Column]", {
+      columns: [ 'Column' ],
+      table: 'Table',
+      context: [ 'Sheet' ]
+    });
+
+    isSREqual("Sheet1!Table1[foo '[bar']]", {
+      columns: [ 'foo [bar]' ],
+      table: 'Table1',
+      context: [ 'Sheet1' ]
+    });
+
+    isSREqual('[myworkbook.xlsx]Sheet1!TMP8w0habhr[#All]', {
+      columns: [],
+      table: 'TMP8w0habhr',
+      context: [ 'myworkbook.xlsx', 'Sheet1' ],
+      sections: [ 'all' ]
+    });
+  });
+
+  test('duplicate section handling', () => {
+    isSREqual('[[#Data],[#data],[#Data],[#Data],[#Totals],[#Totals],[#Totals],foo]', {
+      columns: [ 'foo' ],
+      sections: [ 'data', 'totals' ]
+    });
+  });
+});
+
+describe('structured references parse in xlsx mode', () => {
+  test('workbook-only references', () => {
+    isSREqual('[Workbook.xlsx]!Table[#Data]', {
+      workbookName: 'Workbook.xlsx',
+      table: 'Table',
+      sections: [ 'data' ]
+    }, { xlsx: true });
+  });
+
+  test('workbook and sheet references', () => {
+    isSREqual('[Workbook.xlsx]Sheet1!Table[#Data]', {
+      workbookName: 'Workbook.xlsx',
+      sheetName: 'Sheet1',
+      table: 'Table',
+      sections: [ 'data' ]
+    }, { xlsx: true });
+  });
+
+  test('sheet-only references', () => {
+    isSREqual('Sheet1!Table[#Data]', {
+      sheetName: 'Sheet1',
+      table: 'Table',
+      sections: [ 'data' ]
+    }, { xlsx: true });
+  });
+});
+
+describe('longform parse (in xlsx mode)', () => {
+  test('thisRow option should have no effect when parsing', () => {
+    const expectedResult = {
+      table: 'Table2',
+      columns: [ 'col1' ],
+      sections: [ 'this row' ]
+    };
+
+    isSREqual('Table2[[#This Row],[col1]]', expectedResult, { xlsx: true, thisRow: true });
+    isSREqual('Table2[[#This Row],[col1]]', expectedResult, { xlsx: true, thisRow: false });
+    isSREqual('Table2[[#This Row],[col1]]', expectedResult, { xlsx: false, thisRow: true });
+    isSREqual('Table2[[#This Row],[col1]]', expectedResult, { xlsx: false, thisRow: false });
+  });
+});

package/lib/parseStructRef.ts

@@ -0,0 +1,76 @@
+import type { ReferenceStruct, ReferenceStructXlsx } from './types.ts';
+import { parseRefCtx, parseRefXlsx } from './parseRef.ts';
+import { parseSRange } from './parseSRange.ts';
+
+/**
+ * Parse a structured reference string into an object representing it.
+ *
+ * ```js
+ * parseStructRef('workbook.xlsx!tableName[[#Data],[Column1]:[Column2]]');
+ * // => {
+ * //   context: [ 'workbook.xlsx' ],
+ * //   sections: [ 'data' ],
+ * //   columns: [ 'my column', '@foo' ],
+ * //   table: 'tableName',
+ * // }
+ * ```
+ *
+ * For A:A or A1:A style ranges, `null` will be used for any dimensions that the
+ * syntax does not specify:
+ *
+ * See [References.md](./References.md).
+ *
+ * @param ref A structured reference string
+ * @returns An object representing a valid reference or `undefined` if it is invalid.
+ */
+export function parseStructRef (ref: string): ReferenceStruct | undefined {
+  const r = parseRefCtx(ref);
+  if (r && r.struct) {
+    const structData = parseSRange(r.struct);
+    if (structData && structData.length === r.struct.length) {
+      return {
+        context: r.context,
+        table: r.name,
+        columns: structData.columns,
+        sections: structData.sections
+      };
+    }
+  }
+}
+
+/**
+ * Parse a structured reference string into an object representing it.
+ *
+ * ```js
+ * parseStructRef('[workbook.xlsx]!tableName[[#Data],[Column1]:[Column2]]');
+ * // => {
+ * //   workbookName: 'workbook.xlsx',
+ * //   sections: [ 'data' ],
+ * //   columns: [ 'my column', '@foo' ],
+ * //   table: 'tableName',
+ * // }
+ * ```
+ *
+ * For A:A or A1:A style ranges, `null` will be used for any dimensions that the
+ * syntax does not specify:
+ *
+ * See [References.md](./References.md).
+ *
+ * @param ref A structured reference string
+ * @returns An object representing a valid reference or null if it is invalid.
+ */
+export function parseStructRefXlsx (ref: string): ReferenceStructXlsx | undefined {
+  const r = parseRefXlsx(ref);
+  if (r && r.struct) {
+    const structData = parseSRange(r.struct);
+    if (structData && structData.length === r.struct.length) {
+      return {
+        workbookName: r.workbookName,
+        sheetName: r.sheetName,
+        table: r.name,
+        columns: structData.columns,
+        sections: structData.sections
+      };
+    }
+  }
+}

package/lib/stringifyA1Range.spec.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect } from 'vitest';
+import { stringifyA1Range } from './stringifyA1Range.ts';
+import { MAX_COLS, MAX_ROWS } from './constants.ts';
+
+describe('stringifyA1Range', () => {
+  test('cell references: A1', () => {
+    expect(stringifyA1Range({ top: 9, bottom: 9, left: 2, right: 2 })).toBe('C10');
+    expect(stringifyA1Range({ top: 9, bottom: 9, left: 2, right: 2, $top: true, $bottom: true })).toBe('C$10');
+    expect(stringifyA1Range({ top: 9, bottom: 9, left: 2, right: 2, $left: true, $right: true })).toBe('$C10');
+    expect(stringifyA1Range({ top: 9, bottom: 9, left: 2, right: 2, $top: true, $bottom: true, $left: true, $right: true })).toBe('$C$10');
+  });
+
+  test('rectangle references: A1:B2', () => {
+    expect(stringifyA1Range({ top: 2, bottom: 2, left: 4, right: 4 })).toBe('E3');
+    expect(stringifyA1Range({ top: 2, bottom: 2, left: 4, right: 4, $right: true })).toBe('E3:$E3');
+    expect(stringifyA1Range({ top: 2, bottom: 2, left: 4, right: 4, $top: true })).toBe('E$3:E3');
+    expect(stringifyA1Range({ top: 2, bottom: 2, left: 4, right: 4, $left: true })).toBe('$E3:E3');
+    expect(stringifyA1Range({ top: 2, bottom: 2, left: 4, right: 4, $bottom: true })).toBe('E3:E$3');
+    expect(stringifyA1Range({ top: 2, bottom: 2, left: 4, right: 4, $bottom: true, $right: true })).toBe('E3:$E$3');
+    expect(stringifyA1Range({ top: 2, bottom: 2, left: 4, right: 5 })).toBe('E3:F3');
+    expect(stringifyA1Range({ top: 2, bottom: 3, left: 4, right: 4 })).toBe('E3:E4');
+    expect(stringifyA1Range({ top: 2, bottom: 3, left: 4, right: 5 })).toBe('E3:F4');
+  });
+
+  test('beam references: A:A 1:1', () => {
+    expect(stringifyA1Range({ left: 0, right: 0 })).toBe('A:A');
+    expect(stringifyA1Range({ top: 0, bottom: MAX_ROWS, left: 0, right: 0 })).toBe('A:A');
+    expect(stringifyA1Range({ left: 10, right: 15 })).toBe('K:P');
+    expect(stringifyA1Range({ left: 10, right: 15, $left: true })).toBe('$K:P');
+    expect(stringifyA1Range({ left: 10, right: 15, $right: true })).toBe('K:$P');
+    expect(stringifyA1Range({ left: 10, right: 15, $left: true, $right: true })).toBe('$K:$P');
+    expect(stringifyA1Range({ top: 0, bottom: 0 })).toBe('1:1');
+    expect(stringifyA1Range({ top: 0, bottom: 0, left: 0, right: MAX_COLS })).toBe('1:1');
+    expect(stringifyA1Range({ top: 10, bottom: 15 })).toBe('11:16');
+    expect(stringifyA1Range({ top: 10, bottom: 15, $top: true })).toBe('$11:16');
+    expect(stringifyA1Range({ top: 10, bottom: 15, $bottom: true })).toBe('11:$16');
+    expect(stringifyA1Range({ top: 10, bottom: 15, $top: true, $bottom: true })).toBe('$11:$16');
+  });
+
+  test('partial references: B1:C B2:3', () => {
+    expect(stringifyA1Range({ top: 9, left: 0, right: 0 })).toBe('A10:A');
+    expect(stringifyA1Range({ bottom: 9, left: 0, right: 0 })).toBe('A10:A');
+    expect(stringifyA1Range({ top: 9, left: 0, right: 0, $top: true })).toBe('A$10:A');
+    expect(stringifyA1Range({ top: 9, left: 0, right: 0, $left: true })).toBe('$A10:A');
+    expect(stringifyA1Range({ top: 9, left: 0, right: 0, $right: true })).toBe('A10:$A');
+    expect(stringifyA1Range({ top: 0, left: 3, bottom: 0 })).toBe('D1:1');
+    expect(stringifyA1Range({ top: 0, right: 3, bottom: 0 })).toBe('D1:1');
+    expect(stringifyA1Range({ top: 0, left: 3, bottom: 0, $top: true })).toBe('D$1:1');
+    expect(stringifyA1Range({ top: 0, left: 3, bottom: 0, $left: true })).toBe('$D1:1');
+    expect(stringifyA1Range({ top: 0, left: 3, bottom: 0, $left: true })).toBe('$D1:1');
+  });
+
+  test('edge cases', () => {
+    // allow skipping right/bottom for cells
+    expect(stringifyA1Range({ top: 0, left: 0 })).toBe('A1');
+    // clamp the range at min/max dimensions
+    expect(stringifyA1Range({ top: -10, bottom: -5, left: -10, right: -5 })).toBe('A1');
+    expect(stringifyA1Range({ top: 15e5, bottom: 15e5, left: 20000, right: 20000 })).toBe('XFD1048576');
+    expect(stringifyA1Range({ top: 2, bottom: 2, left: 2.5, right: 2.5 })).toBe('C3');
+    expect(stringifyA1Range({ top: 1.5, bottom: 2.5, left: 4.5, right: 8.5 })).toBe('E2:I3');
+  });
+
+  test('trimming', () => {
+    expect(stringifyA1Range({ top: 2, bottom: 2, left: 4, right: 4, trim: 'both' })).toBe('E3');
+    expect(stringifyA1Range({ top: 2, bottom: 3, left: 4, right: 6, trim: 'both' })).toBe('E3.:.G4');
+    expect(stringifyA1Range({ top: 2, bottom: 3, trim: 'both' })).toBe('3.:.4');
+    expect(stringifyA1Range({ left: 4, right: 6, trim: 'both' })).toBe('E.:.G');
+    expect(stringifyA1Range({ top: 9, left: 0, right: 0, trim: 'tail' })).toBe('A10:.A');
+    expect(stringifyA1Range({ top: 9, left: 0, right: 0, trim: 'head' })).toBe('A10.:A');
+    expect(stringifyA1Range({ top: 9, left: 0, right: 0, trim: 'both' })).toBe('A10.:.A');
+  });
+});

package/lib/stringifyA1Range.ts

@@ -0,0 +1,72 @@
+import { MAX_ROWS, MAX_COLS } from './constants.ts';
+import { toCol } from './toCol.ts';
+import type { RangeA1 } from './types.ts';
+import { rangeOperator } from './a1.ts';
+
+const clamp = (min: number, val: number, max: number) => Math.min(Math.max(val, min), max);
+const toColStr = (c: number, a: boolean) => (a ? '$' : '') + toCol(c);
+const toRowStr = (r: number, a: boolean) => (a ? '$' : '') + toRow(r);
+const toRow = (top: number): string => String(top + 1);
+
+/**
+ * Stringify a range object into A1 syntax.
+ * @param range A range object
+ * @returns An A1-style string represenation of a range
+ * @internal
+ */
+export function stringifyA1Range (range: Partial<RangeA1>): string {
+  // eslint-disable-next-line prefer-const
+  let { top, left, bottom, right, trim } = 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);
+  }
+  const op = rangeOperator(trim);
+  // A:A
+  const allRows = top === 0 && bottom >= MAX_ROWS;
+  const haveAbsCol = ($left && !noLeft) || ($right && !noRight);
+  if ((allRows && !noLeft && !noRight && (!haveAbsCol || left === right)) || (noTop && noBottom)) {
+    return toColStr(left, $left) + op + toColStr(right, $right);
+  }
+  // 1:1
+  const allCols = left === 0 && right >= MAX_COLS;
+  const haveAbsRow = ($top && !noTop) || ($bottom && !noBottom);
+  if ((allCols && !noTop && !noBottom && (!haveAbsRow || top === bottom)) || (noLeft && noRight)) {
+    return toRowStr(top, $top) + op + toRowStr(bottom, $bottom);
+  }
+  // A1:1
+  if (!noLeft && !noTop && !noRight && noBottom) {
+    return toColStr(left, $left) + toRowStr(top, $top) + op + toColStr(right, $right);
+  }
+  // A:A1 => A1:1
+  if (!noLeft && noTop && !noRight && !noBottom) {
+    return toColStr(left, $left) + toRowStr(bottom, $bottom) + op + toColStr(right, $right);
+  }
+  // A1:A
+  if (!noLeft && !noTop && noRight && !noBottom) {
+    return toColStr(left, $left) + toRowStr(top, $top) + op + toRowStr(bottom, $bottom);
+  }
+  // A:A1 => A1:A
+  if (noLeft && !noTop && !noRight && !noBottom) {
+    return toColStr(right, $right) + toRowStr(top, $top) + op + toRowStr(bottom, $bottom);
+  }
+  // A1:A1
+  if (right !== left || bottom !== top || $right !== $left || $bottom !== $top) {
+    return toColStr(left, $left) + toRowStr(top, $top) + op +
+           toColStr(right, $right) + toRowStr(bottom, $bottom);
+  }
+  // A1
+  return toColStr(left, $left) + toRowStr(top, $top);
+}

package/lib/stringifyA1Ref.spec.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect } from 'vitest';
+import { stringifyA1Ref, stringifyA1RefXlsx } from './stringifyA1Ref.ts';
+
+describe('stringifyA1Ref', () => {
+  const rangeA1 = { top: 0, bottom: 0, left: 0, right: 0 };
+
+  test('basic stringification', () => {
+    expect(stringifyA1Ref({ range: rangeA1 })).toBe('A1');
+    expect(stringifyA1Ref({ context: [ 'Sheet1' ], range: rangeA1 })).toBe('Sheet1!A1');
+    expect(stringifyA1Ref({ context: [ 'Sheet 1' ], range: rangeA1 })).toBe("'Sheet 1'!A1");
+    expect(stringifyA1Ref({ context: [ 'MyFile.xlsx', 'Sheet1' ], range: rangeA1 })).toBe('[MyFile.xlsx]Sheet1!A1');
+    expect(stringifyA1Ref({ context: [ 'My File.xlsx', 'Sheet1' ], range: rangeA1 })).toBe("'[My File.xlsx]Sheet1'!A1");
+    expect(stringifyA1Ref({ context: [ 'MyFile.xlsx' ], range: rangeA1 })).toBe('MyFile.xlsx!A1');
+    expect(stringifyA1Ref({ context: [ 'My File.xlsx' ], range: rangeA1 })).toBe("'My File.xlsx'!A1");
+  });
+
+  test('named ranges', () => {
+    expect(stringifyA1Ref({ name: 'foo' })).toBe('foo');
+    expect(stringifyA1Ref({ context: [ 'Sheet1' ], name: 'foo' })).toBe('Sheet1!foo');
+    expect(stringifyA1Ref({ context: [ 'Sheet 1' ], name: 'foo' })).toBe("'Sheet 1'!foo");
+    expect(stringifyA1Ref({ context: [ 'MyFile.xlsx', 'Sheet1' ], name: 'foo' })).toBe('[MyFile.xlsx]Sheet1!foo');
+    expect(stringifyA1Ref({ context: [ 'My File.xlsx', 'Sheet1' ], name: 'foo' })).toBe("'[My File.xlsx]Sheet1'!foo");
+    expect(stringifyA1Ref({ context: [ 'MyFile.xlsx' ], name: 'foo' })).toBe('MyFile.xlsx!foo');
+    expect(stringifyA1Ref({ context: [ 'My File.xlsx' ], name: 'foo' })).toBe("'My File.xlsx'!foo");
+  });
+
+  test('ignore workbookName/sheetName in non-XLSX mode', () => {
+    // @ts-expect-error -- testing invalid input
+    expect(stringifyA1Ref({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', range: rangeA1 })).toBe('A1');
+    // @ts-expect-error -- testing invalid input
+    expect(stringifyA1Ref({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', name: 'foo' })).toBe('foo');
+  });
+});
+
+describe('stringifyA1Ref in XLSX mode', () => {
+  const rangeA1 = { top: 0, bottom: 0, left: 0, right: 0 };
+
+  test('basic stringification', () => {
+    expect(stringifyA1RefXlsx({ range: rangeA1 })).toBe('A1');
+    expect(stringifyA1RefXlsx({ sheetName: 'Sheet1', range: rangeA1 })).toBe('Sheet1!A1');
+    expect(stringifyA1RefXlsx({ sheetName: 'Sheet 1', range: rangeA1 })).toBe("'Sheet 1'!A1");
+    expect(stringifyA1RefXlsx({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', range: rangeA1 })).toBe('[MyFile.xlsx]Sheet1!A1');
+    expect(stringifyA1RefXlsx({ workbookName: 'My File.xlsx', sheetName: 'Sheet1', range: rangeA1 })).toBe("'[My File.xlsx]Sheet1'!A1");
+    expect(stringifyA1RefXlsx({ workbookName: 'MyFile.xlsx', range: rangeA1 })).toBe('[MyFile.xlsx]!A1');
+    expect(stringifyA1RefXlsx({ workbookName: 'My File.xlsx', range: rangeA1 })).toBe("'[My File.xlsx]'!A1");
+  });
+
+  test('named ranges', () => {
+    expect(stringifyA1RefXlsx({ name: 'foo' })).toBe('foo');
+    expect(stringifyA1RefXlsx({ sheetName: 'Sheet1', name: 'foo' })).toBe('Sheet1!foo');
+    expect(stringifyA1RefXlsx({ sheetName: 'Sheet 1', name: 'foo' })).toBe("'Sheet 1'!foo");
+    expect(stringifyA1RefXlsx({ workbookName: 'MyFile.xlsx', sheetName: 'Sheet1', name: 'foo' })).toBe('[MyFile.xlsx]Sheet1!foo');
+    expect(stringifyA1RefXlsx({ workbookName: 'My File.xlsx', sheetName: 'Sheet1', name: 'foo' })).toBe("'[My File.xlsx]Sheet1'!foo");
+    expect(stringifyA1RefXlsx({ workbookName: 'MyFile.xlsx', name: 'foo' })).toBe('[MyFile.xlsx]!foo');
+    expect(stringifyA1RefXlsx({ workbookName: 'My File.xlsx', name: 'foo' })).toBe("'[My File.xlsx]'!foo");
+  });
+
+  test('ignore context in XLSX mode', () => {
+    // @ts-expect-error -- testing invalid input
+    expect(stringifyA1RefXlsx({ context: [ 'MyFile.xlsx', 'Sheet1' ], range: rangeA1 })).toBe('A1');
+    // @ts-expect-error -- testing invalid input
+    expect(stringifyA1RefXlsx({ context: [ 'MyFile.xlsx', 'Sheet1' ], name: 'foo' })).toBe('foo');
+  });
+});

package/lib/stringifyA1Ref.ts

@@ -0,0 +1,59 @@
+import { stringifyPrefix, stringifyPrefixXlsx } from './stringifyPrefix.ts';
+import type { ReferenceA1, ReferenceA1Xlsx, ReferenceName, ReferenceNameXlsx } from './types.ts';
+import { stringifyA1Range } from './stringifyA1Range.ts';
+
+/**
+ * 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 refObject A reference object.
+ * @returns The reference in A1-style string format.
+ */
+export function stringifyA1Ref (refObject: ReferenceA1 | ReferenceName): string {
+  const prefix = stringifyPrefix(refObject);
+  return prefix + ('name' in refObject ? refObject.name : stringifyA1Range(refObject.range));
+}
+
+/**
+ * Get an A1-style string representation of a reference object.
+ *
+ * ```js
+ * stringifyA1Ref({
+ *   sheetName: 'Sheet1',
+ *   range: {
+ *     top: 0,
+ *     left: 0,
+ *     bottom: 1,
+ *     right: 1,
+ *     $top: true,
+ *     $left: false,
+ *     $bottom: false,
+ *     $right: true
+ *   }
+ * });
+ * // => 'Sheet1!A$1:$B2'
+ * ```
+ *
+ * @param refObject A reference object.
+ * @returns The reference in A1-style string format.
+ */
+export function stringifyA1RefXlsx (refObject: ReferenceA1Xlsx | ReferenceNameXlsx): string {
+  const prefix = stringifyPrefixXlsx(refObject);
+  return prefix + ('name' in refObject ? refObject.name : stringifyA1Range(refObject.range));
+}

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

@@ -1,6 +1,19 @@
+import type {
+  ReferenceA1,
+  ReferenceStruct,
+  ReferenceR1C1,
+  ReferenceA1Xlsx,
+  ReferenceStructXlsx,
+  ReferenceR1C1Xlsx,
+  ReferenceName,
+  ReferenceNameXlsx
+} from './types.ts';
+
 const reBannedChars = /[^0-9A-Za-z._¡¤§¨ª\u00ad¯-\uffff]/;
 
-export function stringifyPrefix (ref) {
+export function stringifyPrefix (
+  ref: ReferenceA1 | ReferenceName | ReferenceStruct | ReferenceR1C1
+): string {
   let pre = '';
   let quote = 0;
   let nth = 0;
@@ -20,7 +33,9 @@ export function stringifyPrefix (ref) {
   return pre ? pre + '!' : pre;
 }
 
-export function stringifyPrefixAlt (ref) {
+export function stringifyPrefixXlsx (
+  ref: ReferenceA1Xlsx | ReferenceNameXlsx | ReferenceStructXlsx | ReferenceR1C1Xlsx
+): string {
   let pre = '';
   let quote = 0;
   const { workbookName, sheetName } = ref;

package/lib/stringifyR1C1Range.spec.ts

@@ -0,0 +1,92 @@
+import { describe, test, expect } from 'vitest';
+import { MAX_COLS, MAX_ROWS } from './constants.ts';
+import { stringifyR1C1Range } from './stringifyR1C1Range.ts';
+
+function isR1C1Rendered (range: any, expected: string) {
+  expect(stringifyR1C1Range(range)).toBe(expected);
+}
+
+describe('R1C1 serialization', () => {
+  test('ray serialization', () => {
+    isR1C1Rendered({ r0: 0, c0: 0, r1: 0, c1: MAX_COLS }, 'R');
+    isR1C1Rendered({ r0: 0, r1: 0 }, 'R');
+    isR1C1Rendered({ r0: 0, c0: 0, r1: 0, c1: MAX_COLS, $r0: true, $r1: true }, 'R1');
+    isR1C1Rendered({ r0: 0, r1: 0, $r0: true, $r1: true }, 'R1');
+    isR1C1Rendered({ r0: 1, c0: 0, r1: 1, c1: MAX_COLS }, 'R[1]');
+    isR1C1Rendered({ r0: 1, r1: 1 }, 'R[1]');
+
+    isR1C1Rendered({ r0: 0, c0: 0, r1: MAX_ROWS, c1: 0 }, 'C');
+    isR1C1Rendered({ c0: 0, c1: 0 }, 'C');
+    isR1C1Rendered({ r0: 0, c0: 0, r1: MAX_ROWS, c1: 0, $c0: true, $c1: true }, 'C1');
+    isR1C1Rendered({ c0: 0, c1: 0, $c0: true, $c1: true }, 'C1');
+    isR1C1Rendered({ r0: 0, c0: 1, r1: MAX_ROWS, c1: 1 }, 'C[1]');
+    isR1C1Rendered({ c0: 1, c1: 1 }, 'C[1]');
+  });
+
+  test('rectangle serialization', () => {
+    isR1C1Rendered({ r0: 0, c0: 0, r1: 0, c1: 0 }, 'RC');
+    isR1C1Rendered({ r0: 0, c0: 0, r1: 0, c1: 0, $c0: true, $c1: true, $r0: true, $r1: true }, 'R1C1');
+    isR1C1Rendered({ r0: 9, c0: 7, r1: 9, c1: 7, $c0: true, $c1: true, $r0: true, $r1: true }, 'R10C8');
+    isR1C1Rendered({ r0: 2, c0: 0, r1: 2, c1: 0 }, 'R[2]C');
+    isR1C1Rendered({ r0: -2, c0: 0, r1: -2, c1: 0 }, 'R[-2]C');
+    isR1C1Rendered({ r0: 0, c0: 3, r1: 0, c1: 3 }, 'RC[3]');
+    isR1C1Rendered({ r0: 0, c0: -3, r1: 0, c1: -3 }, 'RC[-3]');
+    isR1C1Rendered({ r0: 2, c0: 4, r1: 2, c1: 4 }, 'R[2]C[4]');
+    isR1C1Rendered({ r0: -2, c0: -4, r1: -2, c1: -4 }, 'R[-2]C[-4]');
+    isR1C1Rendered({ r0: 9, c0: 8, r1: 9, c1: 8, $c0: true, $c1: true }, 'R[9]C9');
+    isR1C1Rendered({ r0: 8, c0: 9, r1: 8, c1: 9, $r0: true, $r1: true }, 'R9C[9]');
+  });
+
+  test('range serialization', () => {
+    isR1C1Rendered({ r0: 1, c0: 1, r1: 0, c1: 0, $c1: true, $r1: true }, 'R[1]C[1]:R1C1');
+    isR1C1Rendered({ r0: 0, c0: 0, r1: 1, c1: 1, $c0: true, $c1: true, $r0: true, $r1: true }, 'R1C1:R2C2');
+    isR1C1Rendered({ c0: 0, c1: 2, $c0: true, $c1: true }, 'C1:C3');
+    isR1C1Rendered({ r0: 1, r1: 2, $r1: true }, 'R[1]:R3');
+    isR1C1Rendered({ r0: 1, c0: 0, r1: 0, c1: -1, $c0: true, $r1: true }, 'R[1]C1:R1C[-1]');
+  });
+
+  test('partial serialization', () => {
+    isR1C1Rendered({ r0: -5, c0: -2, c1: -2 }, 'R[-5]C[-2]:C[-2]');
+    isR1C1Rendered({ r0: -5, c0: -3, r1: -5 }, 'R[-5]C[-3]:R[-5]');
+    isR1C1Rendered({ r0: -6, c0: 0, c1: 0, $c0: true, $c1: true }, 'R[-6]C1:C1');
+    isR1C1Rendered({ r0: -6, c0: 0, r1: -6, $c0: true, $c1: true }, 'R[-6]C1:R[-6]');
+    isR1C1Rendered({ r0: 0, c0: -2, c1: -2, $r0: true, $r1: true }, 'R1C[-2]:C[-2]');
+    isR1C1Rendered({ r0: 0, c0: -3, r1: 0, $r0: true, $r1: true }, 'R1C[-3]:R1');
+    isR1C1Rendered({ r0: 0, c0: 0, c1: 0, $r0: true, $c0: true, $r1: true, $c1: true }, 'R1C1:C1');
+    isR1C1Rendered({ r0: 0, c0: 0, r1: 0, $r0: true, $c0: true, $r1: true, $c1: true }, 'R1C1:R1');
+    isR1C1Rendered({ r0: -5, c0: 10, r1: 4 }, 'R[-5]C[10]:R[4]');
+    isR1C1Rendered({ r0: -6, c0: 15, r1: 3, $c0: true, $c1: true }, 'R[-6]C16:R[3]');
+    isR1C1Rendered({ r0: 0, c0: 10, r1: 9, $r0: true, $r1: true }, 'R1C[10]:R10');
+    isR1C1Rendered({ r0: 0, c0: 15, r1: 9, $r0: true, $c0: true, $r1: true, $c1: true }, 'R1C16:R10');
+  });
+
+  test('edge cases', () => {
+    // allow skipping right/bottom for cells
+    isR1C1Rendered({ r0: -5, c0: -2 }, 'R[-5]C[-2]');
+
+    // clamp the range at min/max dimensions
+    const abs = { $r0: true, $c0: true, $r1: true, $c1: true };
+    isR1C1Rendered({ r0: 1, c0: -20000, r1: 1, c1: 20000, ...abs }, 'R2');
+    isR1C1Rendered({ r0: -15e5, c0: 1, r1: 15e5, c1: 1, ...abs }, 'C2');
+    isR1C1Rendered({ r0: -5, c0: -2, r1: -8, c1: -7, ...abs }, 'R1C1');
+    isR1C1Rendered({ r0: 0, c0: -20000, r1: 0, c1: 20000 }, 'RC[-16383]:RC[16383]');
+    isR1C1Rendered({ r0: -15e5, c0: 0, r1: 15e5, c1: 0 }, 'R[-1048575]C:R[1048575]C');
+    isR1C1Rendered({ r0: 0.5, c0: 0.5, r1: 0.5, c1: 0.5, ...abs }, 'R1C1');
+    isR1C1Rendered({ r0: 0.5, c0: 0.5, r1: 0.5, c1: 0.5 }, 'RC');
+  });
+
+  test('trimming', () => {
+    isR1C1Rendered({ r0: 1, c0: 1, r1: 2, c1: 2 }, 'R[1]C[1]:R[2]C[2]');
+    isR1C1Rendered({ r0: 1, c0: 1, r1: 2, c1: 2, trim: 'head' }, 'R[1]C[1].:R[2]C[2]');
+    isR1C1Rendered({ r0: 1, c0: 1, r1: 2, c1: 2, trim: 'tail' }, 'R[1]C[1]:.R[2]C[2]');
+    isR1C1Rendered({ r0: 1, c0: 1, r1: 2, c1: 2, trim: 'both' }, 'R[1]C[1].:.R[2]C[2]');
+    isR1C1Rendered({ r0: 1, c0: 1, r1: 1, c1: 1, trim: 'both' }, 'R[1]C[1]');
+    isR1C1Rendered({ r0: 1, r1: 1 }, 'R[1]');
+    isR1C1Rendered({ r0: 1, r1: 1, trim: 'head' }, 'R[1].:R[1]');
+    isR1C1Rendered({ r0: 1, r1: 1, trim: 'both' }, 'R[1].:.R[1]');
+    isR1C1Rendered({ c0: 1, c1: 1 }, 'C[1]');
+    isR1C1Rendered({ c0: 1, c1: 1, trim: 'tail' }, 'C[1]:.C[1]');
+    isR1C1Rendered({ c0: 1, c1: 1, trim: 'both' }, 'C[1].:.C[1]');
+    isR1C1Rendered({ r0: -5, c0: -2, c1: -2, trim: 'both' }, 'R[-5]C[-2].:.C[-2]');
+  });
+});