@shbernal/ts-xlsx 1.3.1 → 2.0.0

package/dist/core/date.d.ts

@@ -1,6 +1,6 @@
 /**
  * The number format applied to a `Date` cell that carries no explicit format of its own,
- * so the value renders — and reads back — as a date rather than a bare serial number.
+ * so the value renders, and reads back, as a date rather than a bare serial number.
  */
 export declare const DEFAULT_DATE_NUMFMT = "yyyy-mm-dd";
 /**
@@ -17,8 +17,8 @@ export declare function dateToSerial(date: Date): number;
 export declare function serialToDate(serial: number): Date;
 /**
  * Whether a number-format code renders its value as a date or time. A format is a date
- * format when, once its non-formatting sections are removed — bracketed color/locale/
- * condition directives, quoted literals, and escaped characters — any of the date/time
+ * format when, once its non-formatting sections are removed (bracketed color/locale/
+ * condition directives, quoted literals, and escaped characters) any of the date/time
  * placeholder letters (`y m d h s`) remain. So `"$"#,##0.00` and `0.00%` are not dates
  * while `yyyy-mm-dd`, `dd/mm/yyyy`, and `[$-409]mmmm d, yyyy` are.
  */

package/dist/core/formula.d.ts

@@ -1,12 +1,12 @@
 /**
  * Quote a sheet name for use in a reference exactly when Excel would: a name that is not a plain
- * identifier — or that would read as a cell address — is wrapped in single quotes with its internal
+ * identifier, or that would read as a cell address, is wrapped in single quotes with its internal
  * quotes doubled, and a simple name is left bare. Shared by everything that *builds* a qualified
  * reference: the `_FilterDatabase` name the writer derives from an autofilter, and the `.xlsb`
  * reader's Ptg decoder, which has only a sheet index to work from and must spell the prefix itself.
  *
  * `last` names the far end of a 3-D span (`Data:More!A1`). A span is quoted as a whole or not at all,
- * because the quotes delimit the sheet *reference* rather than either name — so one awkward endpoint
+ * because the quotes delimit the sheet *reference* rather than either name, so one awkward endpoint
  * puts both inside the quotes.
  */
 export declare function quoteSheetName(name: string, last?: string): string;
@@ -14,7 +14,7 @@ export declare function quoteSheetName(name: string, last?: string): string;
  * Prefix every modern function called by its plain name with `_xlfn.` so Excel accepts the stored
  * formula. Names already prefixed are left alone (never doubled), unknown/legacy functions pass
  * through untouched, and opaque regions (string literals, sheet names, structured references) are
- * preserved verbatim. No other rewriting occurs — in particular no `@` implicit-intersection operator
+ * preserved verbatim. No other rewriting occurs: in particular no `@` implicit-intersection operator
  * is ever introduced.
  */
 export declare function mangleFunctions(formula: string): string;
@@ -25,8 +25,8 @@ export declare function mangleFunctions(formula: string): string;
  */
 export declare function unmangleFunctions(formula: string): string;
 /**
- * Prefix every LET/LAMBDA parameter identifier with `_xlpm.` — at its declaration and at each
- * reference within the binding call's parentheses — so Excel accepts the stored formula. The prefix
+ * Prefix every LET/LAMBDA parameter identifier with `_xlpm.`, at its declaration and at each
+ * reference within the binding call's parentheses, so Excel accepts the stored formula. The prefix
  * is lexically scoped: a name is only rewritten inside the call that binds it, opaque regions are
  * copied verbatim, and a lambda-valued parameter used as a call (`f(…)`) is prefixed too. Formulas
  * with no LET/LAMBDA pass through unchanged.
@@ -34,7 +34,7 @@ export declare function unmangleFunctions(formula: string): string;
 export declare function mangleParams(formula: string): string;
 /**
  * Mangle a model formula into its on-disk form: LET/LAMBDA parameter names first (`_xlpm.`), then the
- * modern-function prefix (`_xlfn.`). Ordering matters — parameter mangling reads the plain LET/LAMBDA
+ * modern-function prefix (`_xlfn.`). Ordering matters: parameter mangling reads the plain LET/LAMBDA
  * names before the function pass qualifies them. The inverse for both prefixes is unmangleFunctions.
  */
 export declare function mangleFormula(formula: string): string;

package/dist/core/grid-edits.js

@@ -1,4 +1,4 @@
-import { decodeAddress, decodeRange, encodeAddress } from './address.js';
+import { decodeRange, encodeAddress, tryDecodeCellRef } from './address.js';
 import { Cell, copyCellContent } from './cell.js';
 import { replaceContents } from './containers.js';
 import { isOneCellAnchor } from './image.js';
@@ -95,8 +95,8 @@ export class GridEdits {
                 const value = cell.value;
                 if (!isSharedFormulaValue(value))
                     continue;
-                const master = decodeAddress(value.sharedFormula);
-                if (master.col === undefined || master.row === undefined)
+                const master = tryDecodeCellRef(value.sharedFormula);
+                if (master === undefined)
                     continue;
                 const anchored = axis === 'row'
                     ? encodeAddress(master.col, shiftIndex(master.row, start, count, delta))

package/dist/core/image.d.ts

@@ -17,7 +17,7 @@ export declare const PX_TO_EMU = 9525;
  * them; `oneCell` moves but keeps its size; `absolute` is pinned to the page and does neither. Excel
  * defaults to `oneCell` when the attribute is omitted. */
 export type ImageEditAs = 'oneCell' | 'twoCell' | 'absolute';
-/** A fixed image size in EMUs — the extent of a one-cell anchor, which pixel dimensions convert into
+/** A fixed image size in EMUs: the extent of a one-cell anchor, which pixel dimensions convert into
  * via {@link PX_TO_EMU}. */
 export interface Extent {
     readonly cx: number;
@@ -63,7 +63,7 @@ export interface AnchoredImage {
 }
 /** A picture's bytes and its file kind, as held in the workbook's media registry. */
 export interface WorkbookImage {
-    /** Lower-case file extension without a dot — `"png"`, `"jpeg"`, `"gif"`. Drives the media part's
+    /** Lower-case file extension without a dot: `"png"`, `"jpeg"`, `"gif"`. Drives the media part's
      * name and content type. */
     readonly extension: string;
     readonly data: Uint8Array;
@@ -74,3 +74,38 @@ export interface WorkbookImage {
  * leading run of alphanumerics; a missing or all-punctuation hint falls back to sniffing the bytes'
  * magic number, so the package is always well-formed. */
 export declare function normalizeImageExtension(extension: string | undefined, data: Uint8Array): string;
+/**
+ * An anchored image in workbook-independent form: the picture's own bytes rather than a media id
+ * into one particular workbook's registry.
+ *
+ * An {@link AnchoredImage} means nothing away from that registry: its `imageId` is an index, and
+ * the same index names a different picture (or none) in the next workbook. Attaching the picture
+ * itself is what lets an anchor cross that boundary, which is why the transfer form carries bytes
+ * where the stored form carries an id.
+ */
+export interface PortableImage {
+    readonly image: WorkbookImage;
+    readonly anchor: ImageAnchor;
+}
+/**
+ * Every picture a worksheet shows, in the workbook-independent form of {@link PortableImage}: the
+ * images anchored to the grid, in the order they were added, and the background tiled behind it.
+ * {@link Workbook.exportImages} produces one, {@link Workbook.importImages} applies one.
+ */
+export interface WorksheetImages {
+    readonly anchored: readonly PortableImage[];
+    readonly background: WorkbookImage | undefined;
+}
+/**
+ * The id under which `image` is already registered in `media`, or `undefined` if it is not.
+ *
+ * Content-addressed rather than reference-addressed: two byte-identical pictures are one picture,
+ * however they reached the registry. This is what keeps repeated imports from growing the media
+ * list without bound (the same logo carried onto twenty sheets registers once), and it is why the
+ * comparison is over bytes rather than object identity, which a picture arriving from another
+ * workbook would never satisfy.
+ *
+ * The length check comes first and short-circuits, so pictures of different sizes never reach the
+ * byte loop; only same-extension, same-length candidates are compared in full.
+ */
+export declare function findRegisteredImage(media: readonly WorkbookImage[], image: WorkbookImage): number | undefined;

package/dist/core/image.js

@@ -38,3 +38,9 @@ export function normalizeImageExtension(extension, data) {
     }
     return sniffImageExtension(data);
 }
+export function findRegisteredImage(media, image) {
+    const index = media.findIndex((held) => held.extension === image.extension &&
+        held.data.length === image.data.length &&
+        held.data.every((byte, i) => byte === image.data[i]));
+    return index === -1 ? undefined : index;
+}

package/dist/core/internal.d.ts

@@ -4,8 +4,16 @@
  */
 export declare const INTERNAL: unique symbol;
 /**
- * Keys a `Cell`'s link to a named cell style — its OOXML `xfId`. A single hidden property rather than
+ * Keys a `Cell`'s link to a named cell style, its OOXML `xfId`. A single hidden property rather than
  * a channel object, so it stays a prototype accessor: cells are the one model class allocated in the
  * millions, and a per-instance internals object would be a real cost for state most cells never carry.
  */
 export declare const NAMED_STYLE_ID: unique symbol;
+/**
+ * The exhaustiveness proof the mirror types are built on: instantiate it with a `keyof` difference
+ * that should be empty. An unmirrored field leaves that difference non-`never`, which does not
+ * satisfy the constraint, so the build fails naming the field that was missed: a type error at the
+ * declaration rather than a silent hole discovered by a round trip. `Row`, `Column` and
+ * `WORKSHEET_MODEL_FACETS` each carry one of these proofs; this is the mechanism all three use.
+ */
+export type AssertNever<T extends never> = T;

package/dist/core/limits.d.ts

@@ -4,8 +4,8 @@
  * shown.
  *
  * A file may state more, and stating more loses the value rather than the file. Excel opens such a
- * package without complaint and silently clamps the row — to 409.6, a tick *above* what it lets
- * you assign, being 8192 twentieths of a point and so the width of the field it is read into — and
+ * package without complaint and silently clamps the row to 409.6, a tick *above* what it lets you
+ * assign, being 8192 twentieths of a point and so the width of the field it is read into, then
  * writes 409.6 back on its next save. Check against this constant to keep a stated height from
  * quietly becoming a different one.
  */
@@ -16,12 +16,12 @@ export declare const MAX_ROW_HEIGHT = 409.5;
  *
  * It is also the weaker of the two ceilings: it binds assignment only, and not a file at all.
  * Excel honours a `width` of 1000 read from a package, renders the column at it, and round-trips
- * it verbatim through its own save — where an over-limit row height is clamped away. So a width
+ * it verbatim through its own save, where an over-limit row height is clamped away. So a width
  * above this is a column no Excel user could have produced by dragging, not a value at risk.
  *
  * Character units, not points or pixels: a width is a count of digits of the default font's
  * *maximum digit width*, which is why there is no companion `DEFAULT_COLUMN_WIDTH` constant here.
- * The width a column takes when it states none is a function of that font — the familiar 8.43 holds
+ * The width a column takes when it states none is a function of that font: the familiar 8.43 holds
  * for Calibri 11 and not for a workbook whose normal style says otherwise (Excel reports 8.09 for
  * Aptos Narrow 11). `sheet.properties.defaultColWidth` is what a file declares, and
  * docs/knowledge/specs/default-font-must-not-be-assumed-for-column-widths.md is why assuming a

package/dist/core/merge.d.ts

@@ -1,17 +1,11 @@
+import { type GridRect } from './address.ts';
 import type { Cell } from './cell.ts';
-/** A merged region as inclusive 1-based grid bounds. */
-export interface MergeRect {
-    readonly top: number;
-    readonly left: number;
-    readonly bottom: number;
-    readonly right: number;
-}
-/** Whether two inclusive grid rectangles share at least one cell. */
-export declare function rectsOverlap(a: MergeRect, b: MergeRect): boolean;
+/** A merged region, as the {@link GridRect} every range-shaped thing in the library is. */
+export type MergeRect = GridRect;
 /**
  * Resolve a position to the master (top-left) of the merged region covering it, or to itself when no
  * region does. First covering region wins; `Worksheet.mergeCells` rejects overlaps, so at most one
- * region ever applies. Only fully-bounded rects participate — an unbounded whole-row/column merge
+ * region ever applies. Only fully-bounded rects participate: an unbounded whole-row/column merge
  * carries no rect and so resolves nothing.
  */
 export declare function masterOf(rects: readonly MergeRect[], row: number, col: number): {
@@ -20,12 +14,12 @@ export declare function masterOf(rects: readonly MergeRect[], row: number, col:
 };
 /**
  * Drop any value already sitting in a merge's covered non-anchor cells, keeping only the top-left
- * anchor — the collapse Excel performs on merge. A leftover covered value would serialise as a
+ * anchor, the collapse Excel performs on merge. A leftover covered value would serialise as a
  * populated `<c>` under the range's `<mergeCell>` ref, the geometry that trips Excel's repair prompt.
  * Styles are untouched: a border spanning the merged region rides the covered cells.
  */
 export declare function clearCoveredValues(rows: Map<number, Map<number, Cell>>, rect: MergeRect): void;
 /** Decode an OOXML `sqref` (one or more space-separated ranges) into containment rectangles. A whole
  * column or row leaves one axis unbounded, so its missing edges open to `Infinity` rather than
- * clamping — a cell anywhere down the column still resolves inside it. */
+ * clamping: a cell anywhere down the column still resolves inside it. */
 export declare function decodeSqrefRects(sqref: string): MergeRect[];

package/dist/core/merge.js

@@ -1,7 +1,4 @@
 import { decodeRange } from './address.js';
-export function rectsOverlap(a, b) {
-    return a.left <= b.right && b.left <= a.right && a.top <= b.bottom && b.top <= a.bottom;
-}
 export function masterOf(rects, row, col) {
     for (const rect of rects) {
         if (row >= rect.top && row <= rect.bottom && col >= rect.left && col <= rect.right) {

package/dist/core/page-setup.d.ts

@@ -3,7 +3,7 @@
  * `<pageSetUpPr>` flag (a `<sheetPr>` child) that switches Excel from fixed-zoom to fit-to-page
  * scaling, while the rest are `<pageSetup>` attributes. Excel honours `scale` only when `fitToPage`
  * is off and the `fitToWidth`/`fitToHeight` page counts only when it is on, but the model carries
- * whatever the author set — an unset field is omitted so a round-trip never fabricates one. An
+ * whatever the author set: an unset field is omitted so a round-trip never fabricates one. An
  * empty object emits neither element.
  */
 export interface PageSetup {
@@ -21,7 +21,7 @@ export interface PageSetup {
     pageOrder?: 'downThenOver' | 'overThenDown';
     /**
      * Paper size as Excel's 1-based enumeration index (e.g. `9` = A4, `1` = US Letter). Carried as an
-     * opaque integer — the model does not map it to physical dimensions, only preserves whatever the
+     * opaque integer: the model does not map it to physical dimensions, only preserves whatever the
      * author or source file set.
      */
     paperSize?: number;
@@ -35,7 +35,7 @@ export interface PageSetup {
 }
 /**
  * Print-toggle flags from the `<printOptions>` element. Each maps to a boolean OOXML attribute that
- * defaults false — except `gridLinesSet`, which defaults true and gates whether `gridLines` is
+ * defaults false, except `gridLinesSet`, which defaults true and gates whether `gridLines` is
  * honoured. The model stores only what the source or caller set, so an unset flag is omitted and a
  * round-trip never fabricates one; an empty object emits no element at all.
  */
@@ -54,7 +54,7 @@ export interface PrintOptions {
 /**
  * A manual page break (`<brk>`). For a row break, `id` is the row the layout splits *before*; for a
  * column break it is the column. `max` bounds the break's extent across the other axis (Excel writes
- * the last row/column index) and `man` marks it author-set rather than automatic — the model preserves
+ * the last row/column index) and `man` marks it author-set rather than automatic. The model preserves
  * whatever the source carried so a round-trip reproduces the break's span exactly.
  */
 export interface PageBreak {

package/dist/core/pivot-table.d.ts

@@ -3,12 +3,10 @@ import type { Worksheet } from './worksheet.ts';
  * names verbatim, so a metric doubles as its `<dataField subtotal="…">` value. Excel performs the
  * aggregation itself on refresh; the writer only records which function to apply. */
 export type PivotMetric = 'sum' | 'count' | 'countNums' | 'average' | 'max' | 'min' | 'product' | 'stdDev' | 'stdDevp' | 'var' | 'varp';
-/** Narrow a raw `subtotal` attribute (or any string) to a known {@link PivotMetric}. */
-export declare function isPivotMetric(value: string): value is PivotMetric;
 /** Map an OOXML `<dataField subtotal="…">` value back to its metric. The attribute is absent for
  * `sum` (Excel's implicit default), so `undefined` reads as `sum`; an unrecognised value also reads
- * as `sum` rather than throwing, because reconstructing an existing file is a lenient operation —
- * the strict rejection of unknown metrics belongs on the authoring path, not the read path. */
+ * as `sum` rather than throwing, because reconstructing an existing file is a lenient operation.
+ * The strict rejection of unknown metrics belongs on the authoring path, not the read path. */
 export declare function pivotMetricFromSubtotal(subtotal: string | undefined): PivotMetric;
 /** One field in a loaded pivot's cache catalogue, in declared order; the pivot refers to it by index. */
 export interface ParsedPivotField {

package/dist/core/pivot-table.js

@@ -14,7 +14,7 @@ const PIVOT_METRICS = new Set([
     'var',
     'varp',
 ]);
-export function isPivotMetric(value) {
+function isPivotMetric(value) {
     return PIVOT_METRICS.has(value);
 }
 export function pivotMetricFromSubtotal(subtotal) {
@@ -35,7 +35,7 @@ export class PivotTable {
     constructor(options) {
         const metric = options.metric ?? 'sum';
         if (!PIVOT_METRICS.has(metric)) {
-            throw new AuthoringError(`unsupported pivot metric "${metric}" — expected one of ${[...PIVOT_METRICS].join(', ')}`);
+            throw new AuthoringError(`unsupported pivot metric "${metric}": expected one of ${[...PIVOT_METRICS].join(', ')}`);
         }
         this.metric = metric;
         const source = options.source;
@@ -110,7 +110,7 @@ export class PivotTable {
             records.push(fields.map((_field, fieldIndex) => {
                 const scalar = scalarsForField(columnScalars, fieldIndex)[row];
                 if (scalar === undefined) {
-                    throw new InternalError(`pivot record row ${row} is out of range for field ${fieldIndex} — every column was ` +
+                    throw new InternalError(`pivot record row ${row} is out of range for field ${fieldIndex}: every column was ` +
                         'scanned for the same dataRowCount above, so this index is always in range');
                 }
                 const catalogue = catalogues[fieldIndex];
@@ -127,7 +127,7 @@ export class PivotTable {
     get valueFieldName() {
         const field = this.cacheFields[this.valueField];
         if (field === undefined) {
-            throw new InternalError(`pivot valueField index ${this.valueField} is out of range — resolve() validated it against ` +
+            throw new InternalError(`pivot valueField index ${this.valueField} is out of range: resolve() validated it against ` +
                 'the same fields array cacheFields was built from');
         }
         return field.name;
@@ -136,7 +136,7 @@ export class PivotTable {
 function scalarsForField(columnScalars, fieldIndex) {
     const scalars = columnScalars[fieldIndex];
     if (scalars === undefined) {
-        throw new InternalError(`pivot field index ${fieldIndex} is out of range for columnScalars — it was built from the same fields array`);
+        throw new InternalError(`pivot field index ${fieldIndex} is out of range for columnScalars: it was built from the same fields array`);
     }
     return scalars;
 }

package/dist/core/preserved.d.ts

@@ -2,7 +2,7 @@
  * One outbound relationship of a {@link PreservedPart}: the id it carries inside its own rels part,
  * the relationship Type URI, and its target. An internal relationship's `targetPath` is the resolved
  * package path of the part it points at (the writer re-numbers and rewires it); an `external`
- * relationship's `targetPath` is the raw `Target` verbatim (a linked workbook's path or URL) — it is
+ * relationship's `targetPath` is the raw `Target` verbatim (a linked workbook's path or URL). It is
  * outside the package, so it is emitted unchanged with `TargetMode="External"` and never remapped.
  * Preserving external relationships is what keeps an `externalLink` part's pointer to its source
  * workbook alive, so a round-trip does not orphan the `[n]` external references formulas resolve through.
@@ -26,7 +26,7 @@ export interface PreservedPart {
     readonly rels: readonly PreservedRelationship[];
 }
 /**
- * A worksheet-level reference to package content the model does not model — preserved verbatim across
+ * A worksheet-level reference to package content the model does not model, preserved verbatim across
  * a round-trip instead of being silently dropped. `element` is the worksheet child that wires the
  * reference (`<drawing>` for a vector-shape drawing, `<legacyDrawingHF>` for a header/footer image),
  * or `undefined` when the sheet wires it by relationship alone (a pivot table or slicer Excel
@@ -43,7 +43,7 @@ export interface PreservedWorksheetReference {
 }
 /**
  * A package-root reference to content the model does not model, wired from the package's own
- * `_rels/.rels` rather than the workbook part's rels — the ribbon-customisation parts
+ * `_rels/.rels` rather than the workbook part's rels: the ribbon-customisation parts
  * (`customUI/customUI14.xml`), custom document properties (`docProps/custom.xml`), a thumbnail, and
  * anything else hung off the root. The writer regenerates the root rels for the parts it models
  * (workbook, core/app properties), so these would be dropped unless captured here and re-declared.

package/dist/core/protection.d.ts

@@ -33,7 +33,7 @@ export interface SheetProtectionOptions extends SheetProtectionFlags {
 }
 /**
  * A password-derived credential, in OOXML's agile form: the hash algorithm, the salted
- * iterated hash of the password, the salt, and the iteration count — everything a consumer
+ * iterated hash of the password, the salt, and the iteration count: everything a consumer
  * needs to verify a supplied password without the password ever being stored.
  */
 export interface SheetProtectionCredential {
@@ -50,8 +50,8 @@ export interface SheetProtection {
 /**
  * The OOXML encoding table for the protection flags: each `<sheetProtection>` attribute paired
  * with whether that operation is *forbidden by default* once a sheet is protected. Both directions
- * key off this one list — the writer turns an author allow-flag into an attribute (omitting values
- * equal to the default), the reader turns an attribute back into an allow-flag — so serialization
+ * key off this one list. The writer turns an author allow-flag into an attribute (omitting values
+ * equal to the default) and the reader turns an attribute back into an allow-flag, so serialization
  * and deserialization can never fall out of step. Most editing operations default to forbidden
  * under protection; selecting cells and the object/scenario operations default to permitted.
  */
@@ -61,7 +61,7 @@ export declare const SHEET_PROTECTION_FLAGS: readonly {
 }[];
 /**
  * Derive a fresh {@link SheetProtectionCredential} for a password. Each call generates a new
- * random salt, so protecting two sheets with the same password yields different credentials —
+ * random salt, so protecting two sheets with the same password yields different credentials:
  * the salt is real randomness, not a stub.
  */
 export declare function deriveCredential(password: string, spinCount?: number): SheetProtectionCredential;

package/dist/core/range.d.ts

@@ -1,18 +1,20 @@
+import { type GridRect } from './address.ts';
 import { type Cell } from './cell.ts';
 import { type Alignment, type Border, type CellStyle, type Fill, type Font, type Protection } from './style.ts';
 import type { Worksheet } from './worksheet.ts';
 /**
  * A rectangular block of a worksheet's cells: `sheet.getRange('B2:D5')`.
  *
- * Cheap and stateless — constructing one creates no cells and does not extend the used range.
+ * Cheap and stateless: constructing one creates no cells and does not extend the used range.
  * {@link addresses} walks the block without materialising anything; {@link cells} reports only what
  * already exists.
  *
  * Bounds are **inclusive first/last**, never start-and-count. That is the convention every
  * range-shaped accessor in this library follows, so the three axes cannot disagree about what a
- * pair of numbers means.
+ * pair of numbers means; the handle is declared to satisfy {@link GridRect}, which is that
+ * convention written down once.
  */
-export declare class Range {
+export declare class Range implements GridRect {
     #private;
     /** 1-based row of the block's top edge. Fixed for this handle's lifetime. */
     readonly top: number;
@@ -23,7 +25,7 @@ export declare class Range {
     /** 1-based column of the block's right edge, inclusive. */
     readonly right: number;
     /**
-     * Build a handle from inclusive corners, in any order — `(5, 4, 2, 2)` and `(2, 2, 5, 4)` name the
+     * Build a handle from inclusive corners, in any order: `(5, 4, 2, 2)` and `(2, 2, 5, 4)` name the
      * same block, exactly as `D5:B2` and `B2:D5` do. Prefer {@link Worksheet.getRange}.
      *
      * @throws {RangeError} if a corner is not a positive integer or falls outside the sheet's bounds.
@@ -31,30 +33,30 @@ export declare class Range {
     constructor(sheet: Worksheet, top: number, left: number, bottom: number, right: number);
     /** The worksheet this block belongs to. */
     get sheet(): Worksheet;
-    /** Canonical `tl:br` A1 form — `"B2:D5"`. A one-cell block still reads as `"B2:B2"`. */
+    /** Canonical `tl:br` A1 form, `"B2:D5"`. A one-cell block still reads as `"B2:B2"`. */
     get address(): string;
     /** Rows spanned, inclusive of both edges. */
     get rowCount(): number;
     /** Columns spanned, inclusive of both edges. */
     get columnCount(): number;
-    /** Cells the block covers — `rowCount * columnCount`, whether or not they exist yet. */
+    /** Cells the block covers: `rowCount * columnCount`, whether or not they exist yet. */
     get cellCount(): number;
     /** Whether a 1-based position falls inside the block. */
     contains(row: number, col: number): boolean;
     /**
      * Every address the block covers, row-major (`B2`, `C2`, `D2`, `B3`, …). Materialises nothing, so
-     * this is the cheap way to walk a large block — and, being a generator, it can be abandoned
+     * this is the cheap way to walk a large block, and, being a generator, it can be abandoned
      * part-way without having built the whole list.
      */
     addresses(): IterableIterator<string>;
     /**
      * The block's **materialised** cells, row-major. Sparse: a position nothing has ever written to is
      * simply absent, which is what distinguishes "never written" from a cell holding `null`. Reading
-     * this creates nothing — mirroring {@link Column.cells}.
+     * this creates nothing, mirroring {@link Column.cells}.
      */
     get cells(): readonly Cell[];
     /**
-     * The block's style, facet by facet — the counterpart of {@link Cell.style} over a rectangle, with
+     * The block's style, facet by facet: the counterpart of {@link Cell.style} over a rectangle, with
      * the same semantics in both directions.
      *
      * **Reading** reports a facet only when *every* position in the block carries a structurally
@@ -62,13 +64,13 @@ export declare class Range {
      * through this handle therefore reads back what was written; a block whose cells disagree says so
      * rather than picking a corner's answer and passing it off as the whole.
      *
-     * **Writing** lays each facet the payload names onto every cell, leaving facets it omits untouched
-     * — exactly what `cell.style = {...}` does, so this composes with prior styling instead of clearing
-     * it. Use {@link clearStyle} first for a wholesale replace.
+     * **Writing** lays each facet the payload names onto every cell, leaving facets it omits
+     * untouched, exactly what `cell.style = {...}` does, so this composes with prior styling instead
+     * of clearing it. Use {@link clearStyle} first for a wholesale replace.
      *
      * Writing **materialises** every position in the block, because a styled-but-valueless cell is the
      * only way an empty cell renders with a fill: skipping the holes would leave gaps in a header band.
-     * The cost is bounded by construction — a range is always a bounded rectangle, and whole-axis
+     * The cost is bounded by construction: a range is always a bounded rectangle, and whole-axis
      * styling belongs to {@link Worksheet.getColumn}/{@link Worksheet.getRow} instead. {@link cellCount}
      * is the exact number of cells a write will create.
      */
@@ -77,7 +79,7 @@ export declare class Range {
     /**
      * Strip every style facet from every cell in the block, leaving values untouched. Assigning
      * {@link style} composes, so this is how a wholesale replace is said: `clearStyle()` then assign.
-     * Materialises nothing — a cell that does not exist carries no style to clear.
+     * Materialises nothing: a cell that does not exist carries no style to clear.
      */
     clearStyle(): void;
     /** Fill applied to every cell in the block; `undefined` when they do not all agree. */

package/dist/core/range.js

@@ -154,22 +154,22 @@ function facetKey(value) {
 }
 function checkBound(axis, value, max) {
     if (!Number.isInteger(value) || value < 1) {
-        throw new RangeError(`${axis} ${value} is out of bounds — ${axis}s start at 1`);
+        throw new RangeError(`${axis} ${value} is out of bounds: ${axis}s start at 1`);
     }
     if (value > max) {
-        throw new RangeError(`${axis} ${value} is out of bounds — the sheet ends at ${max}`);
+        throw new RangeError(`${axis} ${value} is out of bounds: the sheet ends at ${max}`);
     }
 }
 export function rangeFrom(sheet, reference) {
     const { top, left, bottom, right, sheetName, dimensions } = decodeRange(reference);
     if (sheetName !== undefined && sheetName.toLowerCase() !== sheet.name.toLowerCase()) {
-        throw new SyntaxError(`"${reference}" names worksheet "${sheetName}", not "${sheet.name}" — a range belongs to the sheet it came from`);
+        throw new SyntaxError(`"${reference}" names worksheet "${sheetName}", not "${sheet.name}": a range belongs to the sheet it came from`);
     }
     if (top === undefined || bottom === undefined) {
-        throw new SyntaxError(`"${reference}" spans whole columns (${dimensions}) — style them through getColumn(n), which says the same thing in one attribute instead of ${MAX_ROW} cells`);
+        throw new SyntaxError(`"${reference}" spans whole columns (${dimensions}): style them through getColumn(n), which says the same thing in one attribute instead of ${MAX_ROW} cells`);
     }
     if (left === undefined || right === undefined) {
-        throw new SyntaxError(`"${reference}" spans whole rows (${dimensions}) — style them through getRow(n), which says the same thing in one attribute instead of ${MAX_COLUMN} cells`);
+        throw new SyntaxError(`"${reference}" spans whole rows (${dimensions}): style them through getRow(n), which says the same thing in one attribute instead of ${MAX_COLUMN} cells`);
     }
     return new Range(sheet, top, left, bottom, right);
 }

package/dist/core/row-input.d.ts

@@ -7,8 +7,8 @@ import type { ColumnProperties, RowInput } from './worksheet.ts';
  * untouched; a keyed object maps each value under the column carrying the matching key.
  *
  * `Array.isArray`, not `instanceof Array`: a row built in another realm (a vm context, a browser
- * iframe) is still an array but fails the identity check, and would then be walked as a keyed object —
- * placing nothing.
+ * iframe) is still an array but fails the identity check, and would then be walked as a keyed
+ * object, placing nothing.
  */
 export declare function rowPlacements(values: RowInput, columns: ReadonlyMap<number, ColumnProperties>): Array<[number, CellValue]>;
 /**
@@ -16,9 +16,3 @@ export declare function rowPlacements(values: RowInput, columns: ReadonlyMap<num
  * keyed by column. The grid-edit machinery then splices this map into place.
  */
 export declare function buildRowCells(number: number, values: RowInput, columns: ReadonlyMap<number, ColumnProperties>): Map<number, Cell>;
-/**
- * The 1-based index of the column carrying `key` (see {@link ColumnProperties.key}).
- *
- * @throws {AuthoringError} if no column declares that key.
- */
-export declare function columnIndexByKey(columns: ReadonlyMap<number, ColumnProperties>, key: string): number;

package/dist/core/row-input.js

@@ -20,10 +20,10 @@ export function buildRowCells(number, values, columns) {
     }
     return row;
 }
-export function columnIndexByKey(columns, key) {
+function columnIndexByKey(columns, key) {
     for (const [index, properties] of columns) {
         if (properties.key === key)
             return index;
     }
-    throw new AuthoringError(`no column is keyed ${JSON.stringify(key)} — set getColumn(n).key first`);
+    throw new AuthoringError(`no column is keyed ${JSON.stringify(key)}: set getColumn(n).key first`);
 }

package/dist/core/row.d.ts

@@ -1,4 +1,5 @@
 import type { Cell } from './cell.ts';
+import { type AssertNever } from './internal.ts';
 import type { Fill } from './style.ts';
 import type { CellValue } from './value.ts';
 import type { RowProperties, Worksheet } from './worksheet.ts';
@@ -6,10 +7,10 @@ export declare class Row {
     #private;
     /** 1-based row number. Fixed for this handle's lifetime. */
     readonly number: number;
-    /** @throws {RangeError} if the number is not a positive integer. */
+    /** @throws {RangeError} unless the number is an integer within Excel's row grid (1..1048576). */
     constructor(sheet: Worksheet, number: number);
     /**
-     * The row's format record if it has one, else `undefined` — a read that never fabricates, so a
+     * The row's format record if it has one, else `undefined`: a read that never fabricates, so a
      * serializer can ask every row it visits whether there are attributes to emit without giving each
      * one an empty record. Read-only on purpose: {@link height} and its siblings are how a row is
      * formatted, and they create the record on first write.
@@ -21,7 +22,7 @@ export declare class Row {
      * Not bounded here, deliberately: {@link MAX_ROW_HEIGHT} is what Excel accepts *being set*, but
      * the schema puts no ceiling on `ht` and this setter is also how the reader loads a foreign
      * file, so refusing a taller row would mean refusing a file Excel opens clean. Check against the
-     * constant when authoring — Excel silently clamps a taller row on read, so a height above it is
+     * constant when authoring: Excel silently clamps a taller row on read, so a height above it is
      * one you state and do not get.
      */
     get height(): number | undefined;
@@ -51,7 +52,7 @@ export declare class Row {
     getCell(column: number | string): Cell;
     /**
      * The row's materialised cells in ascending column order. Sparse: a column never written to has
-     * no cell here, and the array is a fresh snapshot of *which* cells exist — the cells themselves
+     * no cell here, and the array is a fresh snapshot of *which* cells exist; the cells themselves
      * are the live ones.
      */
     get cells(): readonly Cell[];
@@ -60,16 +61,15 @@ export declare class Row {
      * a column with no cell is a hole, which is what distinguishes "never written" from a cell
      * holding `null`.
      *
-     * Assigning places each value it names and leaves every other column untouched — a hole or an
+     * Assigning places each value it names and leaves every other column untouched: a hole or an
      * explicit `undefined` skips that column, and a shorter array does not clear the tail. These are
      * {@link Worksheet.addRow}'s rules, deliberately: `values` is that same row shape addressed by
-     * number rather than appended. To *replace* a row, including clearing what it held, splice it —
+     * number rather than appended. To *replace* a row, including clearing what it held, splice it:
      * `sheet.spliceRows(n, 1, values)`.
      */
     get values(): (CellValue | undefined)[];
     set values(values: (CellValue | undefined)[]);
 }
-type AssertNever<T extends never> = T;
 /**
  * Compile-time proof that {@link Row} mirrors every {@link RowProperties} field. A field added to
  * the record without an accessor here resolves this to that field's name, which does not satisfy
@@ -78,4 +78,3 @@ type AssertNever<T extends never> = T;
  * would simply never mention it.
  */
 export type EveryRowPropertyIsMirrored = AssertNever<Exclude<keyof RowProperties, keyof Row & keyof RowProperties>>;
-export {};

package/dist/core/row.js

@@ -1,12 +1,10 @@
-import { columnToNumber, encodeAddress } from './address.js';
+import { assertRowInBounds, columnToNumber, encodeAddress } from './address.js';
 import { INTERNAL } from './internal.js';
 export class Row {
     #sheet;
     number;
     constructor(sheet, number) {
-        if (!Number.isInteger(number) || number < 1) {
-            throw new RangeError(`row ${number} is out of bounds — rows start at 1`);
-        }
+        assertRowInBounds(number);
         this.#sheet = sheet;
         this.number = number;
     }