Workbook

markClean(): void;

Reset the dirty flag (call after a successful save).

getSheet(sheetId: SheetId): Worksheet;

Get a sheet by internal SheetId. SYNC — no IPC needed. Throws KernelError if not found.

getSheetByName(name: string): Promise<Worksheet>;

Get a sheet by name (case-insensitive). ASYNC — resolves name via Rust.

getSheetByIndex(index: number): Promise<Worksheet>;

Get a sheet by 0-based index. ASYNC — resolves index via Rust.

getActiveSheet(): Worksheet;

Get the currently active sheet. SYNC — uses known activeSheetId.

getOrCreateSheet(name: string): Promise<{ sheet: Worksheet; created: boolean }>;

Get a sheet by name, creating it if it doesn't exist. @param name - Sheet name (case-insensitive lookup) @returns The sheet and whether it was newly created

getSheetCount(): Promise<number>;

Get the number of sheets in the workbook. ASYNC — reads from Rust.

getSheetNames(): Promise<string[]>;

Get the names of all sheets in order. ASYNC — reads from Rust.

batch<T = void>(fn: (wb: Workbook) => Promise<T>): Promise<T>;

Execute a batch of operations as a single undo step. All operations inside the callback are grouped into one undo step. If an operation throws, the undo group is closed and all prior writes in the batch remain committed (Excel-style best-effort, not transactional). Note: Each mutation within the batch still triggers its own recalc pass. True deferred recalculation (single recalc at batch end) is not yet implemented.

createCheckpoint(label?: string): string;

Create a named checkpoint (version snapshot). Returns the checkpoint ID.

restoreCheckpoint(id: string): Promise<void>;

Restore the workbook to a previously saved checkpoint.

listCheckpoints(): CheckpointInfo[];

List all saved checkpoints.

calculate(options?: CalculateOptions | CalculationType): Promise<CalculateResult>;

Trigger recalculation of formulas. For circular references (common in financial models — debt schedules, tax shields), enable iterative calculation: await wb.calculate({ iterative: { maxIterations: 100, maxChange: 0.001 } }); Returns convergence metadata (hasCircularRefs, converged, iterations, maxDelta). @param options - Calculation options, or a CalculationType string for backward compatibility

getCalculationMode(): Promise<'auto' | 'autoNoTable' | 'manual'>;

Get the current calculation mode (auto/manual/autoNoTable). Convenience accessor — equivalent to `(await getSettings()).calculationSettings.calcMode`.

setCalculationMode(mode: 'auto' | 'autoNoTable' | 'manual'): Promise<void>;

Set the calculation mode. Convenience mutator — patches `calculationSettings.calcMode`.

getIterativeCalculation(): Promise<boolean>;

Get whether iterative calculation is enabled for circular references. Convenience accessor — equivalent to `(await getSettings()).calculationSettings.enableIterativeCalculation`.

setIterativeCalculation(enabled: boolean): Promise<void>;

Set whether iterative calculation is enabled for circular references. Convenience mutator — patches `calculationSettings.enableIterativeCalculation`. @deprecated Use calculate({ iterative: ... }) instead.

setMaxIterations(n: number): Promise<void>;

Set the maximum number of iterations for iterative calculation. Convenience mutator — patches `calculationSettings.maxIterations`. @deprecated Use calculate({ iterative: { maxIterations: n } }) instead.

setConvergenceThreshold(threshold: number): Promise<void>;

Set the convergence threshold (maximum change) for iterative calculation. Convenience mutator — patches `calculationSettings.maxChange`. @deprecated Use calculate({ iterative: { maxChange: threshold } }) instead.

getUsePrecisionAsDisplayed(): Promise<boolean>;

Whether to use displayed precision instead of full (15-digit) precision. Convenience accessor — inverted from `calculationSettings.fullPrecision`.

setUsePrecisionAsDisplayed(value: boolean): Promise<void>;

Set whether to use displayed precision. Convenience mutator — inverts and patches `calculationSettings.fullPrecision`.

getCalculationEngineVersion(): string;

Get the calculation engine version string.

on(event: WorkbookEvent | string, handler: (event: any) => void): () => void;

Subscribe to a coarse WorkbookEvent or arbitrary event string. Handler receives the internal event directly.

executeCode(code: string, options?: ExecuteOptions): Promise<CodeResult>;

Execute TypeScript/JavaScript code in the spreadsheet sandbox.

getWorkbookSnapshot(): Promise<WorkbookSnapshot>;

Get a summary snapshot of the entire workbook.

getFunctionCatalog(): FunctionInfo[];

Get the catalog of all available spreadsheet functions.

getFunctionInfo(name: string): FunctionInfo | null;

Get detailed info about a specific function.

describeRanges(
    requests: SheetRangeRequest[],
    includeStyle?: boolean,
  ): Promise<SheetRangeDescribeResult[]>;

Describe multiple ranges across multiple sheets in a single IPC call. Each entry returns the same LLM-formatted output as ws.describeRange().

exportSnapshot(): Promise<WorkbookSnapshot>;

Export the workbook as a snapshot.

toBuffer(): Promise<Uint8Array>;

Export the workbook as an XLSX binary buffer.

insertWorksheetsFromBase64(base64: string, options?: InsertWorksheetOptions): Promise<string[]>;

Import sheets from an XLSX file (base64-encoded). Returns the names of the inserted sheets (may be deduped if names collide).

save(): Promise<Uint8Array>;

Save the workbook. Exports to XLSX, calls platform save handler if provided, marks clean. Returns the XLSX buffer.

copyRangeFrom(source: Workbook, fromRange: string, toRange: string): Promise<void>;

Copy a range from another workbook into this workbook.

indexToAddress(row: number, col: number): string;

Convert row/col to A1 address: (0, 0) -> "A1"

addressToIndex(address: string): { row: number; col: number };

Convert A1 address to row/col: "A1" -> { row: 0, col: 0 }

union(...ranges: string[]): string;

Combine multiple range addresses into a single comma-separated address. Equivalent to OfficeJS Application.union().

getCultureInfo(): Promise<CultureInfo>;

Get full CultureInfo for the workbook's current culture setting. Resolves the `culture` IETF tag (e.g. 'de-DE') into a complete CultureInfo with number/date/currency formatting details.

getDecimalSeparator(): Promise<string>;

Get the decimal separator for the current culture (e.g. '.' or ',').

getThousandsSeparator(): Promise<string>;

Get the thousands separator for the current culture (e.g. ',' or '.').

getAllTables(): Promise<TableInfo[]>;

Get all tables across all sheets.

getAllPivotTables(): Promise<PivotTableInfo[]>;

Get all pivot tables across all sheets.

getAllSlicers(): Promise<SlicerInfo[]>;

Get all slicers across all sheets.

getAllComments(): Promise<Comment[]>;

Get all comments across all sheets.

getAllNotes(): Promise<Note[]>;

Get all notes across all sheets.

searchAllSheets(
    patterns: string[],
    options?: SearchOptions,
  ): Promise<Array<SearchResult & { sheetName: string }>>;

Search all sheets for cells matching regex patterns (single IPC call).

getChartDataPointTrack(): Promise<boolean>;

Get whether chart data points track cell movement. OfficeJS: Workbook.chartDataPointTrack (#44).

setChartDataPointTrack(value: boolean): Promise<void>;

Set whether chart data points track cell movement.

getSettings(): Promise<WorkbookSettings>;

Get workbook-level settings.

setSettings(updates: Partial<WorkbookSettings>): Promise<void>;

Update workbook-level settings.

getCustomSetting(key: string): Promise<string | null>;

Get a custom setting value by key. Returns null if not found.

setCustomSetting(key: string, value: string): Promise<void>;

Set a custom setting value.

deleteCustomSetting(key: string): Promise<void>;

Delete a custom setting by key.

listCustomSettings(): Promise<Array<{ key: string; value: string }>>;

List all custom settings as key-value pairs.

getCustomSettingCount(): Promise<number>;

Get the number of custom settings.

close(closeBehavior?: 'save' | 'skipSave'): Promise<void>;

Close the workbook with optional save behavior. @param closeBehavior - 'save' exports snapshot before disposing, 'skipSave' disposes immediately (default: 'skipSave')

dispose(): void;

Dispose of the workbook and release resources.

getActiveCell(): { sheetId: string; row: number; col: number } | null;

Active cell. Returns null in headless/no-UI contexts.

getSelectedRanges(): string[];

Currently selected range(s) as A1 address strings. Returns [] in headless.

getSelectedRange(): string | null;

Primary selected range. Returns null in headless.

getActiveChart(): string | null;

Active chart object ID, or null.

getActiveShape(): string | null;

Active shape object ID, or null.

getActiveSlicer(): string | null;

Active slicer object ID, or null.