@shbernal/ts-xlsx 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2014-2019 Guyon Roche (original ExcelJS work)
+Copyright (c) 2026 shbernal (ts-xlsx, an independent hard fork)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,230 @@
+# ts-xlsx
+
+A TypeScript-first library for reading and writing spreadsheet documents
+(`.xlsx` / OOXML, and CSV) — synchronous, `Uint8Array`-native, and dependency-lean.
+
+> **Status — 1.0.0, the first release.**
+> `ts-xlsx` began as a hard fork of [ExcelJS](https://github.com/exceljs/exceljs)
+> 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).
+> 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.
+
+## Why it exists
+
+Upstream ExcelJS is effectively unmaintained — no release since 2023, a backlog of
+hundreds of issues and PRs — while still serving tens of millions of downloads a month.
+`ts-xlsx` extracts the accumulated value from that backlog (as a permanent regression
+corpus) and discards the debt: no untyped surfaces, no callback APIs, a single small
+runtime dependency, and every behavior pinned by a test. This is not a compatibility
+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
+  [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,
+  so the same code runs in Node and the browser.
+- **Streaming when you need it.** Bounded-memory row streaming both ways — read a large
+  workbook without materializing it, or write one incrementally to a Node stream so peak
+  memory stays flat.
+- **One runtime dependency** ([`fflate`](https://github.com/101arrowz/fflate) for zip),
+  a hand-written SAX reader with bounded allocation on every parser path, and a
+  build-free, strict-typed source tree.
+
+## Install
+
+```shell
+npm install @shbernal/ts-xlsx
+```
+
+Requires Node ≥ 24 (or any modern browser bundler). ESM only.
+
+## Quick start
+
+The buffered path is synchronous. `writeXlsx` returns the file bytes; `readXlsx` takes them back.
+
+```ts
+import {Workbook, writeXlsx, readXlsx} from '@shbernal/ts-xlsx';
+
+// --- write ---
+const wb = new Workbook();
+const sheet = wb.addWorksheet('People');
+
+sheet.getCell('A1').value = 'Name';
+sheet.getCell('B1').value = 'Joined';
+sheet.addRow(['Ada', new Date('2026-01-01')]);
+sheet.addRow(['Grace', new Date('2026-02-14')]);
+sheet.getCell('C1').value = {formula: 'COUNTA(A:A)', result: 3};
+
+const bytes: Uint8Array = writeXlsx(wb);
+
+// --- read it back ---
+const reopened = readXlsx(bytes);
+const people = reopened.getWorksheet('People');
+console.log(people?.getCell('A2').value); // 'Ada'
+```
+
+Persisting to disk is your platform's job, not the library's — `writeXlsx` hands you the
+bytes:
+
+```ts
+import {writeFileSync, readFileSync} from 'node:fs';
+
+writeFileSync('people.xlsx', writeXlsx(wb));
+const wb2 = readXlsx(readFileSync('people.xlsx')); // a Buffer is a Uint8Array
+```
+
+## Core model
+
+- **`Workbook`** — the document. `addWorksheet(name)`, `getWorksheet(nameOrId)`,
+  `worksheets`, defined names, images, and workbook-level properties.
+- **`Worksheet`** — a sheet. `getCell('B3')`, `addRow(values)`, `addTable(...)`,
+  `mergeCells('A1:B2')`, `getRow(n)` / `getColumn(n)`, `rows()` / `columns()`, page setup,
+  and print options.
+- **`Row`** / **`Column`** — one line of the grid. Formatting is flat (`row.height = 20`,
+  `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).
+
+```ts
+sheet.getRow(1).height = 20;
+sheet.getRow(1).values = ['Name', 'Joined'];
+sheet.getColumn(1).width = 24;
+sheet.getRow(2).getCell('B').value = new Date('2026-01-01');
+
+for (const row of sheet.rows()) {
+  console.log(row.number, row.values);
+}
+```
+
+`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.
+
+Addresses are honest: an axis a reference doesn't mention is `undefined`, never a
+sentinel — see [`decodeAddress`](docs/api/addresses-ranges.md).
+
+Charts, vector shapes, slicers, and legacy form controls are **round-trip-only**: a
+workbook that has them keeps them byte-faithfully through a load/edit/save, but there is
+no API to author a new one — see [`docs/api/preserved.md`](docs/api/preserved.md) and
+[ADR-0014](docs/decisions/0014-charts-shapes-slicers-are-round-trip-only-for-1-0.md).
+
+## Reading, writing, streaming, CSV
+
+```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
+  WorkbookStreamWriter,       // write a workbook incrementally, bounded memory
+  readCsv, writeCsv,          // CSV as Uint8Array
+  writeCsvText,               // CSV as a string
+} from '@shbernal/ts-xlsx';
+
+// 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));
+}
+
+// Bounded-memory generation — commit each row to serialize and free it as you go:
+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
+```
+
+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.
+
+## Writing without blocking the event loop
+
+`writeXlsx` spends the whole cost of DEFLATE on the calling thread — seconds, for a large
+workbook, during which a server answers nothing. `writeXlsxAsync` produces the same package
+with the compression handed to worker threads:
+
+```ts
+import {writeXlsxAsync} from '@shbernal/ts-xlsx';
+
+const bytes = await writeXlsxAsync(wb); // same package, event loop stays live
+```
+
+Measured on a ~42 MB part map: one large sheet takes the same wall-clock either way, but the
+longest event-loop stall drops from the entire write to ~17 ms; a twenty-sheet workbook also
+finishes about 2.4× sooner, because its parts deflate in parallel. Expect responsiveness
+always and speed only when there is more than one substantial part.
+
+There is deliberately **no `readXlsxAsync`**. Reading is dominated by XML parsing and model
+building, which no worker can take off the calling thread, so it would advertise a
+non-blocking read and then block for most of its duration — and the reader's zip-bomb ceiling
+is enforced by counting output between synchronous input slices, a guarantee that weakens the
+moment inflation moves to a worker. If you need a non-blocking read, run the whole read in a
+worker. See [ADR-0024](docs/decisions/0024-async-is-one-writer-not-a-mirrored-pair.md).
+
+The reader decodes untrusted input defensively — entities are decoded but never
+expanded, and inflation is bounded by a running output counter rather than any declared
+size, so a malformed or hostile package can't exhaust memory.
+
+## Entry points
+
+The bare package name gives you everything, and with a bundler that is the right default:
+`"sideEffects": false` is declared, so anything you don't reference is dropped. The subpaths
+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 | 902 KB |
+| `@shbernal/ts-xlsx/core` | `Workbook`, `Worksheet`, `Cell`, styles, values, addresses | 332 KB |
+| `@shbernal/ts-xlsx/xlsx` | `readXlsx`, `writeXlsx`/`writeXlsxAsync`, the streaming pair, VBA part edits | 887 KB |
+| `@shbernal/ts-xlsx/xlsb` | `readXlsb` | 469 KB |
+| `@shbernal/ts-xlsx/csv` | `readCsv`, `writeCsv`, `writeCsvText` | 341 KB |
+| `@shbernal/ts-xlsx/vba` | `parseVbaProject`, `addVbaReference`, `removeVbaModule` | 73 KB |
+| `@shbernal/ts-xlsx/customui` | `parseCustomUi` and the ribbon types | 26 KB |
+| `@shbernal/ts-xlsx/errors` | every error class the library throws | 12 KB |
+
+Every error class lives in `/errors` and nowhere else, because a container-level failure
+belongs to no single codec — `readXlsx` and `readXlsb` both raise `UnsupportedFormatError`.
+Catching and classifying therefore costs 12 KB, not a parser.
+
+`/xlsx` is barely cheaper than the whole package, and that is honest rather than a defect:
+`readXlsx` sniffs the bytes and hands a binary package to the BIFF12 reader, so the `.xlsb`
+codec is not optional on that path. The numbers above are the static-import closure of each
+entry, measured by `pnpm run size` — a bundler can only shrink them further.
+
+## API reference
+
+The full reference is generated from the public types — it cannot drift from what the
+compiler accepts — and lives in **[`docs/api/`](docs/api/README.md)**. Regenerate it with:
+
+```shell
+pnpm run docs
+```
+
+## Coming from ExcelJS?
+
+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.
+
+## Design principles
+
+This project is optimized to be built and maintained largely by autonomous agents, with
+a machine-checkable safety net as the primary guarantor of correctness. The rules that
+govern every change are in [`CLAUDE.md`](CLAUDE.md); the design and working agreements are
+in [`docs/architecture.md`](docs/architecture.md); notable decisions are recorded under
+[`docs/decisions/`](docs/decisions/).
+
+## License
+
+[MIT](LICENSE) — inherited from ExcelJS and retained.

package/dist/core/address.d.ts

@@ -0,0 +1,49 @@
+/** Excel's column bounds: `A` (1) through `XFD` (16384). */
+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;
+/** A decoded single-cell reference. An axis the reference omits is `undefined`. */
+export interface CellAddress {
+    /** Canonical A1 form with `$` anchors stripped — e.g. `"B2"`, `"1"`, `"A"`. */
+    readonly address: string;
+    /** 1-based column, or `undefined` for a row-only reference (`$1`). */
+    readonly col: number | undefined;
+    /** 1-based row, or `undefined` for a column-only reference (`$A`). */
+    readonly row: number | undefined;
+}
+/**
+ * A decoded range reference. Corners are the min/max of the endpoints per axis;
+ * an axis neither endpoint mentions (a whole-row or whole-column range) is
+ * `undefined` on every corner and simply absent from `dimensions`.
+ */
+export interface RangeAddress {
+    readonly top: number | undefined;
+    readonly left: number | undefined;
+    readonly bottom: number | undefined;
+    readonly right: number | undefined;
+    /** The originating sheet, present only when the reference carried one. */
+    readonly sheetName?: string;
+    readonly tl: CellAddress;
+    readonly br: CellAddress;
+    /** Canonical `tl:br` form — `"A1:B2"`, `"1:1"` (rows), `"A:A"` (columns). */
+    readonly dimensions: string;
+}
+/** Convert a 1-based column number to its letters (`1 → "A"`, `27 → "AA"`). */
+export declare function numberToColumn(n: number): string;
+/** Convert column letters to a 1-based number (`"A" → 1`, `"AA" → 27`). */
+export declare function columnToNumber(letters: string): number;
+/**
+ * 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.
+ */
+export declare function decodeAddress(reference: string): CellAddress;
+/**
+ * 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.
+ */
+export declare function decodeRange(reference: string): RangeAddress;
+/** Encode a 1-based `col`/`row` pair into its canonical A1 address (`"B2"`). */
+export declare function encodeAddress(col: number, row: number): string;

package/dist/core/address.js

@@ -0,0 +1,125 @@
+// Address decoding — the foundational spreadsheet primitive.
+//
+// Every higher layer (cells, ranges, defined names, formulas) is ultimately
+// addressed by a `col`/`row` pair, so this module is the first thing the rewrite
+// builds and the bedrock everything else stands on. It is pure, allocation-bounded,
+// and has no I/O or platform dependency.
+//
+// The honesty rule that drives the shape here: an axis that a reference does not
+// mention is `undefined`, never a sentinel. A whole-row reference (`$1`) has no
+// column; a whole-column reference (`$A:$A`) has no row. Legacy code let those
+// absent axes decay into `NaN`/`"undefined"` and leak into serialized addresses
+// (`"$undefined$1"`, `"NaN:NaN"`) — the exact defect the corpus locks against.
+/** Excel's column bounds: `A` (1) through `XFD` (16384). */
+export const MAX_COLUMN = 16384;
+/** Excel's row bound: 1 through 1048576. The other axis of {@link MAX_COLUMN}. */
+export const MAX_ROW = 1048576;
+const SINGLE_REF = /^\$?([A-Z]*)\$?(\d*)$/;
+// A leading `Sheet!` prefix: quoted (`'a''b'!`, doubled apostrophe escapes one) or
+// bare (`Sheet1!`). Group 1 = quoted body, group 2 = bare name, group 3 = the rest.
+const SHEET_PREFIX = /^(?:(?:'((?:[^']|'')*)')|([^'!]+))!(.*)$/;
+/** Convert a 1-based column number to its letters (`1 → "A"`, `27 → "AA"`). */
+export function numberToColumn(n) {
+    if (!Number.isInteger(n) || n < 1 || n > MAX_COLUMN) {
+        throw new RangeError(`column ${n} is out of bounds — Excel supports 1..${MAX_COLUMN}`);
+    }
+    let letters = '';
+    let remaining = n;
+    while (remaining > 0) {
+        const digit = (remaining - 1) % 26;
+        letters = String.fromCharCode(65 + digit) + letters;
+        remaining = Math.floor((remaining - 1) / 26);
+    }
+    return letters;
+}
+/** Convert column letters to a 1-based number (`"A" → 1`, `"AA" → 27`). */
+export function columnToNumber(letters) {
+    if (letters.length === 0 || letters.length > 3) {
+        throw new RangeError(`invalid column letters: "${letters}"`);
+    }
+    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);
+    }
+    if (n > MAX_COLUMN) {
+        throw new RangeError(`column "${letters}" is out of bounds — Excel supports up to ${MAX_COLUMN} (XFD)`);
+    }
+    return n;
+}
+/** Build a {@link CellAddress} corner straight from optional numeric axes — the address string is
+ * assembled from the parts we already hold, so no encode-then-decode round-trip is needed. An axis the
+ * corner omits stays `undefined`; both absent yields the empty address (`""`). */
+function makeCellAddress(col, row) {
+    return {
+        address: `${col !== undefined ? numberToColumn(col) : ''}${row !== undefined ? row : ''}`,
+        col,
+        row,
+    };
+}
+/**
+ * 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.
+ */
+export function decodeAddress(reference) {
+    const match = SINGLE_REF.exec(reference);
+    if (!match) {
+        throw new SyntaxError(`invalid cell reference: "${reference}"`);
+    }
+    const letters = match[1] ?? '';
+    const digits = match[2] ?? '';
+    if (letters.length === 0 && digits.length === 0) {
+        throw new SyntaxError(`invalid cell reference: "${reference}"`);
+    }
+    const col = letters.length > 0 ? columnToNumber(letters) : undefined;
+    const row = digits.length > 0 ? Number.parseInt(digits, 10) : undefined;
+    return { address: `${letters}${digits}`, col, row };
+}
+/**
+ * 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.
+ */
+export function decodeRange(reference) {
+    const prefix = SHEET_PREFIX.exec(reference);
+    let sheetName;
+    let body = reference;
+    if (prefix) {
+        const quoted = prefix[1];
+        sheetName = quoted !== undefined ? quoted.replace(/''/g, "'") : prefix[2];
+        body = prefix[3] ?? '';
+    }
+    const parts = body.split(':');
+    const start = decodeAddress(parts[0] ?? '');
+    const end = parts.length > 1 ? decodeAddress(parts[1] ?? '') : start;
+    const cols = [start.col, end.col].filter((v) => v !== undefined);
+    const rows = [start.row, end.row].filter((v) => v !== undefined);
+    const left = cols.length > 0 ? Math.min(...cols) : undefined;
+    const right = cols.length > 0 ? Math.max(...cols) : undefined;
+    const top = rows.length > 0 ? Math.min(...rows) : undefined;
+    const bottom = rows.length > 0 ? Math.max(...rows) : undefined;
+    const tl = makeCellAddress(left, top);
+    const br = makeCellAddress(right, bottom);
+    return {
+        top,
+        left,
+        bottom,
+        right,
+        ...(sheetName !== undefined ? { sheetName } : {}),
+        tl,
+        br,
+        dimensions: `${tl.address}:${br.address}`,
+    };
+}
+/** Encode a 1-based `col`/`row` pair into its canonical A1 address (`"B2"`). */
+export function encodeAddress(col, row) {
+    if (!Number.isInteger(row) || row < 1) {
+        throw new RangeError(`row ${row} is out of bounds — rows start at 1`);
+    }
+    return `${numberToColumn(col)}${row}`;
+}

package/dist/core/autofilter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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
+ * records the criteria a column is actively filtered by.
+ */
+export interface AutoFilter {
+    /** The filtered region in canonical `A1:C10` form; its top row is the header the dropdowns sit on. */
+    readonly ref: string;
+    /** The columns actively narrowed, each addressed by its offset from the range's left edge. Empty
+     *  when the filter only draws dropdowns without hiding any row. */
+    readonly columns: readonly FilterColumn[];
+}
+/** One filtered column, addressed by its 0-based offset (`colId`) from the filter range's left edge. */
+export interface FilterColumn {
+    readonly colId: number;
+    readonly criteria: FilterCriteria;
+}
+/** The two criteria kinds this library models: a discrete value set, or operator predicates. */
+export type FilterCriteria = ValuesFilter | CustomFilter;
+/**
+ * A column narrowed to a discrete set of allowed values — the checkbox list in Excel's dropdown.
+ * A row survives when its cell in this column matches one of {@link values} (or is blank, when
+ * {@link blank} is set).
+ */
+export interface ValuesFilter {
+    readonly kind: 'values';
+    readonly values: readonly string[];
+    readonly blank: boolean;
+}
+/**
+ * A column narrowed to one or two operator predicates (`> 6`, `<> "draft"`). Two predicates are
+ * AND-combined when {@link and} is set, else OR-combined; Excel permits at most two.
+ */
+export interface CustomFilter {
+    readonly kind: 'custom';
+    readonly and: boolean;
+    readonly predicates: readonly CustomFilterPredicate[];
+}
+export interface CustomFilterPredicate {
+    readonly operator: CustomFilterOperator;
+    /** The comparison operand, kept as its raw string form (a number, or wildcard text like `a*`). */
+    readonly val: string;
+}
+export type CustomFilterOperator = 'equal' | 'notEqual' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual';
+/** Narrow a raw `operator` attribute to a known {@link CustomFilterOperator}. */
+export declare function isCustomFilterOperator(value: string): value is CustomFilterOperator;
+/**
+ * Validate and normalise a settable autofilter into its canonical stored form. A bare range string
+ * is the common case (dropdowns, no criteria); an {@link AutoFilter} object carries per-column
+ * criteria too. Throws when the range is not a bounded rectangle, or a column's `colId` falls
+ * outside it, or a custom filter does not carry one or two predicates — a filter authored wrong is
+ * a bug to surface, not to silently repair. (The reader sanitises hostile input before it reaches
+ * here, so load never trips these guards.)
+ */
+export declare function canonicalizeAutoFilter(input: string | AutoFilter): AutoFilter;

package/dist/core/autofilter.js

@@ -0,0 +1,48 @@
+import { AuthoringError } from "../errors.js";
+import { decodeRange } from "./address.js";
+const CUSTOM_FILTER_OPERATORS = new Set([
+    'equal',
+    'notEqual',
+    'lessThan',
+    'lessThanOrEqual',
+    'greaterThan',
+    'greaterThanOrEqual',
+]);
+/** Narrow a raw `operator` attribute to a known {@link CustomFilterOperator}. */
+export function isCustomFilterOperator(value) {
+    return CUSTOM_FILTER_OPERATORS.has(value);
+}
+/**
+ * Validate and normalise a settable autofilter into its canonical stored form. A bare range string
+ * is the common case (dropdowns, no criteria); an {@link AutoFilter} object carries per-column
+ * criteria too. Throws when the range is not a bounded rectangle, or a column's `colId` falls
+ * outside it, or a custom filter does not carry one or two predicates — a filter authored wrong is
+ * a bug to surface, not to silently repair. (The reader sanitises hostile input before it reaches
+ * here, so load never trips these guards.)
+ */
+export function canonicalizeAutoFilter(input) {
+    const ref = typeof input === 'string' ? input : input.ref;
+    const { top, left, bottom, right, dimensions } = decodeRange(ref);
+    if (top === undefined || left === undefined || bottom === undefined || right === undefined) {
+        throw new AuthoringError(`autofilter range "${ref}" must be a bounded rectangle`);
+    }
+    if (typeof input === 'string')
+        return { ref: dimensions, columns: [] };
+    const width = right - left + 1;
+    return {
+        ref: dimensions,
+        columns: input.columns.map((column) => canonicalizeColumn(column, width)),
+    };
+}
+function canonicalizeColumn(column, width) {
+    if (!Number.isInteger(column.colId) || column.colId < 0 || column.colId >= width) {
+        throw new AuthoringError(`autofilter colId ${column.colId} is outside the filter range`);
+    }
+    if (column.criteria.kind === 'custom') {
+        const count = column.criteria.predicates.length;
+        if (count < 1 || count > 2) {
+            throw new AuthoringError(`a custom filter needs one or two predicates, got ${count}`);
+        }
+    }
+    return column;
+}

package/dist/core/cell.d.ts

@@ -0,0 +1,132 @@
+import { NAMED_STYLE_ID } from './internal.ts';
+import { type Alignment, type Border, type CellStyle, type Fill, type Font, type Protection } from './style.ts';
+import { type CellValue, type RichTextRun, type ValueType } from './value.ts';
+import type { CellModel } from './worksheet.ts';
+/**
+ * A single cell owns its value and every style facet outright. Each facet below — fill, number format,
+ * font, border, alignment, protection, quote-prefix, and note — is held in the cell's own field and
+ * *replaced* (never mutated in place) by its setter, so a facet set on one cell never aliases or bleeds
+ * onto its row, column, or sheet siblings. Each facet's own doc covers only what is specific to it.
+ */
+export declare class Cell {
+    #private;
+    /** 1-based row index. */
+    readonly row: number;
+    /** 1-based column index. */
+    readonly col: number;
+    constructor(row: number, col: number);
+    /** Canonical A1 address of this cell (`"B3"`). */
+    get address(): string;
+    /** The cell's value; `null` when empty. Assigning `undefined` clears it. */
+    get value(): CellValue;
+    set value(value: CellValue | undefined);
+    /** The observable {@link ValueType} of the current value. */
+    get type(): ValueType;
+    /**
+     * Assign rich text whose runs **inherit this cell's font**, so a run needs to state only what it
+     * changes: `setRichText([{text: 'Note:', font: {bold: true}}, {text: ' the rest'}])` keeps the
+     * cell's typeface, size and colour throughout and bolds the first run.
+     *
+     * This exists because a run's format element does **not** inherit anything. A `<rPr>` is a
+     * *complete* character format, and any facet it omits falls back to the workbook default font
+     * ({@link Workbook.defaultFont}) — not to the cell's. Verified against Excel: a cell set to
+     * Courier New 16 whose first run carries only `<b/>` renders that run in the workbook default face
+     * at the default size, bold, while the rest of the cell renders Courier New 16. So a run authored
+     * as `{bold: true}` beside a styled cell silently loses the face, which is the format's rule rather
+     * than a bug — and the reason this is a helper rather than a change to how runs are written.
+     *
+     * Composition is per facet: a facet the run names wins, one it omits comes from the cell. Assigning
+     * `value` directly stays the bare path, for a caller who wants a run that deliberately falls back
+     * to the workbook default.
+     *
+     * A cell that names no font of its own needs no composition — an omitted facet already falls back
+     * to the workbook default, which is exactly what such a cell renders in — so the runs pass through
+     * unchanged.
+     */
+    setRichText(runs: readonly RichTextRun[]): void;
+    /**
+     * The cell's full style — fill, number format, font, border, alignment, and protection — as one
+     * {@link CellStyle}, for restyling a cell wholesale without importing {@link applyCellStyle}
+     * separately (mirrors {@link Worksheet.model}'s getter/setter pair for the whole sheet). The
+     * getter carries only the facets this cell has set (the same shape {@link cellToModel} emits);
+     * the setter lays each facet `style` carries onto this cell — like every per-facet setter, it
+     * replaces that facet outright but leaves a facet `style` omits untouched, so `cell.style = {...}`
+     * composes with prior per-facet sets rather than clearing them wholesale.
+     */
+    get style(): CellStyle;
+    set style(style: Readonly<CellStyle>);
+    /** The cell's background fill, or `undefined` when it has none. */
+    get fill(): Fill | undefined;
+    set fill(fill: Fill | undefined);
+    /**
+     * The cell's number-format code (`"0.00%"`, a custom accounting format, …), or
+     * `undefined` for the General format. Stored verbatim: the invariant form Excel
+     * persists — `.` decimal, `,` grouping, `/` date separator — is neither localized
+     * nor rewritten, so the code round-trips character-for-character. A cell that also carries
+     * a column-level format keeps both, so overriding one facet never drops the other.
+     */
+    get numFmt(): string | undefined;
+    set numFmt(numFmt: string | undefined);
+    /**
+     * The cell's font — bold/italic/underline, size, colour, typeface — as a partial set
+     * of the facets that differ from the default (only the facets actually set are carried,
+     * exactly as OOXML stores them). `undefined` means the cell uses the workbook default font.
+     */
+    get font(): Font | undefined;
+    set font(font: Font | undefined);
+    /**
+     * The cell's border — the line style and colour of each side — or `undefined` when the
+     * cell has none. An absent edge within a border means that side is unbordered, so reading
+     * a cell never fabricates a border it does not have.
+     */
+    get border(): Border | undefined;
+    set border(border: Border | undefined);
+    /**
+     * The cell's alignment — how its content sits within the cell, plus the wrap/shrink flags —
+     * or `undefined` when it uses the defaults. The boolean flags are off unless explicitly set,
+     * so a cell that never enabled wrapping never reads back wrapped.
+     */
+    get alignment(): Alignment | undefined;
+    set alignment(alignment: Alignment | undefined);
+    /**
+     * The cell's protection — its locked/hidden flags, enforced only once the sheet is protected —
+     * or `undefined` when the cell carries neither. `locked` defaults to on in OOXML, so a cell
+     * that never touched protection is implicitly locked and reads back as `undefined`, not as
+     * `{locked: true}`; the flag only becomes explicit when a cell is unlocked.
+     */
+    get protection(): Protection | undefined;
+    set protection(protection: Protection | undefined);
+    /**
+     * The quote-prefix flag: when set, a spreadsheet stores the cell's content as literal text even
+     * when it looks like a formula or number, and shows a leading apostrophe in the formula bar without
+     * that apostrophe being part of the stored value. `undefined` (or `false`) when unset. It is a
+     * cell-format flag — an attribute on the cell's `xf` record — so it composes independently of the
+     * value.
+     */
+    get quotePrefix(): boolean | undefined;
+    set quotePrefix(quotePrefix: boolean | undefined);
+    /**
+     * The index of the named cell style this cell links to (its OOXML `xfId`), or `undefined` when the
+     * cell references no named style beyond the default. The cell inherits any facet its own direct
+     * format leaves unset from that named style; the reader resolves the effective look onto the cell's
+     * own facets, and this link is preserved so a round-trip keeps the cell tied to its named style
+     * rather than flattening it away.
+     *
+     * Codec-only: an index is meaningful only against the workbook's `namedStyles` table as the reader
+     * built it, and a value naming no entry leaves the cell pointing at nothing. Authors set the facets
+     * they want directly.
+     */
+    get [NAMED_STYLE_ID](): number | undefined;
+    set [NAMED_STYLE_ID](namedStyleId: number | undefined);
+    /**
+     * The cell's note (comment) as plain text, or `undefined` when it carries none. A note is
+     * metadata anchored to the cell, independent of its value: a cell can hold a note while empty,
+     * and clearing the value leaves the note intact. A structural edit that shifts the cell carries the
+     * note along to its new position.
+     */
+    get note(): string | undefined;
+    set note(note: string | undefined);
+}
+export declare function applyCellStyle(cell: Cell, style: Readonly<CellStyle>): void;
+export declare function copyCellContent(source: CellModel, target: Cell): void;
+export declare function cellToModel(cell: Cell): CellModel;