ws.tables

add(range: string | CellRange, options?: TableOptions): Promise<TableInfo>;

Create a new table from a cell range. @param range - A1-style range string (e.g. "A1:D10") or CellRange object @param options - Optional table creation settings (name, headers, style) @returns The created table information

get(name: string): Promise<TableInfo | null>;

Get a table by name. Tables are workbook-scoped, so the name is unique across all sheets. @param name - Table name @returns Table information, or null if not found

has(name: string): Promise<boolean>;

Check if a table exists by name. @param name - Table name @returns True if the table exists

list(): Promise<TableInfo[]>;

List all tables in this worksheet. @returns Array of table information objects

getCount(): Promise<number>;

Get the total number of tables on this worksheet. @returns The count of tables

getItemAt(index: number): Promise<TableInfo | null>;

Get a table by its position in the list of tables on this worksheet. @param index - Zero-based index into the table list @returns Table information, or null if the index is out of range

getFirst(): Promise<TableInfo | null>;

Get the first table on this worksheet. Convenience shortcut equivalent to `getAt(0)`. @returns Table information, or null if no tables exist

getColumnByName(tableName: string, columnName: string): Promise<TableColumn | null>;

Look up a column in a table by its header name. @param tableName - Table name @param columnName - Column header name to search for @returns The matching column, or null if not found

remove(name: string): Promise<void>;

Remove a table definition, converting it back to a plain range. Cell data is preserved; only the table metadata is removed. @param name - Table name

clear(): Promise<void>;

Remove all tables from this worksheet.

rename(oldName: string, newName: string): Promise<void>;

Rename a table. @param oldName - Current table name @param newName - New table name

update(tableName: string, updates: TableUpdateOptions): Promise<void>;

Update a table's properties. @param tableName - Table name @param updates - Key-value pairs of properties to update

getAtCell(address: string): Promise<TableInfo | null>;

Get the table at a specific cell position, if one exists. @param address - A1-style cell address (e.g. "B3") @returns Table information, or null if no table exists at that cell

clearFilters(tableName: string): Promise<void>;

Clear all column filters on a table. @param tableName - Table name

setStylePreset(tableName: string, preset: string): Promise<void>;

Set the visual style preset for a table. @param tableName - Table name @param preset - Style preset name (e.g. "TableStyleLight1")

resize(name: string, newRange: string | CellRange): Promise<TableResizeReceipt>;

Resize a table to a new range. @param name - Table name @param newRange - New A1-style range string or CellRange object

addColumn(name: string, columnName: string, position?: number): Promise<TableAddColumnReceipt>;

Add a column to a table. @param name - Table name @param columnName - Name for the new column @param position - Column position (0-based index). If omitted, appends to the end.

removeColumn(name: string, columnIndex: number): Promise<TableRemoveColumnReceipt>;

Remove a column from a table by index. @param name - Table name @param columnIndex - Column index within the table (0-based)

toggleTotalsRow(name: string): Promise<void>;

@deprecated Use {@link setShowTotals} instead. Toggle the totals row visibility on a table. @param name - Table name

toggleHeaderRow(name: string): Promise<void>;

@deprecated Use {@link setShowHeaders} instead. Toggle the header row visibility on a table. @param name - Table name

applyAutoExpansion(tableName: string): Promise<void>;

Apply auto-expansion to a table, extending it to include adjacent data. @param tableName - Table name

setCalculatedColumn(tableName: string, colIndex: number, formula: string): Promise<void>;

Set a calculated column formula for all data cells in a table column. @param tableName - Table name @param colIndex - Column index within the table (0-based) @param formula - The formula to set (e.g. "=[@Price]*[@Quantity]")

clearCalculatedColumn(tableName: string, colIndex: number): Promise<void>;

Clear the calculated column formula from a table column, replacing with empty values. @param tableName - Table name @param colIndex - Column index within the table (0-based)

getDataBodyRange(name: string): Promise<string | null>;

Get the A1-notation range covering the data body of a table (excludes header and totals rows). @param name - Table name @returns A1-notation range string, or null if the table has no data body rows

getHeaderRowRange(name: string): Promise<string | null>;

Get the A1-notation range covering the header row of a table. @param name - Table name @returns A1-notation range string, or null if the table has no header row

getTotalRowRange(name: string): Promise<string | null>;

Get the A1-notation range covering the totals row of a table. @param name - Table name @returns A1-notation range string, or null if the table has no totals row

addRow(tableName: string, index?: number, values?: CellValue[]): Promise<TableAddRowReceipt>;

Add a data row to a table. @param tableName - Table name @param index - Row index within the data body (0-based). If omitted, appends to the end. @param values - Optional cell values for the new row

deleteRow(tableName: string, index: number): Promise<TableDeleteRowReceipt>;

Delete a data row from a table. @param tableName - Table name @param index - Row index within the data body (0-based)

deleteRows(tableName: string, indices: number[]): Promise<void>;

Delete multiple data rows from a table by their data-body-relative indices. Rows are deleted in descending index order to avoid index shifting. @param tableName - Table name @param indices - Array of row indices within the data body (0-based)

deleteRowsAt(tableName: string, index: number, count?: number): Promise<void>;

Delete one or more contiguous data rows from a table starting at `index`. @param tableName - Table name @param index - Starting row index within the data body (0-based) @param count - Number of rows to delete (default 1)

getRowCount(tableName: string): Promise<number>;

Get the number of data rows in a table (excludes header and totals rows). @param tableName - Table name @returns Number of data rows

getRowRange(tableName: string, index: number): Promise<string>;

Get the A1-notation range for a specific data row. @param tableName - Table name @param index - Row index within the data body (0-based) @returns A1-notation range string

getRowValues(tableName: string, index: number): Promise<CellValue[]>;

Get the cell values of a specific data row. @param tableName - Table name @param index - Row index within the data body (0-based) @returns Array of cell values

setRowValues(tableName: string, index: number, values: CellValue[]): Promise<void>;

Set the cell values of a specific data row. @param tableName - Table name @param index - Row index within the data body (0-based) @param values - Cell values to set

getColumnDataBodyRange(tableName: string, columnIndex: number): Promise<string | null>;

Get the A1-notation range covering the data body cells of a table column. @param tableName - Table name @param columnIndex - Column index within the table (0-based) @returns A1-notation range string, or null if no data body rows

getColumnHeaderRange(tableName: string, columnIndex: number): Promise<string | null>;

Get the A1-notation range covering the header cell of a table column. @param tableName - Table name @param columnIndex - Column index within the table (0-based) @returns A1-notation range string, or null if no header row

getColumnRange(tableName: string, columnIndex: number): Promise<string | null>;

Get the A1-notation range covering the entire table column (header + data + totals). @param tableName - Table name @param columnIndex - Column index within the table (0-based) @returns A1-notation range string, or null if column does not exist

getColumnTotalRange(tableName: string, columnIndex: number): Promise<string | null>;

Get the A1-notation range covering the totals cell of a table column. @param tableName - Table name @param columnIndex - Column index within the table (0-based) @returns A1-notation range string, or null if no totals row

getColumnValues(tableName: string, columnIndex: number): Promise<CellValue[]>;

Get the cell values of a table column (data body only). @param tableName - Table name @param columnIndex - Column index within the table (0-based) @returns Array of cell values

setColumnValues(tableName: string, columnIndex: number, values: CellValue[]): Promise<void>;

Set the cell values of a table column (data body only). @param tableName - Table name @param columnIndex - Column index within the table (0-based) @param values - Cell values to set

setHighlightFirstColumn(tableName: string, value: boolean): Promise<void>;

Set whether the first column is highlighted. @param tableName - Table name @param value - Whether to highlight the first column

setHighlightLastColumn(tableName: string, value: boolean): Promise<void>;

Set whether the last column is highlighted. @param tableName - Table name @param value - Whether to highlight the last column

setShowBandedColumns(tableName: string, value: boolean): Promise<void>;

Set whether banded columns are shown. @param tableName - Table name @param value - Whether to show banded columns

setShowBandedRows(tableName: string, value: boolean): Promise<void>;

Set whether banded rows are shown. @param tableName - Table name @param value - Whether to show banded rows

setShowFilterButton(tableName: string, value: boolean): Promise<void>;

Set whether filter buttons are shown on the header row. @param tableName - Table name @param value - Whether to show filter buttons

setShowHeaders(tableName: string, visible: boolean): Promise<void>;

Set whether the header row is visible. @param tableName - Table name @param visible - Whether to show the header row

setShowTotals(tableName: string, visible: boolean): Promise<void>;

Set whether the totals row is visible. @param tableName - Table name @param visible - Whether to show the totals row

applyIconFilter(
    tableName: string,
    columnIndex: number,
    icon: { set: string; index: number },
  ): Promise<void>;

Apply an icon filter to a table column. Filters rows by conditional formatting icon: only rows whose evaluated CF icon matches the specified icon set and index are shown. Requires an icon set CF rule applied to the column's range. @param tableName - Table name @param columnIndex - Column index within the table (0-based) @param icon - Icon to filter by: set name (e.g. "3Arrows") and index (0-based)

getAutoFilter(tableName: string): Promise<FilterInfo | null>;

Get the auto-filter associated with a table. @param tableName - Table name @returns Filter information, or null if the table has no associated filter

getRows(tableName: string): Promise<TableRowCollection>;

Get a collection-like wrapper around the table's data rows. The returned object delegates to the existing row methods on this API. The `count` property is a snapshot taken at call time and does not live-update. @param tableName - Table name @returns A TableRowCollection object