npm / @betteroffice/xlsx
@betteroffice/xlsx
What changed in @betteroffice/xlsx 0.3 to 0.5, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-28.
5 breaking2 security45 new APIs and options7 behavior and defaults31 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@betteroffice/xlsx 0.559 changes
Breaking changes 3
Workbooks with more than 65,536 defined names open and recalculate; edits exceeding a 32 MiB name-and-formula-text bound are refused without changing the workbook.
Implementations must add the new members, including moveRange, setHyperlink and listDefinedNames.
Opening rejects workbook parts with an unsupported main namespace or a non-workbook root instead of opening them, while leaving the current document open.
New APIs and options 28
Agent cell writes, formatting, sorting and find/replace can opt in with protectedSheets: "allow"; protection remains, edits are reported through protectedCells, and the default is "refuse".
readCells results now include sheets[].visibility by default, with unknown when visibility cannot be determined.
Supports typed defined name operations.
Custom async replicas can opt in to merging queued remote updates in one worker command.
Adds a worker entry point with the worker session API and types; the root entry continues to export them.
Reports budgetExhausted: true when the last recalculation ran out of budget, indicating unevaluated cells kept their saved values.
Adds chart discovery for workbooks.
Lists conditional formatting rules for a sheet.
Syncs collaboration replicas whose state lives in a worker.
Adds atomic chart title and series edits, including title replacement or removal, series renaming, and category or value reference changes on unshared chart parts.
Adds paginated reads of defined names.
Adds a merge lookup direction for selection.
Adds a workbook operation for moving a range.
Adds an experimental worker-backed workbook session for async reads, version-checked edits, saving, per-viewport call.frame display lists, and cancellation through signal.
Adds a workbook operation for removing hyperlinks.
Adds optional merge data to SelectionData.
Adds operations to set, extend, or remove worksheet filter buttons while preserving filter criteria; ranges overlapping tables are refused.
Adds a setCellValues step.
Adds a workbook operation for setting hyperlinks.
Listeners now receive { fromPeer }.
Adds an agent tool for editing chart titles and series.
Adds agent operations to add or delete cellIs and expression rules with a differential format.
Adds agent operations for editing workbook- and sheet-scoped defined names, including hidden flags.
Adds an agent tool for chart discovery.
Adds an agent tool for listing conditional formatting rules.
Adds an agent operation for listing workbook- and sheet-scoped defined names, including hidden flags.
Adds an agent tool for reading chart text.
Adds an agent operation to set, extend, or remove worksheet filter buttons while preserving filter criteria; ranges overlapping tables are refused.
Behavior and default changes 3
Sheet outlines include autoFilter by default.
Worker editors now run CollaborationProvider in the workbook worker by default and batch incoming transport frames into one session command.
Keyboard navigation follows Excel by default: Ctrl/Meta+Arrow stops at data edges, Ctrl/Meta+A selects in two stages, Ctrl+End reaches the used range, and hidden rows and columns are skipped.
Fixes and other changes 25
Axes now honour tick label position: none hides labels and frees plot space, high moves labels to the far side, and a deleted category axis draws no labels.
Formulas now coerce currency text when workbook number formats provide currency evidence; formula entry and formatting edits use the same evidence as recalculation.
Bar and column labels now follow PowerPoint and Excel placement for outside end, inside end and inside base; horizontal bars are centred, as are stacked charts by default.
Pie and doughnut labels now follow PowerPoint and Excel placement for their slices, best fit, outside end and doughnut rings.
Zero-valued bar and column labels now sit on the side specified by the value axis, including when the axis is reversed.
INDIRECT now resolves lowercase and R1C1-style references; formulas pointing to a deleted cell on another sheet show #REF! rather than a blank or stale value.
Large-data-sheet SUMPRODUCT formulas using array (Ctrl+Shift+Enter) formulas now calculate every cell instead of stopping partway through with #NUM!.
SUMPRODUCT data columns containing a few formula cells now calculate every cell instead of stopping partway through with #NUM!.
Worksheet titles and sheet-qualified named-range titles in workbook properties stay current when sheets are renamed or moved; properties are preserved when titles cannot be mapped reliably.
Sheets with more than 65,536 styled rows can now open, edit and save; live collaboration is refused for sheets with more than about 333,000 styled rows.
The XlsxSheetVisibility type is now exported from both package roots.
Formulas cut short by the recalculation budget keep saved values under IFERROR, ISERROR, and other IS functions, and show #NUM! when no saved value exists.
Returns Windows-1252 characters for codes 128 to 159, matching Excel.
Maps Windows-1252 characters in the 128-to-159 range back to their codes, as Excel does.
Recalculation now computes FORECAST instead of returning #NAME?.
Recalculation now computes FORECAST.LINEAR instead of returning #NAME?.
The in-thread XLSX editor now calls onChange when a collaborator's edit changes the workbook, including a full-state update into a freshly opened replica.
A workbook too large for engine memory now fails the session with an out-of-memory failure that explains the workbook is too large, rather than a bare trap.
Recalculation now computes RAND instead of returning #NAME?.
Recalculation supports RSQ; RSQ over ranges with no numeric pairs returns #DIV/0!, as Excel does.
Long, mostly empty ranges now recalculate to Excel's results instead of showing #NUM!.
Long recalculations report progress so the 60-second watchdog fires only for a worker that has gone silent; queued edits apply after recalculation returns.
Sessions no longer fail after 256 edits or selection moves without a recovery checkpoint; the session checkpoints its recovery log, including for headless sessions.
Wrapped cells break into lines on screen and in print at line breaks and between words; rows without a set height grow to fit.
Scalar lookups over formula-computed arrays now work; reference arguments are read once, and mismatched lookup-vector orientation returns #VALUE! as Excel does.
@betteroffice/xlsx 0.331 changes
Breaking changes 2
Entering values into Text-formatted cells honors the cell format, including for numeric strings, booleans, and formula-looking text; general cells retain Excel-style coercion.
Text that outgrows a cell spills across adjacent blank cells toward its alignment side, stopping at visible content, merges, or laid-out column edges.
Security 2
Recalculation charges array and text work against budgets and stops early when limits would be exceeded, preserving cached values instead of consuming excessive time or memory.
Exports workbook content as bounded Markdown with per-sheet grids, escaped document text, safe hyperlink destinations, and anchors for export markers.
New APIs and options 17
The formula engine adds twenty-three previously unimplemented functions and supports computed array arguments, whole-row and reference-range references, and per-element results.
Adds a text search API for formatted workbook cell values.
Adds INDIRECT as a reference- and value-resolving function accepted by range-taking functions; it accepts only reference-shaped strings.
The formula engine evaluates LET bindings and LAMBDA values, including callbacks such as BYROW, MAP, REDUCE, SCAN, and MAKEARRAY.
Adds LINEST for one or more predictors, including the requested full statistics block; scalar cells can read array-only results through INDEX.
Adds matrix multiplication with dimension checks, error propagation, and array results that spill in dynamic-array formulas or fill legacy array-formula ranges.
Adds OFFSET as a reference-producing formula function, including negative dimensions, reference-taking functions, and dependency tracking for resolved rectangles.
Opt-in operation profiles are exposed for XLSX edits and display lists, and PPTX layout, edits, and history operations.
Adds RANDBETWEEN with Excel-measured rounding behavior, volatile recalculation, and seedable evaluation through EvalContext::rand_seed.
The error now names each drifted cell's sheet.
Reads XLSX table parts and resolves structured table references, including bands, this-row shorthand, and column spans, as live formula areas.
Adds bounded, read-only structured worksheet export with formulas, stored values, formatted text, hidden-content options, anchors, and omission diagnostics.
The XLSX formula engine supports SUBTOTAL, AGGREGATE, and XMATCH, including aggregate selection, error-ignoring options, and XMATCH match and search modes.
Adds TANH to the XLSX formula engine with standard one-argument math-function coercion.
The formula engine recognizes TRANSPOSE for ranges, arrays, and scalars; blank cells transpose to zero and errors propagate.
Adds version-checked, all-or-nothing edit batches that can guard cell contents and commit inputs, formulas, number formats, and style patches as one recalculated change and undo step.
The editor API gains batch operations, commits pending drafts, nudges, and pastes first, and reports typed admission errors when input cannot be written.
Behavior and default changes 4
Array formulas evaluate once and spill across their occupied range; ranges and operators produce blocks, and array builtins and scalar functions handle block inputs.
Chart rendering is brought closer to Office across legends, labels, axes, markers, fills, and category colors; sparse charts with large cached point indexes avoid excessive allocation.
Column styles move with structural edits, affect workbook collaboration fingerprints, provide inherited cell formatting, and are restored on undo and redo.
Recalculation now advances the workbook version when exported contents change, including cycle or limit status changes and first calculations of formulas without stored results.
Fixes and other changes 6
Workbooks with a negative column width now open; the column collapses to zero width while the authored attribute remains unchanged.
Saved collaboration snapshots can be restored after open-time recalculation when the authority remains pristine; real local edits and incompatible workbook structures still prevent replacement.
RANK, RANK.EQ, RANK.AVG, and MATCH return one result per value when given a range of values.
When recalculation encounters a function outside the engine's table, it preserves an existing cached value; formulas without cached values still report an error.
Rows without explicit heights fit their content using the workbook's resolved normal font, while explicit heights and custom default heights retain their specified behavior.
Strips Excel's _xlfn. and _xlfn._xlws. prefixes before formula builtin lookup so stored post-2007 function names recalculate.