Workbook

Add a Chartsheet to the Workbook. Returns the chartsheet for further population.

function addChartsheet(wb: Workbook, title: string, opts?: { chart?: ChartReference; index?: number; state?: SheetState }): Chartsheet

Add a Worksheet to the Workbook. Returns the sheet for further population.

function addWorksheet(wb: Workbook, title: string, opts?: { index?: number; state?: SheetState }): Worksheet

Build an empty Workbook ready to host worksheets.

function createWorkbook(opts?: { date1904?: boolean }): Workbook

Currently active sheet (worksheet only), or undefined if the active slot is empty or a chartsheet.

function getActiveSheet(wb: Workbook): Worksheet | undefined

Resolve a sheet-qualified A1 address (`'Sheet1!A1'`) to its Cell, or `undefined` when the cell isn't materialised. Throws on malformed addresses, missing sheets, or range inputs.

function getCellAtAddress(wb: Workbook, address: string): Cell | undefined

Look up a Chartsheet by title. Returns undefined for missing names or worksheets.

function getChartsheet(wb: Workbook, title: string): Chartsheet | undefined

Look up a Worksheet by title. Returns undefined for missing names or chartsheets.

function getSheet(wb: Workbook, title: string): Worksheet | undefined

Look up the current visibility state. Throws on unknown title.

function getSheetState(wb: Workbook, title: string): SheetState

Workbook-wide value-kind histogram. Sums countCellsByKind across every Worksheet (chartsheets contribute no cells). Buckets have the same shape as the per-worksheet result; an empty workbook returns all-zero counts.

function getWorkbookCellsByKind(wb: Workbook): CellsByKindCounts

Iterate over every Worksheet in the workbook (skips chartsheets). Yields each worksheet in tab-strip order.

function iterWorksheets(wb: Workbook): IterableIterator<Worksheet>

Read-only view onto the customXml/* pass-through parts.

function listCustomXmlParts(wb: Workbook): { content: Uint8Array; path: string }[]

Move a sheet to a new tab-strip position. `toIndex` is clamped to `[0, sheets.length - 1]`. Adjusts `activeSheetIndex` so the same sheet stays active across the move.

function moveSheet(wb: Workbook, title: string, toIndex: number): void

Remove a sheet by title. No-op if the title is not registered.

function removeSheet(wb: Workbook, title: string): void

Rename a sheet from `oldTitle` to `newTitle`. Throws if no sheet matches `oldTitle`, or if `newTitle` collides with an existing sheet (Excel requires sheet names to be unique within a workbook).

function renameSheet(wb: Workbook, oldTitle: string, newTitle: string): void

Set the active sheet by title; throws on unknown title.

function setActiveSheet(wb: Workbook, title: string): void

Set a single cell by sheet-qualified A1 address. Throws on malformed addresses, missing sheets, or range inputs.

function setCellAtAddress(wb: Workbook, address: string, value: CellValue): Cell

Set the visibility state on a sheet by title. Throws on unknown title. Refuses to hide the last visible sheet: an .xlsx with every sheet hidden fails to open in Excel ("Excel cannot use the object linking and embedding features because no sheet is visible"). Catching it here keeps the workbook recoverable instead of producing a save Excel will reject.

function setSheetState(wb: Workbook, title: string, state: SheetState): void

All worksheet titles, in display order.

function sheetNames(wb: Workbook): string[]

Add a workbook-scope or sheet-scope defined name. If a defined name with the same `name` (and `scope`) already exists, it's replaced — Excel allows one workbook-scope and one per-sheet-scope name, but not two with the same scope. Returns the resulting `DefinedName`.

function addDefinedName(wb: Workbook, opts: Partial<DefinedName> & { name: string; value: string }): DefinedName

Look up a defined name by identifier and (optional) sheet scope.

function getDefinedName(wb: Workbook, name: string, scope?: number): DefinedName | undefined

Resolve a defined name's `value` into one or more DefinedNameTargets. Comma-separated values (e.g. `_xlnm.Print_Titles` typically sets `Sheet!$1:$1,Sheet!$A:$A`) yield one entry per leg; a plain `Sheet!A1:B5` yields a single-element array. Returns `undefined` when the name doesn't exist; throws when the value can't be parsed (e.g. a constant or a non-range formula — defined names are sometimes used for things like `=42` or `=SUM(A:A)` which aren't ranges).

function getDefinedNameTarget(wb: Workbook, name: string, scope?: number): DefinedNameTarget[] | undefined

Read-only snapshot of every defined name. Pass `{ scope }` to narrow to workbook-scope (`scope: undefined`) or one specific sheet (`scope: 0`) — omit the option entirely to list all.

function listDefinedNames(wb: Workbook, opts?: { scope?: number | "all" | "workbook" }): readonly DefinedName[]

Remove a defined name by identifier + scope. Returns true if any entry was removed.

function removeDefinedName(wb: Workbook, name: string, scope?: number): boolean

Insert a string and return its index. Idempotent: calling with the same value twice gives the same index. Empty strings are deduped just like everything else.

function addSharedString(table: SharedStringsTable, value: string): number

Read a shared-string by its 0-based index. Returns `undefined` for out-of-range. Rich-text entries surface their concatenated plain text so callers that want only the textual body don't need to know about the discriminated union.

function getSharedStringAt(table: SharedStringsTable, index: number): string | undefined

Look up a shared-string index by its literal text. Returns `undefined` for unknown values.

function getSharedStringIndex(table: SharedStringsTable, value: string): number | undefined

Number of unique entries in the SST.

function sharedStringCount(table: SharedStringsTable): number