ws.tables

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

Create a new table from a cell range. @param range - A1-style range string (e.g. "A1:D10") @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

list(): Promise<TableInfo[]>;

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

getAt(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<TableRemoveReceipt>;

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

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

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

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

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

getAtCell(row: number, col: number): Promise<TableInfo | null>;

Get the table at a specific cell position, if one exists. @param row - Row index (0-based) @param col - Column index (0-based) @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): Promise<TableResizeReceipt>;

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

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>;

Toggle the totals row visibility on a table. @param name - Table name

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

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

sortApply(
    tableName: string,
    fields: Array<{ columnIndex: number; ascending?: boolean }>,
  ): Promise<void>;

Apply sort fields to a table. @param tableName - Table name @param fields - Array of sort field descriptors

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

Clear all sort fields from a table. @param tableName - Table name

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

Re-evaluate the most recently applied sort specification. Throws if no sort specification has been applied via `sortApply`. @param tableName - Table name

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

onTableAdded(callback: (event: TableCreatedEvent) => void): CallableDisposable;

Subscribe to table creation events on this worksheet. Fires when a new table is added to this worksheet. @param callback - Handler invoked with the TableCreatedEvent @returns A disposable that unsubscribes the handler when disposed

onTableDeleted(callback: (event: TableDeletedEvent) => void): CallableDisposable;

Subscribe to table deletion events on this worksheet. Fires when a table is removed from this worksheet. @param callback - Handler invoked with the TableDeletedEvent @returns A disposable that unsubscribes the handler when disposed

onTableChanged(
    tableName: string,
    callback: (event: TableUpdatedEvent) => void,
  ): CallableDisposable;

Subscribe to change events for a specific table. Fires when the table's structure or properties are updated (e.g. columns added/removed, style changed, renamed, resized, totals toggled, etc.). @param tableName - The name of the table to observe @param callback - Handler invoked with the TableUpdatedEvent @returns A disposable that unsubscribes the handler when disposed

onSelectionChanged(
    tableName: string,
    callback: (event: TableSelectionChangedEvent) => void,
  ): CallableDisposable;

Subscribe to selection change events for a specific table. Fires when the user's selection enters, moves within, or leaves the table. Note: events are only emitted once the selection machine is wired to emit `table:selection-changed`; until then the subscription is inert. @param tableName - The name of the table to observe @param callback - Handler invoked with the TableSelectionChangedEvent @returns A disposable that unsubscribes the handler when disposed