Skip to content
Akmelo

Documentation

JavaScript SDK: Worksheet: sheets and cells

document.sheet(0) returns the first sheet. Sheet indices are zero based, while row and column numbers start at one. Worksheet methods run locally.

Each example is a separate fragment inside async function run(ctx). Use await only for methods whose signature returns a Promise.

Obtaining the object

const document = await ctx.documents().fromBytes('sku,price\nA-1,1250', 'report.csv');
const sheet = document.sheet(0);

Methods

name

sheet.name() → string

The sheet's name in the original file.

const result = sheet.name();

rows

sheet.rows() → Array<Array<unknown>>

All rows, without assuming where headers are. Empty rows and gaps are preserved. Array rows and columns use zero-based indexes.

const result = sheet.rows();

rowCount

sheet.rowCount() → number

The number of extracted rows, including empty ones. This is not a record count: a file can have headers, totals, and multiple sections.

const result = sheet.rowCount();

columnCount

sheet.columnCount() → number

The width of the longest extracted row. Missing cells in shorter rows remain empty.

const result = sheet.columnCount();

cell

sheet.cell(address, resolveMerged) → string|number|boolean|null

Reads a cell such as B2. With resolveMerged=true, it reads the top-left cell of a merged range. Use an address without $ markers.

const result = sheet.cell('B2');

row

sheet.row(number) → Array<unknown>

Read a row by its one-based number. Rows outside the sheet return an empty array; zero or negative numbers raise an error.

const result = sheet.row(2);

column

sheet.column(column, startRow, endRow) → Array<unknown>

Read a column by letters or one-based number. startRow and endRow are inclusive. Missing values stay null.

const result = sheet.column('B');

range

sheet.range(range, resolveMerged) → Array<Array<unknown>>

Read a rectangular matrix such as A1:C10, including empty cells. The limit is 50,000 cells. resolveMerged=true repeats the merged area's anchor value only in the returned matrix. Reversed or invalid ranges raise an error.

const result = sheet.range('A1:B5');

nonEmptyRows

sheet.nonEmptyRows() → object

Non-empty rows keyed by their original one-based row numbers. Values 0 and false count as data.

const result = sheet.nonEmptyRows();

find

sheet.find(text, exact, limit) → Array<{ address: string, value: unknown }>

Search values without regard to case. exact=true requires a whole-value match. Returns address and value, at most limit matches (1–1000). Formula expressions are not executed or searched in place of their values.

const result = sheet.find('A-1');

findHeader

sheet.findHeader(labels, maxRows) → number | null

Find the first row containing all requested labels. Comparison ignores case and surrounding spaces. The first 50 rows are checked by default; maxRows can be 1–5,000. Returns null if no header is found. Use explicit ranges for a multi-level header.

const result = sheet.findHeader(['SKU', 'Price']);

merged

sheet.merged() → Array<unknown>

Merged XLSX/XLS ranges, such as A1:C1. Values in other cells are not duplicated by default. CSV files have no merged cells.

const result = sheet.merged();

formula

sheet.formula(address) → string | null

The original XLSX formula with a leading =, or null. Read the calculated value with cell() and the expression with formula(). Shared formulas in dependent cells may not contain the full expression; consult the cached value when needed.

const result = sheet.formula('B2');

error

sheet.error(address) → string | null

The stored XLSX error, such as #DIV/0!, or null. Errors are not silently replaced with zero.

const result = sheet.error('B2');

records

sheet.records(headerRow, startRow, endRow) → Array<object>

Turn a selected section into records. headerRow is the one-based header row; startRow and endRow set an inclusive data range. headerRow=0 uses column letters A, B, C as keys. Empty rows are skipped. Blank labels become column letters, and duplicate labels get _2, _3, and so on without losing fields. Totals and notes are not detected automatically; set the range explicitly.

const result = sheet.records(1);

structure

sheet.structure() → object

An anonymized layout for AI planning: rows, columns, merged, and a sample of the first 24×16 cells. The sample contains only e (empty), s (string), n (number), and b (Boolean). Sheet names, headers, values, links, and formulas are omitted. This method does not call a model.

const result = sheet.structure();

calculation

sheet.calculation(address) → string

XLSX calculation status: calculated, unsupported, external_reference, circular_reference, error, or limit. not_calculated means a formula exists but was not recalculated; not_formula means this is a regular cell. Unsupported formulas give an explicit error, not zero or an undisclosed fallback to an old value.

const result = sheet.calculation('B2');

cachedValue

sheet.cachedValue(address) → string|number|boolean|null

The value saved in an XLSX file by its author before recalculation. It may be missing or stale. For a regular cell it matches cell(). Use it only as an explicit fallback; the SDK returns recalculated values by default.

const result = sheet.cachedValue('B2');