Cells & values

"Smart" setter: infers the cell value from a JS runtime value. - `string` starting with `=` → formula - `string` matching an Excel error token → error variant - other primitives / Date / null pass through verbatim Intentionally not the default — explicit is clearer for typed code, and inferring on every write costs measurable time on the worksheet write hot path.

function bindValue(c: Cell, value: string | number | boolean | Date | null): void

Coerce a CellValue to `boolean | undefined`. Booleans pass through; `'TRUE'` / `'true'` and `'FALSE'` / `'false'` (case-insensitive) parse to true / false; numbers yield `false` for 0 and `true` for any other finite value (matching Excel's truthy-number coercion); formula cells return their cached boolean if any. Everything else (null, Date, error, duration, rich-text, non-bool strings) yields `undefined`.

function cellValueAsBoolean(v: CellValue): boolean | undefined

Coerce a CellValue to a `Date` when one is meaningful. Pass-through for `Date`-typed values; ISO-8601 strings (anything `new Date(s)` parses to a finite time) round-trip; durations are interpreted as `new Date(ms)`. Numbers, booleans, formulas, errors, rich text, and null all return `undefined` — this helper does **not** apply the Excel-serial-to-Date conversion (use `excelToDate` for that).

function cellValueAsDate(v: CellValue): Date | undefined

Coerce a CellValue to a number when one is meaningful. Booleans yield 0/1; numeric strings parse via `Number(s)`; rich-text concats then parses; formulas with a numeric cached value pass through. Returns `undefined` when there's no sensible numeric reading (text strings, errors, dates, durations, null, empty).

function cellValueAsNumber(v: CellValue): number | undefined

Map a CellValue to the most natural JS primitive for display / export. Unlike `cellValueAsString`/`cellValueAsNumber`/etc., which each force a single target type and return `undefined` when the value can't be coerced, this returns whatever primitive best represents the union variant: - `null` → `null` - `string` / `number` / `boolean` / `Date` → passthrough - rich text → joined run text (`string`) - formula → recursive on `cachedValue` (`null` when uncached) - error → error code (`string`) - duration → `ms` (`number`)

function cellValueAsPrimitive(v: CellValue): string | number | boolean | Date | null

Coerce a CellValue to its plain-string display form. Numbers / booleans convert via `String`; rich text concatenates run text; formulas yield the cached value (or empty string when uncached); errors yield their Excel token; durations yield `"<ms> ms"` with no formatting; Dates yield `Date.toISOString()`; `null` yields `""`. Pass `opts.dateFormat` to override the Date renderer (e.g. a locale-specific format) and `opts.emptyText` to substitute a different placeholder for `null` cells.

function cellValueAsString(v: CellValue, opts?: CellValueAsStringOptions): string

Get the cached value Excel last computed for a formula cell, or `undefined` for non-formula / uncached cells. Useful for `data_only` read paths that want the displayed result without re-evaluating.

function getCachedFormulaValue(c: Cell): string | number | boolean | undefined

Format a Cell's coordinate as the canonical "A1" string.

function getCoordinate(c: Cell): string

Get the formula text from a formula-bearing cell, or `undefined` for non-formula cells. Equivalent to: isFormulaValue(c.value) ? c.value.formula : undefined but spares callers the type-narrow + member access.

function getFormulaText(c: Cell): string | undefined

True iff `v` is the duration variant.

function isDurationValue(v: CellValue): v is { kind: "duration"; ms: number }

Returns true iff the cell has no content.

function isEmptyCell(c: Cell): boolean

Returns true iff the cell holds an Excel error value (`#REF!`, `#NAME?`, …).

function isErrorCell(c: Cell): boolean

True iff `v` is the error variant.

function isErrorValue(v: CellValue): v is { code: ExcelErrorCode; kind: "error" }

True iff `c.value` is the formula variant.

function isFormulaCell(c: Cell): boolean

True iff `v` is the formula variant.

function isFormulaValue(v: CellValue): v is FormulaValue

Type guard for `MergedCell` — true iff the cell is a placeholder for a merged-range covered cell (the top-left of a merged range holds the value; the rest are `MergedCell`). Use this to filter merge-placeholders out of value-walking loops.

function isMergedCell(c: Cell): c is MergedCell

True iff `c.value` is the rich-text variant.

function isRichTextCell(c: Cell): boolean

True iff `v` is the rich-text variant.

function isRichTextValue(v: CellValue): v is { kind: "rich-text"; runs: RichText }

Build a fresh Cell. Validates coordinates against the OOXML grid bounds.

function makeCell(row: number, col: number, value?: CellValue, styleId?: number): Cell

Build a `{ kind: 'duration', ms }` cell value.

function makeDurationValue(ms: number): { kind: "duration"; ms: number }

Build a `{ kind: 'error', code }` cell value.

function makeErrorValue(code: ExcelErrorCode): { code: ExcelErrorCode; kind: "error" }

Array (CSE) formula spanning a `ref` range.

function setArrayFormula(c: Cell, ref: string, formula: string, opts?: { cachedValue?: string | number | boolean }): void

Direct value setter. No type inference, no validation beyond the union — the caller is in charge. Use bindValue for the "do what I mean" path.

function setCellValue(c: Cell, value: CellValue): void

Set a data-table formula on a cell. Preserves all the dt-specific attributes so the writer can re-emit `<f t="dataTable" r1="..." />` verbatim and Excel keeps treating the cell as a Data Table cell.

function setDataTableFormula(c: Cell, formula: string, opts: DataTableFormulaOpts): void

Plain `=A1+B1` style formula. Cached value is optional but recommended for round-trip.

function setFormula(c: Cell, formula: string, opts?: { cachedValue?: string | number | boolean }): void

Shared formula. The first cell in the group carries the formula text + ref; subsequent cells with the same `si` carry only the index and Excel reconstructs the formula via reference shifting.

function setSharedFormula(c: Cell, si: number, formula?: string, ref?: string, opts?: { cachedValue?: string | number | boolean }): void

Concatenate the plain-text content of a rich-text value (rich-text read paths often want the raw text without formatting).

function richTextToString(rt: RichText): string