@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/io/xlsb/read-worksheet.js

@@ -1,21 +1,3 @@
-// The BIFF12 worksheet-body reader: one `xl/worksheets/sheetN.bin` in, one populated {@link Worksheet}
-// out — the binary counterpart of `../xlsx/read-worksheet.ts`, filling the very same model.
-//
-// The cell table is a flat, row-major run of records: a `BrtRowHdr` opens a row and every cell record
-// until the next one belongs to it, so the open row is a single variable rather than nested state.
-// Each cell record is a `Cell` header followed by a value shaped by the record's own type — which is
-// what makes the binary form quick to parse: there is no `t=` attribute to interpret, the record
-// number *is* the type.
-//
-// A formula cell carries both halves of what the XML form spells in `<f>` and `<v>`: a `Ptg` token
-// stream, decoded back to text by `./formula.ts`, and the result Excel last computed. The two are
-// filled independently — a formula whose stream uses a token this reader does not decode still
-// surfaces its cached value, which is exactly what the reader could see before the decoder existed.
-//
-// One shape needs a second look at the sheet. An array formula's member cells hold a `PtgExp`
-// pointing at the group's top-left, and the `BrtArrFmla` record carrying the group's actual formula
-// comes *after* those cells in the stream. Those cells are therefore parked and resolved once the
-// whole part has been read.
 import { encodeAddress, MAX_COLUMN } from '../../core/address.js';
 import { isDateFormat, serialToDate } from '../../core/date.js';
 import { unmangleFunctions } from '../../core/formula.js';
@@ -25,9 +7,6 @@ import { decodeFormula, formulaAnchor } from './formula.js';
 import { errorCodeFor, RecordReader } from './primitives.js';
 import { readRecords } from './record-stream.js';
 import { BRT } from './record-types.js';
-// Every record that carries a plain cell — one whose payload is a value and nothing else. Membership
-// drives the dispatch below, so a record type absent from both this set and {@link FORMULA_RECORDS}
-// is skipped whole rather than being mistaken for a cell and consuming the reader.
 const CELL_RECORDS = new Set([
     BRT.CellBlank,
     BRT.CellRk,
@@ -38,40 +17,23 @@ const CELL_RECORDS = new Set([
     BRT.CellIsst,
     BRT.CellRString,
 ]);
-// Every record that carries a formula: a cached result of the record's own kind, then the token
-// stream that produced it.
 const FORMULA_RECORDS = new Set([
     BRT.FmlaString,
     BRT.FmlaNum,
     BRT.FmlaBool,
     BRT.FmlaError,
 ]);
-/**
- * Read a worksheet part into `sheet`: its column and row geometry, its merged ranges, and every
- * non-empty cell with the style its index resolves to in `xfStyles` and, for a formula cell, the text
- * its token stream decodes to through `scope`.
- */
 export function parseWorksheet(part, sheet, sharedStrings, xfStyles, scope) {
-    // The open row, one-based as the model counts them. -1 means none is open, which a cell record
-    // arriving before any row header (a malformed sheet) is dropped against rather than guessed at.
     let row = -1;
-    // A row that declares a format supplies the default for its cells that carry none, as a column
-    // does; the next row header replaces it.
     let rowStyle = -1;
-    // A column's format is the last fallback. Column records always precede the cell table.
     const columnStyle = new Map();
-    // The sheet's default row height, in twips. Every row header restates its height whether or not the
-    // row has one of its own, so the default is what tells the two apart — see {@link applyRow}.
-    // `BrtWsFmtInfo` precedes the cell table, so it is always known by the time a row is read.
     let defaultRowHeight = -1;
-    // The formula of each array-formula group, keyed by the group's top-left cell, and the member cells
-    // waiting on one. Both are needed because `BrtArrFmla` follows the cells it speaks for.
     const groups = new Map();
     const deferred = [];
     for (const record of readRecords(part)) {
         const reader = new RecordReader(record.data);
         if (record.type === BRT.WsFmtInfo) {
-            reader.skip(6); // dxGCol, cchDefColWidth: the default *column* width, which the model does not read.
+            reader.skip(6);
             defaultRowHeight = reader.u16();
         }
         else if (record.type === BRT.ColInfo) {
@@ -90,7 +52,7 @@ export function parseWorksheet(part, sheet, sharedStrings, xfStyles, scope) {
         }
         else if (record.type === BRT.ArrFmla) {
             const { rowFirst, colFirst } = reader.range();
-            reader.skip(1); // fAlwaysCalc: a recalculation hint, not part of the formula.
+            reader.skip(1);
             groups.set(groupKey(rowFirst, colFirst), {
                 rgce: reader.bytes(reader.u32()),
                 rgcb: reader.bytes(reader.u32()),
@@ -100,9 +62,6 @@ export function parseWorksheet(part, sheet, sharedStrings, xfStyles, scope) {
             const { column, styleIndex } = reader.cell();
             if (!inGrid(column, row - 1))
                 continue;
-            // A cell's own format wins, then its row's, then its column's — the order Excel applies.
-            // Index 0 is the default xf, which BIFF12 writes where XML simply omits `s`, so it means
-            // "no format of my own" and lets the row/column default through.
             const resolved = styleIndex > 0 ? styleIndex : rowStyle >= 0 ? rowStyle : (columnStyle.get(column) ?? -1);
             const style = resolved >= 0 ? xfStyles[resolved] : xfStyles[0];
             const cell = sheet.getCell(encodeAddress(column + 1, row));
@@ -112,7 +71,7 @@ export function parseWorksheet(part, sheet, sharedStrings, xfStyles, scope) {
                 continue;
             }
             const result = cachedResult(record.type, reader, style?.numFmt);
-            reader.skip(2); // grbitFlags: per-cell recalculation hints the model does not carry.
+            reader.skip(2);
             const rgce = reader.bytes(reader.u32());
             const rgcb = reader.bytes(reader.u32());
             const anchor = formulaAnchor(rgce, rgcb);
@@ -132,8 +91,6 @@ export function parseWorksheet(part, sheet, sharedStrings, xfStyles, scope) {
         }
     }
     for (const member of deferred) {
-        // Only the group's top-left cell states the formula; the rest carry the value it produced, which
-        // is exactly what the XML form writes for them.
         const group = groups.get(groupKey(member.anchorRow, member.anchorColumn));
         const own = member.row === member.anchorRow && member.column === member.anchorColumn;
         member.cell.value =
@@ -145,23 +102,15 @@ export function parseWorksheet(part, sheet, sharedStrings, xfStyles, scope) {
 function groupKey(row, column) {
     return `${row}:${column}`;
 }
-// Pair a decoded formula with its cached result, in the shape the XML reader produces for the same
-// cell. A formula the decoder could not read leaves the value alone: the cached result is still true,
-// and is what this reader surfaced before formulas were decoded at all.
 function formulaValue(formula, result) {
     if (formula === undefined)
         return result ?? null;
-    // Strip the `_xlfn.`/`_xlpm.` on-disk mangling, as the XML reader does, so the model never holds it.
     const stored = unmangleFunctions(formula);
     return result === undefined ? { formula: stored } : { formula: stored, result };
 }
-// The result a formula record cached, decoded by the record's own kind — the binary counterpart of
-// reading `<v>` under the `t` attribute.
 function cachedResult(type, reader, numFmt) {
     switch (type) {
         case BRT.FmlaNum:
-            // A formula's cached numeric result honours the cell's date format exactly as a bare number
-            // does, so a date-valued formula reads back as a Date rather than a serial.
             return asNumberOrDate(reader.f64(), numFmt);
         case BRT.FmlaBool:
             return reader.u8() !== 0;
@@ -173,19 +122,11 @@ function cachedResult(type, reader, numFmt) {
             return reader.wideString();
     }
 }
-// Excel's grid bounds, zero-based as the binary format counts. [MS-XLSB] states them as MUST
-// constraints, which is exactly why a reader has to check them: a damaged or hostile file states
-// whatever it likes, and an address beyond the grid has nowhere to go. Everything positional funnels
-// through here before it reaches the model, so an out-of-grid record is dropped rather than turned
-// into an unrepresentable address (which the address encoder would reject) or, worse, a column loop
-// four billion iterations long.
 const MAX_ROW_INDEX = 1048575;
 const MAX_COLUMN_INDEX = MAX_COLUMN - 1;
 function inGrid(column, row) {
     return column >= 0 && column <= MAX_COLUMN_INDEX && row >= 0 && row <= MAX_ROW_INDEX;
 }
-// Decode a cell record's payload — the reader is positioned just past the shared `Cell` header, so
-// what remains is exactly the value this record type carries.
 function decodeCell(type, reader, sharedStrings, numFmt) {
     switch (type) {
         case BRT.CellRk:
@@ -195,45 +136,32 @@ function decodeCell(type, reader, sharedStrings, numFmt) {
         case BRT.CellBool:
             return reader.u8() !== 0;
         case BRT.CellError: {
-            // An unrecognised error byte keeps the cell non-empty without inventing an error the model
-            // does not define; there is no text form to fall back to as there is in XML.
             const error = errorCodeFor(reader.u8());
             return error === undefined ? null : { error };
         }
         case BRT.CellSt:
             return reader.wideString();
         case BRT.CellRString:
-            // Rich runs are not modelled in this cut; the flattened text is what a consumer sees.
             return reader.richString();
         case BRT.CellIsst:
             return sharedStrings[reader.u32()] ?? '';
         default:
-            // BrtCellBlank: formatted but empty. The style is already applied; the value is genuinely none.
             return null;
     }
 }
-// A number stored under a date format is a date serial — surface it as a Date so a date read from an
-// `.xlsb` is the same value the `.xlsx` twin yields, not a bare number.
 function asNumberOrDate(value, numFmt) {
     return numFmt !== undefined && isDateFormat(numFmt) ? serialToDate(value) : value;
 }
-// `BrtRowHdr` ([MS-XLSB] 2.4.770): the row index, its default format, its height, and a byte of
-// layout flags. Returns the open row (one-based) and the style index its cells inherit.
 function applyRow(reader, sheet, defaultRowHeight) {
     const index = reader.u32();
     const styleIndex = reader.u32();
     const height = reader.u16();
-    reader.skip(1); // fExtraAsc/fExtraDsc: border padding, a rendering hint the model does not carry.
+    reader.skip(1);
     const flags = reader.u8();
-    // A row beyond the grid closes the open row without opening another, so its cells are dropped too.
     if (index > MAX_ROW_INDEX)
         return { row: -1, styleIndex: -1 };
     const row = index + 1;
     const handle = sheet.getRow(row);
-    // Every row header restates a height; only a row whose height is its *own* has one to record. That
-    // is a row the user sized by hand, or one Excel auto-fitted to a taller font or wrapped text — both
-    // differ from the sheet default, which is exactly when XML emits `ht`. A row merely restating the
-    // default carries no height, so it must not read back with one.
     if ((flags & ROW_CUSTOM_HEIGHT) !== 0 || height !== defaultRowHeight) {
         handle.height = height / TWIPS_PER_POINT;
     }
@@ -244,7 +172,6 @@ function applyRow(reader, sheet, defaultRowHeight) {
         handle.outlineLevel = outlineLevel;
     if ((flags & ROW_COLLAPSED) !== 0)
         handle.collapsed = true;
-    // The row's format applies only when it says so, mirroring XML's `customFormat="1"` gate.
     return { row, styleIndex: (flags & ROW_CUSTOM_FORMAT) !== 0 ? styleIndex : -1 };
 }
 const TWIPS_PER_POINT = 20;
@@ -253,7 +180,6 @@ const ROW_COLLAPSED = 0b0000_1000;
 const ROW_HIDDEN = 0b0001_0000;
 const ROW_CUSTOM_HEIGHT = 0b0010_0000;
 const ROW_CUSTOM_FORMAT = 0b0100_0000;
-// `BrtColInfo` ([MS-XLSB] 2.4.319): one record per run of identically-sized columns.
 function applyColumn(reader, sheet, xfStyles, columnStyle) {
     const first = reader.u32();
     const last = reader.u32();
@@ -262,24 +188,16 @@ function applyColumn(reader, sheet, xfStyles, columnStyle) {
     const flags = reader.u16();
     const style = styleIndex > 0 ? xfStyles[styleIndex] : undefined;
     const outlineLevel = (flags >> COLUMN_OUTLINE_SHIFT) & 0b111;
-    // A run can name every column to the right of the data; materialising all 16 384 of them would
-    // turn a two-column sheet into a 16 384-entry model, so a run is only applied where it carries
-    // something a default column does not.
     if (style === undefined &&
         outlineLevel === 0 &&
         (flags & (COLUMN_HIDDEN | COLUMN_CUSTOM_WIDTH | COLUMN_COLLAPSED)) === 0) {
         return;
     }
-    // The loop bound comes from the file, so it is clamped to the grid before it is one: an unclamped
-    // run declaring four billion columns is a denial of service, not a wide sheet.
     const lastInGrid = Math.min(last, MAX_COLUMN_INDEX);
     if (first > lastInGrid)
         return;
     for (let index = first; index <= lastInGrid; index++) {
         const column = sheet.getColumn(index + 1);
-        // The stored width is taken whether or not the file marks it user-set, matching the XML reader:
-        // a `<col>`/`BrtColInfo` exists only for a column that differs from the sheet default in *some*
-        // way, and it always states the width that column actually has.
         column.width = width / COLUMN_WIDTH_UNITS;
         if ((flags & COLUMN_HIDDEN) !== 0)
             column.hidden = true;
@@ -293,7 +211,6 @@ function applyColumn(reader, sheet, xfStyles, columnStyle) {
             columnStyle.set(index, styleIndex);
     }
 }
-// Column width is stored in 1/256ths of a character, where XML states the character count directly.
 const COLUMN_WIDTH_UNITS = 256;
 const COLUMN_HIDDEN = 0b0000_0001;
 const COLUMN_CUSTOM_WIDTH = 0b0000_0010;

package/dist/io/xlsb/read.js

@@ -1,18 +1,3 @@
-// The buffered `.xlsb` reader: a binary OPC package in, a {@link Workbook} model out.
-//
-// An `.xlsb` is the *same* OPC/ZIP container and the *same* relationship graph as an `.xlsx` — the
-// workbook part points at its sheets, its shared strings, and its style sheet through ordinary
-// `.rels` XML. Only the office-document parts differ: `xl/workbook.bin`, `xl/worksheets/sheetN.bin`
-// and friends are BIFF12 record streams instead of XML. So this module reuses the container layer
-// wholesale (`../opc/`, the bounded inflater) and swaps only the part parsers, which is
-// exactly the "two codecs over one model" shape the format note argues for.
-//
-// The model produced is the one `readXlsx` produces, not a parallel one: the same `Workbook`, the
-// same `XfStyle` table, the same cells. That is what lets a caller convert between the two forms —
-// and what the corpus asserts, by reading a workbook Excel saved in both forms and comparing.
-//
-// Not yet decoded (each its own slice of work, none silently wrong): rich-text runs, tables, pivots,
-// and conditional formatting.
 import { unmangleFunctions } from '../../core/formula.js';
 import { INTERNAL } from '../../core/internal.js';
 import { Workbook } from '../../core/workbook.js';
@@ -27,26 +12,11 @@ import { parseStyleTable } from './read-styles.js';
 import { parseWorksheet } from './read-worksheet.js';
 import { readRecords } from './record-stream.js';
 import { BRT } from './record-types.js';
-/** The office-document part every `.xlsb` package is entered through. */
 export const XLSB_WORKBOOK_PART = 'xl/workbook.bin';
-/**
- * Read an `.xlsb` (binary BIFF12) package into a {@link Workbook}.
- *
- * @throws {UnsupportedFormatError} if the input is not an `.xlsb` package — a legacy `.xls`
- *   (`.format === 'xls'`), an XML `.xlsx` or unrecognised blob (`'unknown'`).
- * @throws {XlsbParseError} if a binary part is malformed.
- * @throws {PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
- *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
- */
 export function readXlsb(data, options = {}) {
     const cap = options.maxUncompressedBytes ?? DEFAULT_MAX_UNCOMPRESSED;
     return readXlsbPackage(inflateSpreadsheetPackage(data, cap));
 }
-/**
- * Build the model from an already-inflated `.xlsb` package. Separate from {@link readXlsb} so the
- * `.xlsx` reader can hand over a package it has already inflated and classified, rather than
- * inflating the same bytes twice.
- */
 export function readXlsbPackage(files) {
     const { partText, partBytes } = packageAccessors(files);
     const workbookPart = partBytes(XLSB_WORKBOOK_PART);
@@ -57,12 +27,8 @@ export function readXlsbPackage(files) {
     const sharedStrings = parseSharedStrings(partBytes('xl/sharedStrings.bin'));
     const { cellXfs, namedStyles, defaultFont } = parseStyleTable(partBytes('xl/styles.bin'));
     const workbook = new Workbook();
-    // As in the XML reader, the named-style layer is restored only when a file declares more than the
-    // Normal default, so an ordinary workbook keeps an empty table and writes just that default back.
     if (namedStyles.length > 1)
         workbook[INTERNAL].restoreNamedStyles(namedStyles);
-    // As in the XML reader, font 0 is the workbook's declared default and must survive a re-write; an
-    // assumed Calibri in its place changes every empty cell and every character-unit column width.
     workbook[INTERNAL].restoreDefaultFont(defaultFont);
     const declaration = readWorkbookPart(workbookPart);
     const scope = {
@@ -82,17 +48,12 @@ export function readXlsbPackage(files) {
         workbook.defineName(defined);
     return workbook;
 }
-// One pass over `xl/workbook.bin`, gathering everything the rest of the read depends on: the sheet
-// bundle, the externals block a 3-D reference resolves through, and the defined names.
 function readWorkbookPart(part) {
     const sheets = [];
     const names = [];
     let externSheets = [];
     let inBundle = false;
     let inExternals = false;
-    // A workbook with no external links declares exactly one supporting book: itself. Rather than
-    // enumerate every record type that could open another — and risk miscounting into a *wrong* sheet
-    // name — anything else inside the externals block disqualifies the whole table.
     let supportingBooks = 0;
     let selfSupBook;
     for (const record of readRecords(part)) {
@@ -122,21 +83,17 @@ function readWorkbookPart(part) {
         selfSupBook: supportingBooks === 1 ? selfSupBook : undefined,
     };
 }
-// `BrtBundleSh` ([MS-XLSB] 2.4.303) — the binary spelling of `<sheet name state r:id/>`.
 function readSheet(data) {
     const reader = new RecordReader(data);
     const state = SHEET_STATES[reader.u32()] ?? 'visible';
-    reader.skip(4); // iTabId: the sheet's stable id, which the model assigns itself.
+    reader.skip(4);
     const relId = reader.nullableWideString();
     return { name: reader.wideString(), relId, state };
 }
-// `BrtExternSheet` ([MS-XLSB] 2.4.677): the `Xti` table every 3-D reference indexes into.
 function readExternSheets(data) {
     const reader = new RecordReader(data);
     const count = reader.u32();
     const entries = [];
-    // Each entry is three 4-byte fields; checking the count against what the record holds keeps a forged
-    // one from driving the loop rather than the record's own length.
     if (count * XTI_BYTES > reader.remaining)
         return entries;
     for (let index = 0; index < count; index++) {
@@ -145,12 +102,10 @@ function readExternSheets(data) {
     return entries;
 }
 const XTI_BYTES = 12;
-// `BrtName` ([MS-XLSB] 2.4.673). The target is left undecoded here: it is a token stream that may cite
-// a sheet by index, and the sheet bundle is not necessarily complete at this point in the stream.
 function readName(data) {
     const reader = new RecordReader(data);
     const flags = reader.u32();
-    reader.skip(1); // chKey: the Alt-key shortcut a macro name can carry.
+    reader.skip(1);
     const itab = reader.u32();
     const name = reader.wideString();
     const rgce = reader.bytes(reader.u32());
@@ -163,19 +118,8 @@ function readName(data) {
         rgcb,
     };
 }
-// `itab` for a workbook-global name; any other value is a zero-based sheet index.
 const GLOBAL_NAME_SCOPE = 0xffffffff;
-// `fFunc`: the name registers something callable rather than a range.
 const NAME_IS_FUNCTION = 0x00000002;
-// The workbook's defined names, as the model holds them.
-//
-// Two kinds of `BrtName` are dropped, both because the XML form does not persist them either — so
-// carrying them through would make the two readings of one workbook disagree. A *function* name is
-// Excel's registration of a callable (every post-2007 function gets one, `_xlfn.TEXTJOIN` and
-// friends); its target is the placeholder `#NAME?`, not a range. And `_xlnm._FilterDatabase` is the
-// built-in Excel derives from a sheet's autofilter, which the model reconstructs from the autofilter
-// itself. A name whose target uses a token this reader cannot decode is dropped too, rather than
-// surfaced with a target that is a guess.
 function definedNames(declaration, scope) {
     const names = [];
     for (const declared of declaration.names) {
@@ -188,12 +132,10 @@ function definedNames(declaration, scope) {
         names.push({
             name: declared.name,
             ...(sheet === undefined ? {} : { scope: sheet }),
-            // Stripped back to the readable form, the same normalisation the XML reader applies.
             refersTo: unmangleFunctions(refersTo),
         });
     }
     return names;
 }
 const FILTER_DATABASE_NAME = '_xlnm._FilterDatabase';
-// `hsState` ([MS-XLSB] 2.4.303), indexed by its stored value.
 const SHEET_STATES = ['visible', 'hidden', 'veryHidden'];

package/dist/io/xlsb/record-stream.js

@@ -1,24 +1,4 @@
-// The BIFF12 record framing every `.bin` part of an `.xlsb` package is built from ([MS-XLSB] 2.1.4).
-//
-// A part is a bare concatenation of records — no header, no index, no terminator — each framed as a
-// variable-length type, a variable-length size, and that many payload bytes. Both prefixes are
-// 7-bits-per-byte with the high bit meaning "one more byte follows": the type is 1–2 bytes (so the
-// single-byte space is reserved for the hot records — a cell is one byte of framing), the size is 1–4.
-//
-// **This is the reader's hostile-input frontier.** The declared size is attacker-controlled, so it is
-// never allowed to drive an allocation: a record's payload is handed out as a `subarray` *view* onto
-// the part the inflate bound already materialised and capped, and a size that would run past the end
-// of the part is rejected outright rather than clamped. A lying length therefore costs nothing and
-// fails closed, and the whole stream's memory is exactly the part's own bytes.
 import { XlsbParseError } from './errors.js';
-/**
- * Decode a `.bin` part into its record sequence, in order.
- *
- * Lazy: a caller that stops early (having found what it needs) never frames the rest of the part.
- *
- * @throws {XlsbParseError} if a record header is truncated or a record's declared size runs past the
- *   end of the part.
- */
 export function* readRecords(part) {
     let offset = 0;
     while (offset < part.length) {
@@ -26,8 +6,6 @@ export function* readRecords(part) {
         let type = lowType & 0x7f;
         if ((lowType & 0x80) !== 0)
             type |= (byteAt(part, offset++) & 0x7f) << 7;
-        // Up to four size bytes, least-significant seven bits first. The fourth byte's continuation bit
-        // is specified as ignored, which the fixed bound expresses: the loop simply stops there.
         let size = 0;
         for (let index = 0; index < 4; index++) {
             const piece = byteAt(part, offset++);
@@ -35,9 +13,6 @@ export function* readRecords(part) {
             if ((piece & 0x80) === 0)
                 break;
         }
-        // The one check that makes a forged size harmless: compare it against what the part *actually*
-        // holds, before anything is handed out. `part.length - offset` cannot be negative here — byteAt
-        // has already proven every header byte was in range.
         if (size > part.length - offset) {
             throw new XlsbParseError(`BIFF12 record ${type} declares ${size} bytes but only ${part.length - offset} remain in the part`);
         }
@@ -45,9 +20,6 @@ export function* readRecords(part) {
         offset += size;
     }
 }
-// Every header byte goes through here, so a part that ends mid-header fails closed rather than
-// folding `undefined` into the arithmetic (which `noUncheckedIndexedAccess` would otherwise let
-// through as a silent NaN-shaped type or size).
 function byteAt(part, index) {
     const value = part[index];
     if (value === undefined)

package/dist/io/xlsb/record-types.js

@@ -1,15 +1,4 @@
-// The BIFF12 record types this reader consumes, by their [MS-XLSB] "Record Enumeration" (section 2.3)
-// numbers. Named constants rather than magic numbers at the switch sites: a record number carries no
-// hint of what it is, so `BRT.CellRk` is the difference between a readable parser and a table of
-// unexplained integers.
-//
-// Deliberately partial. [MS-XLSB] enumerates ~760 record types; listing the ones we do not decode
-// would claim coverage we do not have. A record whose type is absent here is skipped by the parsers,
-// which is the correct behaviour for a forward-compatible reader — the format grows, and an unknown
-// record is always safely framed (its size is in the stream) even when its meaning is not known.
-/** BIFF12 record numbers, grouped by the part whose stream they appear in. */
 export const BRT = {
-    // Cell table (worksheet part). The single-byte record space — these are the hot path.
     RowHdr: 0,
     CellBlank: 1,
     CellRk: 2,
@@ -25,13 +14,9 @@ export const BRT = {
     CellRString: 62,
     ColInfo: 60,
     MergeCell: 176,
-    // Shared-string table.
     SSTItem: 19,
     BeginSst: 159,
     EndSst: 160,
-    // Style sheet: each collection is a Begin/End pair around its entries, and `XF` appears inside two
-    // of them (the named-style layer and the direct-format layer), so the style parser tracks which
-    // collection it is in rather than keying on the record number alone.
     Fmt: 44,
     Font: 43,
     Fill: 45,
@@ -52,18 +37,14 @@ export const BRT = {
     EndCellXFs: 618,
     BeginStyles: 619,
     EndStyles: 620,
-    // Workbook part.
     BundleSh: 156,
     BeginBundleShs: 143,
     EndBundleShs: 144,
     Name: 39,
-    // The externals block: which workbooks a formula can reach, and which sheets of them each `ixti` a
-    // 3-D reference carries names. `SupSelf` declares a supporting book that is *this* workbook.
     BeginExternals: 353,
     EndExternals: 354,
     SupSelf: 357,
     ExternSheet: 362,
-    // Worksheet structure.
     WsProp: 147,
     WsDim: 148,
     WsFmtInfo: 485,

package/dist/io/xlsx/cell-accumulator.js

@@ -1,9 +1,3 @@
-// Cell-gathering state machine for the worksheet-body reader. It owns the still-textual pieces of the
-// one `<c>` currently being read — its address/type/style, formula, cached value, inline text, and
-// rich-text runs — plus the shared-formula master map that spans the whole sheet. Each `<c>` resets
-// the per-cell state on {@link beginCell} and commits it on {@link finalize}, so this class is the
-// single owner of "what has this cell gathered so far" — to a cell what {@link RunAccumulator} is to a
-// rich string. Value *decoding* stays in `cell-value.ts`; this class only gathers the raw pieces.
 import { decodeAddress, encodeAddress } from '../../core/address.js';
 import { translateFormula, unmangleFunctions } from '../../core/formula.js';
 import { boolPresent } from '../../xml/xml-read.js';
@@ -17,8 +11,6 @@ export class CellAccumulator {
     #col = -1;
     #row = -1;
     #formula = '';
-    // Shared-formula bookkeeping. A master `<f t="shared" ref si>TEXT</f>` seeds the group; every clone
-    // `<f t="shared" si/>` in the sheet references it by `si` and carries no text of its own.
     #formulaShared = false;
     #formulaSi = -1;
     #sharedClone = false;
@@ -28,27 +20,19 @@ export class CellAccumulator {
     #hasFormula = false;
     #hasValue = false;
     #runs = new RunAccumulator();
-    // Masters always precede their clones (Excel keeps the master top-left), so a clone resolves against
-    // a map filled as the sheet streams: the master's formula translated to the clone's position.
     #masters = new Map();
-    /** This cell's `<c r>` address (`"B3"`), or '' when it carried none. */
     get ref() {
         return this.#ref;
     }
-    /** This cell's own `<c s>` style index, or -1 when it carries none. */
     get styleIndex() {
         return this.#style;
     }
-    /** This cell's 1-based column, or -1 when its address was absent or unparseable. */
     get col() {
         return this.#col;
     }
-    /** The rich-text run accumulator, driven by the surrounding parser's `<r>`/`<rPr>` handling. */
     get runs() {
         return this.#runs;
     }
-    // Begin a new `<c>`: record its address/type/style and clear every per-cell gathered field so the
-    // last cell's formula, value, runs, or shared/data-table declaration cannot bleed into this one.
     beginCell(attrs) {
         this.#ref = attrs.r ?? '';
         this.#type = attrs.t ?? '';
@@ -66,9 +50,6 @@ export class CellAccumulator {
         this.#sharedClone = false;
         this.#dataTable = null;
     }
-    // Begin an `<f>`: record its shared-formula grouping and any data-table declaration. A self-closing
-    // `<f t="shared" si/>` is a clone — it fires no close and carries no text — so mark it here to
-    // resolve against its master when the cell finalises.
     beginFormula(attrs, selfClosing) {
         this.#formulaShared = attrs.t === 'shared';
         this.#formulaSi = attrs.si !== undefined ? Number(attrs.si) : -1;
@@ -92,22 +73,14 @@ export class CellAccumulator {
         this.#valueText = text;
         this.#hasValue = true;
     }
-    // Begin an `<is>`: clear the inline string and its runs so a rich value built from a previous cell's
-    // runs keeps its own array.
     beginInlineString() {
         this.#inlineText = '';
         this.#runs.reset();
     }
-    // Route a `<t>`'s text: to the open run when one is active, otherwise to the inline string when the
-    // parser is inside an `<is>`. A run takes precedence — a run is also inside the inline string.
     appendText(text, inInlineString) {
         if (!this.#runs.appendText(text) && inInlineString)
             this.#inlineText += text;
     }
-    // Commit the gathered cell to the sheet with its already-resolved style (the caller applies the
-    // cell → row → column inheritance order). A data-table cell surfaces its declaration; a shared-formula
-    // master seeds the group before finalising, and a clone resolves to the master translated to its own
-    // position. Everything else decodes as an ordinary `<c>` payload. An address-less cell is a no-op.
     finalize(sheet, sharedStrings, style) {
         if (this.#ref === '')
             return;
@@ -138,7 +111,6 @@ export class CellAccumulator {
                 const value = {
                     sharedFormula: encodeAddress(master.col, master.row),
                     formula: unmangleFunctions(translated),
-                    // A clone's cached result honours the cell's date format the same way a plain formula's does.
                     ...(this.#hasValue
                         ? { result: decodeFormulaResult(this.#type, this.#valueText, style?.numFmt) }
                         : {}),
@@ -153,10 +125,6 @@ export class CellAccumulator {
         applyXfToCell(cell, style);
         cell.value = this.decode(sharedStrings, style);
     }
-    // Decode the gathered pieces into a plain cell value, resolving the shared pool and date formats but
-    // NOT the shared-formula / data-table declarations {@link finalize} handles. This is what a data
-    // read (the streaming reader) wants: the cell's own value, with a shared-formula clone surfacing its
-    // cached result rather than a translated formula it will not evaluate.
     decode(sharedStrings, style) {
         const raw = {
             type: this.#type,

package/dist/io/xlsx/cell-value.js

@@ -1,34 +1,17 @@
-// Decoding a worksheet cell's on-disk `<c>` payload into a model {@link CellValue}.
-//
-// This is the single value-decoding surface both readers share: the buffered reader
-// (`./read.ts`) and the streaming row reader (`./read-rows.ts`). Keeping it in one place is
-// what guarantees a cell read one row at a time decodes identically to the same cell read as
-// part of a whole workbook — a divergence here would be a silent data bug in exactly one path.
 import { isDateFormat, serialToDate } from '../../core/date.js';
 import { unmangleFunctions } from '../../core/formula.js';
 import { isErrorCode, } from '../../core/value.js';
 import { boolStrict } from '../../xml/xml-read.js';
-/**
- * Decode a gathered cell into its model value. A formula cell becomes a `{formula, result?}`
- * object (the on-disk `_xlfn.`/`_xlpm.` mangling stripped back to the readable name); a plain
- * numeric cell under a date number format becomes a {@link Date}; everything else decodes by its
- * `t` type. `numFmt` is the cell's resolved number-format code, used only for date detection.
- */
 export function decodeCellContent(raw, sharedStrings, numFmt) {
     if (raw.hasFormula) {
         const stored = unmangleFunctions(raw.formula);
         const result = raw.hasValue ? decodeFormulaResult(raw.type, raw.valueText, numFmt) : undefined;
         return result === undefined ? { formula: stored } : { formula: stored, result };
     }
-    // An inline string built from `<r>` runs is rich text — surface its runs rather than flattening
-    // them to the concatenated `inlineText` a plain string would decode to.
     if (raw.type === 'inlineStr' && raw.richTextRuns !== undefined && raw.richTextRuns.length > 0) {
         return { richText: raw.richTextRuns };
     }
     const value = decodeValue(raw.type, raw.valueText, raw.inlineText, raw.hasValue, sharedStrings);
-    // A number stored under a date format is a date serial — surface it as a Date so a written
-    // date round-trips as a date, not a bare number. Only plain numeric cells qualify; a string,
-    // boolean, or formula result under a date format keeps its own kind.
     return typeof value === 'number' && numFmt !== undefined && isDateFormat(numFmt)
         ? serialToDate(value)
         : value;
@@ -40,13 +23,8 @@ function decodeValue(type, valueText, inlineText, hasValue, sharedStrings) {
         case 'str':
             return valueText;
         case 'd':
-            // A Strict-mode (ISO/IEC 29500 Strict) date cell stores an ISO 8601 value directly, not a
-            // serial. Parse it literally — an ISO date is UTC — so it reads as the date it states rather
-            // than a 1900-epoch serial the transitional decoder would fabricate from the text.
             return valueText === '' ? null : new Date(valueText);
         case 's': {
-            // A `t="s"` cell indexes the shared pool; the entry is a plain string or, when Excel pooled a
-            // rich value, a {@link RichTextValue} whose runs surface here rather than being flattened.
             const index = Number(valueText);
             return Number.isInteger(index) ? (sharedStrings[index] ?? '') : '';
         }
@@ -58,19 +36,12 @@ function decodeValue(type, valueText, inlineText, hasValue, sharedStrings) {
             return hasValue ? Number(valueText) : null;
     }
 }
-/** Decode a formula's cached `<v>` result by its `t` type, coercing a numeric result under a date
- * `numFmt` to a {@link Date} exactly as a bare numeric cell is — so a date-valued formula result
- * (e.g. `TODAY()`) reads back as a Date, not a serial. Shared by the buffered reader's shared-formula
- * clone resolution, which caches a result the same way a plain formula cell does. */
 export function decodeFormulaResult(type, valueText, numFmt) {
     const result = decodeResult(type, valueText);
     return typeof result === 'number' && numFmt !== undefined && isDateFormat(numFmt)
         ? serialToDate(result)
         : result;
 }
-// The formula-result subset of `decodeValue`: a cached result is only ever a string, boolean,
-// error, or number — never a shared-string index, inline string, or Strict-mode date — so this
-// handles just those cases rather than the full cell-value grammar.
 function decodeResult(type, valueText) {
     switch (type) {
         case 'str':