Workbook API

This reference covers the workbook operations exposed in three places:

witan xlsx exec: call await xlsx.method(wb, ...) from the sandboxed script.
JavaScript SDK: call await wb.method(...) on a Workbook opened from the witan npm package.
Python SDK: call wb.method(...) or await wb.method(...) on Workbook / AsyncWorkbook from the witan PyPI package.

Call Shapes

witan xlsx exec report.xlsx --expr 'await xlsx.readCell(wb, "Summary!A1")'

// JavaScript SDK
await using wb = await Workbook.open("report.xlsx")
await wb.readCell("Summary!A1")

# Python SDK
with Workbook("report.xlsx") as wb:
    wb.read_cell("Summary!A1")

SDK Lifecycle

These methods manage SDK sessions. They are not callable as xlsx.* methods inside witan xlsx exec; exec opens the workbook before your script starts and persists only when the CLI is run with --save.

Method	Purpose	JavaScript	Python
Workbook.open	Open an existing workbook-backed RPC session from an SDK.	Workbook.open(path, options?)	Workbook(path, options) / AsyncWorkbook(path, options)
Workbook.save	Persist the current RPC session to disk. Not available inside `witan xlsx exec` scripts.	wb.save()	wb.save()
Workbook.close	Close the SDK RPC session. Not available inside `witan xlsx exec` scripts.	wb.close()	wb.close()

Method Summary

Workbook and sheets

Method	JavaScript SDK	Python SDK
getWorkbookProperties	wb.getWorkbookProperties()	wb.get_workbook_properties()
setWorkbookProperties	wb.setWorkbookProperties(properties: JsonMapping)	wb.set_workbook_properties(properties: WorkbookPropertiesUpdate)
listSheets	wb.listSheets()	wb.list_sheets()
listDefinedNames	wb.listDefinedNames()	wb.list_defined_names()
addDefinedName	wb.addDefinedName(name: string, range: string, options: { scope?: string } = {})	wb.add_defined_name(name: str, range: str, scope: str \| None = None)
deleteDefinedName	wb.deleteDefinedName(name: string, options: { scope?: string } = {})	wb.delete_defined_name(name: str, scope: str \| None = None)
addSheet	wb.addSheet(name: string)	wb.add_sheet(name: str)
deleteSheet	wb.deleteSheet(name: string)	wb.delete_sheet(name: str)
renameSheet	wb.renameSheet(oldName: string, newName: string)	wb.rename_sheet(old_name: str, new_name: str)
setSheetProperties	wb.setSheetProperties(sheet: string, properties: JsonMapping)	wb.set_sheet_properties(sheet_name: str, properties: SheetPropertiesUpdate)
getSheetProperties	wb.getSheetProperties(sheet: string, options: { columns?: (number \| string)[]; rows?: number[] } = {})	wb.get_sheet_properties(sheet_name: str, columns: Sequence[int \| str] \| None = None, rows: Sequence[int] \| None = None)

Reading

Method	JavaScript SDK	Python SDK
readCell	wb.readCell(cell: string, options: { context?: number } = {})	wb.read_cell(cell: CellRef, context: int \| None = None)
readRange	wb.readRange(range: string)	wb.read_range(range: RangeRef)
readColumn	wb.readColumn(sheet: string, col: number \| string, options: { startRow?: number; endRow?: number } = {})	wb.read_column(sheet_name: str, col: int \| str, start_row: int \| None = None, end_row: int \| None = None)
readRow	wb.readRow(sheet: string, row: number, options: { startCol?: number; endCol?: number } = {})	wb.read_row(sheet_name: str, row: int, start_col: int \| None = None, end_col: int \| None = None)
readRangeTsv	wb.readRangeTsv(range: string, options: { includeEmpty?: boolean; includeFormulas?: boolean } = {})	wb.read_range_tsv(range: RangeRef, include_empty: bool \| None = None, include_formulas: bool \| None = None)
readColumnTsv	wb.readColumnTsv(sheet: string, col: number \| string, options: { startRow?: number; endRow?: number; includeEmpty?: boolean; includeFormulas?: boolean; } = {})	wb.read_column_tsv(sheet_name: str, col: int \| str, start_row: int \| None = None, end_row: int \| None = None, include_empty: bool \| None = None, include_formulas: bool \| None = None)
readRowTsv	wb.readRowTsv(sheet: string, row: number, options: { startCol?: number; endCol?: number; includeEmpty?: boolean; includeFormulas?: boolean; } = {})	wb.read_row_tsv(sheet_name: str, row: int, start_col: int \| None = None, end_col: int \| None = None, include_empty: bool \| None = None, include_formulas: bool \| None = None)

Search and discovery

Method	JavaScript SDK	Python SDK
findCells	wb.findCells(matcher: Matcher, options: { in?: string; context?: number; limit?: number; offset?: number; formulas?: boolean; } = {})	wb.find_cells(matcher: Matcher, in_: RangeRef \| None = None, context: int = 2, limit: int = 20, offset: int = 0, formulas: bool \| None = None)
findRows	wb.findRows(matcher: Matcher, options: { in?: string; context?: number; limit?: number; offset?: number; } = {})	wb.find_rows(matcher: Matcher, in_: RangeRef \| None = None, context: int \| None = None, limit: int = 20, offset: int = 0)
findAndReplace	wb.findAndReplace(find: ReplaceMatcher, replace: string, options: { in?: string; matchCase?: boolean; wholeCell?: boolean; inFormulas?: boolean; limit?: number; } = {})	wb.find_and_replace(find: ReplaceMatcher, replace: str, in_: RangeRef \| None = None, match_case: bool \| None = None, whole_cell: bool \| None = None, in_formulas: bool \| None = None, limit: int \| None = None)
describeSheet	wb.describeSheet(sheet: string)	wb.describe_sheet(sheet_name: str)
tableLookup	wb.tableLookup(table: string, rowLabel: string \| number \| boolean, columnLabel: string \| number \| boolean)	wb.table_lookup(table: str, row_label: str \| int \| float \| bool, column_label: str \| int \| float \| bool)

Tables, data tables, and charts

Method	JavaScript SDK	Python SDK
listCharts	wb.listCharts(options: { sheet?: string } = {})	wb.list_charts(sheet: str \| None = None)
getChart	wb.getChart(sheet: string, name: string)	wb.get_chart(sheet: str, name: str)
addChart	wb.addChart(sheet: string, chart: ChartSpec)	wb.add_chart(sheet: str, chart: ChartSpec)
setChart	wb.setChart(sheet: string, name: string, chart: ChartSpec)	wb.set_chart(sheet: str, name: str, chart: ChartSpec)
deleteChart	wb.deleteChart(sheet: string, name: string)	wb.delete_chart(sheet: str, name: str)
getListObject	wb.getListObject(name: string)	wb.get_list_object(name: str)
addListObject	wb.addListObject(sheet: string, listObject: ListObjectSpec)	wb.add_list_object(sheet_name: str, list_object: ListObjectSpec)
setListObject	wb.setListObject(name: string, listObject: ListObjectUpdate)	wb.set_list_object(name: str, list_object: ListObjectUpdate)
deleteListObject	wb.deleteListObject(name: string)	wb.delete_list_object(name: str)
getDataTable	wb.getDataTable(address: string)	wb.get_data_table(address: str)
addDataTable	wb.addDataTable(sheet: string, dataTable: DataTableSpec)	wb.add_data_table(sheet_name: str, data_table: DataTableSpec)
deleteDataTable	wb.deleteDataTable(address: string)	wb.delete_data_table(address: str)

Writing and structure

Method	JavaScript SDK	Python SDK
setCells	wb.setCells(cells: CellAssignment[])	wb.set_cells(cells: Sequence[JsonMapping])
scaleRange	wb.scaleRange(range: string, factor: number, options: { skipFormulas?: boolean } = {})	wb.scale_range(range: RangeRef, factor: float, skip_formulas: bool = True)
insertRowAfter	wb.insertRowAfter(sheet: string, row: number, count = 1)	wb.insert_row_after(sheet_name: str, row: int, count: int = 1)
deleteRows	wb.deleteRows(sheet: string, row: number, count = 1)	wb.delete_rows(sheet_name: str, row: int, count: int = 1)
insertColumnAfter	wb.insertColumnAfter(sheet: string, column: number \| string, count = 1)	wb.insert_column_after(sheet_name: str, column: int \| str, count: int = 1)
deleteColumns	wb.deleteColumns(sheet: string, column: number \| string, count = 1)	wb.delete_columns(sheet_name: str, column: int \| str, count: int = 1)
autoFitColumns	wb.autoFitColumns(sheet: string, columns?: (number \| string)[], options: { minWidth?: number; maxWidth?: number; padding?: number } = {})	wb.auto_fit_columns(sheet_name: str, columns: Sequence[int \| str] \| None = None, min_width: float \| None = None, max_width: float \| None = None, padding: float \| None = None)
autoFitRows	wb.autoFitRows(sheet: string, rows?: number[], options: { minHeight?: number; maxHeight?: number } = {})	wb.auto_fit_rows(sheet_name: str, rows: Sequence[int] \| None = None, min_height: float \| None = None, max_height: float \| None = None)
sortRange	wb.sortRange(range: string, keys: SortKey[], options: { hasHeader?: boolean } = {})	wb.sort_range(range: RangeRef, keys: Sequence[JsonMapping], has_header: bool \| None = None)
copyRange	wb.copyRange(source: string, destination: string, options: { pasteType?: PasteType } = {})	wb.copy_range(source: RangeRef, destination: CellRef, paste_type: Literal["all", "values", "formulas", "formats"] \| None = None)
setRowProperties	wb.setRowProperties(sheet: string, fromRow: number, toRow: number, properties: JsonMapping)	wb.set_row_properties(sheet_name: str, from_row: int, to_row: int, properties: JsonMapping)
setColumnProperties	wb.setColumnProperties(sheet: string, fromCol: number \| string, toCol: number \| string, properties: JsonMapping)	wb.set_column_properties(sheet_name: str, from_col: int \| str, to_col: int \| str, properties: JsonMapping)

Styles and formatting

Method	JavaScript SDK	Python SDK
getConditionalFormatting	wb.getConditionalFormatting(sheet: string)	wb.get_conditional_formatting(sheet_name: str)
setConditionalFormatting	wb.setConditionalFormatting(sheet: string, rules: ConditionalFormattingRule[], options: { clear?: boolean } = {})	wb.set_conditional_formatting(sheet_name: str, rules: Sequence[ConditionalFormattingRule], clear: bool \| None = None)
removeConditionalFormatting	wb.removeConditionalFormatting(sheet: string, indices: number[])	wb.remove_conditional_formatting(sheet_name: str, indices: Sequence[int])
getStyle	wb.getStyle(cell: string)	wb.get_style(cell: CellRef)
setStyle	wb.setStyle(target: string, style: Style)	wb.set_style(target: CellRef \| RangeRef, style: Style)

Formulas and dependencies

Method	JavaScript SDK	Python SDK
getCellPrecedents	wb.getCellPrecedents(address: string, depth: number \| typeof Infinity = 1)	wb.get_cell_precedents(address: CellRef, depth: int \| float = 1)
getCellDependents	wb.getCellDependents(address: string, depth: number \| typeof Infinity = 1)	wb.get_cell_dependents(address: CellRef, depth: int \| float = 1)
traceToInputs	wb.traceToInputs(address: string)	wb.trace_to_inputs(cell: CellRef)
traceToOutputs	wb.traceToOutputs(address: string)	wb.trace_to_outputs(cell: CellRef)
sweepInputs	wb.sweepInputs(inputs: SweepInput[], outputs: string[], options: { mode?: SweepMode; includeStats?: boolean } = {})	wb.sweep_inputs(inputs: Sequence[JsonMapping], outputs: Sequence[str \| CellRef], mode: Literal["cartesian", "parallel"] \| None = None, include_stats: bool \| None = None)
evaluateFormulas	wb.evaluateFormulas(sheet: string, formulas: string[])	wb.evaluate_formulas(sheet: str, formulas: Sequence[str])
evaluateFormula	wb.evaluateFormula(sheet: string, formula: string)	wb.evaluate_formula(sheet: str, formula: str)

Verification and rendering

Method	JavaScript SDK	Python SDK
lint	wb.lint(options: { rangeAddresses?: string[]; skipRuleIds?: string[]; onlyRuleIds?: string[]; } = {})	wb.lint(range_addresses: Sequence[str] \| None = None, skip_rule_ids: Sequence[str] \| None = None, only_rule_ids: Sequence[str] \| None = None)
previewStyles	wb.previewStyles(range: string)	wb.preview_styles(range: RangeRef)

Utilities

Method	JavaScript SDK	Python SDK
reduceAddresses	wb.reduceAddresses(addresses: string[])	wb.reduce_addresses(addresses: Sequence[CellRef \| RangeRef])

Workbook and sheets

getWorkbookProperties

Get workbook-level properties including theme, and metadata.

Surface	Call
Exec	`await xlsx.getWorkbookProperties(wb)`
JavaScript SDK	`wb.getWorkbookProperties()`
Python SDK	`wb.get_workbook_properties()`

Signature

async function getWorkbookProperties(wb: WorkbookContext): Promise<{
  activeSheetIndex: number;
  defaultFont: {
    name: string;
    size: number;
  };
  iterativeCalculation: {
    enabled: boolean;
    maxIterations: number;
    maxChange: number;
  };
  metadata?: {
    author?: string;
    title?: string;
    subject?: string;
    company?: string;
    created?: string;
    modified?: string;
  };
  themeColors?: {
    dark1: string;
    light1: string;
    dark2: string;
    light2: string;
    accent1: string;
    accent2: string;
    accent3: string;
    accent4: string;
    accent5: string;
    accent6: string;
    hyperlink: string;
    followedHyperlink: string;
    majorFont?: string;
    minorFont?: string;
  };
}>

setWorkbookProperties

Set workbook-level properties. Supports partial updates - only specified properties are modified.

Surface	Call
Exec	`await xlsx.setWorkbookProperties(wb, ...)`
JavaScript SDK	`wb.setWorkbookProperties(properties: JsonMapping)`
Python SDK	`wb.set_workbook_properties(properties: WorkbookPropertiesUpdate)`

Signature

async function setWorkbookProperties(wb: WorkbookContext, properties: { activeSheetIndex?: number; defaultFont?: { name?: string; size?: number }; iterativeCalculation?: { enabled?: boolean; maxIterations?: number; maxChange?: number; }; metadata?: { author?: string; title?: string; subject?: string; company?: string; }; themeColors?: { dark1?: string; light1?: string; dark2?: string; light2?: string; accent1?: string; accent2?: string; accent3?: string; accent4?: string; accent5?: string; accent6?: string; hyperlink?: string; followedHyperlink?: string; majorFont?: string; minorFont?: string; }; }): Promise<void>

listSheets

List all sheets with their used ranges, visibility, and cross-sheet dependencies.

Surface	Call
Exec	`await xlsx.listSheets(wb)`
JavaScript SDK	`wb.listSheets()`
Python SDK	`wb.list_sheets()`

Signature

async function listSheets(wb: WorkbookContext): Promise<{
  address: string;
  rows: number;
  cols: number;
  sheet: string;
  hidden?: boolean;
  printArea?: string;
  listObjects?: string[];
  dataTables?: string[];
  precedents?: string[];
  dependents?: string[];
}[]>

listDefinedNames

List all named ranges in the workbook.

Surface	Call
Exec	`await xlsx.listDefinedNames(wb)`
JavaScript SDK	`wb.listDefinedNames()`
Python SDK	`wb.list_defined_names()`

Signature

async function listDefinedNames(wb: WorkbookContext): Promise<{
  name: string;
  range: string;
  scope: string | null;
}[]>

addDefinedName

Create a named range, optionally scoped to a sheet.

Surface	Call
Exec	`await xlsx.addDefinedName(wb, ...)`
JavaScript SDK	`wb.addDefinedName(name: string, range: string, options: { scope?: string } = {})`
Python SDK	`wb.add_defined_name(name: str, range: str, scope: str \| None = None)`

Signature

async function addDefinedName(wb: WorkbookContext, name: string, range: string, scope?: string): Promise<{
  name: string;
  range: string;
  scope: string | null;
}>

deleteDefinedName

Delete a named range, optionally scoped to a sheet.

Surface	Call
Exec	`await xlsx.deleteDefinedName(wb, ...)`
JavaScript SDK	`wb.deleteDefinedName(name: string, options: { scope?: string } = {})`
Python SDK	`wb.delete_defined_name(name: str, scope: str \| None = None)`

Signature

async function deleteDefinedName(wb: WorkbookContext, name: string, scope?: string): Promise<{
  name: string;
  range: string;
  scope: string | null;
}>

addSheet

Add a new worksheet to the workbook.

Surface	Call
Exec	`await xlsx.addSheet(wb, ...)`
JavaScript SDK	`wb.addSheet(name: string)`
Python SDK	`wb.add_sheet(name: str)`

Signature

async function addSheet(wb: WorkbookContext, name: string): Promise<string>

deleteSheet

Remove a worksheet from the workbook.

Surface	Call
Exec	`await xlsx.deleteSheet(wb, ...)`
JavaScript SDK	`wb.deleteSheet(name: string)`
Python SDK	`wb.delete_sheet(name: str)`

Signature

async function deleteSheet(wb: WorkbookContext, name: string): Promise<void>

renameSheet

Rename a worksheet.

Surface	Call
Exec	`await xlsx.renameSheet(wb, ...)`
JavaScript SDK	`wb.renameSheet(oldName: string, newName: string)`
Python SDK	`wb.rename_sheet(old_name: str, new_name: str)`

Signature

async function renameSheet(wb: WorkbookContext, oldName: string, newName: string): Promise<void>

setSheetProperties

Set worksheet properties using a hierarchical structure. Supports partial updates - only specified properties are modified.

Surface	Call
Exec	`await xlsx.setSheetProperties(wb, ...)`
JavaScript SDK	`wb.setSheetProperties(sheet: string, properties: JsonMapping)`
Python SDK	`wb.set_sheet_properties(sheet_name: str, properties: SheetPropertiesUpdate)`

Signature

async function setSheetProperties(wb: WorkbookContext, sheetName: string, properties: { visibility?: SheetVisibility; view?: { showGridLines?: boolean; zoomScale?: number; freezeRows?: number; freezeColumns?: number; }; outline?: { summaryRowsBelow?: boolean; summaryColumnsRight?: boolean; showSymbols?: boolean; }; format?: { defaultRowHeight?: number; defaultColWidth?: number; font?: { name?: string; size?: number }; }; merges?: string[]; }): Promise<void>

getSheetProperties

Get worksheet properties in a hierarchical structure. Always includes sheet-wide defaults (view/format); columns/rows are returned for the specified filters or for all known dimensions when no filters are provided.

Surface	Call
Exec	`await xlsx.getSheetProperties(wb, ...)`
JavaScript SDK	`wb.getSheetProperties(sheet: string, options: { columns?: (number \| string)[]; rows?: number[] } = {})`
Python SDK	`wb.get_sheet_properties(sheet_name: str, columns: Sequence[int \| str] \| None = None, rows: Sequence[int] \| None = None)`

Signature

async function getSheetProperties(wb: WorkbookContext, sheetName: string, filter?: { columns?: (number | string)[]; rows?: number[] }): Promise<{
  visibility: "visible" | "hidden" | "veryHidden";
  view: {
    showGridLines: boolean;
    zoomScale: number;
    freezeRows: number;
    freezeColumns: number;
  };
  outline: {
    summaryRowsBelow: boolean;
    summaryColumnsRight: boolean;
    showSymbols: boolean;
  };
  format: {
    defaultRowHeight: number;
    defaultColWidth: number;
    font?: | {
        name?: string;
        size?: number;
      }
    | null;
  };
  columns: {
    [key: string]: {
    col: string;
    width: number;
    hidden?: boolean;
    outlineLevel?: number;
    collapsed?: boolean;
  };
  };
  rows: {
    [key: number]: {
    row: number;
    height: number;
    hidden?: boolean;
    outlineLevel?: number;
    collapsed?: boolean;
  };
  };
  merges?: string[] | null;
}>

Reading

readCell

Read a single cell's value and metadata; includes note/link/thread when present.

Surface	Call
Exec	`await xlsx.readCell(wb, ...)`
JavaScript SDK	`wb.readCell(cell: string, options: { context?: number } = {})`
Python SDK	`wb.read_cell(cell: CellRef, context: int \| None = None)`

Signature

async function readCell(wb: WorkbookContext, cell: CellAddressOrCoordinates, opts?: { context?: number }): Promise<{
  address: string;
  sheet: string;
  row: number;
  col: number;
  colLetter: string;
  value: string | number | boolean | null;
  formula?: string;
  type: "string" | "number" | "bool" | "date" | "error" | "blank";
  text: string;
  format?: string;
  numberType?: "currency" | "percent" | "fraction" | "exponential" | "date" | "text" | "number";
  visibility: "visible" | "outsidePrintArea" | "collapsed" | "hidden";
  context?: string;
  note?: {
    author: string;
    text: string;
  };
  link?: {
    type: "internal" | "external";
    target: string;
    tooltip?: string;
  };
  thread?: {
    resolved: boolean;
    comments: {
      authorId: string;
      text: string;
      createdAt: string;
    }[];
  };
}>

readRange

Read non-empty cells in a rectangular range as sparse rows; set includeEmpty for dense output.

Surface	Call
Exec	`await xlsx.readRange(wb, ...)`
JavaScript SDK	`wb.readRange(range: string)`
Python SDK	`wb.read_range(range: RangeRef)`

Signature

async function readRange(wb: WorkbookContext, range: RangeAddressOrCoordinates, opts?: { includeEmpty?: boolean }): Promise<{
  address: string;
  sheet: string;
  row: number;
  col: number;
  colLetter: string;
  value: string | number | boolean | null;
  formula?: string;
  type: "string" | "number" | "bool" | "date" | "error" | "blank";
  text: string;
  format?: string;
  numberType?: "currency" | "percent" | "fraction" | "exponential" | "date" | "text" | "number";
  visibility: "visible" | "outsidePrintArea" | "collapsed" | "hidden";
  context?: string;
  note?: {
    author: string;
    text: string;
  };
  link?: {
    type: "internal" | "external";
    target: string;
    tooltip?: string;
  };
  thread?: {
    resolved: boolean;
    comments: {
      authorId: string;
      text: string;
      createdAt: string;
    }[];
  };
}[][]>

readColumn

Read non-empty cells in a column within the used range; set includeEmpty for dense output.

Surface	Call
Exec	`await xlsx.readColumn(wb, ...)`
JavaScript SDK	`wb.readColumn(sheet: string, col: number \| string, options: { startRow?: number; endRow?: number } = {})`
Python SDK	`wb.read_column(sheet_name: str, col: int \| str, start_row: int \| None = None, end_row: int \| None = None)`

Signature

async function readColumn(wb: WorkbookContext, sheetName: string, col: number | string, opts?: { startRow?: number; endRow?: number; includeEmpty?: boolean }): Promise<{
  address: string;
  sheet: string;
  row: number;
  col: number;
  colLetter: string;
  value: string | number | boolean | null;
  formula?: string;
  type: "string" | "number" | "bool" | "date" | "error" | "blank";
  text: string;
  format?: string;
  numberType?: "currency" | "percent" | "fraction" | "exponential" | "date" | "text" | "number";
  visibility: "visible" | "outsidePrintArea" | "collapsed" | "hidden";
  context?: string;
  note?: {
    author: string;
    text: string;
  };
  link?: {
    type: "internal" | "external";
    target: string;
    tooltip?: string;
  };
  thread?: {
    resolved: boolean;
    comments: {
      authorId: string;
      text: string;
      createdAt: string;
    }[];
  };
}[]>

readRow

Read non-empty cells in a row within the used range; set includeEmpty for dense output.

Surface	Call
Exec	`await xlsx.readRow(wb, ...)`
JavaScript SDK	`wb.readRow(sheet: string, row: number, options: { startCol?: number; endCol?: number } = {})`
Python SDK	`wb.read_row(sheet_name: str, row: int, start_col: int \| None = None, end_col: int \| None = None)`

Signature

async function readRow(wb: WorkbookContext, sheetName: string, row: number, opts?: { startCol?: number; endCol?: number; includeEmpty?: boolean }): Promise<{
  address: string;
  sheet: string;
  row: number;
  col: number;
  colLetter: string;
  value: string | number | boolean | null;
  formula?: string;
  type: "string" | "number" | "bool" | "date" | "error" | "blank";
  text: string;
  format?: string;
  numberType?: "currency" | "percent" | "fraction" | "exponential" | "date" | "text" | "number";
  visibility: "visible" | "outsidePrintArea" | "collapsed" | "hidden";
  context?: string;
  note?: {
    author: string;
    text: string;
  };
  link?: {
    type: "internal" | "external";
    target: string;
    tooltip?: string;
  };
  thread?: {
    resolved: boolean;
    comments: {
      authorId: string;
      text: string;
      createdAt: string;
    }[];
  };
}[]>

readRangeTsv

Read a range as tab-separated values with row/column headers.

Surface	Call
Exec	`await xlsx.readRangeTsv(wb, ...)`
JavaScript SDK	`wb.readRangeTsv(range: string, options: { includeEmpty?: boolean; includeFormulas?: boolean } = {})`
Python SDK	`wb.read_range_tsv(range: RangeRef, include_empty: bool \| None = None, include_formulas: bool \| None = None)`

Signature

async function readRangeTsv(wb: WorkbookContext, range: RangeAddressOrCoordinates, opts?: { includeEmpty?: boolean; includeFormulas?: boolean }): Promise<string>

readColumnTsv

Read a column as tab-separated values.

Surface	Call
Exec	`await xlsx.readColumnTsv(wb, ...)`
JavaScript SDK	`wb.readColumnTsv(sheet: string, col: number \| string, options: { startRow?: number; endRow?: number; includeEmpty?: boolean; includeFormulas?: boolean; } = {})`
Python SDK	`wb.read_column_tsv(sheet_name: str, col: int \| str, start_row: int \| None = None, end_row: int \| None = None, include_empty: bool \| None = None, include_formulas: bool \| None = None)`

Signature

async function readColumnTsv(wb: WorkbookContext, sheetName: string, col: number | string, opts?: { startRow?: number; endRow?: number; includeEmpty?: boolean; includeFormulas?: boolean; }): Promise<string>

readRowTsv

Read a row as tab-separated values.

Surface	Call
Exec	`await xlsx.readRowTsv(wb, ...)`
JavaScript SDK	`wb.readRowTsv(sheet: string, row: number, options: { startCol?: number; endCol?: number; includeEmpty?: boolean; includeFormulas?: boolean; } = {})`
Python SDK	`wb.read_row_tsv(sheet_name: str, row: int, start_col: int \| None = None, end_col: int \| None = None, include_empty: bool \| None = None, include_formulas: bool \| None = None)`

Signature

async function readRowTsv(wb: WorkbookContext, sheetName: string, row: number, opts?: { startCol?: number; endCol?: number; includeEmpty?: boolean; includeFormulas?: boolean; }): Promise<string>

Search and discovery

findCells

Search for cells matching a value, substring, or regex pattern. When formulas is true, matches against formulas instead of text/values; cells without formulas are skipped. Examples:

text: findCells(wb, "Revenue")
number: findCells(wb, 42)
boolean: findCells(wb, true)
text synonyms: findCells(wb, ["Rev", "Revenue"])
regex: findCells(wb, /rev(enue)?/i)
regex array: findCells(wb, [/invest/i, /sales/i]) // OR matching
formula search: findCells(wb, "SUM", { formulas: true })

Surface	Call
Exec	`await xlsx.findCells(wb, ...)`
JavaScript SDK	`wb.findCells(matcher: Matcher, options: { in?: string; context?: number; limit?: number; offset?: number; formulas?: boolean; } = {})`
Python SDK	`wb.find_cells(matcher: Matcher, in_: RangeRef \| None = None, context: int = 2, limit: int = 20, offset: int = 0, formulas: bool \| None = None)`

Signature

async function findCells(wb: WorkbookContext, matcher: MatcherInput, opts: { in?: RangeAddressOrCoordinates | string; context?: number; limit?: number; offset?: number; formulas?: boolean; } = {}): Promise<{
  type: "cell";
  address: string;
  value: any;
  text: string;
  formula?: string;
  row: number;
  col: number;
  colLetter: string;
  sheet: string;
  visibility: "visible" | "outsidePrintArea" | "collapsed" | "hidden";
  context?: string;
  role: string;
}[]>

findRows

Search for rows containing a matching cell; returns full row data.

Surface	Call
Exec	`await xlsx.findRows(wb, ...)`
JavaScript SDK	`wb.findRows(matcher: Matcher, options: { in?: string; context?: number; limit?: number; offset?: number; } = {})`
Python SDK	`wb.find_rows(matcher: Matcher, in_: RangeRef \| None = None, context: int \| None = None, limit: int = 20, offset: int = 0)`

Signature

async function findRows(wb: WorkbookContext, matcher: MatcherInput, opts: { in?: RangeAddressOrCoordinates | string; context?: number; limit?: number; offset?: number; } = {}): Promise<{
  type: "row";
  row: number;
  sheet: string;
  matchedAt: string;
  range: string;
  tsv: string;
  visibility: "visible" | "outsidePrintArea" | "collapsed" | "hidden";
  context?: string;
}[]>

findAndReplace

Replace text in cell values or formulas across a workbook scope. For formula edits, prefer regex boundaries to avoid accidental partial reference replacements.

Surface	Call
Exec	`await xlsx.findAndReplace(wb, ...)`
JavaScript SDK	`wb.findAndReplace(find: ReplaceMatcher, replace: string, options: { in?: string; matchCase?: boolean; wholeCell?: boolean; inFormulas?: boolean; limit?: number; } = {})`
Python SDK	`wb.find_and_replace(find: ReplaceMatcher, replace: str, in_: RangeRef \| None = None, match_case: bool \| None = None, whole_cell: bool \| None = None, in_formulas: bool \| None = None, limit: int \| None = None)`

Signature

async function findAndReplace(wb: WorkbookContext, find: ReplaceMatcherInput, replace: string, opts: { in?: RangeAddressOrCoordinates | string; matchCase?: boolean; wholeCell?: boolean; inFormulas?: boolean; limit?: number; } = {}): Promise<{
  replaced: number;
  cells: string[];
  errors: {
    code: string;
    detail?: string;
    address: string;
    formula?: string;
  }[];
}>

describeSheet

Detected tables + compact ASCII structure map.

Surface	Call
Exec	`await xlsx.describeSheet(wb, ...)`
JavaScript SDK	`wb.describeSheet(sheet: string)`
Python SDK	`wb.describe_sheet(sheet_name: str)`

Signature

async function describeSheet(wb: WorkbookContext, sheet: string): Promise<{
  tables: {
    [key: string]: {
    address: string;
    headerRows: string;
    headerCols: string | null;
    tableName?: string;
  };
  };
  structure: string;
}>

tableLookup

Look up values in a table by row and column labels.

Searches the first column for rowLabel and the first row for columnLabel, returning all matching intersections sorted by match quality.

Surface	Call
Exec	`await xlsx.tableLookup(wb, ...)`
JavaScript SDK	`wb.tableLookup(table: string, rowLabel: string \| number \| boolean, columnLabel: string \| number \| boolean)`
Python SDK	`wb.table_lookup(table: str, row_label: str \| int \| float \| bool, column_label: str \| int \| float \| bool)`

Signature

async function tableLookup(wb: WorkbookContext, args: { /** Range address for the table (eg. "Sheet1!A1:D10") */ table: string; /** Row label to search for in the first column */ rowLabel: string | number | boolean; /** Column label to search for in the first row */ columnLabel: string | number | boolean; }): Promise<{
  address: string;
  value: any;
  text: string;
  row: number;
  col: number;
  colLetter: string;
  sheet: string;
  visibility: "visible" | "outsidePrintArea" | "collapsed" | "hidden";
  rowLabelFoundAt: string;
  rowLabelFound: string;
  columnLabelFoundAt: string;
  columnLabelFound: string;
}[]>

Tables, data tables, and charts

listCharts

List charts in the workbook or on a specific sheet.

Surface	Call
Exec	`await xlsx.listCharts(wb, ...)`
JavaScript SDK	`wb.listCharts(options: { sheet?: string } = {})`
Python SDK	`wb.list_charts(sheet: str \| None = None)`

Signature

async function listCharts(wb: WorkbookContext, options: { sheet?: string } = {}): Promise<{
  id?: number;
  sheet: string;
  name: string;
  type: string;
  groups: {
    type: string;
    axis?: "primary" | "secondary";
    seriesCount: number;
  }[];
  groupCount: number;
  seriesCount: number;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    sheet: string;
  };
}[]>

getChart

Get the canonical chart spec for an existing chart.

Surface	Call
Exec	`await xlsx.getChart(wb, ...)`
JavaScript SDK	`wb.getChart(sheet: string, name: string)`
Python SDK	`wb.get_chart(sheet: str, name: str)`

Signature

async function getChart(wb: WorkbookContext, sheet: string, chart: ChartSelector): Promise<{
  id?: number;
  name: string;
  groups: {
    type: "column" | "bar" | "line" | "area" | "pie" | "doughnut" | "scatter" | "bubble";
    scatterStyle?: "line" | "lineMarker" | "marker" | "smooth" | "smoothMarker";
    grouping?: "standard" | "stacked" | "percentStacked";
    axis?: "primary" | "secondary";
    gapWidth?: number;
    overlap?: number;
    varyColors?: boolean;
    smooth?: boolean;
    bubbleScale?: number;
    showNegativeBubbles?: boolean;
    sizeRepresents?: "area" | "width";
    firstSliceAngle?: number;
    holeSize?: number;
    series: {
      name?: ChartTextSource;
      categories?: string;
      categoriesRefType?: "string" | "number";
      values?: string;
      xValues?: string;
      yValues?: string;
      bubbleSizes?: string;
      fillColor?: string;
      lineColor?: string;
      lineWidth?: number;
      lineDashStyle?: string;
      smooth?: boolean;
      invertIfNegative?: boolean;
      marker?: ChartMarkerSpec;
      dataLabels?: ChartDataLabelsSpec;
    }[];
  }[];
  title?: {
    text?: string;
    ref?: string;
    overlay?: boolean;
  };
  legend?: {
    visible?: boolean;
    position?: "left" | "right" | "top" | "bottom" | "topRight";
    overlay?: boolean;
  };
  axes?: {
    category?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
    value?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
    secondaryCategory?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
    secondaryValue?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
  };
  displayBlanksAs?: "gap" | "span" | "zero";
  roundedCorners?: boolean;
  styleId?: number;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    sheet: string;
  };
}>

addChart

Add a new chart to a worksheet.

Surface	Call
Exec	`await xlsx.addChart(wb, ...)`
JavaScript SDK	`wb.addChart(sheet: string, chart: ChartSpec)`
Python SDK	`wb.add_chart(sheet: str, chart: ChartSpec)`

Signature

async function addChart(wb: WorkbookContext, sheet: string, chart: ChartSpec): Promise<{
  id?: number;
  name: string;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
  };
  groups: {
    type: "column" | "bar" | "line" | "area" | "pie" | "doughnut" | "scatter" | "bubble";
    scatterStyle?: "line" | "lineMarker" | "marker" | "smooth" | "smoothMarker";
    grouping?: "standard" | "stacked" | "percentStacked";
    axis?: "primary" | "secondary";
    gapWidth?: number;
    overlap?: number;
    varyColors?: boolean;
    smooth?: boolean;
    bubbleScale?: number;
    showNegativeBubbles?: boolean;
    sizeRepresents?: "area" | "width";
    firstSliceAngle?: number;
    holeSize?: number;
    series: {
      name?: ChartTextSource;
      categories?: string;
      categoriesRefType?: "string" | "number";
      values?: string;
      xValues?: string;
      yValues?: string;
      bubbleSizes?: string;
      fillColor?: string;
      lineColor?: string;
      lineWidth?: number;
      lineDashStyle?: string;
      smooth?: boolean;
      invertIfNegative?: boolean;
      marker?: ChartMarkerSpec;
      dataLabels?: ChartDataLabelsSpec;
    }[];
  }[];
  title?: {
    text?: string;
    ref?: string;
    overlay?: boolean;
  };
  legend?: {
    visible?: boolean;
    position?: "left" | "right" | "top" | "bottom" | "topRight";
    overlay?: boolean;
  };
  axes?: {
    category?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
    value?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
    secondaryCategory?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
    secondaryValue?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
  };
  displayBlanksAs?: "gap" | "span" | "zero";
  roundedCorners?: boolean;
  styleId?: number;
}>

setChart

Replace the spec of an existing chart.

Surface	Call
Exec	`await xlsx.setChart(wb, ...)`
JavaScript SDK	`wb.setChart(sheet: string, name: string, chart: ChartSpec)`
Python SDK	`wb.set_chart(sheet: str, name: str, chart: ChartSpec)`

Signature

async function setChart(wb: WorkbookContext, sheet: string, selector: ChartSelector, chart: ChartSpec): Promise<{
  id?: number;
  name: string;
  position: {
    from: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
    to: {
      cell: string;
      xOffsetPts?: number;
      yOffsetPts?: number;
    };
  };
  groups: {
    type: "column" | "bar" | "line" | "area" | "pie" | "doughnut" | "scatter" | "bubble";
    scatterStyle?: "line" | "lineMarker" | "marker" | "smooth" | "smoothMarker";
    grouping?: "standard" | "stacked" | "percentStacked";
    axis?: "primary" | "secondary";
    gapWidth?: number;
    overlap?: number;
    varyColors?: boolean;
    smooth?: boolean;
    bubbleScale?: number;
    showNegativeBubbles?: boolean;
    sizeRepresents?: "area" | "width";
    firstSliceAngle?: number;
    holeSize?: number;
    series: {
      name?: ChartTextSource;
      categories?: string;
      categoriesRefType?: "string" | "number";
      values?: string;
      xValues?: string;
      yValues?: string;
      bubbleSizes?: string;
      fillColor?: string;
      lineColor?: string;
      lineWidth?: number;
      lineDashStyle?: string;
      smooth?: boolean;
      invertIfNegative?: boolean;
      marker?: ChartMarkerSpec;
      dataLabels?: ChartDataLabelsSpec;
    }[];
  }[];
  title?: {
    text?: string;
    ref?: string;
    overlay?: boolean;
  };
  legend?: {
    visible?: boolean;
    position?: "left" | "right" | "top" | "bottom" | "topRight";
    overlay?: boolean;
  };
  axes?: {
    category?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
    value?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
    secondaryCategory?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
    secondaryValue?: {
      title?: {
        text?: string;
        ref?: string;
      };
      visible?: boolean;
      categoryType?: "category" | "date";
      min?: number;
      max?: number;
      majorUnit?: number;
      minorUnit?: number;
      baseTimeUnit?: "days" | "months" | "years";
      majorTimeUnit?: "days" | "months" | "years";
      minorTimeUnit?: "days" | "months" | "years";
      numberFormat?: string;
      reversed?: boolean;
      majorGridlines?: boolean;
      minorGridlines?: boolean;
      position?: "left" | "right" | "top" | "bottom";
    };
  };
  displayBlanksAs?: "gap" | "span" | "zero";
  roundedCorners?: boolean;
  styleId?: number;
}>

deleteChart

Delete a chart from a worksheet.

Surface	Call
Exec	`await xlsx.deleteChart(wb, ...)`
JavaScript SDK	`wb.deleteChart(sheet: string, name: string)`
Python SDK	`wb.delete_chart(sheet: str, name: str)`

Signature

async function deleteChart(wb: WorkbookContext, sheet: string, chart: ChartSelector): Promise<void>

getListObject

Get canonical metadata for a workbook ListObject.

Surface	Call
Exec	`await xlsx.getListObject(wb, ...)`
JavaScript SDK	`wb.getListObject(name: string)`
Python SDK	`wb.get_list_object(name: str)`

Signature

async function getListObject(wb: WorkbookContext, name: string): Promise<{
  name: string;
  sheet: string;
  ref: string;
  showHeaderRow: boolean;
  showTotalsRow: boolean;
  showAutoFilter: boolean;
  tableStyleName: string | null;
  showFirstColumn: boolean;
  showLastColumn: boolean;
  showRowStripes: boolean;
  showColumnStripes: boolean;
  headerRowRange: string | null;
  dataRange: string | null;
  totalsRowRange: string | null;
  columns: {
    name: string;
    totalsRowFunction?: string | null;
    totalsRowLabel?: string | null;
    totalsRowFormula?: string | null;
    calculatedColumnFormula?: string | null;
  }[];
}>

addListObject

Create a new ListObject on a worksheet.

Surface	Call
Exec	`await xlsx.addListObject(wb, ...)`
JavaScript SDK	`wb.addListObject(sheet: string, listObject: ListObjectSpec)`
Python SDK	`wb.add_list_object(sheet_name: str, list_object: ListObjectSpec)`

Signature

async function addListObject(wb: WorkbookContext, sheetName: string, listObject: ListObjectSpec): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    detail?: string;
    address: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
  listObject: {
    name: string;
    sheet: string;
    ref: string;
    showHeaderRow: boolean;
    showTotalsRow: boolean;
    showAutoFilter: boolean;
    tableStyleName: string | null;
    showFirstColumn: boolean;
    showLastColumn: boolean;
    showRowStripes: boolean;
    showColumnStripes: boolean;
    headerRowRange: string | null;
    dataRange: string | null;
    totalsRowRange: string | null;
    columns: {
      name: string;
      totalsRowFunction?: string | null;
      totalsRowLabel?: string | null;
      totalsRowFormula?: string | null;
      calculatedColumnFormula?: string | null;
    }[];
  };
}>

setListObject

Replace ListObject structure and properties in one operation.

Surface	Call
Exec	`await xlsx.setListObject(wb, ...)`
JavaScript SDK	`wb.setListObject(name: string, listObject: ListObjectUpdate)`
Python SDK	`wb.set_list_object(name: str, list_object: ListObjectUpdate)`

Signature

async function setListObject(wb: WorkbookContext, name: string, listObject: ListObjectUpdate): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    detail?: string;
    address: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
  listObject: {
    name: string;
    sheet: string;
    ref: string;
    showHeaderRow: boolean;
    showTotalsRow: boolean;
    showAutoFilter: boolean;
    tableStyleName: string | null;
    showFirstColumn: boolean;
    showLastColumn: boolean;
    showRowStripes: boolean;
    showColumnStripes: boolean;
    headerRowRange: string | null;
    dataRange: string | null;
    totalsRowRange: string | null;
    columns: {
      name: string;
      totalsRowFunction?: string | null;
      totalsRowLabel?: string | null;
      totalsRowFormula?: string | null;
      calculatedColumnFormula?: string | null;
    }[];
  };
}>

deleteListObject

Delete a ListObject but keep the underlying range cells.

Surface	Call
Exec	`await xlsx.deleteListObject(wb, ...)`
JavaScript SDK	`wb.deleteListObject(name: string)`
Python SDK	`wb.delete_list_object(name: str)`

Signature

async function deleteListObject(wb: WorkbookContext, name: string): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    detail?: string;
    address: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
}>

getDataTable

Get canonical metadata for a What-If DataTable.

Surface	Call
Exec	`await xlsx.getDataTable(wb, ...)`
JavaScript SDK	`wb.getDataTable(address: string)`
Python SDK	`wb.get_data_table(address: str)`

Signature

async function getDataTable(wb: WorkbookContext, address: string): Promise<| {
    type: "oneVariableColumn";
    sheet: string;
    ref: string;
    dataTableRange: string;
    rowInputCell: null;
    columnInputCell: string;
    inputValues: string | number | boolean | null[];
    rowInputValues: null;
    columnInputValues: null;
    formulas: {
      formula: string;
    }[];
    formula: null;
  }
| {
    type: "oneVariableRow";
    sheet: string;
    ref: string;
    dataTableRange: string;
    rowInputCell: string;
    columnInputCell: null;
    inputValues: string | number | boolean | null[];
    rowInputValues: null;
    columnInputValues: null;
    formulas: {
      formula: string;
    }[];
    formula: null;
  }
| {
    type: "twoVariable";
    sheet: string;
    ref: string;
    dataTableRange: string;
    rowInputCell: string;
    columnInputCell: string;
    inputValues: null;
    rowInputValues: string | number | boolean | null[];
    columnInputValues: string | number | boolean | null[];
    formulas: null;
    formula: string;
  }>

addDataTable

Create a What-If DataTable from its visible footprint and input metadata.

Surface	Call
Exec	`await xlsx.addDataTable(wb, ...)`
JavaScript SDK	`wb.addDataTable(sheet: string, dataTable: DataTableSpec)`
Python SDK	`wb.add_data_table(sheet_name: str, data_table: DataTableSpec)`

Signature

async function addDataTable(wb: WorkbookContext, sheetName: string, dataTable: DataTableSpec): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    detail?: string;
    address: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
  dataTable: | {
      type: "oneVariableColumn";
      sheet: string;
      ref: string;
      dataTableRange: string;
      rowInputCell: null;
      columnInputCell: string;
      inputValues: string | number | boolean | null[];
      rowInputValues: null;
      columnInputValues: null;
      formulas: {
        formula: string;
      }[];
      formula: null;
    }
  | {
      type: "oneVariableRow";
      sheet: string;
      ref: string;
      dataTableRange: string;
      rowInputCell: string;
      columnInputCell: null;
      inputValues: string | number | boolean | null[];
      rowInputValues: null;
      columnInputValues: null;
      formulas: {
        formula: string;
      }[];
      formula: null;
    }
  | {
      type: "twoVariable";
      sheet: string;
      ref: string;
      dataTableRange: string;
      rowInputCell: string;
      columnInputCell: string;
      inputValues: null;
      rowInputValues: string | number | boolean | null[];
      columnInputValues: string | number | boolean | null[];
      formulas: null;
      formula: string;
    };
}>

deleteDataTable

Delete a What-If DataTable and clear its visible footprint.

Surface	Call
Exec	`await xlsx.deleteDataTable(wb, ...)`
JavaScript SDK	`wb.deleteDataTable(address: string)`
Python SDK	`wb.delete_data_table(address: str)`

Signature

async function deleteDataTable(wb: WorkbookContext, address: string): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    detail?: string;
    address: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
}>

Writing and structure

setCells

Write to one or more cells in a single operation.

Surface	Call
Exec	`await xlsx.setCells(wb, ...)`
JavaScript SDK	`wb.setCells(cells: CellAssignment[])`
Python SDK	`wb.set_cells(cells: Sequence[JsonMapping])`

Signature

async function setCells(wb: WorkbookContext, cells: Array< { address: CellAddressOrCoordinates; } & CellWrite >): Promise<{
  touched: {
    [key: string]: string;
  };
  changed: string[];
  errors: {
    code: string;
    detail?: string;
    address: string;
    formula?: string;
  }[];
  invalidatedTiles: {
    sheet: string;
    tileRow: number;
    tileCol: number;
  }[];
  updatedSheets: {
    name: string;
    usedRange: | {
        startRow: number;
        startCol: number;
        endRow: number;
        endCol: number;
      }
    | null;
    tileRowCount: number;
    tileColCount: number;
  }[];
}>

scaleRange

Multiply all numeric cells in a range by a scale factor. Formula cells are skipped by default.

Surface	Call
Exec	`await xlsx.scaleRange(wb, ...)`
JavaScript SDK	`wb.scaleRange(range: string, factor: number, options: { skipFormulas?: boolean } = {})`
Python SDK	`wb.scale_range(range: RangeRef, factor: float, skip_formulas: bool = True)`

Signature

async function scaleRange(wb: WorkbookContext, range: RangeAddressOrCoordinates, factor: number, opts?: { skipFormulas?: boolean }): Promise<| {
    touched: {
      [key: string]: string;
    };
    changed: string[];
    errors: {
      code: string;
      detail?: string;
      address: string;
      formula?: string;
    }[];
    invalidatedTiles: {
      sheet: string;
      tileRow: number;
      tileCol: number;
    }[];
    updatedSheets: {
      name: string;
      usedRange: | {
          startRow: number;
          startCol: number;
          endRow: number;
          endCol: number;
        }
      | null;
      tileRowCount: number;
      tileColCount: number;
    }[];
  }
| null>

insertRowAfter

Insert one or more rows after the specified row.

Surface	Call
Exec	`await xlsx.insertRowAfter(wb, ...)`
JavaScript SDK	`wb.insertRowAfter(sheet: string, row: number, count = 1)`
Python SDK	`wb.insert_row_after(sheet_name: str, row: int, count: int = 1)`

Signature

async function insertRowAfter(wb: WorkbookContext, sheetName: string, row: number, count: number = 1): Promise<void>

deleteRows

Delete one or more rows starting at the specified row.

Surface	Call
Exec	`await xlsx.deleteRows(wb, ...)`
JavaScript SDK	`wb.deleteRows(sheet: string, row: number, count = 1)`
Python SDK	`wb.delete_rows(sheet_name: str, row: int, count: int = 1)`

Signature

async function deleteRows(wb: WorkbookContext, sheetName: string, row: number, count: number = 1): Promise<void>

insertColumnAfter

Insert one or more columns after the specified column.

Surface	Call
Exec	`await xlsx.insertColumnAfter(wb, ...)`
JavaScript SDK	`wb.insertColumnAfter(sheet: string, column: number \| string, count = 1)`
Python SDK	`wb.insert_column_after(sheet_name: str, column: int \| str, count: int = 1)`

Signature

async function insertColumnAfter(wb: WorkbookContext, sheetName: string, column: number | string, count: number = 1): Promise<void>

deleteColumns

Delete one or more columns starting at the specified column.

Surface	Call
Exec	`await xlsx.deleteColumns(wb, ...)`
JavaScript SDK	`wb.deleteColumns(sheet: string, column: number \| string, count = 1)`
Python SDK	`wb.delete_columns(sheet_name: str, column: int \| str, count: int = 1)`

Signature

async function deleteColumns(wb: WorkbookContext, sheetName: string, column: number | string, count: number = 1): Promise<void>

autoFitColumns

Auto-fit one or more columns to their visible cell contents.

Surface	Call
Exec	`await xlsx.autoFitColumns(wb, ...)`
JavaScript SDK	`wb.autoFitColumns(sheet: string, columns?: (number \| string)[], options: { minWidth?: number; maxWidth?: number; padding?: number } = {})`
Python SDK	`wb.auto_fit_columns(sheet_name: str, columns: Sequence[int \| str] \| None = None, min_width: float \| None = None, max_width: float \| None = None, padding: float \| None = None)`

Signature

async function autoFitColumns(wb: WorkbookContext, sheetName: string, columns?: Array<number | string>, opts?: { minWidth?: number; maxWidth?: number; padding?: number; }): Promise<{
  [key: string]: {
  width: number;
  previousWidth: number;
};
}>

autoFitRows

Auto-fit one or more rows to their visible cell contents.

Surface	Call
Exec	`await xlsx.autoFitRows(wb, ...)`
JavaScript SDK	`wb.autoFitRows(sheet: string, rows?: number[], options: { minHeight?: number; maxHeight?: number } = {})`
Python SDK	`wb.auto_fit_rows(sheet_name: str, rows: Sequence[int] \| None = None, min_height: float \| None = None, max_height: float \| None = None)`

Signature

async function autoFitRows(wb: WorkbookContext, sheetName: string, rows?: number[], opts?: { minHeight?: number; maxHeight?: number; }): Promise<{
  [key: string]: {
  height: number;
  previousHeight: number;
  hidden: boolean;
  previousHidden: boolean;
};
}>

sortRange

Sort rows in a rectangular range by one or more column keys.

Surface	Call
Exec	`await xlsx.sortRange(wb, ...)`
JavaScript SDK	`wb.sortRange(range: string, keys: SortKey[], options: { hasHeader?: boolean } = {})`
Python SDK	`wb.sort_range(range: RangeRef, keys: Sequence[JsonMapping], has_header: bool \| None = None)`

Signature

async function sortRange(wb: WorkbookContext, range: RangeAddressOrCoordinates, keys: Array<{ col: number | string; order?: "asc" | "desc" }>, opts?: { hasHeader?: boolean }): Promise<void>

copyRange

Copy a source range to a destination anchor, with optional paste behavior.

Surface	Call
Exec	`await xlsx.copyRange(wb, ...)`
JavaScript SDK	`wb.copyRange(source: string, destination: string, options: { pasteType?: PasteType } = {})`
Python SDK	`wb.copy_range(source: RangeRef, destination: CellRef, paste_type: Literal["all", "values", "formulas", "formats"] \| None = None)`

Signature

async function copyRange(wb: WorkbookContext, source: RangeAddressOrCoordinates, destination: CellAddressOrCoordinates, opts?: { pasteType?: "all" | "values" | "formulas" | "formats"; }): Promise<{
  destination: string;
  cellsCopied: number;
}>

setRowProperties

Set properties for a contiguous row range.

Surface	Call
Exec	`await xlsx.setRowProperties(wb, ...)`
JavaScript SDK	`wb.setRowProperties(sheet: string, fromRow: number, toRow: number, properties: JsonMapping)`
Python SDK	`wb.set_row_properties(sheet_name: str, from_row: int, to_row: int, properties: JsonMapping)`

Signature

async function setRowProperties(wb: WorkbookContext, sheetName: string, fromRow: number, toRow: number, properties: { height?: number; hidden?: boolean; outlineLevel?: number; collapsed?: boolean; }): Promise<void>

setColumnProperties

Set properties for a contiguous column range.

Surface	Call
Exec	`await xlsx.setColumnProperties(wb, ...)`
JavaScript SDK	`wb.setColumnProperties(sheet: string, fromCol: number \| string, toCol: number \| string, properties: JsonMapping)`
Python SDK	`wb.set_column_properties(sheet_name: str, from_col: int \| str, to_col: int \| str, properties: JsonMapping)`

Signature

async function setColumnProperties(wb: WorkbookContext, sheetName: string, fromCol: number | string, toCol: number | string, properties: { width?: number; hidden?: boolean; outlineLevel?: number; collapsed?: boolean; }): Promise<void>

Styles and formatting

getConditionalFormatting

Get all conditional formatting rules on a sheet.

Surface	Call
Exec	`await xlsx.getConditionalFormatting(wb, ...)`
JavaScript SDK	`wb.getConditionalFormatting(sheet: string)`
Python SDK	`wb.get_conditional_formatting(sheet_name: str)`

Signature

async function getConditionalFormatting(wb: WorkbookContext, sheetName: string): Promise<{
  address: string;
  priority?: number;
  stopIfTrue?: boolean;
  style?: {
    fill?: {
      color?: string;
      pattern?: string;
      patternColor?: string;
      gradient?: {
        type: string;
        degree?: number;
        color1: string;
        color2: string;
        top?: number;
        bottom?: number;
        left?: number;
        right?: number;
      };
    };
    font?: {
      name?: string;
      size?: number;
      color?: string;
      bold?: boolean;
      italic?: boolean;
      strike?: boolean;
      underline?: string;
      verticalAlign?: string;
    };
    alignment?: {
      horizontal?: string;
      vertical?: string;
      rotation?: number;
      wrapText?: boolean;
      shrinkToFit?: boolean;
      indent?: number;
      readingOrder?: "context" | "leftToRight" | "rightToLeft";
      autoIndent?: boolean;
    };
    protection?: {
      locked?: boolean;
      formulaHidden?: boolean;
    };
    border?: {
      top?: {
        style?: string;
        color?: string;
        themeColor?: ThemeColorName;
        tintAndShade?: number;
      };
      bottom?: {
        style?: string;
        color?: string;
        themeColor?: ThemeColorName;
        tintAndShade?: number;
      };
      left?: {
        style?: string;
        color?: string;
        themeColor?: ThemeColorName;
        tintAndShade?: number;
      };
      right?: {
        style?: string;
        color?: string;
        themeColor?: ThemeColorName;
        tintAndShade?: number;
      };
      diagonal?: {
        style?: string;
        color?: string;
        themeColor?: | "background1" | "light1" | "text1" | "dark1" | "background2" | "light2" | "text2" | "dark2" | "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "hyperlink" | "followedHyperlink";
        tintAndShade?: number;
        up?: boolean;
        down?: boolean;
      };
    };
    numberFormat?: string;
    centerContinuousSpan?: number;
    richText?: {
      text: string;
      style?: { name?: string; size?: number; color?: string; bold?: boolean; italic?: boolean; strike?: boolean; underline?: string; verticalAlign?: string; };
    }[];
  };
  operator?: | "equal"
  | "notEqual"
  | "greaterThan"
  | "greaterThanOrEqual"
  | "lessThan"
  | "lessThanOrEqual"
  | "between"
  | "notBetween";
  formula?: string;
  formula2?: string;
  text?: string;
  rank?: number;
  percent?: boolean;
  equalAverage?: boolean;
  stdDev?: number;
  lowValue?: {
    type: "formula" | "max" | "min" | "num" | "percent" | "percentile" | "autoMin" | "autoMax";
    value?: number;
    formula?: string;
    color?: string;
  };
  midValue?: {
    type: "formula" | "max" | "min" | "num" | "percent" | "percentile" | "autoMin" | "autoMax";
    value?: number;
    formula?: string;
    color?: string;
  };
  highValue?: {
    type: "formula" | "max" | "min" | "num" | "percent" | "percentile" | "autoMin" | "autoMax";
    value?: number;
    formula?: string;
    color?: string;
  };
  dataBar?: {
    showValue?: boolean;
    gradient?: boolean;
    border?: boolean;
    negativeBarColorSameAsPositive?: boolean;
    negativeBarBorderColorSameAsPositive?: boolean;
    axisPosition?: "automatic" | "middle" | "none";
    direction?: "context" | "leftToRight" | "rightToLeft";
    fillColor?: string;
    borderColor?: string;
    negativeFillColor?: string;
    negativeBorderColor?: string;
    axisColor?: string;
    lowValue?: {
      type: "formula" | "max" | "min" | "num" | "percent" | "percentile" | "autoMin" | "autoMax";
      value?: number;
      formula?: string;
    };
    highValue?: {
      type: "formula" | "max" | "min" | "num" | "percent" | "percentile" | "autoMin" | "autoMax";
      value?: number;
      formula?: string;
    };
  };
  timePeriod?: | "today"
  | "yesterday"
  | "tomorrow"
  | "last7Days"
  | "thisWeek"
  | "lastWeek"
  | "nextWeek"
  | "thisMonth"
  | "lastMonth"
  | "nextMonth";
  index?: number;
  type: | "cellValue"
  | "containsText"
  | "notContainsText"
  | "beginsWith"
  | "endsWith"
  | "containsBlanks"
  | "notContainsBlanks"
  | "containsErrors"
  | "notContainsErrors"
  | "expression"
  | "timePeriod"
  | "top"
  | "bottom"
  | "aboveAverage"
  | "belowAverage"
  | "duplicateValues"
  | "uniqueValues"
  | "twoColorScale"
  | "threeColorScale"
  | "dataBar"
  | "iconSet";
}[]>

setConditionalFormatting

Add conditional formatting rules to a sheet. Rule addresses must be concrete A1 ranges on the target sheet; same-sheet multi-area unions are supported. Use opts.clear=true to replace all existing rules first.

Surface	Call
Exec	`await xlsx.setConditionalFormatting(wb, ...)`
JavaScript SDK	`wb.setConditionalFormatting(sheet: string, rules: ConditionalFormattingRule[], options: { clear?: boolean } = {})`
Python SDK	`wb.set_conditional_formatting(sheet_name: str, rules: Sequence[ConditionalFormattingRule], clear: bool \| None = None)`

Signature

async function setConditionalFormatting(wb: WorkbookContext, sheetName: string, rules: CfWritableRule[], opts?: { clear?: boolean }): Promise<void>

removeConditionalFormatting

Remove conditional formatting rules by index.

Surface	Call
Exec	`await xlsx.removeConditionalFormatting(wb, ...)`
JavaScript SDK	`wb.removeConditionalFormatting(sheet: string, indices: number[])`
Python SDK	`wb.remove_conditional_formatting(sheet_name: str, indices: Sequence[int])`

Signature

async function removeConditionalFormatting(wb: WorkbookContext, sheetName: string, indices: number[]): Promise<void>

getStyle

Get the style properties of a cell.

Surface	Call
Exec	`await xlsx.getStyle(wb, ...)`
JavaScript SDK	`wb.getStyle(cell: string)`
Python SDK	`wb.get_style(cell: CellRef)`

Signature

async function getStyle(wb: WorkbookContext, cell: CellAddressOrCoordinates): Promise<{
  fill?: {
    color?: string;
    pattern?: string;
    patternColor?: string;
    gradient?: {
      type: string;
      degree?: number;
      color1: string;
      color2: string;
      top?: number;
      bottom?: number;
      left?: number;
      right?: number;
    };
  };
  font?: {
    name?: string;
    size?: number;
    color?: string;
    bold?: boolean;
    italic?: boolean;
    strike?: boolean;
    underline?: string;
    verticalAlign?: string;
  };
  alignment?: {
    horizontal?: string;
    vertical?: string;
    rotation?: number;
    wrapText?: boolean;
    shrinkToFit?: boolean;
    indent?: number;
    readingOrder?: "context" | "leftToRight" | "rightToLeft";
    autoIndent?: boolean;
  };
  protection?: {
    locked?: boolean;
    formulaHidden?: boolean;
  };
  border?: {
    top?: {
      style?: string;
      color?: string;
      themeColor?: | "background1"
      | "light1"
      | "text1"
      | "dark1"
      | "background2"
      | "light2"
      | "text2"
      | "dark2"
      | "accent1"
      | "accent2"
      | "accent3"
      | "accent4"
      | "accent5"
      | "accent6"
      | "hyperlink"
      | "followedHyperlink";
      tintAndShade?: number;
    };
    bottom?: {
      style?: string;
      color?: string;
      themeColor?: | "background1"
      | "light1"
      | "text1"
      | "dark1"
      | "background2"
      | "light2"
      | "text2"
      | "dark2"
      | "accent1"
      | "accent2"
      | "accent3"
      | "accent4"
      | "accent5"
      | "accent6"
      | "hyperlink"
      | "followedHyperlink";
      tintAndShade?: number;
    };
    left?: {
      style?: string;
      color?: string;
      themeColor?: | "background1"
      | "light1"
      | "text1"
      | "dark1"
      | "background2"
      | "light2"
      | "text2"
      | "dark2"
      | "accent1"
      | "accent2"
      | "accent3"
      | "accent4"
      | "accent5"
      | "accent6"
      | "hyperlink"
      | "followedHyperlink";
      tintAndShade?: number;
    };
    right?: {
      style?: string;
      color?: string;
      themeColor?: | "background1"
      | "light1"
      | "text1"
      | "dark1"
      | "background2"
      | "light2"
      | "text2"
      | "dark2"
      | "accent1"
      | "accent2"
      | "accent3"
      | "accent4"
      | "accent5"
      | "accent6"
      | "hyperlink"
      | "followedHyperlink";
      tintAndShade?: number;
    };
    diagonal?: {
      style?: string;
      color?: string;
      themeColor?: | "background1"
      | "light1"
      | "text1"
      | "dark1"
      | "background2"
      | "light2"
      | "text2"
      | "dark2"
      | "accent1"
      | "accent2"
      | "accent3"
      | "accent4"
      | "accent5"
      | "accent6"
      | "hyperlink"
      | "followedHyperlink";
      tintAndShade?: number;
      up?: boolean;
      down?: boolean;
    };
  };
  numberFormat?: string;
  centerContinuousSpan?: number;
  richText?: {
    text: string;
    style?: {
      name?: string;
      size?: number;
      color?: string;
      bold?: boolean;
      italic?: boolean;
      strike?: boolean;
      underline?: string;
      verticalAlign?: string;
    };
  }[];
}>

setStyle

Apply style properties to a cell or range. Available fields: bold/italic/underline (booleans), color/background (hex strings), align/valign (horizontal/vertical alignment), readingOrder, protection, format (number format string), border (thin|medium|thick plus color/themeColor/tintAndShade), wrapText (boolean), fontSize/fontName, and indent (number).

Surface	Call
Exec	`await xlsx.setStyle(wb, ...)`
JavaScript SDK	`wb.setStyle(target: string, style: Style)`
Python SDK	`wb.set_style(target: CellRef \| RangeRef, style: Style)`

Signature

async function setStyle(wb: WorkbookContext, target: CellAddressOrCoordinates | RangeAddressOrCoordinates, style: StyleObj): Promise<void>

Formulas and dependencies

getCellPrecedents

Get cells that the given cell depends on (its precedents)

Surface	Call
Exec	`await xlsx.getCellPrecedents(wb, ...)`
JavaScript SDK	`wb.getCellPrecedents(address: string, depth: number \| typeof Infinity = 1)`
Python SDK	`wb.get_cell_precedents(address: CellRef, depth: int \| float = 1)`

Signature

async function getCellPrecedents(wb: WorkbookContext, address: CellAddressOrCoordinates, depth: number = 1): Promise<{
  cells: {
    address: string;
    depth: number;
    formula?: string;
    referenceType?: "direct" | "range" | "named" | "table";
  }[];
  warnings?: {
    code: string;
    detail?: string;
    address: string;
    formula?: string;
  }[];
}>

getCellDependents

Get cells that depend on the given cell (its dependents)

Surface	Call
Exec	`await xlsx.getCellDependents(wb, ...)`
JavaScript SDK	`wb.getCellDependents(address: string, depth: number \| typeof Infinity = 1)`
Python SDK	`wb.get_cell_dependents(address: CellRef, depth: int \| float = 1)`

Signature

async function getCellDependents(wb: WorkbookContext, address: CellAddressOrCoordinates, depth: number = 1): Promise<{
  cells: {
    address: string;
    depth: number;
    formula?: string;
    referenceType?: "direct" | "range" | "named" | "table";
  }[];
  warnings?: {
    code: string;
    detail?: string;
    address: string;
    formula?: string;
  }[];
}>

traceToInputs

Trace backwards from a cell to find all input cells that feed into it

Surface	Call
Exec	`await xlsx.traceToInputs(wb, ...)`
JavaScript SDK	`wb.traceToInputs(address: string)`
Python SDK	`wb.trace_to_inputs(cell: CellRef)`

Signature

async function traceToInputs(wb: WorkbookContext, cell: CellAddressOrCoordinates): Promise<{
  address: string;
  referenceCount: number;
  text?: string;
  nearbyLabel?: string;
  context?: string;
}[]>

traceToOutputs

Trace forwards from a cell to find all output cells that depend on it

Surface	Call
Exec	`await xlsx.traceToOutputs(wb, ...)`
JavaScript SDK	`wb.traceToOutputs(address: string)`
Python SDK	`wb.trace_to_outputs(cell: CellRef)`

Signature

async function traceToOutputs(wb: WorkbookContext, cell: CellAddressOrCoordinates): Promise<{
  address: string;
  formula?: string;
  text?: string;
  visibility: "visible" | "outsidePrintArea" | "collapsed" | "hidden";
  nearbyLabel?: string;
  context?: string;
}[]>

sweepInputs

Run a batch what-if input sweep across one or more input cells and collect before/after outputs. Supports cartesian product or parallel zip semantics. The first output entry is the baseline before applying new inputs.

Surface	Call
Exec	`await xlsx.sweepInputs(wb, ...)`
JavaScript SDK	`wb.sweepInputs(inputs: SweepInput[], outputs: string[], options: { mode?: SweepMode; includeStats?: boolean } = {})`
Python SDK	`wb.sweep_inputs(inputs: Sequence[JsonMapping], outputs: Sequence[str \| CellRef], mode: Literal["cartesian", "parallel"] \| None = None, include_stats: bool \| None = None)`

Signature

async function sweepInputs(wb: WorkbookContext, args: { inputs: SweepInput[]; outputs: (string | CellAddressOrCoordinates)[]; mode?: "cartesian" | "parallel"; includeStats?: boolean; }): Promise<{
  tsv: string;
  sweeps: {
    inputs: {
      [key: string]: string;
    };
    outputs: {
      [key: string]: string;
    };
    errors: {
      code: string;
      detail?: string;
      address: string;
      formula?: string;
    }[];
  }[];
  stats?: {
    [key: string]: {
    min: number;
    max: number;
    mean: number;
    count: number;
  };
  };
  sweepCount: number;
  inputCount: number;
  outputCount: number;
}>

evaluateFormulas

Evaluate multiple formulas in the context of a specific worksheet. Useful for ad-hoc calculations; formulas are evaluated without modifying any cells.

The sheet parameter specifies which worksheet the formulas are evaluated in. This affects how unqualified cell references (like A1) and sheet-scoped named ranges are resolved.

@example

const results = await evaluateFormulas(wb, "Sheet1", [
  "=SUM(A1:A10)",           // Resolved as Sheet1!A1:A10
  "=AVERAGE(B:B)",          // Resolved as Sheet1!B:B
  "=MAX('Other Sheet'!C1:C100)", // Explicit sheet reference
]);

Surface	Call
Exec	`await xlsx.evaluateFormulas(wb, ...)`
JavaScript SDK	`wb.evaluateFormulas(sheet: string, formulas: string[])`
Python SDK	`wb.evaluate_formulas(sheet: str, formulas: Sequence[str])`

Signature

async function evaluateFormulas(wb: WorkbookContext, sheet: string, formulas: string[]): Promise<{
  formula: string;
  value: number | string | boolean | null | unknown[][];
  error?: {
    code: string;
    detail?: string;
  };
}[]>

evaluateFormula

Evaluate a single formula in the context of a specific worksheet. Useful for ad-hoc calculations; the formula is evaluated without modifying any cells.

The sheet parameter specifies which worksheet the formula is evaluated in. This affects how unqualified cell references (like A1) and sheet-scoped named ranges are resolved.

@example

// Unqualified references resolved in Sheet1's context
const sum = await evaluateFormula(wb, "Sheet1", "=SUM(A1:A100)");
console.log(sum.value); // 1500

// Named ranges resolved with sheet scope
const total = await evaluateFormula(wb, "Data", "=SUM(Revenue)");

// Cross-sheet formulas work with explicit references
const diff = await evaluateFormula(wb, "Summary", "='Sheet1'!A1 - 'Sheet2'!A1");

// Array formula result
const unique = await evaluateFormula(wb, "Sheet1", "=UNIQUE(A1:A10)");
console.log(unique.type); // "array"
console.log(unique.value); // [["Apple"], ["Banana"], ["Cherry"]]

Surface	Call
Exec	`await xlsx.evaluateFormula(wb, ...)`
JavaScript SDK	`wb.evaluateFormula(sheet: string, formula: string)`
Python SDK	`wb.evaluate_formula(sheet: str, formula: str)`

Signature

async function evaluateFormula(wb: WorkbookContext, sheet: string, formula: string): Promise<{
  formula: string;
  value: number | string | boolean | null | unknown[][];
  error?: {
    code: string;
    detail?: string;
  };
}>

Verification and rendering

lint

Lint the workbook to find potential issues and code smells.

Returns diagnostics for issues like:

Empty cell coercion (D003)
Non-numeric values in aggregate functions (D005)
Duplicate values in lookup arrays (D007)

@example

// Get all diagnostics
const result = await lint(wb);
console.log(`Found ${result.total} issues`);
for (const diag of result.diagnostics) {
  console.log(`[${diag.severity}] ${diag.ruleId}: ${diag.message} at ${diag.location}`);
}

// Lint only specific ranges
const rangeResult = await lint(wb, { rangeAddresses: ["Sheet1!A1:B10", "Sheet2!C1:C20"] });

// Only check for empty cell coercion
const coercionIssues = await lint(wb, { onlyRuleIds: ["D003"] });

Surface	Call
Exec	`await xlsx.lint(wb, ...)`
JavaScript SDK	`wb.lint(options: { rangeAddresses?: string[]; skipRuleIds?: string[]; onlyRuleIds?: string[]; } = {})`
Python SDK	`wb.lint(range_addresses: Sequence[str] \| None = None, skip_rule_ids: Sequence[str] \| None = None, only_rule_ids: Sequence[str] \| None = None)`

Signature

async function lint(wb: WorkbookContext, options?: { /** Array of cell ranges to analyze (e.g., ["Sheet1!A1:B10", "Sheet2!C1:C20"]). If omitted, analyzes entire workbook. */ rangeAddresses?: string[]; /** Array of rule IDs to skip (e.g., ["D003"] to skip empty cell coercion checks) */ skipRuleIds?: string[]; /** Array of rule IDs to exclusively run (e.g., ["D003"] to only check empty cell coercion) */ onlyRuleIds?: string[]; }): Promise<{
  diagnostics: {
    severity: "Info" | "Warning" | "Error";
    ruleId: string;
    message: string;
    location: string | null;
    visibility: "visible" | "outsidePrintArea" | "collapsed" | "hidden" | null;
  }[];
  total: number;
}>

previewStyles

Generate a PNG screenshot of a specified cell range.

Surface	Call
Exec	`await xlsx.previewStyles(wb, ...)`
JavaScript SDK	`wb.previewStyles(range: string)`
Python SDK	`wb.preview_styles(range: RangeRef)`

Signature

async function previewStyles(wb: WorkbookContext, range: RangeAddressOrCoordinates): Promise<void>

Utilities

reduceAddresses

Reduce overlapping or adjacent addresses to the smallest equivalent address list.

Surface	Call
Exec	`await xlsx.reduceAddresses(wb, ...)`
JavaScript SDK	`wb.reduceAddresses(addresses: string[])`
Python SDK	`wb.reduce_addresses(addresses: Sequence[CellRef \| RangeRef])`

Signature

async function reduceAddresses(wb: WorkbookContext, addresses: string[]): Promise<string[]>

CLI