Coordinates & ranges

Inverse of rangeBoundaries for the rectangular case.

function boundariesToRangeString(b: CellRangeBoundaries): string

Column letter → 1-based column index. Case-insensitive but at most 3 letters (the spec ceiling). Throws on empty / non-A-Z / over-range.

function columnIndexFromLetter(letter: string): number

1-based column index → spreadsheet column letter ("A", "Z", "AA", "XFD"). Throws OpenXmlSchemaError when out of range.

function columnLetterFromIndex(n: number): string

Parse a single-cell coordinate string ("A1", "$XFD$1048576") into its column letter (always uppercased) and 1-based row.

function coordinateFromString(coord: string): CellCoordinate

Same as coordinateFromString but returning the column as its 1-based numeric index. Thin convenience for the worksheet read path.

function coordinateToTuple(coord: string): CellCoordinateNumeric

Inverse of parseSheetRange: format a sheet title + range (or single-cell ref) as `Sheet1!A1` or `'Quarter 1'!A1` per Excel's sheet-qualified syntax. Single quotes inside the title are escaped by doubling (`'Bob''s Sheet'`). Quoting rule: sheet titles consisting only of `[A-Za-z_][A-Za-z0-9_]*` are emitted bare; everything else (spaces, digits-leading, hyphens, apostrophes, punctuation…) gets wrapped in single quotes.

function formatSheetQualifiedRef(sheet: string, ref: string): string

Predicate: true iff `s` is a valid single-cell A1 coordinate (`"A1"`, `"XFD1048576"`). Strings with `$` absolute markers, surrounding whitespace, ranges (`A1:B2`), or out-of-bound row / column return false. Useful for sanitising user input before passing to coordinateToTuple or `setCellByCoord`.

function isValidCellRef(s: unknown): s is string

Predicate: true iff `s` is a valid 1..3-char column letter (`"A"` through `"XFD"`, case-insensitive). Empty / over-long / out-of-bound / non-string fails.

function isValidColumnLetter(s: unknown): s is string

Predicate: true iff `n` is a valid 1-based column index in `[1, 16384]`. Non-finite / non-integer / out-of-bound fails.

function isValidColumnNumber(n: unknown): n is number

Predicate: true iff `s` is a valid A1-style range expression — single cell, two-corner range, whole column (`A:A`), or whole row (`1:1`). `$` markers, whitespace, and out-of-bound bounds fail. Sanity-check before rangeBoundaries / `parseRange`.

function isValidRangeRef(s: unknown): s is string

Predicate: true iff `n` is a valid 1-based row index in `[1, 1048576]`. Non-finite / non-integer / out-of-bound fails.

function isValidRowNumber(n: unknown): n is number

Parse a sheet-qualified range ("Sheet1!A1:B5" / "'Quarter 1'!A1"). Sheet names with single quotes inside use SQL-style doubling ("'Bob''s Sheet'!A1") — we unescape on the way out.

function parseSheetRange(input: string): { bounds: CellRangeBoundaries; range: string; sheet: string }

Parse "A1:B5" / "A:A" / "1:1" / single-cell into 1-based (minCol, minRow, maxCol, maxRow). Whole-column ranges fill rows to [1, MAX_ROW]; whole-row ranges fill cols to [1, MAX_COL].

function rangeBoundaries(range: string): CellRangeBoundaries

Compose `"A1"` from a 1-based (col, row).

function tupleToCoordinate(col: number, row: number): string

Maximum column index Excel accepts (XFD).

const MAX_COL: 16384

Maximum row index Excel accepts.

const MAX_ROW: 1048576

Expand (or shrink) an A1 range by adding `deltaRows` to its bottom edge and `deltaCols` to its right edge. The top-left corner is preserved. Negative deltas shrink the range; the result must still have at least 1 row and 1 column (otherwise throws). Useful for "this is the data range — also reserve room for a totals row" or "include one more column to the right" patterns.

function expandRangeStr(range: string, deltaRows: number, deltaCols: number): string

Returns the rectangular intersection of two ranges, or `null` when disjoint.

function intersectionRange(a: CellRangeBoundaries, b: CellRangeBoundaries): CellRangeBoundaries | null

A1-string convenience for rangeContainsCell. Parses `cellRef` (e.g. `"B3"`) and `rangeRef` (e.g. `"A1:C5"`) and returns `true` iff the cell sits inside the range (boundary-inclusive). Throws when either input is malformed.

function isCellInRange(cellRef: string, rangeRef: string): boolean

A1-string convenience for rangeContainsRange. Returns `true` iff the `inner` range is wholly contained by `outer` (boundary-inclusive). Single-cell refs are accepted on either side via parseRange. Throws on malformed input.

function isRangeInRange(inner: string, outer: string): boolean

Inclusive cell count covered by a range.

function rangeArea(r: CellRangeBoundaries): number

Inclusive containment of a single (row, col) within a range.

function rangeContainsCell(r: CellRangeBoundaries, row: number, col: number): boolean

Inclusive containment of `inner` within `outer`.

function rangeContainsRange(outer: CellRangeBoundaries, inner: CellRangeBoundaries): boolean

True iff two ranges share at least one cell.

function rangesOverlap(a: CellRangeBoundaries, b: CellRangeBoundaries): boolean

Shift a range by (dr, dc) integer offsets. The returned range is clamped to the OOXML grid; callers that want hard bounds should pass values that keep the result inside the spec.

function shiftRange(r: CellRangeBoundaries, dr: number, dc: number): CellRangeBoundaries

Bounding-box union of two ranges. Always non-null.

function unionRange(a: CellRangeBoundaries, b: CellRangeBoundaries): CellRangeBoundaries

Convert a JS `Date` into an Excel serial. The Date is read in UTC. On Windows 1900, dates ≤ 1900-02-28 get a -1 day correction to account for Excel's phantom leap day.

function dateToExcel(date: Date, opts?: { epoch?: ExcelEpoch }): number

Milliseconds → Excel duration serial (fraction of a day).

function durationToExcel(ms: number): number

Convert an Excel serial date into a JS `Date` (UTC). The fractional part is treated as a fraction of a day. For Windows 1900 the leap-bug compensation kicks in for serials in [0, 60).

function excelToDate(serial: number, opts?: { epoch?: ExcelEpoch }): Date

Excel duration serial (fraction of a day) → milliseconds.

function excelToDuration(serial: number): number

Parse an ISO-8601 / W3CDTF datetime string into a `Date`. Same grammar as `new Date(string)`; the wrapper just adds typed error reporting and a stricter "must be a recognised ISO" guard.

function fromIso8601(s: string): Date

Format a `Date` as ISO-8601 with second precision in UTC. Trims the millisecond fragment that `Date.toISOString()` always produces, so the output matches Excel / openpyxl's W3CDTF style.

function toIso8601(d: Date): string

1904-01-01 (UTC) — the Mac / 1904-system epoch in ms.

const MAC_EPOCH_MS: number

1899-12-30 (UTC) — the Windows / 1900-system epoch in ms.

const WINDOWS_EPOCH_MS: number