Changelog

v17.0.0-beta.1 (2026-06-29)

The second 17.0 beta, continuing to iron out the pivot-table kinks from beta.0. Still subject to further breaking changes before the stable release.

Features

• Workbook.deleteCells(range, shift) and Workbook.insertCells(range, shift) implement Excel’s “Delete cells → shift up/left” and “Insert cells → shift down/right” for an arbitrary bounded rectangle (e.g. B3:C5), the bounded-rectangle counterparts to the existing full-row/column deleteRows/deleteColumns/insertRows/insertColumns. Surviving cells slide in (delete) or displaced cells push out (insert) to fill or open the gap; this workbook’s own formulas are rewritten in place, with references to removed or pushed-off cells becoming #REF!, and a RewriteFormula callback is returned to adjust other workbooks’ references. Overlapping tables, pivot tables, and merges move whole, grow, or dissolve per Excel’s rules; an edit that would tear a table or pivot table, or push non-empty content off the grid, is refused.
• New PivotTable.pageArea reports the geometry of the page-field (report filter) area that sits above a pivot’s output range, so a renderer can locate and style those cells.
• New PivotTable.rowRoles / PivotTable.colRoles list which output rows and columns are subheadings or subtotals (as 0-based offsets from the output’s top-left, each with its kind and 1-based nesting level), so a renderer can apply a declared pivot style’s subheading and subtotal styling.

Bug fixes

• What-if data tables now evaluate each scenario with a real model recalculation (substitute the input cells, recalculate, read the source cell), matching Excel’s documented behaviour. Previously only the source formula’s own AST was re-evaluated against the substituted input, which silently produced wrong results whenever the source reached the input indirectly: through intermediate formula cells, INDIRECT/OFFSET, defined names, cross-sheet references, volatile functions, array spills, or iterative-calculation cycles.
• A custom workbook theme now survives model serialization. deserializeModel previously dropped the theme and reverted every workbook to the default palette (with theme.isDefault set true); it now restores the serialized theme, so theme-resolved colours and fonts round-trip. Already-serialized models recover their theme too, since the data was present all along and only the read path was at fault.
• A pivot table’s saved output cells are now kept as-is on load instead of being recomputed, matching Excel — computed output fills only the cells the file left empty. A cache flagged refreshOnLoad="1" is instead rebuilt from its worksheet source and re-rendered once at load time.
• Refreshing a pivot cache that holds a derived field (a calculated field or a derived grouped field) no longer throws when the source columns are reordered, renamed, added, or deleted. The derived fields are kept and reconciled against the new column set, matching Excel; previously the presence of any derived field, even one unrelated to the change, aborted the refresh.
• The single-data-field pivot header (“corner”) cell now matches modern Excel: the data field’s display name (e.g. Sum of Sales) in every layout, the bare field name only on pivots carrying a legacy AutoFormat, and an empty cell when the data field has no name. Previously it wrote the bare cache-field name unconditionally.
• “Show items with no data” (showAll) densification on load now matches Excel: it defaults to dense for ordinary discrete fields (the spec default), lists only the items surviving the pivot’s active filters, evaluates a label/caption filter against the field’s full item set (so an item the caption filter keeps still shows even with no data), and includes orphan cache items as empty “no data” rows.
• Pivots mixing compact and tabular row-field layouts now match Excel: an outer-compact mix collapses to one compact “Row Labels” column, an outer-tabular mix captions its first column “Row Labels”, and a tabular outer field writes its group label on the group’s first output row. Field-name row captions appear only on row-only pivots whose row fields are all tabular with compactData off.
• A pivot that places the Values pseudo-field at a mid position among its column fields now lays the data fields out as interleaved sub-blocks at that depth, with the field-button row in raw field order, the way Excel does. Previously any non-first Values position was treated as innermost.
• A Values-last multi-data pivot now serializes its colItems with the data field varying fastest (df-innermost interleaving), matching Excel. Previously even a dormant load→save rewrote them into a df-major order Excel does not use.
• A Values-outer pivot’s column axis-label row no longer drops the Values button: it now reads Values ahead of the real field buttons, matching Excel.
• A multi-data pivot whose Values pseudo-field sits on the row axis now lays the data fields out as row blocks — a synthetic “Values” row-label column, with per-data-field subtotal and grand-total captions — matching Excel. Previously the row-axis Values position was ignored and the data fields were always emitted on the column axis.
• A multi-data pivot with no column field now omits the synthetic “Values” caption row — the data-field names form the header row — matching Excel, instead of emitting an extra caption row that pushed the body down.
• On refresh, a pivot’s header-row offsets (firstHeaderRow/firstDataRow) are now re-derived from its definition so the output lands where Excel’s refresh would, regardless of the offsets the file stored: an over-reserved blank row above the headers is removed, and a multi-data pivot missing its reserved Values header row has that row rebuilt (instead of collapsing to a single data field and inventing hideValuesRow="1" on export).
• Pivot column widths are sized to the formatted value text (currency, percent, and date number formats) instead of the raw number’s digits, so formatted value columns are no longer too narrow.
• Date fields on a pivot’s row or column axis now keep their number format on refresh, so header cells show formatted dates instead of raw serials. Previously only data, subtotal, and grand-total cells kept the format through re-materialization.
• Pivots with report filters now emit their page-field cells — a caption/selected-item cell pair per page field, in Excel’s single-column stack or wrapped multi-column grid — in the rows above the output range. Previously the report-filter area was omitted entirely.
• A pivot page-field (report filter) selection cell now carries the field’s own number format, so a date filter shows a formatted date instead of a raw serial.
• Pivot structural cell styles now match Excel: the column-caption dropdown-button flag is stamped on the axis-label row and only when the pivot has a real column field, and row-label left alignment is written only when the row axis has at least one compact field (not on fully-tabular layouts).
• Classic (gridDropZones) pivots now show field-name captions on their row and column axes instead of the modern literal Row Labels / Column Labels, matching Excel.
• Pivot calculated-field formulas now evaluate through the engine’s normal formula path, removing divergences from Excel’s coercion semantics that the old per-record closure tree had drifted into (e.g. unary-plus coercion on text, and empty-string arithmetic).
• Exported pivots now stamp showAll="0" on axis fields that were materialized sparse (“show items with no data” off). Excel reads an absent showAll as dense, so refreshing a previously-exported pivot re-densified the layout to the full item set and overflowed the saved footprint.
• A fully non-compact (tabular/outline) pivot now writes the table-level compact="0" compactData="0" attributes on export. Excel derives the row-label caption from these, so without them an Apiary-saved tabular pivot came back retitled (field names → Row Labels) on its first refresh.
• A grouped (date/range/discrete) pivot field now exports its full item universe in <items> (backfilled from the field group’s items), not just the materialized subset. Excel rejects a grouped field whose items list omits any bucket.
• A pivot field carrying an explicit defaultSubtotal: false without subtotalFunctions no longer gets a contradictory trailing default-subtotal item on export — a combination Excel offers to “repair” once the field also carries showAll="0".
• Exporting a page-fields-only single-data pivot no longer produces a file Excel offers to repair: its <location> geometry (anchor, header/data offsets, and the blank separator below the page area) now matches what Excel writes.
• Exported pivots now compress members repeated from the previous item of <rowItems>/<colItems> into the r (“repeated item count”) attribute, the way Excel writes them. Without it, Excel drew phantom expand/collapse buttons on the blank continuation label cells of saved multi-row-field pivots until the table was refreshed.
• Workbook.deleteRows/deleteColumns now match Excel in guarding a pivot table’s output range. A deletion that partially overlaps a pivot table is refused (throws PivotEditBlocked, like the analogous insertRows/insertColumns guard); a deletion that fully encompasses a pivot table removes it (and its cache if not also referenced by another pivot table).

Performance

• Data tables now recompute only when something they depend on changed (their source, parameters, input cells, or any cell those transitively read), and at most once per recalculation, instead of unconditionally on every recalculation. Tables whose source closure contains a dynamic reference (INDIRECT/OFFSET) still recompute on every recalculation, conservatively.
• Per-call function and operator timing now reads performance.now() only when a metricsCallback is set, removing a small per-call cost from the common no-metrics path (including hot inner loops). Behaviour is unchanged when metrics are enabled.

Build

• dist/ now ships code-split output alongside the existing index.{js,cjs,d.ts,d.cts} entry bundles (e.g. parser-*, toXlsx-*, fsHelpers-*). The package’s public entry points (exports, main, module, types) and what consumers see when they import '@grid-is/apiary' are unchanged. Consumers reaching past exports to load files inside dist/ directly would need to update: chunk filenames are content-hashed and the chunking strategy is an internal implementation detail.

v17.0.0-beta.0 (2026-06-11)

First beta of the 17.0 major line. Pivot tables — the headline 17.0 feature — land here, in beta: some known kinks are still being ironed out. Subject to further breaking changes before the stable release.

Breaking changes

(Note, these are breaking change since v17.0.0-alpha.0; note also the breaking changes reported for that version.)

Operations on Workbook may now throw new errors when they conflict with pivot-table output:

• PivotEditBlocked — thrown by insertRows/insertColumns when the insert lands strictly inside a pivot’s output area, by moveRows/moveColumns when the move’s source or destination crosses a pivot’s boundary, and by moveCells/clearCells when the affected range overlaps pivot output. Excel’s GUI refuses the same operations (usually silently); Apiary throws so the host can surface the refusal.
• PivotCellWriteBlocked — thrown by Workbook.editCell (and the write wrappers around it) when the target cell falls inside a pivot’s output region.
• PivotOutputOverlapsData — thrown by a pivot cache refresh when the refreshed pivot’s output would grow onto populated cells previously outside it.

StyleManager now reserves styles index 0 as the workbook default style (XLSX cellXf 0). A workbook built from scratch seeds slot 0 with the empty style {}, so workbook.styles.length starts at 1 and the first style created via findOrCreate gets index 1 (previously 0). Exported JSF for styled built workbooks carries the {} default at styles[0]; unstyled built workbooks still export with no styles array. Consumers should resolve styles through cell s indices rather than assuming the first created style sits at index 0.

Features

• Pivot table support (beta — some known kinks are still being ironed out):

  • Evaluation matches Excel: all OOXML aggregations and showDataAs modes, calculated fields, grouped fields, label/value/top-N filters, custom-list and autoSortScope sorting.
  • The GETPIVOTDATA spreadsheet function is now supported.
  • PivotManager.refreshCache refreshes a pivot cache from its source; structural edits adjust pivot output and cache source ranges; pivots round-trip through JSF and XLSX.
  • Look up pivots via workbook.pivots.get(name, sheetName?) and workbook.pivots.findAt(sheetName, row, col).
  • Visual pivot styling is not baked into cells: as in Excel, only the declared pivot style name is stored, and resolving it to an appearance is the renderer’s job.

• Formula parsing accepts more of Excel’s grammar (via @grid-is/waspiary 1.13.0): the @ implicit-intersection prefix operator and the structured-reference @ this-row shorthand, reference operators and calls after parenthesised references ((A1):B2, (A1)#, (A1)(B2), …), and workbook/sheet prefixes on structured references ([0]Sheet1!Table1[Col]). Calling a parenthesised non-lambda reference, e.g. (A1)(B2), evaluates to #REF! as in Excel.

API changes

• New StyleManager.defaultStyle getter and setDefaultStyle(style) method read and replace the workbook default style (slot 0). The default cannot carry extendsStyle.
• New recalcAll?: boolean on AddWorkbookOptions forces (or, when false, suppresses) a full recalculation when the workbook is attached. The default honours the file’s fullCalcOnLoad signal (see Bug fixes).

Bug fixes

• <calcPr fullCalcOnLoad="1"/> (ECMA-376 §18.2.2) is now honoured: attaching a workbook that carries the flag (and is not in manual calculation mode) performs a full recalculation instead of trusting cached values as-is, matching Excel. Previously the flag was ignored, which could leave formula cells without a usable value when the writer emitted empty cached values. The flag is cleared after a successful full recalculation, as the spec requires.
• ValueSnapshot.applyTo no longer leaves a stale cell node in the R-tree when it rebuilds a spill anchor that had been collapsed to a value cell beforehand; previously a later value write over the restored anchor tripped an internal invariant.
• A formula written via editCell to a blank-but-formatted cell that a pre-existing formula depends on now evaluates. Previously its dependency-graph vertex kept pointing at a throwaway cell object created at load, so reads returned null and recalculation recorded an “Invariant violation” model error, with no recovery even via a full recalc.

v17.0.0-alpha.0 (2026-05-30)

First alpha of the 17.0 major line. Subject to further breaking changes before the stable release; notably, pivot-table support is still to come.

Breaking changes

Structural edits and writes that would change part of a what-if data table now throw DataTableEditBlocked (exported from the package index) instead of silently corrupting the table. Excel refuses each of these edits in its UI (via a modal alert or a silent no-op); Apiary surfaces the refusal so the host application can decide how to react. The refused edits, matching Excel’s empirically verified rules, are:

• row/column inserts strictly inside a data table’s block (the range spanning its source cell, parameter cells, and result range);
• row/column deletes overlapping the block without covering the whole result range (covering it removes the table, like Excel);
• moveCells / moveRows / moveColumns taking part of the block (a move must contain all of it --- the whole table then moves) or landing on part of the result range (landing on all of it removes the table);
• writes (editCell and the write wrappers) targeting a result cell, and clearCells covering part but not all of the result range.

The error carries dataTableRef (the A1 range of the table’s result cells) and operation (a stable DataTableBlockedOperation identifier of the refused edit kind, e.g. 'insert-rows' or 'move-cells-onto') for programmatic handling, e.g. a localized host-application message.

The source and parameter cells remain freely editable, and the table recomputes from the new values. Allowed structural edits now also maintain the table’s metadata --- previously any insert/delete/move silently desynchronized it.

Transient writes and “reset” are gone, replaced by value snapshots (see below). Model.write, Model.writeMultiple, and Workbook.write still exist but are now thin wrappers around Workbook.editCell. They are persistent edits, not transient overlays. Notable differences in behaviour:

• One state, no reset. Each write mutates the workbook in place; there is no separate transient state to enumerate or roll back. To undo a value edit later, capture a ValueSnapshot beforehand and apply it to revert.

• No formula neutralization option. Writing a value to a formula cell now unconditionally replaces the formula with that value. The neutralizeFormulaOnSingleCellWrite flag is removed.

• No range writes. Model.write / Workbook.write no longer accept a multi-cell range reference. To assign values to many cells, use Model.writeMultiple([[refA, val], [refB, val], …]); for a real spill, use Workbook.editCell with an array formula.

• No writes inside merges. Model.write etc. now wrap Workbook.editCell, which throws when the target is a non-anchor cell of a merge range. Write to the merge anchor instead, or unmerge first.

• No writes to defined names. Model.write / Model.writeMultiple / Workbook.write accept string | A1Reference and throw on a defined-name reference (including a string that parses to one):

  • The “named values” feature (writing a literal value as a defined name’s formula) is gone. Workbook.editCell on a name reference now requires an explicit f formula
  • To write through a chained defined-name reference, resolve first: const ref = Reference.from(name, { ctx: model }).resolveToNonName() and then model.write(ref, v)
  • Existing workbooks with literal-formula defined names still load and evaluate read-only

The following public APIs are removed:

• Model.reset, Workbook.reset, WorkSheet.reset.
• The 'reset' model event.
• Model.writes, Workbook.writes, Model.writeState, Workbook.writeState, the ModelStateTree type, and the GRID.SCENARIO() spreadsheet function. No replacement: these all reported transient write state, which no longer exists. =GRID.SCENARIO() now resolves to #NAME?.
• The neutralizeFormulaOnSingleCellWrite and reset properties of WriteOptions. The surviving properties are forceRecalc, skipRecalc, and skipVolatiles.
• Cell._v and Cell.resetValueBoxed (the per-cell reset value).

Serialization: the _rangeWrites and _spillResetState fields and the per-cell reset value are no longer written. v17.x still loads models serialized by older Apiary versions; the dropped fields ride along in the payload and are silently ignored. Older Apiary versions cannot load v17.x serializations.

The RecalcUreachedEvent type is renamed to RecalcUnreachedEvent (the old name was a typo). The event payload is unchanged.

Features

• Value snapshots:
  • ValueSnapshot.capture(model) returns a reusable snapshot of cell and defined-name values (boxed, so number formats are preserved) and spill matrices across every workbook; formulas are captured as fingerprints only.
  • snapshot.applyTo(model, { skipRecalc?, includeDeferred? }) restores values and spills, then triggers a recalc. Any cell or name whose formula changed (added, edited, or removed) since capture is skipped, and one WARNING-level ModelError listing every affected cell/name is recorded per workbook. The check is per-position and best-effort: a structural edit that rearranges cells may produce a partially-warned, partially-corrupted revert.
  • Styles and structural edits (row/column inserts/deletes, sheet adds/removes/renames, moveCells) are out of scope and invalidate the snapshot; applying after such edits may leave the model in an incorrect state with no per-cell WARNING. For guaranteed-correct reverts across formula or structural edits, serialise the model (binary, JSF, or XLSX) and restore from that.

API changes

• Workbook.editCell is the canonical cell-mutation entry point: it keeps recalc bookkeeping in sync automatically. Model.write, Model.writeMultiple, and Workbook.write are now thin wrappers around it.
• Cell.userZ is now marked @internal and excluded from the public .d.ts type. To read the effective number format use Cell.z, or Cell.style for the full StyleRelaxed (which includes the user-assigned format under numberFormat). To set a number format use Workbook.editCell({ z }) or cell.style = { ... }. No runtime change.
• The RewriteFormula callback returned by structural-edit methods (deleteRows/deleteColumns/insertRows/insertColumns/moveRows/moveColumns/moveCells) gains two context parameters: (formula, formulaSheet, formulaWorkbook) => string. Callers that apply the returned rewriter to formulas in another sheet or workbook must now pass that context. Previously the rewriter assumed every unprefixed reference lived in the mutation’s source sheet/workbook, so it corrupted formulas applied elsewhere; moveCells in particular returned a rewriter that was a silent no-op across workbooks.

Bug fixes

• XLSX export font fix (via @grid-is/jsf2xlsx 2.2.0): the cell style cascade did not resolve fonts correctly, so cells could export with the wrong typeface.

Packaging

• Bumped Excel import/export dependencies: @grid-is/jsf2xlsx ^2.1.0 → ^2.2.0, @borgar/xlsx-convert ^5.2.0 → ^5.3.0, and @jsfkit/types ^2.2.0 → ^2.4.0.

v16.1.0

Features

• Workbook.calcMode is now a public getter/setter. Reading it returns the workbook’s current calculation mode ('auto', 'autoNoTable', or 'manual'). Setting it to 'autoNoTable' also enables data-table deferral (equivalent to Model.deferDataTables = true).

Bug fixes

• deleteRows and deleteColumns no longer rewrite formula references on sheets other than the one being modified. Previously, unqualified references on every sheet were treated as if they lived on the target sheet.
• Loading JSF containing external workbooks whose defined names carry no value no longer crashes with “Cannot set defined name with invalid name or empty formula”.
• Model.writeMultiple now correctly honours the skipVolatiles option. Previously the option was silently ignored, causing volatile functions such as RAND() and NOW() to be recalculated even when the caller asked to skip them.

v16.0.2

API changes

• Cell.edit and DefinedName.edit are now @deprecated aliases that forward to internal _edit methods. Consumers should use Workbook.editCell instead — editCell keeps the dependency graph and recalc bookkeeping in sync, which the raw edit paths do not. No runtime behaviour change.

Bug fixes

• Workbook.editCell({ v: '#N/A' }) (and Cell.edit) no longer coerces error-looking strings to error values — v is preserved as a string, matching the Cell constructor. Coercion still happens when the input includes t: 'e'.
• Workbook.editCell no longer clears existing ModelErrors on a cell before its per-branch validation guards run, so a formula edit rejected by the merge-follower guard now leaves prior errors intact.
• toJSF typing fix: External.names entries are typed as ExternalDefinedName (was JSFDefinedName, structurally compatible but wrong). Type-only fix, no behaviour change.

Performance

• Model.fromJSF external-load loop is no longer O(externals × main-cells). _addExternals defers per-external recalculate() and optimize() to a single trailing pass; on a real 125-external, 18k-cell workbook, Model.fromJSF drops from ~16s to ~2s. Callers passing recalcVolatiles: false, recalcErrors: false (the round-trip harnesses) still see no recalc.

Packaging

• numfmt moved from peerDependencies to dependencies (range unchanged, ~3.2.2). Apiary uses numfmt internally and consumers never pass instances in or out of the API; the peer-dependency placement was incidental, and demoting it means npm install @grid-is/apiary works without consumers having to add a matching numfmt entry.
• @types/node moved from dependencies to optional peerDependencies (range: >=20.19.23 <21 || >=22.19.0 <23 || >=24.10.0). The published dist/index.d.ts still references Node’s Buffer, so a TypeScript Node consumer needs @types/node resolvable — but the consumer’s own pin now wins. Pure-JS consumers see no missing-peer warning thanks to optional: true. The per-major minimum reflects the late-2025 DefinitelyTyped round that narrowed Buffer.buffer from ArrayBufferLike to ArrayBuffer; below that, our public Workbook.fromXLSX / Model.fromXlsx types are unsound.
• @borgar/xlsx-convert bumped to 5.2.0, picking up an XLSX color/theme parsing fix that surfaced through Model.fromXlsx in an add-ins consumer (undefined is not an object (evaluating 'readColor(elm.children[0], …)')).

v16.0.1

API changes

• Removed the NamedStyle and Style re-exports from the package entry point. These were unintentionally exposed during the 16.0 cycle and were never meant to be part of Apiary’s public API; import them from @jsfkit/types directly. Type-only change with no runtime impact.

Bug fixes

• Model now emits addsheet when a sheet is added (previously dropped silently), and no longer emits a spurious recalc for that operation.
• Three independent deserialization-fidelity bugs in the binary cache, jointly affecting autoNoTable-mode roundtrips, are fixed:
  • Workbook._calcMode is restored from the payload (was silently reverting to 'auto').
  • Cells._dataTableCells (the data-table-anchor index) is repopulated, so iterDataTableCells() works on deserialized workbooks — unblocking the Model.deferDataTables = true setter and Model.attachWorkbook’s autoNoTable handling.
  • Model._deferDataTables and the deferral cell Sets (cellsToDefer, staleDeferredCells) are now serialized and restored, so a model in deferral mode no longer loses it through a roundtrip.
• toJSF compacts full-row/full-column spill ranges in cell.F (A3:XFD3 → 3:3, B1:B1048576 → B:B), eliminating spurious roundtrip diffs when a code path holds an expanded F.
• Error subclasses now set their own name field, so stack traces, console.log, inspect(), and Sentry display the actual class name (e.g. FormulaSyntaxError) instead of the inherited Error.
• @jsfkit/types moved from devDependencies to dependencies so it is installed transitively when consumers npm install @grid-is/apiary. The published dist/index.d.{ts,cts} references @jsfkit/types directly because those types appear in Apiary’s public API; consumers’ type-checking previously failed unless they happened to depend on @jsfkit/types for other reasons.
• typescript moved from dependencies to devDependencies. It is only used here as a CLI build tool (tsc --noEmit, tsup); nothing in lib/ imports it and the published types do not reference it. There is no public-API reason for consumers to receive Apiary’s pinned typescript version transitively. Originally added to dependencies during the apiary monorepo extraction without a deliberate placement choice.

Serialization

• CURRENT_SERIALIZATION_VERSION bumped 5 → 6 to carry the previously-omitted Model._deferDataTables boolean and the two deferral cell Sets. MINIMUM_ACCEPTABLE_SERIALIZATION_VERSION is unchanged — older payloads still load, with the new fields defaulted to off / empty.

Documentation

• JSF types referenced from the generated API reference (NamedStyle, Note, Style, Theme, ThemeColorScheme, ThemeCustomColor, ThemeFontCollection, ThreadedComment) now link to jsfkit.github.io instead of being mirrored as local Apiary type-alias pages.
• EvaluateExpressionOptions.cropTo is now documented.
• Cleaned up a confusing JSF-normalizer docstring.

v16.0.0 (2026-04-30)

Breaking changes

• Workbook.views is now a ViewManager (was WorkbookView[] | undefined). Workbook.getViews() and WorkSheet.getViews() are removed; WorkSheet.views is now @internal. Per-sheet view state is now read/written via workbook.views.get(index).getSheetView(sheetName).
• Workbook.theme is now a ThemeManager (always present), not Theme | undefined.
• WorkSheet.showGridLines property removed; gridline visibility now lives on WorkSheet.views[].showGridLines (per-view).
• @jsfkit/types 1.x → 2.x: colours are now structured Color objects instead of hex strings, themes are restructured, and several types are reshaped.
• Workbook.rowHeight(rowIndex, sheetName) now throws SheetNotFoundError when the sheet does not exist (previously returned the default 16 silently), and consults sheet.defaults.rowHeight before falling back to the Excel default. The new Workbook.columnWidth() follows the same precedence on its axis.
• WorkSheet.rowHeights and WorkSheet.colWidths fields removed. Per-row height and per-column width are now read from WorkSheet.rows and WorkSheet.columns (the GridSize[] span arrays).

Removed @deprecated symbols (each deprecation note already pointed at the replacement shown here):

• Cell.hasValue() / DefinedName.hasValue() and Cell.isBlank() / DefinedName.isBlank() removed. Use hasValueOrFormula().
• Workbook.getTables() and Workbook.getTable(name) removed. Use workbook.tables.getAll() and workbook.tables.get(name).
• WorkSheet.getComments() and WorkSheet.getNotes() removed. Use workbook.comments.get(sheetName) and workbook.notes.get(sheetName).
• Model.fromData removed. Use Model.fromCsf.
• Workbook.lazyImportPromise, Model.lazyImportPromise, loadLazy(), and the loadLazy re-export removed. All four were already no-ops; just delete the calls.
• A batch of @deprecated @internal re-exports removed from the package entry point: formula-evaluation helpers (run, errorForCode, errorTable, …) and dependency graph helpers (cellToVertexId, wbNameToKey, …). Use cell.vertexId / definedName.vertexId instead of cellToVertexId(cell).

(Several dependency-graph items previously marked @deprecated @internal (or not exported at all) are now part of the public API: VertexId, CellVertexId, NameVertexId, RangeVertexId, KnownVertexId, VertexIdSet. The helpers referenceToVertexId, vertexIdToCell, and vertexIdToReference are re-exported with @internal markers — available, but excluded from documentation.)

Features

• Views CRUD via Workbook.views, with two new public types ViewManager and WorkbookView.
• Theme CRUD via Workbook.theme (new ThemeManager): read/write the theme as a whole, the 12-colour scheme, major/minor fonts, and custom colours.
• Named-style CRUD via styleManager.named (new NamedStyles collection), with case-insensitive lookup and original casing preserved on NamedStyle.name.
• Workbook.reorderSheet(name, newIndex) and Workbook.copySheet(name, newName?).
• Table is now a public type export with new methods (appendRow, insertRow, rename, rowRef) and a new dataRowCount getter. TableManager is also exported as a type. (The runtime classes are not re-exported: instances come from workbook.tables.get(name) / workbook.tables.add().)
• Public-API types now exported from the package entry point (previously reachable only via Parameters<typeof model.write>[2]-style tricks): WriteOptions, AddWorkbookOptions, WorkbookOptions, ReplaceTableReferencesFn, ModelEventArgs, ModelEventType, ModelEventListener, EvaluateExpressionOptions, ModelMeta.
• NotesManager and CommentsManager are now exported so they show up in the generated public docs.
• Workbook.toXLSX(outputType?, options?) gains both arguments. outputType is 'nodebuffer' (default) or 'arraybuffer' for browser-compatible XLSX export. options (typed as ToXLSXOptions) carries a compressionLevel setting (DEFLATE 0–9), now defaulting to 6, down from 9 — measurably faster export with negligible size impact on typical XLSX payloads.
• Workbook.columnWidth(columnIndex, sheetName) — analogous to Workbook.rowHeight(). Returns the column width in pixels.
• Workbook.moveCells and Workbook.rewriteFormulas accept an optional recalcNow (default true); pass false to defer the trailing recalculate().

API changes

• Workbook.editCell() added as the preferred name for writeCellData() (which stays as a @deprecated alias). Its parameter type simplifies to plain CellData, which now includes the optional ft field.
• Identifier casing standardized on uppercase JSF/XLSX: Model.fromJSF, toJSF, csfToJSF, normalizeJSFForComparison, toXLSX, toXLSXFile, validateXLSXFilePath, plus type XLSXOutputType. The old title-case spellings remain as @deprecated aliases with identical signatures — no breaking change.

Bug fixes

• moveCells now handles merged cells. Destination merges are dissolved silently (matching Excel Scripts and Office.js behavior), and cells moved out of a source merge no longer carry stale .M merge pointers.
• Loading a workbook with a table whose name is not valid as a defined name (e.g. T1, A1, R1C1) now sanitizes and uniquifies the name instead of dropping the table with a ModelError.
• Iterative calculation now converges correctly when the iterative set contains a spill; previously the calc ran to maxIterations every time and dependents of unchanged spills could be flagged as false-positive circular references.
• getEntities no longer crashes on workbooks containing sheet-scoped defined names.
• SORTN silently ignores out-of-bounds sort-column indices instead of returning #VALUE!, matching verified Google Sheets behavior.
• toJSF preserves values in merged-cell “ghosts” (non-anchor cells); mergeCells keeps styles on follower cells and only clears values, matching Excel.
• Deserializing models serialized by older Apiary versions no longer crashes on missing views/comments/notes/people/externals/rows properties or on the stable.csf -> stable.jsf Table key rename.
• replaceTableReferences now correctly rewrites bare-name references to tables (not just bracketed structured references).
• Dynamic dependencies of LAMBDA closures passed to BYROW/BYCOL/MAP/REDUCE/SCAN with INDIRECT/OFFSET/ANCHORARRAY in the body are now tracked, so edits to referenced cells correctly trigger recalc.
• Lambda parameter resolution during reference analysis no longer crashes on INDIRECT/OFFSET inside directly-called lambdas or nested lambda scopes.
• toJSF no longer crashes on full-row or full-column spill ranges.
• rewriteFormulas skips unparseable formulas instead of throwing.
• Loading CSF workbooks: the literal string "#SPILL!" in a cell is no longer coerced to an error value, fixing an R-tree invariant violation that crashed describeWorkbook in some cases.
• Cells in JSF with error-looking string values ("#VALUE!", "#N/A", …) but no explicit t: 'e' marker are preserved as strings, not coerced to errors.

Performance

• Faster label detection in describeWorkbook via cheaper subordinate-style checks (weighted geomean ~23.5% faster, worst-case workbooks up to 43% faster).

Serialization

• CURRENT_SERIALIZATION_VERSION bumped 3 → 5 over the v16 cycle. The 3 → 4 step was a marker for shape changes that had already landed without a version bump (Table csf → jsf key, cellsWithDynamicDependencies, notes/comments/views/tables), giving consumers that cached v3 payloads a proper signal to invalidate. The 4 → 5 step adds the namedStyles field and folds the legacy parallel rowHeights/colWidths maps into the WorkSheet.rows/WorkSheet.columns span arrays. MINIMUM_ACCEPTABLE_SERIALIZATION_VERSION stays at 1 — older cached payloads still load.

Documentation

• ModelError.toJSON API documentation cleaned up (the raw inferred-return-type property list is gone); the MDN link gets a readable link text.

Dependencies

• @jsfkit/types ^1.4.1 → ^2.2.0 (see Breaking changes for the structural shifts).
• @borgar/xlsx-convert and @grid-is/jsf2xlsx upgraded for XLSX import/export of named styles and the CSE array-formula flag, plus round-trip and repair-dialog fixes.
• @grid-is/waspiary → 1.11.0 for structured-reference bare-name rewrite.

v16.0.0-rc.0 (2026-04-16)

First release candidate for the 16.0 major line. Covers the deprecation cleanup, API additions, and fixes landed since v16.0.0-alpha.0.

Breaking changes

All of the following remove symbols that were already @deprecated, with their deprecation notes pointing at the replacement shown here.

• Cell.hasValue() / DefinedName.hasValue() and Cell.isBlank() / DefinedName.isBlank() removed. Use hasValueOrFormula().
• Workbook.getTables() and Workbook.getTable(name) removed. Use workbook.tables.getAll() and workbook.tables.get(name).
• WorkSheet.getComments() and WorkSheet.getNotes() removed. Use workbook.comments.get(sheetName) and workbook.notes.get(sheetName).
• Model.fromData removed. Use Model.fromCsf.
• Workbook.lazyImportPromise, Model.lazyImportPromise, loadLazy(), and the loadLazy re-export removed. All four were already no-ops; just delete the calls.
• A batch of @deprecated @internal re-exports removed from the package entry point: formula-evaluation helpers (run, errorForCode, errorTable, …) and dependency graph helpers (cellToVertexId, wbNameToKey, …). Use cell.vertexId / definedName.vertexId instead of cellToVertexId(cell).

(Some dependency graph classes and utilities were previously marked @deprecated @internal but are now instead made public: VertexId, CellVertexId, NameVertexId, RangeVertexId, KnownVertexId, VertexIdSet, referenceToVertexId, vertexIdToCell, vertexIdToReference.)

Features

• Public-API types now exported from the package entry point (previously reachable only via Parameters<typeof model.write>[2]-style tricks): WriteOptions, AddWorkbookOptions, WorkbookOptions, ReplaceTableReferencesFn, ModelEventArgs, ModelEventType, ModelEventListener, EvaluateExpressionOptions, ModelMeta.
• Named-style CRUD via styleManager.named (new NamedStyles collection), with case-insensitive lookup and original casing preserved on NamedStyle.name.

API changes

• Workbook.editCell() added as the preferred name for writeCellData() (which stays as a @deprecated alias). Its parameter type simplifies to plain CellData, which now includes the optional ft field.
• Identifier casing standardized on uppercase JSF/XLSX: Model.fromJSF, toJSF, csfToJSF, normalizeJSFForComparison, toXLSX, toXLSXFile, validateXLSXFilePath, plus types XLSXOutputMap and XLSXOutputType. The old title-case spellings remain as @deprecated aliases with identical signatures — no breaking change.

Bug fixes

• moveCells now handles merged cells. Destination merges are dissolved silently (matching Excel Scripts and Office.js behavior), and cells moved out of a source merge no longer carry stale .M merge pointers.
• Loading a workbook with a table whose name is not valid as a defined name (e.g. T1, A1, R1C1) now sanitizes and uniquifies the name instead of dropping the table with a ModelError.

Serialization

• CURRENT_SERIALIZATION_VERSION bumped 3 → 4 as a marker for shape changes that had landed without a version bump (Table csf → jsf key, cellsWithDynamicDependencies, notes/comments/views/tables), giving consumers that cached v3 payloads a proper signal to invalidate.
• CURRENT_SERIALIZATION_VERSION bumped 4 → 5 for the named-styles addition. MINIMUM_ACCEPTABLE_SERIALIZATION_VERSION stays at 1 — older cached payloads still load.

Documentation

• ModelError.toJSON API documentation cleaned up (the raw inferred-return-type property list is gone); the MDN link gets a readable link text.

v16.0.0-alpha.0 (2026-04-08)

First alpha of the 16.0 major line. Subject to further breaking changes before the stable release.

Breaking changes

• Workbook.views is now a ViewManager (was WorkbookView[] | undefined). Workbook.getViews() and WorkSheet.getViews() are removed; WorkSheet.views is now @internal. Per-sheet view state is now read/written via workbook.views.get(index).getSheetView(sheetName).
• Workbook.theme is now a ThemeManager (always present), not Theme | undefined.
• WorkSheet.showGridLines property removed; gridline visibility now lives on WorkSheet.views[].showGridLines (per-view).
• @jsfkit/types 1.x → 2.0.0: colours are now structured Color objects instead of hex strings, themes are restructured, and GridSize gains an optional size.

Features

• Views CRUD via Workbook.views, with two new public types ViewManager and WorkbookView.
• Theme CRUD via Workbook.theme (new ThemeManager): read/write the theme as a whole, the 12-colour scheme, major/minor fonts, and custom colours.
• Workbook.reorderSheet(name, newIndex) and Workbook.copySheet(name, newName?).
• Table class is now a public export with new methods (appendRow, insertRow, rename, rowRef) and a new dataRowCount getter. TableManager is also exported.
• toXlsx accepts an optional outputType argument ('nodebuffer' (default) or 'arraybuffer') for browser-compatible XLSX export. New exports XlsxOutputType and XlsxOutputMap.
• NotesManager and CommentsManager are now exported so they show up in the generated public docs.
• Workbook.moveCells and Workbook.rewriteFormulas accept an optional recalcNow (default true); pass false to defer the trailing recalculate().

Bug fixes

• getEntities no longer crashes on workbooks containing sheet-scoped defined names.
• SORTN silently ignores out-of-bounds sort-column indices instead of returning #VALUE!, matching verified Google Sheets behavior.
• toJsf preserves values in merged-cell “ghosts” (non-anchor cells); mergeCells keeps styles on follower cells and only clears values, matching Excel.
• Deserializing models serialized by older Apiary versions no longer crashes on missing views/comments/notes/people/externals/rows properties or on the stable.csf -> stable.jsf Table key rename.
• replaceTableReferences now correctly rewrites bare-name references to tables (not just bracketed structured references).
• Dynamic dependencies of LAMBDA closures passed to BYROW/BYCOL/MAP/REDUCE/SCAN with INDIRECT/OFFSET/ANCHORARRAY in the body are now tracked, so edits to referenced cells correctly trigger recalc.
• Lambda parameter resolution during reference analysis no longer crashes on INDIRECT/OFFSET inside directly-called lambdas or nested lambda scopes.
• toJsf no longer crashes on full-row or full-column spill ranges.
• rewriteFormulas skips unparseable formulas instead of throwing.
• Loading CSF workbooks: the literal string "#SPILL!" in a cell is no longer coerced to an error value, fixing an R-tree invariant violation that crashed describeWorkbook in some cases.
• Cells in JSF with error-looking string values ("#VALUE!", "#N/A", …) but no explicit t: 'e' marker are preserved as strings, not coerced to errors.

Performance

• Faster label detection in describeWorkbook via cheaper subordinate-style checks (weighted geomean ~23.5% faster, worst-case workbooks up to 43% faster).

Dependencies

• @jsfkit/types ^1.4.1 -> ^2.0.0 (see Breaking changes).
• @grid-is/waspiary -> 1.11.0 for structured-reference bare-name rewrite.

v15.5.0 (2026-03-05)

Features

• Cell notes CRUD via NotesManager (workbook.notes): add, get, getByCell, update, delete

Bug fixes

• AND/OR/XOR/NOT evaluation with strings and other edge-case arguments, matching Excel and Google Sheets behavior
• TEXTJOIN and JOIN now apply cell display formats (e.g. date formats) in Google mode

Interface changes

These are technically breaking, but very minor and in very recent features, so did not demand a major-version bump.

• CommentsManager now throws SheetNotFoundError (instead of plain Error) for missing sheets, with a differently worded message.
• WorkSheet.notes type changed to Note[] (no longer possibly undefined)

Dependencies

• Update @grid-is/jsf2xlsx to ^1.3.2, updating default column width and fixing extraneous activeTab="0" attributes in workbookView elements.

v15.4.0 (2026-03-02)

Features

• Respect ‘autoNoTables’ from XLSX file, plus deferDataTables option for manual control
  • And more generally, mark any formula cells to be deferred in recalculation
• Threaded comments CRUD via CommentsManager (workbook.comments)

Bug fixes

• MATCH returned #N/A instead of #REF! in Excel missing-sheet edge case
• toJsf export expanded external workbooks to nonexistent cells if referenced in ranges
• Error-like strings (e.g. #REF!) not treated as error values when loading styled cells from CSF
• Default (named) styles were not preserved in toJsf export

Performance

• Much faster worst-case describeWorkbook (label-detection) performance

Documentation

• Update quickstart to use Model.fromXlsxFile instead of manual xlsx-convert

v15.3.1 (2026-02-23)

Bug fixes

• Preserve formula type (array or not) when result is 1x1, and classify correctly on edit
• Serialization did not preserve views, annotations, rows, and externals
• Remove Node.js util imports so consumers need not polyfill for browser compatibility

Documentation

• Add changelog to public docs

v15.3.0 (2026-02-19)

Features

• Excel data tables
• Function SORTN
• getViews method in WorkSheet and Workbook
• Google Sheets FLATTEN function
• Merge/unmerge cells

Bug fixes

• Make HYPERLINK()-derived hyperlinks ephemeral
• Preserve external workbooks in JSF roundtrip
• Update comment and note cell refs on move, insert, and delete
• Wrap fs/promises imports in try-catch to avoid bundler errors

Performance

• Speed up describeWorkbook by pre-filtering parseDate calls

Documentation

• Pare down public API, marking stuff @deprecated and/or @internal
• Use code blocks in Typedoc-generated docs

v15.2.0 (2026-02-10)

Features

• Support JSF cell notes and threaded comments

Bug fixes

• describeWorkbook crash on cross-workbook ref to formula cell
• Support QUERY with COUNT(DISTINCT value)

v15.1.1 (2026-02-10)

Bug fixes

• Missed dynamic dependencies in lambda-calling functions at init time
• Preserve cells with explicit empty styles through round-trip
• Strip numberFormatFromFormula from exported styles in toJSF

v15.1.0 (2026-02-04)

Features

• toJsf
• toXlsx
• Add fromXlsx methods for direct XLSX loading
• Native QUERY without pg-mem (calling it “feat” because it supports a lot that the old one did not)
• Output style indexes on rows and columns

Bug fixes

• Real workbooks override external workbooks with same name
• Fix invariant error on insert after row is deleted
• Export ft property in toCSF for array formulas
• Init recalc was skipped if !recalcVolatiles && !recalcErrors
• Load XLSX files in Excel mode by default
• Respect recalcVolatiles option during initial recalculation
• Preserve text strings that look like errors in JSF loading
• ERROR.TYPE did not support modern error codes
• describeWorkbook throws on JSF workbook with externals
• Upgrade xlsx-convert to 3.6.4 for bugfixes
• Fix handlerRels to work with absolute paths
• Fix external refs order
• The r property on cells is optional

Breaking changes

• Remove Flags module and flags export

v15.0.0 (2026-01-14)

Features

• Public Model.attachWorkbook, and document addWorkbook as just a wrapper
• Export StyleManager
• Export CellData type
• Add support for JSF workbook/worksheet view props
• Specific Error subclass for invalid reference strings
• Add missing detail messages on #CALC! errors

Bug fixes

• Google-mode early-date date function discrepancies
• Matrix.expand makes fully-populated matrices, causing performance disasters
• Nonresolving name in LOOKUP vector arg borks reference analysis
• Propagate markDirty to all dependents of spill ranges
• Blank spill anchor missing in Cells.getCells
• Don’t propagate recalc from unchanged spill matrix
• numberFormatFromFormula propagation
• SUMIFS etc. wrong for Matrix with defaulted regions
• Incorrect swap in Brent root-finding setup
• QUERY with now() not treated as volatile if no dependencies
• GSDV blocker in extended range should not block other columns
• Evaluate array expressions with mismatched row widths as #VALUE!
• Fix default column-width units discrepancy
• Fix Table serialization property name mismatch
• Fix serialization invariant violation
• Fix errors in toCSF export structures
• Fix GSDV spill range inference: use offset not absolute row
• Fix regression in evaluateExpression
• Preserve CSF style array when loading workbooks

Performance

• Add vertexId to Cell and DefinedName
• Non-volatile OFFSET and INDIRECT and ANCHORARRAY with dynamic dependencies

Breaking changes

• CSF type should have filename, not name
• Change NameReference.width and .height to be undefined, not throw

Dependencies

• Update fx to 5.0
• Upgrade Waspiary to 1.10.0 to permit R and C names

v15.0.0-rc3 (2026-01-08)

Features

• Add missing detail messages on #CALC! errors
• Export CellData type
• Specific Error subclass for invalid reference strings
• Add support for JSF workbook/worksheet view props
• Preserve CSF style array when loading workbooks

Bug fixes

• GSDV blocker in extended range should not block other columns
• numberFormatFromFormula propagation
• SUMIFS etc. wrong for Matrix with defaulted regions
• Incorrect swap in Brent root-finding setup
• QUERY with now() not treated as volatile if no dependencies
• Evaluate array expressions with mismatched row widths as #VALUE!
• Fix GSDV spill range inference: use offset not absolute row
• Fix Table serialization property name mismatch
• Fix serialization invariant violation
• Fix errors in toCSF export structures

v15.0.0-rc2 (2025-12-10)

Bug fixes

• Blank spill anchor missing in Cells.getCells
• Don’t propagate recalc from unchanged spill matrix
• Fix regression in evaluateExpression
• CSF type should have filename, not name

Performance

• Non-volatile OFFSET and INDIRECT and ANCHORARRAY with dynamic dependencies

v15.0.0-rc1 (2025-12-08)

Features

• Public Model.attachWorkbook, and document addWorkbook as just a wrapper
• Export StyleManager

Bug fixes

• Google-mode early-date date function discrepancies
• Matrix.expand makes fully-populated matrices, causing performance disasters
• Non-resolving name in LOOKUP vector arg borks reference analysis
• Propagate markDirty to all dependents of spill ranges
• Fix default column-width units discrepancy

Performance

• Add vertexId to Cell and DefinedName

Breaking changes

• Change NameReference.width and .height to be undefined, not throw

Dependencies

• Update fx to 5.0

v14.13.0 (2025-11-19)

Features

• Read JSF directly

Bug fixes

• Bugs in row and column deletion and moves
• Support R1C1 syntax in INDIRECT
• Handle changed serialization
• Replace ERROR_SPILL 'foo' placeholder with proper detail message
• Serialize model with lambdas in arrays
• VLOOKUP/HLOOKUP can return non-up-to-date value
• Direct call to UPLUS fails with internal error
• Recalculate affected formulas if clearGsdv clears cells

Breaking changes

• Remove reset value from DefinedName and CellInterface

Dependencies

• Switch to @jsfkit/types for JSF type definitions

Other

• Install from, and publish to, npmjs.com registry

v14.12.0 (2025-10-17)

Breaking changes

• Make FormulaError and Reference fully immutable

Features

• Store origin cell in FormulaError
• Add and improve error-value detail messages
• Add detail messages to #SPILL! errors

Bug fixes

• Make Cell.isBlank() closer to what its name implies
• Minor bugs in reference intersection and add a test
• Rename and deprecate Cell methods

Documentation

• Deploy public API docs to GitHub Pages site
• Remove internal stuff from docs
• Mention case-insensitivity in name parameters

v14.11.0 (2025-10-15)

Features

• Recalculate error-valued cells at init time
• Remove defined name

Bug fixes

• Wrong spill-operator result for blocked spill
• QUERY coerces dates to string by local timezone
• Support structured references in INDIRECT
• IF result should not be marked dynamic
• Make apiary bin work again

v14.10.1 (2025-10-01)

Features

• Allow disabling common-subexpression extraction

Bug fixes

• Fix 1904 epoch bug when converting JSF to CSF

v14.10.0 (2025-09-25)

Features

• Export FormulaSyntaxError and EvaluationError
• Add Model.empty() convenience method
• Export recalculation option symbols

Bug fixes

• ADDRESS with invalid coordinates yields wrong results or throws exception
• Use source number format in TO_TEXT
• Set number format in TO_* functions
• XLOOKUP third argument wrongly forced up-to-date
• ROW etc. fail to update when name ref updates
• False-pos circdep in SUMIF/AVERAGEIF on target range extension
• Workbook.iterFormulaCells had a bug and a redundant sibling
• Update JSF support

Documentation

• Add a quick start guide
• Add Starlight-based documentation system
• Add tutorial for creating a spreadsheet from scratch
• Document some methods on the Model class

v14.9.5 (2025-09-01)

Features

• Add support for loading and converting JSF format

v14.9.3 (2025-08-12)

Bug fixes

• CONVERT failed to handle reference value argument

Dependencies

• Bump fx from 4.11.2 to 4.12.0 [bot]
• Bump msgpackr from 1.11.4 to 1.11.5 [bot]

v14.9.2 (2025-07-23)

Bug fixes

• Fix defined names causing slow iterative calculation

v14.9.1 (2025-07-22)

Version revoked due to incorrect fix.

v14.9.0 (2025-06-27)

• Detect parent labels

v14.8.7 (2025-06-26)

Bug fixes

• Label sequence confusion from sparse values at island top/left

Dependencies

• Bump component-emitter from 1.3.0 to 2.0.0
• Upgrade pg-mem to 2.6.15

v14.8.6 (2025-06-12)

Bug fixes

• Leftmost-column data mistaken for a label sequence

v14.8.5 (2025-06-08)

Bug fixes

• Skip over gaps in mixed-type label subsequences

v14.8.4 (2025-06-08)

• Improve island-based label detection