@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/README.md

@@ -16,7 +16,7 @@ A TypeScript-first library for reading and writing spreadsheet documents
 > and has been rebuilt from the ground up into a modern, strict-TypeScript library.
 > **It carries no backwards-compatibility guarantee with ExcelJS** — the API below is
 > its own, not a drop-in. From 1.0.0 onward it follows
-> [SemVer](https://semver.org/) against *itself*; see the [changelog](CHANGELOG.md).
+> [SemVer](https://semver.org/) against _itself_; see the [changelog](CHANGELOG.md).
 > See [`CLAUDE.md`](CLAUDE.md) for the goals and [`docs/architecture.md`](docs/architecture.md)
 > for the design, and [migrating from ExcelJS](docs/migrating-from-exceljs.md) if you are coming across.
 
@@ -32,7 +32,7 @@ shim. It is a different, better library that happens to share ancestry.
 What that buys you today:
 
 - **Strict, precise types are the contract.** `strict` + `noUncheckedIndexedAccess` +
-  `exactOptionalPropertyTypes`. The published `.d.ts` *is* the documentation, and the
+  `exactOptionalPropertyTypes`. The published `.d.ts` _is_ the documentation, and the
   [API reference](docs/api/README.md) is generated straight from it.
 - **Synchronous, buffer-native I/O.** `readXlsx`/`writeXlsx` take and return a
   `Uint8Array` — no streams to await for the buffered path, no Node `Buffer` assumption,
@@ -98,8 +98,10 @@ const wb2 = readXlsx(readFileSync('people.xlsx')); // a Buffer is a Uint8Array
   `column.width = 12`, `column.key = 'name'`), and cells are reachable from it:
   `row.getCell('B')`, `row.cells`, `row.values`.
 - **`Cell`** — one cell. `cell.value` is the whole story: a `number`, `string`,
-  `boolean`, `Date`, `null` (empty), a formula (`{formula, result}`), rich text, a
-  hyperlink, or an error — all precisely typed as [`CellValue`](docs/api/cell-values.md).
+  `boolean`, `Date`, `null` (empty), a formula (`{formula, result}`), rich text, or an
+  error — all precisely typed as [`CellValue`](docs/api/cell-values.md). A hyperlink is not
+  a value: it sits on the sheet, over any cell, through
+  `sheet.addHyperlink({ref: 'B2', target: 'https://example.com'})`.
 
 ```ts
 sheet.getRow(1).height = 20;
@@ -112,7 +114,7 @@ for (const row of sheet.rows()) {
 }
 ```
 
-`Row` and `Column` are *handles*, not snapshots: they read and write straight through to the
+`Row` and `Column` are _handles_, not snapshots: they read and write straight through to the
 sheet, so two handles on the same line always agree, and reading one creates nothing — asking
 about row 500 costs nothing and does not extend the used range. Position is fixed, exactly as a
 `Cell`'s is: after a splice, `getRow(3)` still means row 3, now holding whatever moved there.
@@ -129,11 +131,13 @@ no API to author a new one — see [`docs/api/preserved.md`](docs/api/preserved.
 
 ```ts
 import {
-  readXlsx, writeXlsx,        // buffered .xlsx  (Uint8Array ⇄ Workbook)
-  readSheetRows,              // stream one sheet's rows, bounded memory
-  readWorkbookStream,         // stream every sheet, rows one at a time
-  readCsv, writeCsv,          // CSV as Uint8Array
-  writeCsvText,               // CSV as a string
+  readXlsx,
+  writeXlsx, // buffered .xlsx  (Uint8Array ⇄ Workbook)
+  readSheetRows, // stream one sheet's rows, bounded memory
+  readWorkbookStream, // stream every sheet, rows one at a time
+  readCsv,
+  writeCsv, // CSV as Uint8Array
+  writeCsvText, // CSV as a string
 } from '@shbernal/ts-xlsx';
 // The streaming writer opens files and pipes Node streams, so it is the one Node-only face
 // and lives behind its own subpath — which is what keeps everything above browser-safe:
@@ -141,7 +145,10 @@ import {WorkbookStreamWriter} from '@shbernal/ts-xlsx/node';
 
 // Bounded-memory extraction — the whole workbook is never materialized:
 for (const row of readSheetRows(bytes, {sheet: 'People'})) {
-  console.log(row.number, row.cells.map((c) => c.value));
+  console.log(
+    row.number,
+    row.cells.map((c) => c.value),
+  );
 }
 
 // Bounded-memory generation — commit each row to serialize and free it as you go:
@@ -149,12 +156,15 @@ const writer = new WorkbookStreamWriter();
 const out = writer.addWorksheet('Big');
 for (let i = 1; i <= 1_000_000; i++) out.addRow([i, i * i]).commit();
 out.commit();
-const packaged: Uint8Array = await writer.commit(); // also delivered via writer.stream
+const packaged = await writer.commit(); // Uint8Array here; also delivered via writer.stream
 ```
 
 The streaming writer is asynchronous where the buffered path is synchronous: `commit()`
 resolves to the package bytes and simultaneously pipes them through `writer.stream` (a Node
 `Readable`), so `writer.stream.pipe(res)` streams a workbook straight to an HTTP response.
+Hand the writer its own sink instead (`{stream}` or `{filename}`) and never touch
+`writer.stream`, and `commit()` resolves with `undefined`: the archive goes to the sink and is
+never assembled as one object, which is what passing a sink was for.
 
 ## Writing without blocking the event loop
 
@@ -191,17 +201,17 @@ The bare package name gives you everything, and with a bundler that is the right
 are for when you'd rather the module graph itself said which half of the library you depend
 on — a Lambda with no bundler, a service that only classifies failures:
 
-| Import from | You get | It loads |
-| --- | --- | --- |
-| `@shbernal/ts-xlsx` | everything except the streaming writer | 501 KB |
-| `@shbernal/ts-xlsx/core` | `Workbook`, `Worksheet`, `Cell`, styles, values, addresses | 185 KB |
-| `@shbernal/ts-xlsx/xlsx` | `readXlsx`, `writeXlsx`/`writeXlsxAsync`, the streaming reader, VBA part edits | 490 KB |
-| `@shbernal/ts-xlsx/xlsb` | `readXlsb` | 256 KB |
-| `@shbernal/ts-xlsx/csv` | `readCsv`, `writeCsv`, `writeCsvText` | 191 KB |
-| `@shbernal/ts-xlsx/node` | `WorkbookStreamWriter` and the rest of the streaming writer | 358 KB |
-| `@shbernal/ts-xlsx/vba` | `parseVbaProject`, `addVbaReference`, `removeVbaModule` | 46 KB |
-| `@shbernal/ts-xlsx/customui` | `parseCustomUi` and the ribbon types | 15 KB |
-| `@shbernal/ts-xlsx/errors` | every error class the library throws | 3 KB |
+| Import from                  | You get                                                                        | It loads |
+| ---------------------------- | ------------------------------------------------------------------------------ | -------- |
+| `@shbernal/ts-xlsx`          | everything except the streaming writer                                         | 501 KB   |
+| `@shbernal/ts-xlsx/core`     | `Workbook`, `Worksheet`, `Cell`, styles, values, addresses                     | 185 KB   |
+| `@shbernal/ts-xlsx/xlsx`     | `readXlsx`, `writeXlsx`/`writeXlsxAsync`, the streaming reader, VBA part edits | 490 KB   |
+| `@shbernal/ts-xlsx/xlsb`     | `readXlsb`                                                                     | 256 KB   |
+| `@shbernal/ts-xlsx/csv`      | `readCsv`, `writeCsv`, `writeCsvText`                                          | 191 KB   |
+| `@shbernal/ts-xlsx/node`     | `WorkbookStreamWriter` and the rest of the streaming writer                    | 358 KB   |
+| `@shbernal/ts-xlsx/vba`      | `parseVbaProject`, `addVbaReference`, `removeVbaModule`                        | 46 KB    |
+| `@shbernal/ts-xlsx/customui` | `parseCustomUi` and the ribbon types                                           | 15 KB    |
+| `@shbernal/ts-xlsx/errors`   | every error class the library throws                                           | 3 KB     |
 
 `/node` is the only one the root specifier does not carry, and the reason is its imports
 rather than its size: it reaches `node:fs` and `node:stream`, and every other entry reaches
@@ -231,7 +241,7 @@ pnpm run docs
 Read **[migrating from ExcelJS](docs/migrating-from-exceljs.md)**. The short version: the
 shapes are deliberately different (synchronous `Uint8Array` I/O instead of async
 `Buffer`/stream methods, `readXlsx`/`writeXlsx` free functions instead of
-`workbook.xlsx.*`), because the goal was the *right* API, not the familiar one.
+`workbook.xlsx.*`), because the goal was the _right_ API, not the familiar one.
 
 ## Hit a bug? There is a skill for that
 

package/dist/bytes.d.ts

@@ -18,7 +18,15 @@ export declare function concat(chunks: readonly Uint8Array[], size?: number): Ui
  * Spelled out rather than delegated because both platform routes are unavailable here: `Buffer` is
  * a Node global, which is exactly what a browser-safe module may not reach for, and `btoa` is
  * declared deprecated in Node's types (so the `no-deprecated` lint rule rejects it) and takes a
- * binary string rather than bytes anyway. The one caller encodes a 16-byte salt and a 64-byte
- * hash, so the loop below is not on any path where its cost is measurable.
+ * binary string rather than bytes anyway. The callers encode a 16-byte salt and a 64-byte hash, a
+ * sheet password's when one is set and a binary sheet's credential when one is read, so the loop below
+ * is not on any path where its cost is measurable.
  */
 export declare function toBase64(bytes: Uint8Array): string;
+/** A string's UTF-16LE bytes, code unit by code unit, with lone surrogates carried through. */
+export declare function utf16leBytes(text: string): Uint8Array;
+/**
+ * Decode UTF-16LE code units. A trailing odd byte is dropped: these fields are length-prefixed by
+ * their producer, and half a code unit carries nothing to decode.
+ */
+export declare function decodeUtf16le(bytes: Uint8Array): string;

package/dist/bytes.js

@@ -32,3 +32,25 @@ export function toBase64(bytes) {
     }
     return out;
 }
+export function utf16leBytes(text) {
+    const bytes = new Uint8Array(text.length * 2);
+    for (let i = 0; i < text.length; i++) {
+        const unit = text.charCodeAt(i);
+        bytes[i * 2] = unit & 0xff;
+        bytes[i * 2 + 1] = unit >>> 8;
+    }
+    return bytes;
+}
+const CHARS_PER_BATCH = 4096;
+export function decodeUtf16le(bytes) {
+    let text = '';
+    let batch = [];
+    for (let i = 0; i + 1 < bytes.length; i += 2) {
+        batch.push(bytes[i] | (bytes[i + 1] << 8));
+        if (batch.length === CHARS_PER_BATCH) {
+            text += String.fromCharCode(...batch);
+            batch = [];
+        }
+    }
+    return batch.length > 0 ? text + String.fromCharCode(...batch) : text;
+}

package/dist/core/address.d.ts

@@ -2,6 +2,22 @@
 export declare const MAX_COLUMN = 16384;
 /** Excel's row bound: 1 through 1048576. The other axis of {@link MAX_COLUMN}. */
 export declare const MAX_ROW = 1048576;
+/**
+ * The same two bounds, zero-based: the last valid *index* on each axis.
+ *
+ * BIFF12 counts from zero throughout, so its reader and its formula decoder both need these, and both
+ * were deriving them privately. Two derivations of one fact is one fewer than three, but it is still
+ * the shape where a change to a limit reaches some of its consequences. The subtraction belongs beside
+ * the number it subtracts from.
+ */
+export declare const MAX_COLUMN_INDEX: number;
+export declare const MAX_ROW_INDEX: number;
+/**
+ * Refuse a coordinate that names no position on the grid.
+ *
+ * @throws {RangeError} unless `value` is an integer within the axis's bounds.
+ */
+export declare function assertAxisInBounds(axis: 'row' | 'column', value: number): void;
 /** @throws {RangeError} unless `n` is an integer in `1..MAX_COLUMN`. */
 export declare function assertColumnInBounds(n: number): void;
 /** @throws {RangeError} unless `n` is an integer in `1..MAX_ROW`. */
@@ -56,7 +72,19 @@ export interface RangeAddress {
  *
  * @throws {RangeError} unless `n` is an integer in `1..MAX_COLUMN`. */
 export declare function numberToColumn(n: number): string;
-/** Convert column letters to a 1-based number (`"A" → 1`, `"AA" → 27`). */
+/**
+ * Convert column letters to a 1-based number (`"A" → 1`, `"AA" → 27`), or `undefined` when they name
+ * no column that can exist: not letters at all, or past `XFD` (`"ZZZ"` is well-formed and is column
+ * 18278, which the grid does not have). The tolerant half of the pair the module header describes,
+ * for a caller reading a file rather than a caller's own argument.
+ */
+export declare function tryColumnToNumber(letters: string): number | undefined;
+/**
+ * Convert column letters to a 1-based number (`"A" → 1`, `"AA" → 27`).
+ *
+ * @throws {RangeError} if the letters are malformed or name a column past `XFD`. The two are
+ *   separate messages because a caller fixes them differently.
+ */
 export declare function columnToNumber(letters: string): number;
 /**
  * One corner of a range, as its reference text. An axis the corner omits contributes nothing, so a
@@ -67,11 +95,29 @@ export declare function columnToNumber(letters: string): number;
  * The unbounded counterpart to {@link encodeAddress}, which names one cell and so requires both.
  */
 export declare function encodeCornerRef(col: number | undefined, row: number | undefined): string;
+/**
+ * A bounded rectangle as its canonical `tl:br` A1 range, `"B2:D5"`. A one-cell rectangle still reads
+ * as `"B2:B2"`, which is the form Excel writes and the form every consumer of these refs parses.
+ *
+ * The rendering half of {@link boundedRect}, and it belongs beside it for the same reason: ten sites
+ * spelled `` `${encodeAddress(left, top)}:${encodeAddress(right, bottom)}` `` by hand, and the risk in
+ * that expression is not its length but its argument order. `encodeAddress` takes column first and a
+ * rectangle names its rows first, so the two orders are transposed with respect to each other at every
+ * one of those sites.
+ */
+export declare function encodeRect(rect: GridRect): string;
+/**
+ * A bounded rectangle as a formula's `ref` spells it: {@link encodeRect}'s `"B1:B3"`, except that one
+ * cell is its bare address, `"B1"`. Excel writes an array formula over a single cell that way, and a
+ * range that moves keeps the spelling it would be saved with.
+ */
+export declare function encodeRange(rect: GridRect): string;
 /**
  * Decode a single cell/row/column reference into `{address, col, row}`. Anchoring
  * `$` signs are accepted and dropped; an absent axis is `undefined`.
  *
  * @throws {SyntaxError} if the reference mentions neither a column nor a row.
+ * @throws {RangeError} if it names a column past `XFD` or a row outside `1..1048576`.
  */
 export declare function decodeAddress(reference: string): CellAddress;
 /**
@@ -88,6 +134,7 @@ export interface CellPosition {
  * Decode a reference that must name a single cell. Anchoring `$` signs are accepted and dropped.
  *
  * @throws {SyntaxError} if the reference is unparseable, or parses but omits an axis (`"A"`, `"1"`).
+ * @throws {RangeError} if it names a position off the grid (`"A0"`, `"XFE1"`).
  */
 export declare function decodeCellRef(reference: string): CellPosition;
 /**
@@ -98,6 +145,19 @@ export declare function decodeCellRef(reference: string): CellPosition;
  * there is nothing here".
  */
 export declare function tryDecodeCellRef(reference: string): CellPosition | undefined;
+/**
+ * Narrow a decoded range to a {@link GridRect}, or `undefined` when either axis is unbounded.
+ *
+ * A whole-column reference (`A:A`) and a whole-row one (`1:1`) are legal range references whose
+ * corners are partly absent, so every caller that needs a real rectangle has to test all four. Doing
+ * that in seven places is the other half of the convention `GridRect` already exists to state once:
+ * the shape is declared here, and so is the one narrowing that produces it.
+ *
+ * A caller wanting to say something *different* about each axis (a `Range` refuses `A:A` and `1:1`
+ * with two distinct messages) still tests them separately, and one that only cares about the axis it
+ * is splicing still tests only that one. Neither is this question.
+ */
+export declare function boundedRect(range: RangeAddress): GridRect | undefined;
 /**
  * {@link decodeRange} for a reference that came out of a file: `undefined` for anything that does
  * not name a region that can exist. The sibling of {@link tryDecodeCellRef} on the other arity: a
@@ -108,11 +168,45 @@ export declare function tryDecodeCellRef(reference: string): CellPosition | unde
  * range is unbounded, not unreadable, and a caller that needs a bounded rectangle says so itself.
  */
 export declare function tryDecodeRange(reference: string): RangeAddress | undefined;
+/**
+ * The rectangle `reference` names when its top-left cell is (`col`, `row`), or `undefined` for a
+ * reference that does not parse, is unbounded, names a sheet, or starts at another cell. That is the
+ * shape of the range an array formula fills: Excel states the formula on the cell the range starts at,
+ * so a `ref` read from a file and one handed to the writer are both held to it.
+ */
+export declare function tryDecodeAnchoredRange(reference: string, col: number, row: number): GridRect | undefined;
 /**
  * Decode a range reference (`A1:B2`, `$1:$1`, `Sheet1!$A:$A`) into its corners and
  * canonical dimensions. A single reference collapses to a degenerate range whose
  * corners coincide.
+ *
+ * @throws {SyntaxError} if an endpoint is unparseable.
+ * @throws {RangeError} if an endpoint names a column past `XFD` or a row outside `1..1048576`.
  */
 export declare function decodeRange(reference: string): RangeAddress;
-/** Encode a 1-based `col`/`row` pair into its canonical A1 address (`"B2"`). */
+/**
+ * Encode a 1-based `col`/`row` pair into its canonical A1 address (`"B2"`).
+ *
+ * Both axes go through the shared guard. The column already did, through `numberToColumn`; the row
+ * checked only its lower bound in a message of its own, so `encodeAddress(1, 1048577)` produced an
+ * address naming a row Excel has no reference for while `encodeAddress(16385, 1)` refused.
+ */
 export declare function encodeAddress(col: number, row: number): string;
+/**
+ * Does Excel read this name as a reference, where it expects a name? Such a name must be quoted as a
+ * sheet prefix (`'R1C1'!A1`), and cannot name a table at all.
+ *
+ * Four shapes, case-insensitive, all found by asking Excel (16.0 build 20326) rather than read off a
+ * specification, which states the rule as "not the same as a cell reference, and not `C` or `R`" and
+ * leaves the edges to the implementation:
+ *
+ * - an A1 cell **on the grid**: `T1`, `a01`, `XFD1048576`, but not `XFE1` or `A0`;
+ * - a whole R1C1 reference, each number optional and on the grid: `R`, `C`, `RC`, `R1C`, `R1C1`;
+ * - an R1C1 row or column number followed by a letter or underscore: `R1X`, `C1X`, `R1C1_`, but
+ *   not `R1.5`, nor `RCX`, which carries no number;
+ * - `TRUE` or `FALSE`.
+ *
+ * Every name tried both ways was quoted in a formula exactly when a table by that name made Excel
+ * offer to repair the package, so the two rules are one.
+ */
+export declare function nameReadsAsReference(name: string): boolean;

package/dist/core/address.js

@@ -1,14 +1,20 @@
+import { quoted } from '../errors.js';
 export const MAX_COLUMN = 16384;
 export const MAX_ROW = 1048576;
-export function assertColumnInBounds(n) {
-    if (!Number.isInteger(n) || n < 1 || n > MAX_COLUMN) {
-        throw new RangeError(`column ${n} is out of bounds: Excel supports 1..${MAX_COLUMN}`);
+export const MAX_COLUMN_INDEX = MAX_COLUMN - 1;
+export const MAX_ROW_INDEX = MAX_ROW - 1;
+const AXIS_BOUND = { row: MAX_ROW, column: MAX_COLUMN };
+export function assertAxisInBounds(axis, value) {
+    const bound = AXIS_BOUND[axis];
+    if (!Number.isInteger(value) || value < 1 || value > bound) {
+        throw new RangeError(`${axis} ${value} is out of bounds: Excel supports 1..${bound}`);
     }
 }
+export function assertColumnInBounds(n) {
+    assertAxisInBounds('column', n);
+}
 export function assertRowInBounds(n) {
-    if (!Number.isInteger(n) || n < 1 || n > MAX_ROW) {
-        throw new RangeError(`row ${n} is out of bounds: Excel supports 1..${MAX_ROW}`);
-    }
+    assertAxisInBounds('row', n);
 }
 export function rectsOverlap(a, b) {
     return a.left <= b.right && b.left <= a.right && a.top <= b.bottom && b.top <= a.bottom;
@@ -26,72 +32,91 @@ export function numberToColumn(n) {
     }
     return letters;
 }
-export function columnToNumber(letters) {
-    if (letters.length === 0 || letters.length > 3) {
-        throw new RangeError(`invalid column letters: "${letters}"`);
-    }
+const COLUMN_LETTERS = /^[A-Z]{1,3}$/;
+export function tryColumnToNumber(letters) {
+    if (!COLUMN_LETTERS.test(letters))
+        return undefined;
     let n = 0;
     for (let i = 0; i < letters.length; i++) {
-        const code = letters.charCodeAt(i);
-        if (code < 65 || code > 90) {
-            throw new RangeError(`invalid column letters: "${letters}"`);
-        }
-        n = n * 26 + (code - 64);
+        n = n * 26 + (letters.charCodeAt(i) - 64);
     }
-    if (n > MAX_COLUMN) {
-        throw new RangeError(`column "${letters}" is out of bounds: Excel supports up to ${MAX_COLUMN} (XFD)`);
+    return n > MAX_COLUMN ? undefined : n;
+}
+export function columnToNumber(letters) {
+    const n = tryColumnToNumber(letters);
+    if (n !== undefined)
+        return n;
+    if (!COLUMN_LETTERS.test(letters)) {
+        throw new RangeError(`invalid column letters: ${quoted(letters)}`);
     }
-    return n;
+    throw new RangeError(`column ${quoted(letters)} is out of bounds: Excel supports up to ${MAX_COLUMN} (XFD)`);
 }
 export function encodeCornerRef(col, row) {
     return `${col !== undefined ? numberToColumn(col) : ''}${row !== undefined ? row : ''}`;
 }
+export function encodeRect(rect) {
+    return `${encodeAddress(rect.left, rect.top)}:${encodeAddress(rect.right, rect.bottom)}`;
+}
+export function encodeRange(rect) {
+    return rect.top === rect.bottom && rect.left === rect.right
+        ? encodeAddress(rect.left, rect.top)
+        : encodeRect(rect);
+}
 function makeCellAddress(col, row) {
     return { address: encodeCornerRef(col, row), col, row };
 }
 export function decodeAddress(reference) {
     const match = SINGLE_REF.exec(reference);
     if (!match) {
-        throw new SyntaxError(`invalid cell reference: "${reference}"`);
+        throw new SyntaxError(`invalid cell reference: ${quoted(reference)}`);
     }
     const letters = match[1] ?? '';
     const digits = match[2] ?? '';
     if (letters.length === 0 && digits.length === 0) {
-        throw new SyntaxError(`invalid cell reference: "${reference}"`);
+        throw new SyntaxError(`invalid cell reference: ${quoted(reference)}`);
     }
     const col = letters.length > 0 ? columnToNumber(letters) : undefined;
     const row = digits.length > 0 ? Number.parseInt(digits, 10) : undefined;
+    if (row !== undefined)
+        assertRowInBounds(row);
     return { address: `${letters}${digits}`, col, row };
 }
 export function decodeCellRef(reference) {
     const { col, row } = decodeAddress(reference);
     if (col === undefined || row === undefined) {
-        throw new SyntaxError(`"${reference}" is not a single-cell reference: it omits a column or row`);
+        throw new SyntaxError(`${quoted(reference)} is not a single-cell reference: it omits a column or row`);
     }
     return { col, row };
 }
-function rowCanExist(row) {
-    return row === undefined || (Number.isInteger(row) && row >= 1 && row <= MAX_ROW);
-}
 export function tryDecodeCellRef(reference) {
-    let position;
     try {
-        position = decodeCellRef(reference);
+        return decodeCellRef(reference);
     }
     catch {
         return undefined;
     }
-    return rowCanExist(position.row) ? position : undefined;
+}
+export function boundedRect(range) {
+    const { top, left, bottom, right } = range;
+    if (top === undefined || left === undefined || bottom === undefined || right === undefined) {
+        return undefined;
+    }
+    return { top, left, bottom, right };
 }
 export function tryDecodeRange(reference) {
-    let range;
     try {
-        range = decodeRange(reference);
+        return decodeRange(reference);
     }
     catch {
         return undefined;
     }
-    return rowCanExist(range.top) && rowCanExist(range.bottom) ? range : undefined;
+}
+export function tryDecodeAnchoredRange(reference, col, row) {
+    const range = tryDecodeRange(reference);
+    if (range === undefined || range.sheetName !== undefined)
+        return undefined;
+    const rect = boundedRect(range);
+    return rect !== undefined && rect.left === col && rect.top === row ? rect : undefined;
 }
 export function decodeRange(reference) {
     const prefix = SHEET_PREFIX.exec(reference);
@@ -125,8 +150,37 @@ export function decodeRange(reference) {
     };
 }
 export function encodeAddress(col, row) {
-    if (!Number.isInteger(row) || row < 1) {
-        throw new RangeError(`row ${row} is out of bounds: rows start at 1`);
-    }
+    assertRowInBounds(row);
     return `${numberToColumn(col)}${row}`;
 }
+function isLineNumber(digits, bound) {
+    const n = Number(digits);
+    return n >= 1 && n <= bound;
+}
+const A1_NAME = /^([A-Za-z]{1,3})(\d+)$/;
+const R1C1_NAME = /^(?:R(\d*)C(\d*)|R(\d*)|C(\d*))$/i;
+const R1C1_PREFIX = /^(?:R(\d+)|C(\d+))[A-Za-z_]/i;
+export function nameReadsAsReference(name) {
+    const a1 = A1_NAME.exec(name);
+    if (a1 !== null) {
+        const [, letters = '', digits = ''] = a1;
+        if (tryColumnToNumber(letters.toUpperCase()) !== undefined && isLineNumber(digits, MAX_ROW)) {
+            return true;
+        }
+    }
+    const r1c1 = R1C1_NAME.exec(name);
+    if (r1c1 !== null) {
+        const [, row, column, rowOnly, columnOnly] = r1c1;
+        const on = (digits, bound) => digits === undefined || digits === '' || isLineNumber(digits, bound);
+        if (on(row ?? rowOnly, MAX_ROW) && on(column ?? columnOnly, MAX_COLUMN))
+            return true;
+    }
+    const prefix = R1C1_PREFIX.exec(name);
+    if (prefix !== null) {
+        const [, row, column] = prefix;
+        if (row !== undefined ? isLineNumber(row, MAX_ROW) : isLineNumber(column ?? '', MAX_COLUMN)) {
+            return true;
+        }
+    }
+    return /^(?:TRUE|FALSE)$/i.test(name);
+}

package/dist/core/array-formula-ranges.d.ts

@@ -0,0 +1,33 @@
+import { type CellValue } from './value.ts';
+/**
+ * Where a cell holding `value` places a formula, or `undefined` when the value is no formula. A shared
+ * formula's clone and a data table's cell count: each is a formula Excel will not find inside another
+ * array formula's range.
+ */
+export declare function formulaPlacement(address: string, col: number, row: number, value: CellValue): FormulaPlacement | undefined;
+/** A cell holding a formula of any kind, with the range it fills when it is an array formula. */
+export interface FormulaPlacement {
+    readonly address: string;
+    readonly col: number;
+    readonly row: number;
+    /** The array formula's `ref`, as its value states it; absent for any other formula. */
+    readonly arrayRef?: string | undefined;
+}
+/** An array formula whose range holds another formula's cell, or shares a cell with a range kept. */
+export interface ArrayRangeConflict {
+    readonly array: FormulaPlacement;
+    /** The address of the other formula in the range, or of the array formula whose range it overlaps. */
+    readonly other: string;
+    readonly kind: 'formula-inside' | 'ranges-overlap';
+}
+/**
+ * The array formulas that cannot stand, deciding in reading order: an array formula conflicts when
+ * another formula's cell lies in its range, or when its range shares a cell with the range of an
+ * array formula decided before it that did not conflict. The array formulas left over hold ranges
+ * that share no cell with each other and hold no formula but their own, so reading each conflict as
+ * its plain formula leaves a sheet the writer accepts.
+ *
+ * A `ref` that names no bounded range starting at its own cell fills no cells here; the reader never
+ * produces one and the writer refuses it on its own terms.
+ */
+export declare function arrayRangeConflicts(placements: Iterable<FormulaPlacement>): ArrayRangeConflict[];

package/dist/core/array-formula-ranges.js

@@ -0,0 +1,62 @@
+import { tryDecodeAnchoredRange } from './address.js';
+import { MergeIndex } from './merge-index.js';
+import { isArrayFormulaValue, isDataTableFormulaValue, isFormulaValue, isSharedFormulaValue, } from './value.js';
+export function formulaPlacement(address, col, row, value) {
+    if (isArrayFormulaValue(value))
+        return { address, col, row, arrayRef: value.ref };
+    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
+        return { address, col, row };
+    }
+    return undefined;
+}
+export function arrayRangeConflicts(placements) {
+    const all = [...placements];
+    const cellRects = [];
+    const placementOfCell = new Map();
+    const arrays = [];
+    for (const placement of all) {
+        const cell = {
+            top: placement.row,
+            left: placement.col,
+            bottom: placement.row,
+            right: placement.col,
+        };
+        cellRects.push(cell);
+        placementOfCell.set(cell, placement);
+        const range = placement.arrayRef === undefined
+            ? undefined
+            : tryDecodeAnchoredRange(placement.arrayRef, placement.col, placement.row);
+        if (range !== undefined)
+            arrays.push({ placement, range });
+    }
+    arrays.sort((a, b) => a.placement.row - b.placement.row || a.placement.col - b.placement.col);
+    const cells = new MergeIndex(cellRects);
+    const keptRanges = [];
+    const kept = new MergeIndex(keptRanges);
+    const placementOfRange = new Map();
+    const conflicts = [];
+    for (const { placement, range } of arrays) {
+        const inside = formulaInside(range, cells);
+        if (inside !== undefined) {
+            const other = placementOfCell.get(inside)?.address ?? '';
+            conflicts.push({ array: placement, other, kind: 'formula-inside' });
+            continue;
+        }
+        const overlapped = kept.overlapping(range);
+        if (overlapped !== undefined) {
+            const other = placementOfRange.get(overlapped)?.address ?? '';
+            conflicts.push({ array: placement, other, kind: 'ranges-overlap' });
+            continue;
+        }
+        keptRanges.push(range);
+        placementOfRange.set(range, placement);
+        kept.note(range);
+    }
+    return conflicts;
+}
+function formulaInside(range, cells) {
+    const below = { ...range, top: range.top + 1 };
+    const beside = { ...range, bottom: range.top, left: range.left + 1 };
+    return ((below.top <= below.bottom ? cells.overlapping(below) : undefined) ??
+        (beside.left <= beside.right ? cells.overlapping(beside) : undefined));
+}

package/dist/core/autofilter.d.ts

@@ -1,3 +1,4 @@
+import { type AxisSplice } from './grid-shift.ts';
 /**
  * A worksheet's autofilter: the filtered region plus any per-column criteria narrowing it. A bare
  * range (no columns) is just the header-row dropdowns Excel draws; adding {@link FilterColumn}s
@@ -54,8 +55,8 @@ export declare const isCustomFilterOperator: (value: string) => value is CustomF
  */
 export declare function canonicalizeAutoFilter(input: string | AutoFilter): AutoFilter;
 /**
- * Re-anchor a filter through a splice of `count` lines at `start` on `axis`, or drop it (`undefined`)
- * when the splice deleted every line it covered.
+ * Re-anchor a filter through a splice, or drop it (`undefined`) when the splice deleted every line
+ * it covered.
  *
  * A row splice only moves the range. A column splice moves its left edge too, and a criterion is
  * addressed by its offset from that edge rather than by an absolute column, so every offset is
@@ -63,4 +64,4 @@ export declare function canonicalizeAutoFilter(input: string | AutoFilter): Auto
  * Left alone, those offsets would keep their old numbers and silently re-point each filter at a
  * neighbouring column.
  */
-export declare function shiftAutoFilter(filter: AutoFilter, axis: 'row' | 'col', start: number, count: number, delta: number): AutoFilter | undefined;
+export declare function shiftAutoFilter(filter: AutoFilter, splice: AxisSplice): AutoFilter | undefined;