Coordinates & ranges

A1 ↔ row/col conversion, range parsing, EMU and date helpers.

48 exports from 4 source files

Coordinate

boundariesToRangeString function

Inverse of rangeBoundaries for the rectangular case. opts forwards to tupleToCoordinate, so { absoluteCol: true, absoluteRow: true } yields the "$A$4:$H$20" form a formula or defined name wants.

function boundariesToRangeString(b: CellRangeBoundaries, opts?: AbsoluteRefOptions): string

Parameters

Name	Type	Description
`b`	`CellRangeBoundaries`
`opts?` = {}	`AbsoluteRefOptions`

Returns

string

columnIndexFromLetter function

src/utils/coordinate.ts:45

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

Parameters

Name	Type	Description
`letter`	`string`

Returns

number

columnLetterFromIndex function

src/utils/coordinate.ts:24

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

function columnLetterFromIndex(n: number): string

Parameters

Name	Type	Description
`n`	`number`

Returns

string

coordinateFromString function

src/utils/coordinate.ts:114

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

function coordinateFromString(coord: string): CellCoordinate

Parameters

Name	Type	Description
`coord`	`string`

Returns

CellCoordinate

coordinateToTuple function

src/utils/coordinate.ts:133

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

Parameters

Name	Type	Description
`coord`	`string`

Returns

CellCoordinateNumeric

formatSheetQualifiedRef function

src/utils/coordinate.ts:430

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

Parameters

Name	Type	Description
`sheet`	`string`
`ref`	`string`

Returns

string

isValidCellRef function

src/utils/coordinate.ts:168

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

Parameters

Name	Type	Description
`s`	`unknown`

Returns

s is string

isValidColumnLetter function

src/utils/coordinate.ts:237

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

Parameters

Name	Type	Description
`s`	`unknown`

Returns

s is string

isValidColumnNumber function

src/utils/coordinate.ts:297

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

Parameters

Name	Type	Description
`n`	`unknown`

Returns

n is number

isValidRangeRef function

src/utils/coordinate.ts:188

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

Parameters

Name	Type	Description
`s`	`unknown`

Returns

s is string

isValidRowNumber function

src/utils/coordinate.ts:248

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

Parameters

Name	Type	Description
`n`	`unknown`

Returns

n is number

parseSheetRange function

src/utils/coordinate.ts:377

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 }

Parameters

Name	Type	Description
`input`	`string`

Returns

{ bounds: CellRangeBoundaries; range: string; sheet: string }

rangeBoundaries function

src/utils/coordinate.ts:306

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

Parameters

Name	Type	Description
`range`	`string`

Returns

CellRangeBoundaries

tupleToCoordinate function

src/utils/coordinate.ts:152

Compose "A1" from a 1-based (col, row). Set absoluteCol / absoluteRow to get the $ forms formula text needs ("$B$5", "B$5"), so callers tracking integer coordinates never have to concatenate a column letter themselves.

function tupleToCoordinate(col: number, row: number, opts?: AbsoluteRefOptions): string

Parameters

Name	Type	Description
`col`	`number`
`row`	`number`
`opts?` = {}	`AbsoluteRefOptions`

Returns

string

MAX_COL const

src/utils/coordinate.ts:11

Maximum column index Excel accepts (XFD).

const MAX_COL: 16384

MAX_ROW const

src/utils/coordinate.ts:13

Maximum row index Excel accepts.

const MAX_ROW: 1048576

Units

src/utils/units.ts

cmFromEmu function

src/utils/units.ts:30

function cmFromEmu(emu: number): number

Parameters

Name	Type	Description
`emu`	`number`

Returns

number

emuFromCm function

src/utils/units.ts:27

function emuFromCm(cm: number): number

Parameters

Name	Type	Description
`cm`	`number`

Returns

number

emuFromInch function

src/utils/units.ts:36

function emuFromInch(inch: number): number

Parameters

Name	Type	Description
`inch`	`number`

Returns

number

emuFromPoint function

src/utils/units.ts:45

function emuFromPoint(pt: number): number

Parameters

Name	Type	Description
`pt`	`number`

Returns

number

emuFromPx function

src/utils/units.ts:18

function emuFromPx(px: number): number

Parameters

Name	Type	Description
`px`	`number`

Returns

number

inchFromEmu function

src/utils/units.ts:39

function inchFromEmu(emu: number): number

Parameters

Name	Type	Description
`emu`	`number`

Returns

number

pixelToPoint function

src/utils/units.ts:57

function pixelToPoint(px: number, dpi?: number): number

Parameters

Name	Type	Description
`px`	`number`
`dpi?` = DEFAULT_PIXEL_DPI	`number`

Returns

number

pointFromEmu function

src/utils/units.ts:48

function pointFromEmu(emu: number): number

Parameters

Name	Type	Description
`emu`	`number`

Returns

number

pointToPixel function

src/utils/units.ts:54

function pointToPixel(pt: number, dpi?: number): number

Parameters

Name	Type	Description
`pt`	`number`
`dpi?` = DEFAULT_PIXEL_DPI	`number`

Returns

number

pxFromEmu function

src/utils/units.ts:21

function pxFromEmu(emu: number): number

Parameters

Name	Type	Description
`emu`	`number`

Returns

number

EMU_PER_CM const

src/utils/units.ts:9

const EMU_PER_CM: 360000

EMU_PER_INCH const

src/utils/units.ts:8

const EMU_PER_INCH: 914400

EMU_PER_PIXEL const

src/utils/units.ts:10

const EMU_PER_PIXEL: 9525

EMU_PER_POINT const

src/utils/units.ts:11

const EMU_PER_POINT: 12700

Cell range

src/worksheet/cell-range.ts

expandRangeStr function

src/worksheet/cell-range.ts:185

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

Parameters

Name	Type	Description
`range`	`string`
`deltaRows`	`number`
`deltaCols`	`number`

Returns

string

intersectionRange function

src/worksheet/cell-range.ts:227

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

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

Parameters

Name	Type	Description
`a`	`CellRangeBoundaries`
`b`	`CellRangeBoundaries`

Returns

CellRangeBoundaries | null

isCellInRange function

src/worksheet/cell-range.ts:104

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

Parameters

Name	Type	Description
`cellRef`	`string`
`rangeRef`	`string`

Returns

boolean

isRangeInRange function

src/worksheet/cell-range.ts:115

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

Parameters

Name	Type	Description
`inner`	`string`
`outer`	`string`

Returns

boolean

rangeArea function

src/worksheet/cell-range.ts:242

Inclusive cell count covered by a range.

function rangeArea(r: CellRangeBoundaries): number

Parameters

Name	Type	Description
`r`	`CellRangeBoundaries`

Returns

number

rangeContainsCell function

src/worksheet/cell-range.ts:95

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

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

Parameters

Name	Type	Description
`r`	`CellRangeBoundaries`
`row`	`number`
`col`	`number`

Returns

boolean

rangeContainsRange function

src/worksheet/cell-range.ts:194

Inclusive containment of inner within outer.

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

Parameters

Name	Type	Description
`outer`	`CellRangeBoundaries`
`inner`	`CellRangeBoundaries`

Returns

boolean

rangesOverlap function

src/worksheet/cell-range.ts:237

True iff two ranges share at least one cell.

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

Parameters

Name	Type	Description
`a`	`CellRangeBoundaries`
`b`	`CellRangeBoundaries`

Returns

boolean

shiftRange function

src/worksheet/cell-range.ts:209

Shift a range by (dr, dc) integer offsets. Throws when the result falls outside the OOXML grid (rows 1..1048576, cols 1..16384) rather than clamping to it, so a shift that would silently change which cells the range covers fails instead. shiftRangeStr is the same rule on A1 strings.

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

Parameters

Name	Type	Description
`r`	`CellRangeBoundaries`
`dr`	`number`
`dc`	`number`

Returns

CellRangeBoundaries

unionRange function

src/worksheet/cell-range.ts:217

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

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

Parameters

Name	Type	Description
`a`	`CellRangeBoundaries`
`b`	`CellRangeBoundaries`

Returns

CellRangeBoundaries

Datetime

src/utils/datetime.ts

dateToExcel function

src/utils/datetime.ts:58

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

Parameters

Name	Type	Description
`date`	`Date`
`opts?`	`{ epoch?: ExcelEpoch }`

Returns

number

durationToExcel function

src/utils/datetime.ts:81

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

function durationToExcel(ms: number): number

Parameters

Name	Type	Description
`ms`	`number`

Returns

number

excelToDate function

src/utils/datetime.ts:38

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

Parameters

Name	Type	Description
`serial`	`number`
`opts?`	`{ epoch?: ExcelEpoch }`

Returns

Date

excelToDuration function

src/utils/datetime.ts:73

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

function excelToDuration(serial: number): number

Parameters

Name	Type	Description
`serial`	`number`

Returns

number

fromIso8601 function

src/utils/datetime.ts:95

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

Parameters

Name	Type	Description
`s`	`string`

Returns

Date

toIso8601 function

src/utils/datetime.ts:111

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

Parameters

Name	Type	Description
`d`	`Date`

Returns

string

MAC_EPOCH_MS const

src/utils/datetime.ts:25

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

const MAC_EPOCH_MS: number

WINDOWS_EPOCH_MS const

src/utils/datetime.ts:23

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

const WINDOWS_EPOCH_MS: number