@borgar/fx 4.13.0 → 5.0.0

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

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