Skip to content

Tab ​

Represents a worksheet (sheet tab) within a spreadsheet.

ts
import { Tab } from "betterspread"

Methods ​

values() ​

ts
values(opts?: ValuesOpts): Promise<Row[]>

Reads rows from the tab. Default returns all rows with cell format data.

ValuesOpts ​

PropertyTypeDescription
rangestringA1 range (e.g. "Sheet1!A1:B10")
valueRenderOptionValueRenderOption"FORMATTED_VALUE" (default), "UNFORMATTED_VALUE", or "FORMULA"

getRow() ​

ts
getRow(opts: GetRowOpts): Promise<Row>

Reads a single row by number.

GetRowOpts ​

PropertyTypeDescription
serialNonumberRow number (1-indexed)
valueRenderOption?ValueRenderOptionRender option for values

getCell() ​

ts
getCell(opts: GetCellOpts): Promise<Cell>

Reads a single cell by A1 address.

GetCellOpts ​

PropertyTypeDescription
cellNamestringA1 notation (e.g. "B3")
valueRenderOption?ValueRenderOptionRender option (default "FORMATTED_VALUE")

append() ​

ts
append(opts: AppendOpts): Promise<Row | null>

Appends a row to the end of the tab.

AppendOpts ​

PropertyTypeDescription
valuesunknown[] | Record<string, unknown>Array of values or object keyed by header
inputFormat?ValueInputOption"RAW" (default) or "USER_ENTERED"
getRow?booleanIf true, returns the appended Row

delRow() ​

ts
delRow(opts: DelRowOpts): Promise<void>

Deletes a row or range of rows.

DelRowOpts ​

PropertyTypeDescription
startnumberStart row (1-indexed)
end?numberEnd row (exclusive)

delCell() ​

ts
delCell(opts: DelCellOpts): Promise<void>

Deletes a cell or range with shift.

DelCellOpts ​

PropertyTypeDescription
startstringStart cell (A1 notation)
end?stringEnd cell (A1 notation)
shift?"up" | "left"Shift direction (default "up")

setSchema() ​

ts
setSchema(schema: z.ZodObject): this

Attaches a Zod schema for validation. Returns this for chaining. Throws if any schema key is missing from the tab's cached headers (case-sensitive). Columns map by header name, not schema key order.

getSchema() ​

ts
getSchema(): z.ZodObject | null

getHeaders() ​

ts
getHeaders(): string[]

Returns cached column headers from last values() call.