Worksheet utilities

These functions are under XLSX.utils. Worksheets and cells are plain JavaScript objects. Helpers that add or change data mutate the object passed in; functions that return a worksheet do not imply that they made a copy.

Template helpers are documented separately.

Addresses and ranges

A CellAddress is { r, c } with zero-based row and column indexes. A Range is { s, e }, with inclusive start and end addresses. A1 strings use the familiar one-based row numbers.

Signature	Meaning	Returns
`encode_cell({ r, c })`	Convert an address object to A1 notation	String
`decode_cell(address)`	Convert an A1 string to an address object	`{ r, c }`
`encode_row(row)`	Convert a zero-based row to its A1 row text	String
`decode_row(row)`	Convert row text to a zero-based row	Number
`encode_col(column)`	Convert a zero-based column to letters	String
`decode_col(column)`	Convert column letters to a zero-based column	Number
`encode_range(range)`	Convert `{ s, e }` to range text	String
`encode_range(start, end)`	Convert two address objects to range text	String
`decode_range(range)`	Convert range text to `{ s, e }`	Range object
`split_cell(address)`	Separate column and row text; preserves `$` markers	Two-element string array

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
assert.deepEqual(XLSX.utils.decode_cell("C4"), { c: 2, r: 3 });
assert.equal(XLSX.utils.encode_cell({ c: 2, r: 3 }), "C4");
assert.equal(XLSX.utils.encode_range({ s: { r: 0, c: 0 }, e: { r: 2, c: 1 } }), "A1:B3");
assert.deepEqual(XLSX.utils.split_cell("$B$3"), ["$B", "$3"]);

Use finite, valid indexes. encode_col(Infinity) throws a RangeError rather than exhausting memory as in the original @sheet/edit package.

Create and extend worksheets

Signature	Parameters and mutation	Returns
`sheet_new(options?)`	Create an empty worksheet; `dense: true` requests `!data` storage	New worksheet
`aoa_to_sheet(rows, options?)`	Create from an array of row arrays containing primitive values or cell objects	New worksheet
`sheet_add_aoa(worksheet, rows, options?)`	Add row arrays at `options.origin`; updates the existing worksheet	Same worksheet
`json_to_sheet(objects, options?)`	Create from an array of objects; keys become headers	New worksheet
`sheet_add_json(worksheet, objects, options?)`	Add object records at `options.origin`; updates the existing worksheet	Same worksheet

origin accepts an A1 string, { r, c }, a zero-based row number, or -1 to append below the existing used range. Its default is the top-left cell.

Array-of-arrays options

Option	Meaning
`dense`	Use `!data` row arrays for a new worksheet
`cellDates`	Store JavaScript dates as date cells rather than serial numbers
`dateNF`	Date format to use where none is specified
`UTC`	Date interpretation setting
`sheetStubs`	Create blank stub cells for `null` values
`origin`	Start position for `sheet_add_aoa`

Numbers, booleans and strings become typed cells. Cell objects such as { t: "n", v: 5, z: "0.00" } let you supply metadata directly. Holes and undefined entries are skipped. This is ordinary worksheet construction; template cell editing has separate null semantics.

Object-record options

json_to_sheet and sheet_add_json accept the date/dense options above plus:

Option	Meaning
`header`	Array of field names defining column order
`skipHeader`	Omit the header row
`origin`	Start position; `-1` appends below the existing data

header defines order, not a projection: keys not already in it can add columns. The helper can extend the supplied header array as it encounters new keys. Filter objects yourself if you want to exclude fields.

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
const sheet = XLSX.utils.json_to_sheet([{ Item: "Pen", Qty: 3 }], { header: ["Item", "Qty"] });
XLSX.utils.sheet_add_json(sheet, [{ Item: "Book", Qty: 2 }], {
  origin: -1, skipHeader: true, header: ["Item", "Qty"]
});
assert.equal(sheet["!ref"], "A1:B3");
assert.deepEqual(XLSX.utils.sheet_to_json(sheet), [
  { Item: "Pen", Qty: 3 }, { Item: "Book", Qty: 2 }
]);

See Building sheets for construction patterns.

HTML table input

These helpers need a DOM table element. They do not accept an HTML string. To parse an HTML string, use the top-level read API.

Signature	Meaning	Returns
`table_to_sheet(table, options?)`	Convert a DOM table into a worksheet	New worksheet
`table_to_book(table, options?)`	Convert a DOM table into a one-sheet workbook	New workbook
`sheet_add_dom(worksheet, table, options?)`	Add DOM table cells to an existing worksheet	Same worksheet

Options: raw, rawDates, dateNF, UTC, cellDates, sheetRows, display, borders, and origin. display: true omits hidden table content. table_to_book also accepts sheet for the sheet name.

See DOM tables for browser examples and attributes.

Convert worksheets

Signature	Meaning	Returns
`sheet_to_json(worksheet, options?)`	Convert cells to row objects or arrays	Array of rows
`sheet_to_row_object_array(worksheet, options?)`	Legacy alias of `sheet_to_json`	Array of rows
`sheet_to_csv(worksheet, options?)`	Convert the used range to delimited text	String
`sheet_to_txt(worksheet, options?)`	Convert to tab-delimited UTF-16 text	String
`sheet_to_html(worksheet, options?)`	Convert to HTML table markup	String
`sheet_to_formulae(worksheet)`	Emit cell-address assignments for formulas or values	String array
`cell_array_to_csv_row(cells, options?)`	Convert an array of cell objects into one delimited row	String

JSON options

Option	Meaning
`header`	Omit to use the first row as keys; `1` yields arrays; `"A"` uses column letters; a string array supplies keys
`range`	Restrict the conversion with range text/object, or a zero-based starting row
`raw`	Use raw values instead of formatted display text
`rawNumbers`	Keep numeric values raw
`defval`	Value to use for missing cells
`blankrows`	Include blank rows; default differs for array and object output
`skipHidden`	Skip hidden rows and columns
`dateNF`	Date format override
`UTC`	Date interpretation setting

With default headers, the first row supplies keys and is not returned as data. With header: 1, blank rows are included by default; object output skips them by default. Duplicate header names are disambiguated. raw does not undo type inference that occurred while reading the file.

CSV/text options

FS is the field separator (CSV default comma), RS the row separator (default newline), strip removes trailing separators, blankrows defaults to true, skipHidden skips hidden rows/columns, forceQuotes quotes fields, rawNumbers uses raw numbers, and dateNF overrides date formatting.

HTML options

id chooses the table ID, editable requests editable cells, header and footer replace the surrounding HTML, and gridcolor supplies grid color.

See Converting sheets for detailed output examples.

Workbook helpers

Signature	Parameters and mutation	Returns
`book_new(worksheet?, name?)`	Create a workbook, optionally with an initial worksheet and name	New workbook
`book_append_sheet(workbook, worksheet, name?, roll?)`	Append a worksheet. `roll: true` chooses a new name when the requested name exists	Appended sheet name
`book_set_sheet_visibility(workbook, sheet, visibility)`	Set a sheet by name or zero-based index to `0`, `1` or `2`	No result to consume

Visibility constants are utils.consts.SHEET_VISIBLE (0), SHEET_HIDDEN (1), and SHEET_VERY_HIDDEN (2). The declaration’s spelling SHEET_VERYHIDDEN is not defined at runtime.

book_append_sheet recognizes a template workbook and updates the original package too. Apply the worksheet’s styles before appending in template mode.

Cells and formulas

Signature	Parameters and mutation	Returns
`sheet_get_cell(worksheet, address)`	Get a cell by A1 string; create a blank stub when missing	Cell object
`sheet_get_cell(worksheet, row, column)`	Same, using zero-based numeric indexes	Cell object
`format_cell(cell, value?, options?)`	Format the supplied value, or the cell’s value, using its number format	String
`cell_set_number_format(cell, format)`	Assign `z`; format is a string or built-in format number	Same cell
`cell_set_hyperlink(cell, target, tooltip?)`	Assign an external hyperlink	Same cell
`cell_set_internal_link(cell, target, tooltip?)`	Assign an internal workbook link	Same cell
`cell_add_comment(cell, text, author?)`	Add a plain-text comment to the cell	No result to consume
`sheet_set_array_formula(worksheet, range, formula, dynamic?)`	Set an array formula across a string/object range; `dynamic: true` marks it as dynamic	Same worksheet
`html_to_rs(html)`	Parse an HTML fragment into rich-text runs	Array of rich-text fragments

Formula strings omit the leading =. These helpers store formulas; they do not calculate their results. Formatting uses cached w where available. When changing a value or number format on a cell that already has w, remove stale w if you need it regenerated.

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
const sheet = XLSX.utils.aoa_to_sheet([[12.5]]);
XLSX.utils.cell_set_number_format(sheet.A1, "0.00");
assert.equal(XLSX.utils.format_cell(sheet.A1), "12.50");
XLSX.utils.cell_set_hyperlink(sheet.A1, "https://example.com", "Open site");
assert.equal(sheet.A1.l.Target, "https://example.com");
XLSX.utils.sheet_set_array_formula(sheet, "B1:B2", "A1*2");
assert.equal(sheet.B1.f, "A1*2");

See Hyperlinks, Comments, Rich text and Number formats and dates.

Styles

Signature	Parameters and mutation	Returns
`sheet_set_range_style(worksheet, range, style)`	Apply a style to a string/object range; creates blank cells as needed	No result to consume
`apply_style_delta(style, delta)`	Merge differential keys into `style` in place; `null` removes a property	No result to consume
`get_computed_style(worksheet, address)`	Get a copy of a cell’s style, including resolved table styling where available	Style object

For range styles, z sets the number format, incol sets interior vertical borders, and inrow sets interior horizontal borders. top, bottom, left and right apply to the outer edges. A style value of false removes that styling. get_computed_style does not evaluate conditional-format rules.

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
const sheet = XLSX.utils.aoa_to_sheet([[1, 2]]);
XLSX.utils.sheet_set_range_style(sheet, "A1:B1", { bold: true, z: "0.00" });
assert.ok(XLSX.utils.get_computed_style(sheet, "A1").bold);
assert.equal(sheet.B1.z, "0.00");
const style = { bold: true };
XLSX.utils.apply_style_delta(style, { bold: null, italic: true });
assert.deepEqual(style, { italic: true });

See Cell styles for style fields and format limits.

Declared but unavailable encryption helpers

hash_password(password) and test_password(hash, password) are retained in the types for compatibility with the original package. Neither is a runtime function. Do not call them to implement worksheet protection or file encryption.