Large files and performance

Spreadsheet calls run synchronously. Reading, writing, and converting a large workbook can block the thread. Use a worker to keep your application responsive.

Reduce the work

• Read only needed sheets with sheets.
• Use sheetRows when you only need the first rows.
• Use bookSheets or bookProps when you only need metadata.
• Skip style loading unless you need it.
• For template-only edits, use template: true, skipParse: true.
• Stream CSV, HTML, or JSON output when it fits your application. These streams do not make workbook parsing incremental. The worksheet still exists in memory.

const XLSX = require("@agent-sheet/wasm");
const original = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(original, XLSX.utils.aoa_to_sheet([["Count"], [1], [2], [3]]), "Data");
const bytes = XLSX.write(original, { type: "buffer", bookType: "xlsx" });
const wb = XLSX.read(bytes, { sheets: "Data", sheetRows: 2 });
require("node:assert/strict").equal(wb.Sheets.Data["!ref"], "A1:A2");

Memory

The engine uses one WebAssembly instance per JavaScript realm. Its linear memory grows as needed and does not shrink. A later small operation can reuse memory grown for an earlier large workbook. Workbook objects also use JavaScript memory. The 32-bit WebAssembly memory limit is 4 GiB; practical file limits can be lower.

A worker has its own instance. Ending a worker releases its realm and is useful when a large, occasional job would otherwise leave a high memory watermark in the main thread. There is no workbook disposal API.

Compared with the original JavaScript build

Performance depends on the operation, data, and machine. In version 0.2 measurements on workbooks of 5,000 to 100,000 rows:

• sheet_to_csv, sheet_to_json and the stream CSV and JSON outputs ran at about the same speed as the original JavaScript build.
• Reading XLSX files ran at about the same speed; reading a 100,000-row workbook and converting it to JSON was slightly faster.
• Small reads and template edits were faster than the original.
• Writing large XLSX files was slower: about 1.2 times as long for a read-then-write of a 100,000-row workbook, and about 1.7 times as long when building it with aoa_to_sheet.

These are rough observations, not speed guarantees.

WebAssembly does not imply lower memory use for every job. Measure the complete read, edit, and write workflow with your own files. See Troubleshooting for the public diagnostics hook.