Workbook

markClean(): void;

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

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

Get a sheet by name (case-insensitive). ASYNC — resolves name via Rust. This is the primary sheet accessor for agents, LLMs, and app code. For internal code that already has a SheetId, use `getSheetById()`.

getSheetById(sheetId: SheetId): Worksheet;

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

findSheet(name: string): Promise<Worksheet | null>;

Find a worksheet by name (case-insensitive), returning null if not found. Non-throwing alternative to {@link getSheet}. @param name - Sheet name (case-insensitive) @returns The worksheet, or null if no sheet with that name exists

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

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

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

getSheets(): Promise<Worksheet[]>;

Get all worksheets in display order. ASYNC — resolves each sheet by name.

getSheetCount(): Promise<number>;

Get the count of sheets. Convenience wrapper around sheetCount property.

getSheetNames(): Promise<string[]>;

Get all sheet names in display order. Convenience wrapper around sheetNames property.

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

Execute a group of operations as a single undo step. NOT transactional: if an operation throws, prior writes in the group remain committed. Each mutation within the group still triggers its own recalc pass.

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

Execute a group of operations as a single undo step with a label. Like `undoGroup`, but attaches a human-readable label to the undo entry (e.g. "Import data"). NOT transactional: partial writes remain committed if fn throws. Each mutation still triggers its own recalc pass.

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): 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) plus `recomputedCount` — the number of formula cells recomputed during this call. @param options - Calculation options.

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`.

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`.

on(event: string, handler: (event: unknown) => void): CallableDisposable;

Subscribe to an arbitrary event string. Handler receives unknown payload.

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().

toXlsx(): Promise<Uint8Array>;

Export the workbook as XLSX binary data.

insertWorksheets(data: string | Uint8Array, options?: InsertWorksheetOptions): Promise<string[]>;

Import sheets from XLSX data. Accepts base64-encoded string or raw Uint8Array. Returns the names of the inserted sheets (may be deduped if names collide).

save(path: string): Promise<Uint8Array>;

Save the workbook to a file path or buffer. Marks the workbook as clean.

captureScreenshot(sheet: Worksheet | string, range: string, options?: ScreenshotOptions): Promise<Uint8Array>;

Capture a PNG screenshot of a cell range. @param sheet - Sheet name (e.g. "Sheet1") or Worksheet instance @param range - A1-notation cell range (e.g. "A1:G10") @param options - Rendering options (DPR, headers, gridlines, max dimensions) @returns PNG image as a Buffer

copyRangeFrom(source: Workbook, fromRange: string, toRange: string, options?: {
        fromSheet?: string | Worksheet;
        toSheet?: string | Worksheet;
    }): 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 spreadsheet special-cell typeApplication.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 '.').

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. Workbook chart data point tracking..

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.

getCustomLists(): Promise<readonly CustomList[]>;

Get workbook-level custom fill/sort lists. Returns the complete catalog: immutable built-in lists followed by workbook-scoped user-defined lists.

addCustomList(input: WorkbookCustomListInput): Promise<CustomList>;

Add a user-defined custom fill/sort list.

updateCustomList(id: string, updates: WorkbookCustomListUpdate): Promise<boolean>;

Update a user-defined custom fill/sort list. Returns false when the list does not exist or is built-in.

deleteCustomList(id: string): Promise<boolean>;

Delete a user-defined custom fill/sort list. Returns false when the list does not exist or is built-in.

setCustomLists(lists: readonly WorkbookCustomListInput[]): Promise<void>;

Replace all user-defined custom fill/sort lists. Built-in lists are code-owned and are never persisted through this method.

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. If this workbook was created via `DocumentHandle.workbook()`, disposing also cleans up the underlying DocumentHandle (and vice versa).

[Symbol.asyncDispose](): Promise<void>;

Async dispose for TC39 Explicit Resource Management. @example ```typescript await using wb = await createWorkbook(); ```

getActiveCell(): {
        sheetId: string;
        row: number;
        col: number;
        address: string;
    } | 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.

setActivePrincipal(principal: string[] | AccessPrincipal | null): Promise<void>;

Set the active principal for this session. Pass `null` (or an empty tag list) to clear. Semantics tied to document state, not session state: when the document has no policies, this is effectively a no-op for access decisions (the gated delegate's fast path skips the principal entirely). Once any policy exists, `null` means anonymous — a caller that never set a principal is denied, not owner. Accepts either a flat tag list or an `AccessPrincipal` envelope for symmetry with `explainAccess` / `getEffectiveAccess`.

activePrincipal(): Promise<AccessPrincipal | null>;

Current active principal, or `null` if none is set.

securityActive(): Promise<boolean>;

Whether access-control enforcement is currently active on this document. `false` when the policy set is empty. SDKs use this to warn users who set a principal on a doc that has no policies ("you set a principal but nothing will be enforced").

makePrincipal(tags: string[]): Promise<AccessPrincipal>;

Canonicalize a tag list through the engine's intern pool and return the canonical (sorted + deduped) form. Primary purpose is to pre-warm the pool so the next `setActivePrincipal` with the same tag set hits an existing slab — matrix-cache pointer identity stays sound on the first call post-swap.