Error behavior

Spreadsheet operations report errors with synchronous throws. Catch failures around read, write, and editing helpers. The callback-based writeFileAsync is the exception for file I/O; spreadsheet serialization still happens synchronously.

const XLSX = require("@agent-sheet/wasm");
const assert = require("node:assert/strict");
const wb = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(wb, XLSX.utils.aoa_to_sheet([[1]]), "Data");
assert.throws(() => XLSX.write(wb, { type: "buffer", bookType: "unsupported" }));
const back = XLSX.read(XLSX.write(wb, { type: "buffer", bookType: "xlsx" }));
assert.equal(back.Sheets.Data.A1.v, 1);

Error messages

Messages are kept identical to the original @sheet/edit package where compatibility requires it. Some messages are terse or use unfamiliar names. Those names are not public API functions. New environment failures, such as blocked WebAssembly compilation, have package-specific messages.

Do not infer supported features from a message alone. Check Known differences and Supported formats.

Recovery

An error leaves the library usable, including an exception from your own property getter. If the engine encounters a WebAssembly trap, the next call starts a fresh instance. You do not need to reload the package. Configuration is shared within the realm and survives that replacement. Worker configuration remains separate.

The WTF parsing option asks readers to throw on malformed or unsupported content rather than skip it. It does not turn spreadsheet parsing into a general file-validation service.