@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/io/opc/read-opc.js

@@ -1,11 +1,6 @@
-// The OPC (Open Packaging Conventions) layer of the reader: resolving relationship targets to part
-// paths, reading a part's `.rels`, resolving a part's declared content type, and walking the transitive
-// closure of parts a preserved reference reaches. Every helper here is pure over the inflated package —
-// it takes part text/bytes accessors and returns paths or records, touching no Workbook model.
 import { strFromU8 } from 'fflate';
 import { openElements } from '../../xml/xml-read.js';
 import { extensionOf, relsPathFor } from './part-paths.js';
-// Bind the part-lookup accessors over an inflated package (a part-path → bytes map).
 export function packageAccessors(files) {
     return {
         partText(path) {
@@ -15,20 +10,12 @@ export function packageAccessors(files) {
         partBytes: (path) => files[path],
     };
 }
-// Whether a <Relationship> carries a resolvable Target and its Type ends with `/<suffix>` (a
-// local-name match, so a namespaced or oddly-cased type still resolves). The type guard lets a
-// matching relationship's Target be read without a further presence check.
 function matchesType(attrs, suffix) {
     return (attrs.Type !== undefined && attrs.Target !== undefined && attrs.Type.endsWith(`/${suffix}`));
 }
-// The Target of the first relationship whose Type ends with `/<suffix>`, or undefined when none is
-// declared — for a single expected reference, where the plural form below would over-gather.
 export function relationshipTargetByType(xml, suffix) {
     return relationshipTargetsByType(xml, suffix)[0];
 }
-// Every Target whose Type ends with `/<suffix>`, in declaration order — for a part class a sheet may
-// reference more than once (a sheet can own several tables), where the singular helper's first-match
-// would miss all but one.
 export function relationshipTargetsByType(xml, suffix) {
     const targets = [];
     for (const { attrs } of openElements(xml, 'Relationship')) {
@@ -37,10 +24,6 @@ export function relationshipTargetsByType(xml, suffix) {
     }
     return targets;
 }
-// The package part a sheet reaches through the first relationship of a given type, already resolved
-// relative to the sheet — the "load the sheet's rels, find the one relationship of this type, resolve
-// its target" preamble every single-part sheet lookup (notes, printer settings, drawing, background)
-// opens with. undefined when the sheet has no rels part or declares no such relationship.
 export function sheetRelTarget(sheetPath, partText, type) {
     const relsXml = partText(relsPathFor(sheetPath));
     if (relsXml === undefined)
@@ -48,8 +31,6 @@ export function sheetRelTarget(sheetPath, partText, type) {
     const target = relationshipTargetByType(relsXml, type);
     return target === undefined ? undefined : resolveRelativePart(sheetPath, target);
 }
-// Resolve a relationship target (relative to the referencing part's directory, or absolute from the
-// package root) into a package part path, collapsing `.`/`..` segments.
 export function resolveRelativePart(basePart, target) {
     if (target.startsWith('/'))
         return target.slice(1);
@@ -65,8 +46,6 @@ export function resolveRelativePart(basePart, target) {
     }
     return out.join('/');
 }
-// A workbook relationship target is relative to the `xl/` directory (`worksheets/sheet1.xml`)
-// or absolute from the package root (`/xl/worksheets/sheet1.xml`); normalise both to a part path.
 export function resolveWorkbookPart(target) {
     if (target.startsWith('/'))
         return target.slice(1);
@@ -95,9 +74,6 @@ export function parseRelationshipRecords(xml) {
     }
     return records;
 }
-// Resolve a package part path to its declared content type the way OPC does: an `<Override>` naming
-// the exact part wins, else the `<Default>` registered for the part's extension. An unknown part
-// falls back to the generic binary type so re-declaring it never emits an empty content type.
 export function contentTypeResolver(contentTypesXml) {
     const overrides = new Map();
     const defaults = new Map();
@@ -115,11 +91,6 @@ export function contentTypeResolver(contentTypesXml) {
         defaults.get(extensionOf(path).toLowerCase()) ??
         'application/octet-stream';
 }
-// Gather the transitive closure of package parts reachable from an entry part — the part itself, then
-// every internal part its relationships target, breadth-first — each with its raw bytes, content type,
-// and (internal) relationships. Returns undefined when the entry part is absent (a dangling reference
-// preserves nothing). A `visited` set dedupes shared parts and bounds the walk to the (finite,
-// inflate-capped) package, so a maliciously self-referential rels graph cannot loop.
 export function capturePartClosure(entryPath, partText, partBytes, contentTypeOf) {
     const parts = [];
     const visited = new Set();
@@ -137,8 +108,6 @@ export function capturePartClosure(entryPath, partText, partBytes, contentTypeOf
         if (relsXml !== undefined) {
             for (const rel of parseRelationshipRecords(relsXml)) {
                 if (rel.external) {
-                    // A linked workbook lives outside the package: keep the wiring verbatim (an externalLink
-                    // part's pointer to its source), but do not walk into it — there is no package part to visit.
                     rels.push({ id: rel.id, type: rel.type, targetPath: rel.target, external: true });
                     continue;
                 }

package/dist/io/opc/read-options.js

@@ -1,7 +1 @@
-// The one knob every reader takes, declared apart from any of them.
-//
-// `readXlsx`, `readXlsb`, and the row streamer all inflate the same OPC container under the same
-// bound, so the option bag belongs to none of them individually — and a reader that dispatches to
-// another (the `.xlsx` entry point hands a binary package to the `.xlsb` codec) cannot import it from
-// its peer without the two modules importing each other.
 export const DEFAULT_MAX_UNCOMPRESSED = 512 * 1024 * 1024;

package/dist/io/opc/rels.js

@@ -1,28 +1,15 @@
-// The write side of the relationship graph: a single `<Relationship>` element and the `.rels` part
-// envelope that wraps a set of them. Pure OPC — a `.rels` part has the same shape whatever the parts
-// it wires together are spelled in, so this is stated once here rather than inside a codec.
-//
-// The reader's half of the same graph (resolving targets, walking a part closure) is in `read-opc.ts`.
 import { escapeAttr, XML_DECLARATION } from '../../xml/xml.js';
 import { PKG_RELS_NS } from './namespaces.js';
-// A single `<Relationship>`. An `external` target lives outside the package (a hyperlink URL), so the
-// element carries `TargetMode="External"`; a package-internal target (the default) omits it. The caller
-// escapes the target when it is not a writer-controlled package path.
 export function relationship(id, type, target, options) {
     const mode = options?.external ? ' TargetMode="External"' : '';
     return `<Relationship Id="${id}" Type="${type}" Target="${target}"${mode}/>`;
 }
-// Wrap a part's `<Relationship>` elements in the OPC `.rels` envelope (XML declaration + the namespaced
-// `<Relationships>` root). Every `.rels` part the writer emits shares this envelope; only the elements
-// inside differ, so each caller builds its own list of {@link relationship} strings and hands them here.
 export function relationshipsPart(relationships) {
     return `${XML_DECLARATION}<Relationships xmlns="${PKG_RELS_NS}">${relationships.join('')}</Relationships>`;
 }
 export function preservedRelsXml(rels) {
     return relationshipsPart(rels.map((rel) => relationship(rel.id, rel.type, escapeAttr(rel.target), rel.external ? { external: true } : {})));
 }
-// A `.rels` part for a generated part chain (pivot table → cache definition → cache records). Targets
-// are writer-controlled package paths, so no attribute escaping is needed.
 export function relsPartXml(rels) {
     return relationshipsPart(rels.map((rel) => relationship(rel.id, rel.type, rel.target)));
 }

package/dist/io/opc/sniff-format.js

@@ -1,31 +1,7 @@
-// Front of the read pipe: format detection, the inflate bound both readers share, and the typed
-// rejection of everything that is neither an `.xlsx` nor an `.xlsb`.
-//
-// The reader's first job on an arbitrary blob is to reject what it cannot read with a clear, typed
-// error rather than a raw fflate crash. A cheap magic-byte sniff runs *before* the zip layer (so a
-// legacy `.xls` compound file or non-ZIP garbage fails fast, before fflate throws its opaque "end of
-// central directory" error — which can also leak an absolute path from below), and a malformed ZIP is
-// translated after it.
-//
-// The two outcomes are deliberately different types, because they answer different questions. A blob
-// the sniff rejects is the *wrong kind of thing* — {@link UnsupportedFormatError}, branchable on
-// `.format`. A `PK`-headed blob the zip layer then chokes on is the right kind of thing we cannot
-// unpack — {@link PackageReadError}. Whichever it is, the message states the check that actually ran,
-// and callers branch on the type, never on message text.
-//
-// The `.xlsx` and `.xlsb` serialisations share this whole layer — same container, same bound, same
-// rejections — so it is stated once here and neither reader owns it.
 import { PackageReadError, UnsupportedFormatError } from './errors.js';
 import { inflatePackage } from './inflate.js';
-// The OLE2 / Compound File Binary signature ([MS-CFB] 2.2) that opens every legacy `.xls` (and the
-// `.doc`/`.ppt` siblings). `src/vba/cfb.ts` reads this same magic for `vbaProject.bin`; here we need
-// only recognise it, not parse the container.
 const CFB_MAGIC = Uint8Array.of(0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1);
-// The ZIP local-file-header signature (`PK\x03\x04`) that opens every OPC package — `.xlsx`, `.xlsb`,
-// and the rest. An empty or spanned archive starts with a different `PK` marker, but a real workbook
-// package always leads with a local file header.
 const ZIP_LOCAL_FILE_MAGIC = Uint8Array.of(0x50, 0x4b, 0x03, 0x04);
-/** Classify a blob's container by its leading magic bytes alone — no allocation, no inflation. */
 export function sniffContainer(data) {
     if (startsWith(data, CFB_MAGIC))
         return 'cfb';
@@ -42,24 +18,10 @@ function startsWith(data, magic) {
     }
     return true;
 }
-/**
- * Inflate a spreadsheet package (`.xlsx` or `.xlsb` — the container is the same), translating input
- * that is neither into a typed error before or instead of a raw zip failure:
- * - a legacy `.xls` (CFB) blob → {@link UnsupportedFormatError} `'xls'`, caught by the magic sniff so
- *   fflate never runs on it;
- * - a non-ZIP blob → {@link UnsupportedFormatError} `'unknown'`, likewise caught before inflation;
- * - a `PK`-headed blob that fflate then rejects as malformed → {@link PackageReadError}, with the
- *   underlying zip message discarded so no internals (or path) leak.
- *
- * The bounded-inflation guard (a probable zip bomb) already raises {@link PackageReadError} with its
- * own informative message, and is re-thrown unchanged.
- */
 export function inflateSpreadsheetPackage(data, cap) {
     const container = sniffContainer(data);
     if (container === 'cfb')
         throw new UnsupportedFormatError('xls');
-    // Not the default message: nothing here has looked for a workbook part, and saying so would point
-    // an investigation a layer past the one that actually refused.
     if (container === 'other') {
         throw new UnsupportedFormatError('unknown', 'not a valid .xlsx package: the input is not a ZIP');
     }
@@ -67,23 +29,11 @@ export function inflateSpreadsheetPackage(data, cap) {
         return inflatePackage(data, cap);
     }
     catch (err) {
-        // The bomb guard already throws the right type with a better message — surface it. Anything else
-        // is fflate reporting a malformed archive: same classification (a ZIP we cannot unpack), but its
-        // raw text is replaced wholesale rather than wrapped or attached as `cause`, because it comes from
-        // a layer whose strings may name internals — or an absolute path — that must not reach a caller.
         if (err instanceof PackageReadError)
             throw err;
         throw new PackageReadError('not a readable .xlsx package: the ZIP container is corrupt or truncated and could not be inflated');
     }
 }
-/**
- * The typed error for an inflated package that carries no `xl/workbook.xml`: a `.xlsb` if its binary
- * `xl/workbook.bin` office document is present, otherwise an unrecognised (non-workbook) ZIP.
- *
- * The `.xlsb` branch takes the caller's own explanation, because whether a binary workbook is
- * readable now depends on *which* entry point was asked: `readXlsx` reads one, the row streamer
- * cannot yet. A single baked-in "not supported" message would be wrong for one of them.
- */
 export function unsupportedWorkbookPart(partText, xlsbMessage) {
     if (partText('xl/workbook.bin') !== undefined) {
         return new UnsupportedFormatError('xlsb', xlsbMessage);

package/dist/io/style/xf-style.js

@@ -1,17 +1,5 @@
-// The resolved cell-format table both codecs read into: what an xf *is* once its id-indirection is
-// flattened, which of the two number-format tables an id resolves against, and what applying an xf to
-// a cell means.
-//
-// None of that is a property of how the style table is spelled — `xl/styles.xml` and `xl/styles.bin`
-// state the same model in XML and BIFF12 records — so it is stated once here, above both codecs. The
-// XML parsing lives in `../xlsx/read-styles.ts`, the record parsing in `../xlsb/read-styles.ts`, and
-// each hands back the same {@link StyleTable}.
 import { applyCellStyle } from '../../core/cell.js';
 import { NAMED_STYLE_ID } from '../../core/internal.js';
-// ECMA-376 reserves numFmt ids below 164 for formats every consumer knows implicitly, so a
-// foreign file may name one with no <numFmt> entry. This maps the standard ids to their
-// codes; id 0 (General) and any unknown id resolve to no format. The writer never emits
-// these — it always defines a custom id — but reading them keeps foreign files faithful.
 const BUILTIN_NUMFMTS = new Map([
     [1, '0'],
     [2, '0.00'],
@@ -40,11 +28,6 @@ const BUILTIN_NUMFMTS = new Map([
     [47, 'mmss.0'],
     [48, '##0.0E+0'],
     [49, '@'],
-    // Ids 27..36 and 50..58 are reserved for locale-specific built-in East Asian date/time formats;
-    // a file authored in a CJK locale styles date cells with them and, being built-ins, emits no
-    // <numFmt>. The exact code is locale-defined — these are the representative Excel forms — but what
-    // matters for reading is that each resolves to a non-empty date/time code so the serial reads as a
-    // date rather than a bare number.
     [27, '[$-404]e/m/d'],
     [28, '[$-404]e"年"m"月"d"日"'],
     [29, '[$-404]e"年"m"月"d"日"'],
@@ -65,25 +48,11 @@ const BUILTIN_NUMFMTS = new Map([
     [57, '[$-404]yyyy"年"m"月"'],
     [58, '[$-404]m"月"d"日"'],
 ]);
-/**
- * The format code a number-format id denotes: the file's own `<numFmt>`/`BrtFmt` declaration if it
- * has one, else the built-in Excel defines for that id. Id 0 is General — the absence of a format —
- * and resolves to nothing so an ordinary cell carries no `numFmt`.
- */
 export function numFmtCodeFor(id, custom) {
     if (!Number.isInteger(id) || id === 0)
         return undefined;
     return custom.get(id) ?? BUILTIN_NUMFMTS.get(id);
 }
-/**
- * Apply a resolved xf's non-value facets to a cell — the six {@link CellStyle} facets through the
- * shared {@link applyCellStyle}, plus the two links that live on the xf itself rather than in the
- * facet tuple (`quotePrefix`, and the `xfId` pointer into the named-style layer).
- *
- * Shared by every path that commits a cell: the XML reader's ordinary and shared-formula-clone paths,
- * and the BIFF12 reader — so a styled cell keeps its look regardless of which serialisation it came
- * from, and the two cannot drift on what "applying a style" means.
- */
 export function applyXfToCell(cell, style) {
     if (style === undefined)
         return;

package/dist/io/xlsb/errors.js

@@ -1,14 +1,4 @@
 import { XlsxError } from '../../errors.js';
-/**
- * Thrown when an `.xlsb` package's binary BIFF12 content cannot be parsed — a record whose declared
- * size runs past the end of its part, a truncated record header, or a structure that does not conform
- * to [MS-XLSB].
- *
- * The record streams are hostile input (a spreadsheet library parses untrusted files), so a malformed
- * part fails closed with this error rather than crashing, hanging, or over-allocating. It is distinct
- * from {@link UnsupportedFormatError}, which reports that the *container* is not a format we read at
- * all; by the time this is raised the input has already been recognised as an `.xlsb`.
- */
 export class XlsbParseError extends XlsxError {
     name = 'XlsbParseError';
     code = 'malformed-input';

package/dist/io/xlsb/formula.js

@@ -1,47 +1,11 @@
-// Decoding a BIFF12 `Ptg` token stream back into formula text — the one place where the binary and
-// XML serialisations of a workbook are genuinely different *languages* rather than different spellings.
-//
-// An `.xlsx` stores `SUM(A1:A5)/COUNT(A1:A5)` as those nineteen characters. An `.xlsb` stores the same
-// formula as a postfix (reverse-Polish) token stream: two range operands, two calls, a divide. So the
-// decoder is a stack machine — each operand pushes its own text, each operator pops what it needs and
-// pushes the joined result, and a well-formed stream leaves exactly one string behind.
-//
-// Two things make the reconstruction exact rather than approximate:
-//
-//   - **Parentheses are stored, not inferred.** Excel emits an explicit `PtgParen` wherever the author
-//     typed one, so there is no precedence arithmetic here and no risk of `(1+2)*3` reading back as
-//     `1+2*3`. The token stream already says which is which.
-//   - **A reference names no sheet.** A 3-D reference carries an *index* into the workbook's
-//     `BrtExternSheet` table, which in turn names a span of sheets in a supporting book. Resolving
-//     that indirection — and re-quoting the sheet name the way Excel would — is what turns token
-//     `ixti=2` back into `'Odd Name'!A1`.
-//
-// **A token this decoder does not know makes the whole formula undecodable, by design.** The stream is
-// self-describing only if every token's length is known, so guessing past an unrecognised token would
-// desynchronise the parse and produce confident nonsense. Instead the decoder returns `undefined` and
-// its caller keeps what it can still trust — the cached result Excel stored beside the formula. The
-// gaps that reach that path are listed in `docs/knowledge/specs/xlsb-binary-format-output.md`.
 import { MAX_COLUMN, numberToColumn } from '../../core/address.js';
 import { quoteSheetName } from '../../core/formula.js';
 import { errorCodeFor, RecordReader } from './primitives.js';
 import { FTAB_USER_DEFINED, fixedArityFor, functionNameFor } from './ptg-functions.js';
-/**
- * Decode a `CellParsedFormula`'s token stream into formula text, in the same on-disk spelling the XML
- * form writes into `<f>` — `_xlfn.`-prefixed function names included, so the caller applies the same
- * `unmangleFunctions` normalisation to either serialisation.
- *
- * @param rgce the token stream.
- * @param rgcb the trailing extra-data block: the array constants, and the cell ranges a precomputed
- *   range token refers to. Its entries are consumed in token order.
- * @returns the formula text, or `undefined` if the stream uses a token this reader does not decode.
- * @throws {XlsbParseError} if a token runs past the end of the stream (a malformed formula).
- */
 export function decodeFormula(rgce, rgcb, scope) {
     const tokens = new RecordReader(rgce);
     const extra = new RecordReader(rgcb);
     const stack = [];
-    // Pushing `undefined` is how an undecodable token is reported without unwinding: the loop stops and
-    // the arity check below rejects the stream. It keeps every token case a plain expression.
     const push = (text) => {
         if (text === undefined)
             return false;
@@ -54,13 +18,6 @@ export function decodeFormula(rgce, rgcb, scope) {
     }
     return stack.length === 1 ? stack[0] : undefined;
 }
-/**
- * The master cell a token stream defers to, when the stream is nothing but a `PtgExp` (a shared or
- * array formula's member) or a `PtgTbl` (a data-table cell) rather than a formula of its own.
- *
- * The column lives in the extra-data block rather than the token, which is the one place BIFF12
- * splits a single reference across the two halves of a `CellParsedFormula`.
- */
 export function formulaAnchor(rgce, rgcb) {
     if (rgce.length !== 5 || (rgce[0] !== PTG.Exp && rgce[0] !== PTG.Tbl))
         return undefined;
@@ -72,7 +29,6 @@ export function formulaAnchor(rgce, rgcb) {
         return undefined;
     return { row, column: extra.u32() };
 }
-// One token: decode it, mutate the stack, and report whether the stream is still decodable.
 function step(ptg, tokens, extra, stack, scope, push) {
     const binary = BINARY_OPERATORS.get(ptg);
     if (binary !== undefined) {
@@ -94,7 +50,6 @@ function step(ptg, tokens, extra, stack, scope, push) {
             return operand !== undefined && push(`(${operand})`);
         }
         case PTG.MissArg:
-            // An omitted argument — `IF(A1>0,,1)` — is a real operand whose text is nothing at all.
             return push('');
         case PTG.Str:
             return push(quoteString(tokens.shortString()));
@@ -109,18 +64,15 @@ function step(ptg, tokens, extra, stack, scope, push) {
         case PTG.Num:
             return push(numberText(tokens.f64()));
         default:
-            // Every remaining token is an operand or call whose meaning is independent of its result class
-            // (reference, value, or array) — the class only tells the calculation engine how to coerce it.
             return ptg >= CLASSED_TOKEN_FLOOR
                 ? operand((ptg & CLASSED_TOKEN_MASK) | CLASSED_TOKEN_FLOOR, tokens, extra, stack, scope, push)
                 : false;
     }
 }
-// A class-carrying operand or call token, reduced to its base ptg.
 function operand(base, tokens, extra, stack, scope, push) {
     switch (base) {
         case PTG.Array:
-            tokens.skip(14); // A size hint the extra-data block restates; the block is the authority.
+            tokens.skip(14);
             return push(arrayConstant(extra));
         case PTG.Func: {
             const name = functionNameFor(tokens.u16());
@@ -130,8 +82,6 @@ function operand(base, tokens, extra, stack, scope, push) {
         case PTG.FuncVar:
             return variadicCall(tokens, stack, push);
         case PTG.Name: {
-            // Cited 1-based, and into the *unfiltered* name list — the placeholder names Excel registers for
-            // post-2007 functions occupy indices too, even though they are not the workbook's defined names.
             return push(scope.names[tokens.u32() - 1]);
         }
         case PTG.Ref:
@@ -161,38 +111,23 @@ function operand(base, tokens, extra, stack, scope, push) {
             tokens.skip(14);
             return push(REFERENCE_ERROR);
         case PTG.MemArea:
-            // A precomputed range: the tokens it was computed from follow inline, so the header is skipped
-            // and the walk simply continues into them. Its extra-data entry — the resulting rectangles — is
-            // a calculation shortcut with nothing to say about the text, but must still be consumed in order.
             tokens.skip(6);
             return skipExtraRanges(extra);
         default:
             return false;
     }
 }
-// `PtgAttr` ([MS-XLSB] 2.5.97.1): a family of hints the calculation engine leaves in the stream.
-// Almost all are invisible in the formula text — the jump offsets an `IF` uses to skip the branch it
-// did not take, the marker on a volatile function. The one that carries meaning is `bitSum`, Excel's
-// encoding of a single-argument `SUM`, which is a call by any other name.
 function attribute(tokens, stack, push) {
     const flags = tokens.u8();
     const data = tokens.u16();
     if ((flags & ATTR_CHOOSE) !== 0) {
-        // The one variable-length attribute: `data` counts CHOOSE's branches, each with a jump offset,
-        // plus one for the end of the call.
         tokens.skip((data + 1) * 2);
         return true;
     }
     if ((flags & ATTR_SUM) !== 0)
         return push(call('SUM', 1, stack));
-    // `bitSpace` records whitespace the author typed around a token. It is cosmetic — Excel redisplays
-    // the formula identically without it — and reattaching it to the right operand is not something a
-    // postfix walk can do, so it is dropped rather than misplaced.
     return true;
 }
-// `PtgFuncVar` ([MS-XLSB] 2.5.97.4): a call whose argument count is in the token. Index 255 is not a
-// function at all but the indirection every post-2007 function is called through: the name comes from
-// the stream's first operand, which is a `PtgName` pointing at Excel's `_xlfn.`-prefixed placeholder.
 function variadicCall(tokens, stack, push) {
     const count = tokens.u8() & FUNCVAR_PARAM_MASK;
     const index = tokens.u16() & FUNCVAR_INDEX_MASK;
@@ -206,16 +141,11 @@ function variadicCall(tokens, stack, push) {
     const [name, ...args] = parts;
     return push(`${name}(${args.join(',')})`);
 }
-// Pop `arity` arguments and push the call. Arguments were pushed left to right, so they come off the
-// stack as one contiguous run in source order.
 function call(name, arity, stack) {
     if (stack.length < arity)
         return undefined;
     return `${name}(${stack.splice(stack.length - arity, arity).join(',')})`;
 }
-// `PtgExtraArray` ([MS-XLSB] 2.5.97.2): the elements of an array constant, row-major, behind a
-// row/column count. The element encodings are fixed-width apart from the string, which carries its
-// own length — so the block is walked, never indexed.
 function arrayConstant(extra) {
     const rows = extra.u32();
     const columns = extra.u32();
@@ -234,7 +164,6 @@ function arrayConstant(extra) {
     }
     return `{${lines.join(';')}}`;
 }
-// One `SerAr` ([MS-XLSB] 2.5.129) element of an array constant.
 function arrayElement(extra) {
     switch (extra.u8()) {
         case SER_NUM:
@@ -252,7 +181,6 @@ function arrayElement(extra) {
             return undefined;
     }
 }
-// Consume the `PtgExtraMem` a precomputed-range token owns: a count, then that many cell ranges.
 function skipExtraRanges(extra) {
     const count = extra.u32();
     if (count * RANGE_BYTES > extra.remaining)
@@ -260,8 +188,6 @@ function skipExtraRanges(extra) {
     extra.skip(count * RANGE_BYTES);
     return true;
 }
-// The sheet part of a 3-D reference, `Data!` or `'Odd Name'!` or `Data:More!`, from the index the
-// token carries into the workbook's extern-sheet table.
 function sheetPrefix(ixti, scope) {
     const xti = scope.externSheets[ixti];
     if (xti === undefined || xti.supBook !== scope.selfSupBook)
@@ -272,8 +198,6 @@ function sheetPrefix(ixti, scope) {
         return undefined;
     return `${first === last ? quoteSheetName(first) : quoteSheetName(first, last)}!`;
 }
-// A single cell, from the row and the packed column word every reference token shares. The two high
-// bits of that word say whether each axis is relative, which is exactly where the `$` signs go.
 function cellText(row, packedColumn) {
     const column = packedColumn & COLUMN_MASK;
     if (row > MAX_ROW_INDEX || column >= MAX_COLUMN)
@@ -282,9 +206,6 @@ function cellText(row, packedColumn) {
     const rowAbs = (packedColumn & ROW_RELATIVE) === 0 ? '$' : '';
     return `${columnAbs}${numberToColumn(column + 1)}${rowAbs}${row + 1}`;
 }
-// A range. A range that spans every row of its columns, or every column of its rows, is written in
-// Excel's abbreviated form (`A:A`, `2:2`) — which is not cosmetic: it is the only spelling Excel
-// writes for a whole-column reference, so anything else would fail to match the XML twin.
 function rangeText(rowFirst, rowLast, packedFirst, packedLast) {
     if (rowFirst === 0 && rowLast === MAX_ROW_INDEX) {
         const first = columnOnly(packedFirst);
@@ -309,19 +230,13 @@ function columnOnly(packedColumn) {
 function rowOnly(row, packedColumn) {
     return `${(packedColumn & ROW_RELATIVE) === 0 ? '$' : ''}${row + 1}`;
 }
-// A string literal, in the formula's own escaping: the delimiter is a double quote, and a double quote
-// inside the text is doubled.
 function quoteString(text) {
     return `"${text.replace(/"/g, '""')}"`;
 }
-// A numeric literal. JavaScript and Excel agree on every ordinary number; they part company only at
-// the exponent's case, which is normalised here so `1E+21` does not read back as `1e+21`.
 function numberText(value) {
     return String(value).toUpperCase();
 }
 const REFERENCE_ERROR = '#REF!';
-// The infix operators, by their ptg. `PtgIsect` is Excel's space operator (`A1:A3 A2:A5`) and
-// `PtgUnion` its comma — both are operators despite looking like punctuation.
 const BINARY_OPERATORS = new Map([
     [0x03, '+'],
     [0x04, '-'],
@@ -339,9 +254,6 @@ const BINARY_OPERATORS = new Map([
     [0x10, ','],
     [0x11, ':'],
 ]);
-// The token numbers this decoder names. Operand tokens are listed at their *base* value: the stream
-// carries them offset by a result class (+0x20 value, +0x40 array), which changes how the calculation
-// engine coerces the operand but never what it says.
 const PTG = {
     Exp: 0x01,
     Tbl: 0x02,
@@ -372,27 +284,17 @@ const PTG = {
 };
 const CLASSED_TOKEN_FLOOR = 0x20;
 const CLASSED_TOKEN_MASK = 0x1f;
-// `PtgAttr` flag bits.
 const ATTR_CHOOSE = 0x04;
 const ATTR_SUM = 0x10;
-// `PtgFuncVar`'s two packed fields each reserve their top bit for a flag the text does not carry.
 const FUNCVAR_PARAM_MASK = 0x7f;
 const FUNCVAR_INDEX_MASK = 0x7fff;
-// The packed column word shared by every reference token: 14 bits of column, then the two relative-
-// axis flags.
 const COLUMN_MASK = 0x3fff;
 const COLUMN_RELATIVE = 0x4000;
 const ROW_RELATIVE = 0x8000;
 const MAX_ROW_INDEX = 1048575;
-// `SerAr` element tags.
 const SER_NUM = 0x00;
 const SER_STR = 0x01;
 const SER_BOOL = 0x02;
 const SER_ERR = 0x04;
-// An `UncheckedRfX` is four 32-bit bounds.
 const RANGE_BYTES = 16;
-// A bound on an array constant's declared size. The elements themselves are read from the extra-data
-// block, which cannot outrun its own record — but the row × column product is multiplied *before* any
-// of it is read, and a forged pair would otherwise buy a loop of its own choosing. Excel's own limit
-// on an array constant is far below this.
 const MAX_ARRAY_ELEMENTS = 1 << 20;