@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/io/xlsb/primitives.js

@@ -1,35 +1,8 @@
-// The [MS-XLSB] primitive types a record payload is built from, behind one bounds-checked cursor.
-//
-// Binary parsing is where a reader most easily goes wrong in two directions at once: silently reading
-// past the end of a buffer, and allocating on a length the file (not the reader) chose. `RecordReader`
-// closes both. Every read goes through a single `#take`, so overrunning the record is impossible
-// rather than merely unlikely; and a length-prefixed string checks its byte count against what the
-// record actually holds *before* a single character is materialised, so a forged `cch` costs one
-// comparison instead of gigabytes.
-//
-// Structures decoded here — RkNumber, XLWideString, BrtColor, Cell, UncheckedRfX, BErr — are shared
-// across the workbook, worksheet, styles, and shared-string parsers; nothing part-specific lives here.
 import { isErrorCode } from '../../core/value.js';
 import { XlsbParseError } from './errors.js';
-// A length-prefixed string is decoded in code-unit batches rather than one `String.fromCharCode` call
-// per character (quadratic concatenation) or one spread of every unit (which blows the argument limit
-// on a long string). 4096 is comfortably under every engine's limit and makes the batching invisible.
 const CHARS_PER_BATCH = 4096;
-// `XLNullableWideString` marks "no string" with a character count of 0xFFFFFFFF rather than 0 — an
-// empty string and an absent one are different values (a sheet's relationship id is nullable; its
-// name is not).
 const NULL_STRING_LENGTH = 0xffffffff;
-// One reusable 8-byte window for reassembling an RkNumber's truncated double. The alternative — a
-// fresh ArrayBuffer per RK cell — would allocate once per numeric cell in the workbook, on the single
-// hottest path in the reader. Safe to share: the write and the read below are one synchronous pair.
 const rkScratch = new DataView(new ArrayBuffer(8));
-/**
- * A bounds-checked cursor over one record's payload.
- *
- * Each accessor advances the cursor by exactly the bytes it consumed, so a record is decoded by
- * naming its fields in order. Reading past the payload throws {@link XlsbParseError} — a record that
- * is shorter than its own definition is a malformed file, not a case to guess through.
- */
 export class RecordReader {
     #data;
     #view;
@@ -38,24 +11,15 @@ export class RecordReader {
         this.#data = data;
         this.#view = new DataView(data.buffer, data.byteOffset, data.byteLength);
     }
-    /** Bytes left in the record. */
     get remaining() {
         return this.#data.length - this.#offset;
     }
-    /** Whether the whole payload has been consumed. */
     get done() {
         return this.remaining <= 0;
     }
-    /** Advance past `count` bytes without decoding them — a reserved or unmodelled field. */
     skip(count) {
         this.#take(count);
     }
-    /**
-     * The next `count` bytes as a **view**, for a field whose own decoding happens elsewhere — a formula
-     * token stream, whose meaning depends on workbook tables this record knows nothing about. A view
-     * rather than a copy for the same reason a record's payload is one: the declared length comes from
-     * the file, so it must bound a read, never an allocation.
-     */
     bytes(count) {
         return this.#data.subarray(this.#take(count), this.#offset);
     }
@@ -74,57 +38,32 @@ export class RecordReader {
     i32() {
         return this.#view.getInt32(this.#take(4), true);
     }
-    /** An `Xnum` ([MS-XLSB] 2.5.172): a little-endian IEEE-754 double. */
     f64() {
         return this.#view.getFloat64(this.#take(8), true);
     }
-    /**
-     * An `RkNumber` ([MS-XLSB] 2.5.122): a number packed into 32 bits. Two flag bits steal the low end
-     * of the word — `fInt` says the remaining 30 bits are a signed integer rather than the *high* 30
-     * bits of a double whose low 34 bits are zero, and `fX100` says the result was scaled up by 100 to
-     * keep two decimal places in the integer form. It exists because most real spreadsheet numbers are
-     * small integers or two-decimal currency, and this stores them in half the bytes of a double.
-     */
     rk() {
-        // Read signed: the `fInt` branch needs an arithmetic shift to sign-extend a negative 30-bit
-        // integer, which only works on a value JavaScript already considers negative.
         const raw = this.i32();
         const value = (raw & 0b10) !== 0 ? raw >> 2 : truncatedDouble(raw & ~0b11);
         return (raw & 0b01) !== 0 ? value / 100 : value;
     }
-    /** An `XLWideString` ([MS-XLSB] 2.5.169): a 4-byte character count then that many UTF-16LE units. */
     wideString() {
         return this.#characters(this.u32());
     }
-    /**
-     * A UTF-16 string whose character count is 16-bit rather than 32-bit — the form used *inside* a
-     * formula token stream (`PtgStr`, and the string elements of an array constant), where a 4-byte
-     * count on every literal would be pure overhead.
-     */
     shortString() {
         return this.#characters(this.u16());
     }
-    /** An `XLNullableWideString` ([MS-XLSB] 2.5.166): an {@link wideString} that can also be absent. */
     nullableWideString() {
         const length = this.u32();
         return length === NULL_STRING_LENGTH ? undefined : this.#characters(length);
     }
-    /**
-     * A `RichStr` ([MS-XLSB] 2.5.124): a string that may carry per-run formatting and phonetic guides.
-     * Only the text is returned — the run and phonetic tails are left unread, which is safe because the
-     * record's framing (not this cursor) bounds where the payload ends.
-     */
     richString() {
-        this.skip(1); // fRichStr / fExtStr flags: which optional tails follow the text.
+        this.skip(1);
         return this.wideString();
     }
-    /** The `Cell` structure ([MS-XLSB] 2.5.10) that opens every cell record. */
     cell() {
         const column = this.u32();
-        // The style index shares its word with a phonetic-display flag in the high byte.
         return { column, styleIndex: this.u32() & 0x00ffffff };
     }
-    /** An `UncheckedRfX` ([MS-XLSB] 2.5.155): four zero-based, inclusive range bounds. */
     range() {
         return {
             rowFirst: this.u32(),
@@ -133,14 +72,6 @@ export class RecordReader {
             colLast: this.u32(),
         };
     }
-    /**
-     * A `BrtColor` ([MS-XLSB] 2.4.337), mapped onto the model's {@link Color}.
-     *
-     * The four encodings are mutually exclusive and the type tag picks which of the payload's fields
-     * carry meaning; the rest are explicitly undefined. An *automatic* colour (type 0) names nothing at
-     * all, and reads back as no colour — the same absence the XML reader produces for `<color auto="1"/>`,
-     * so a cell whose font colour was never set does not gain one on read.
-     */
     color() {
         const flags = this.u8();
         const index = this.u8();
@@ -152,15 +83,11 @@ export class RecordReader {
         const base = colorByType(flags >> 1, index, alpha, red, green, blue);
         if (base === undefined)
             return undefined;
-        // Tint is stored as a fraction of the signed 16-bit range, where the extreme values mean 100%
-        // lightening/darkening; the model carries it as OOXML does, in [-1, 1].
         if (tintAndShade === 0)
             return base;
         return { ...base, tint: Math.max(-1, Math.min(1, tintAndShade / 0x7fff)) };
     }
     #characters(count) {
-        // Check the byte count against the record *before* building anything: this is the guard that
-        // makes a forged character count a cheap failure rather than an allocation the file chose.
         const start = this.#take(count * 2);
         let text = '';
         let batch = [];
@@ -173,8 +100,6 @@ export class RecordReader {
         }
         return batch.length > 0 ? text + String.fromCharCode(...batch) : text;
     }
-    // The single choke point every read passes through. Returns the offset the caller may read from,
-    // having proven that `count` bytes are there.
     #take(count) {
         if (count > this.remaining) {
             throw new XlsbParseError(`BIFF12 record field needs ${count} bytes but only ${this.remaining} remain in the record`);
@@ -184,7 +109,6 @@ export class RecordReader {
         return start;
     }
 }
-/** A `BErr` ([MS-XLSB] 2.5.98.2) error code, as the model's error string. */
 export function errorCodeFor(code) {
     const text = BERR_CODES.get(code);
     return text !== undefined && isErrorCode(text) ? text : undefined;
@@ -199,14 +123,11 @@ const BERR_CODES = new Map([
     [0x2a, '#N/A'],
     [0x2b, '#GETTING_DATA'],
 ]);
-// Rebuild the double whose *high* 32 bits are `high` and whose low 34 bits [MS-XLSB] guarantees to be
-// zero. Written big-endian so the given word lands in the high half regardless of host endianness.
 function truncatedDouble(high) {
     rkScratch.setInt32(0, high, false);
     rkScratch.setUint32(4, 0, false);
     return rkScratch.getFloat64(0, false);
 }
-// The `xColorType` tag ([MS-XLSB] 2.4.337) selects which of a BrtColor's fields carry the colour.
 const COLOR_TYPE_INDEXED = 1;
 const COLOR_TYPE_RGB = 2;
 const COLOR_TYPE_THEME = 3;
@@ -217,9 +138,6 @@ function colorByType(type, index, alpha, red, green, blue) {
         case COLOR_TYPE_RGB:
             return { argb: hexByte(alpha) + hexByte(red) + hexByte(green) + hexByte(blue) };
         case COLOR_TYPE_THEME:
-            // The binary theme index and OOXML's `theme="…"` attribute both count the `clrScheme`
-            // subelements in declaration order (dk1, lt1, dk2, lt2, accent1–6, hlink, folHlink), so the
-            // index carries across unchanged.
             return { theme: index };
         default:
             return undefined;

package/dist/io/xlsb/ptg-functions.js

@@ -1,42 +1,11 @@
-// The `Ftab` built-in function table ([MS-XLS] 2.5.198.17, shared verbatim by BIFF12): the index a
-// `PtgFunc`/`PtgFuncVar` token carries, mapped to the function name that index means.
-//
-// A binary formula names no function — it cites one by number — so this table is the whole difference
-// between `SUM(A1:A5)` and an unreadable stream. It is transcribed from the normative table rather
-// than assembled from Excel's UI, which matters at both ends: the low indices include the XLM macro
-// functions (`GOTO`, `ADD.BAR`, …) that no modern sheet uses but a legacy file may still carry, and
-// the table simply stops at `RTD`. Everything Microsoft added after that — the whole modern library,
-// `TEXTJOIN` through `LAMBDA` — is *not* here and never will be: a post-2007 function is called
-// through index 255 ("user defined") with an `_xlfn.`-prefixed name as its first operand, which is
-// the same indirection the XML form spells out in the function name itself.
-//
-// The four gaps (0x00CA–CB, 0x00D9–DA, 0x00F9–FA, 0x014D) are gaps in the specification: those
-// indices name no function, so a formula citing one is not decodable rather than decodable as
-// something adjacent.
-/** The index [MS-XLS] reserves for a call whose name is given by the token stream's first operand. */
 export const FTAB_USER_DEFINED = 0x00ff;
-/** Look up a built-in function name by its `iftab` index, or `undefined` if the index names none. */
 export function functionNameFor(index) {
     return FTAB[index];
 }
-/**
- * How many arguments a fixed-arity function takes, or `undefined` for one whose argument count varies.
- *
- * A `PtgFunc` token states only *which* function is called, never with how many arguments — it is the
- * token Excel emits precisely because the count is implied by the function. So decoding `ROUND(A1,2)`
- * back from its two operands and one call token is impossible without this: the arity is the only
- * thing that says which operands on the stack belong to the call. (`PtgFuncVar` carries its own count
- * and needs none of this; the two token forms partition the table between them.)
- *
- * Transcribed from the parameter grammar each function's [MS-XLS] 2.5.198.17 entry states.
- */
 export function fixedArityFor(name) {
     return FIXED_ARITY.get(name);
 }
-// Keyed by name rather than index: an arity belongs to the function, and a name is checkable at a
-// glance where a hex index is not.
 const FIXED_ARITY = new Map(Object.entries({
-    // "This function takes no parameters."
     NA: 0,
     PI: 0,
     TRUE: 0,
@@ -248,8 +217,6 @@ const FIXED_ARITY = new Map(Object.entries({
     TTEST: 4,
     WEIBULL: 4,
 }));
-// The table as contiguous runs, each `[first index, names in order]`. Written this way so the four
-// specification gaps are visible as run boundaries instead of hiding as miscounted array entries.
 const RUNS = [
     [
         0x0000,
@@ -650,7 +617,6 @@ const RUNS = [
         ],
     ],
 ];
-// Indexed by `iftab`; a hole is an index the specification does not define.
 const FTAB = RUNS.reduce((table, [start, names]) => {
     names.forEach((name, offset) => {
         table[start + offset] = name;

package/dist/io/xlsb/read-shared-strings.js

@@ -1,13 +1,6 @@
-// The BIFF12 shared-string table: `xl/sharedStrings.bin` in, the pool a `BrtCellIsst` cell indexes.
-//
-// The binary table is a flat run of `BrtSSTItem` records between a Begin/End pair, each holding one
-// `RichStr`. Only the text is taken: a pooled string's per-run formatting is not modelled in this cut,
-// so the runs are left unread rather than half-decoded (see `primitives.ts`). Reading stops at the
-// closing record, so trailing future-record blocks are never framed.
 import { RecordReader } from './primitives.js';
 import { readRecords } from './record-stream.js';
 import { BRT } from './record-types.js';
-/** Parse `xl/sharedStrings.bin` into the pool, in index order. An absent part is an empty pool. */
 export function parseSharedStrings(part) {
     if (part === undefined)
         return [];

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

@@ -1,14 +1,3 @@
-// The BIFF12 style-sheet reader: `xl/styles.bin` in, the same {@link StyleTable} the XML reader
-// produces out. Every collection (`fmts`, `fonts`, `fills`, `borders`, `cellStyleXfs`, `cellXfs`,
-// `styles`) is a Begin/End record pair around its entries, so the pass tracks which collection it is
-// inside — `BrtXF` appears in two of them and is meaningless without that context.
-//
-// The resolution *rules* are deliberately not restated here: number-format ids go through the XML
-// reader's `numFmtCodeFor`, and each facet is emitted with the same "only when it differs from the
-// default" discipline the XML path uses. That is what makes the binary and XML readings of one
-// workbook the same model rather than two similar ones — a bottom vertical alignment, a locked cell,
-// or a General number format is written explicitly in BIFF12 and omitted in XML, so the binary side
-// has to drop exactly what the XML side never had.
 import { assignStyleFacets } from '../../core/style.js';
 import { numFmtCodeFor } from '../style/xf-style.js';
 import { RecordReader } from './primitives.js';
@@ -32,7 +21,6 @@ const COLLECTION_ENDS = new Set([
     BRT.EndCellXFs,
     BRT.EndStyles,
 ]);
-/** Parse `xl/styles.bin` into the flat cell-format table a worksheet's style indices resolve against. */
 export function parseStyleTable(part) {
     if (part === undefined)
         return { cellXfs: [], namedStyles: [] };
@@ -86,8 +74,6 @@ export function parseStyleTable(part) {
                 break;
         }
     }
-    // Layer each direct format over the named style its xfId links to, exactly as the XML reader does:
-    // a facet the cell's own xf sets wins, one it leaves unset falls through to the named base.
     const cellXfs = directXfs.map((xf) => {
         if (xf.xfId === undefined)
             return xf;
@@ -104,22 +90,15 @@ export function parseStyleTable(part) {
             style.builtinId = label.builtinId;
         return style;
     });
-    // Font 0 is the workbook's declared default, carried out whole as well as flattened onto the xfs
-    // that name it — see {@link StyleTable.defaultFont}. The XML reader does the same.
     const defaultFont = fonts[0];
     return defaultFont === undefined ? { cellXfs, namedStyles } : { cellXfs, namedStyles, defaultFont };
 }
-// `BrtXF` ([MS-XLSB] 2.4.876): five facet indices, the two inline alignment scalars, then two flag
-// words. `isDirect` distinguishes a cellXfs entry (whose ixfeParent links to a named style) from a
-// cellStyleXfs entry (whose ixfeParent is the 0xFFFF "I am the named style" marker).
 function readXf(reader, deps, isDirect) {
     const parent = reader.u16();
     const numFmt = numFmtCodeFor(reader.u16(), deps.numFmtCodes);
     const font = deps.fonts[reader.u16()];
     const fill = deps.fills[reader.u16()];
     const borderIndex = reader.u16();
-    // Border 0 is the genuinely empty default (font 0, by contrast, is the workbook's real default
-    // face), so only a custom index names an actual border — the same asymmetry the XML reader keeps.
     const border = borderIndex > 0 ? deps.borders[borderIndex] : undefined;
     const rotation = reader.u8();
     const indent = reader.u8();
@@ -139,20 +118,13 @@ function readXf(reader, deps, isDirect) {
     const protection = readProtection(flags);
     if (protection !== undefined)
         draft.protection = protection;
-    // f123Prefix is the binary spelling of the `quotePrefix` attribute: the cell's text is displayed
-    // with a leading apostrophe stripped.
     if ((flags & 0x8000) !== 0)
         draft.quotePrefix = true;
-    // Only a link beyond the Normal default (0) carries information, and only a direct format has one.
     if (isDirect && parent !== NOT_A_CELL_XF && parent > 0)
         draft.xfId = parent;
     return draft;
 }
-// The `ixfeParent` value a cell *style* XF carries in place of a link, since it is itself the base.
 const NOT_A_CELL_XF = 0xffff;
-// BIFF12 states every alignment field on every xf, where XML omits the ones at their default. Keep
-// only what the XML reader would have seen, so the two readings of one workbook agree: `general`
-// horizontal, `bottom` vertical, and zero rotation/indent/reading-order are absences, not values.
 function readAlignment(flags, rotation, indent) {
     const out = {};
     const horizontal = HORIZONTAL_ALIGNMENTS[flags & 0b111];
@@ -174,8 +146,6 @@ function readAlignment(flags, rotation, indent) {
         out.readingOrder = readingOrder;
     return Object.keys(out).length > 0 ? out : undefined;
 }
-// `locked` defaults to TRUE in OOXML, so an *unlocked* cell is the state that carries information;
-// `hidden` defaults to false, so only a set flag does. A default xf yields no protection at all.
 function readProtection(flags) {
     const out = {};
     if ((flags & 0x1000) === 0)
@@ -184,8 +154,6 @@ function readProtection(flags) {
         out.hidden = true;
     return Object.keys(out).length > 0 ? out : undefined;
 }
-// `alc` ([MS-XLSB] 2.4.876), indexed by its stored value. `general` is index 0 and is left out
-// deliberately: it is the type-dependent default, which the model spells as no horizontal alignment.
 const HORIZONTAL_ALIGNMENTS = [
     undefined,
     'left',
@@ -196,7 +164,6 @@ const HORIZONTAL_ALIGNMENTS = [
     'centerContinuous',
     'distributed',
 ];
-// `alcv`, likewise — with `bottom` (index 2) left out as the default.
 const VERTICAL_ALIGNMENTS = [
     'top',
     'center',
@@ -204,8 +171,6 @@ const VERTICAL_ALIGNMENTS = [
     'justify',
     'distributed',
 ];
-// `BrtFont` ([MS-XLSB] 2.4.690). Weight is a numeric scale (400 normal, 700 bold) rather than a flag,
-// and the italic/strike/outline bits live in a separate word from it.
 function readFont(reader) {
     const height = reader.u16();
     const flags = reader.u16();
@@ -214,14 +179,13 @@ function readFont(reader) {
     const underline = reader.u8();
     const family = reader.u8();
     const charset = reader.u8();
-    reader.skip(1); // unused
+    reader.skip(1);
     const color = reader.color();
     const scheme = reader.u8();
     const name = reader.wideString();
     const font = {};
     if (name !== '')
         font.name = name;
-    // Stored in twips; the model (like the XML) carries points.
     if (height > 0)
         font.size = height / 20;
     if (family !== 0)
@@ -234,8 +198,6 @@ function readFont(reader) {
         font.scheme = 'minor';
     if (color !== undefined)
         font.color = color;
-    // Each boolean facet is recorded only when on, mirroring XML's present-or-absent `<b/>`/`<i/>`:
-    // a non-bold font must not read back as `bold: false`.
     if (weight >= BOLD_WEIGHT)
         font.bold = true;
     if ((flags & 0b0000_0010) !== 0)
@@ -254,27 +216,16 @@ function readFont(reader) {
     return font;
 }
 const BOLD_WEIGHT = 700;
-// `uls` ([MS-XLSB] 2.4.690). A single underline is `true`, not `'single'`, because that is what XML's
-// bare `<u/>` — which is what Excel writes for it — reads back as.
 const UNDERLINE_STYLES = new Map([
     [0x01, true],
     [0x02, 'double'],
     [0x21, 'singleAccounting'],
     [0x22, 'doubleAccounting'],
 ]);
-// `BrtFill` ([MS-XLSB] 2.4.681). The pattern code and OOXML's `ST_PatternType` enumerate the same
-// patterns in the same order, so the code indexes the name list directly.
 function readFill(reader) {
     const pattern = FILL_PATTERNS[reader.u32()];
-    // `none` is the absence of a fill, and an unmodelled pattern (a gradient — see below) is dropped
-    // rather than guessed, so an unfilled cell reads back unfilled either way.
     if (pattern === undefined)
         return undefined;
-    // BIFF12 always states both colours; XML states only the ones the fill actually has, using the two
-    // legacy-palette sentinels for the rest — 64 is "automatic foreground", 65 "automatic background".
-    // Dropping each in its own slot reproduces exactly what the XML reader sees: an untouched hatch
-    // pattern carries no colours at all, while a solid fill keeps the explicit `bgColor indexed="64"`
-    // Excel writes beside its foreground.
     const fgColor = notSentinel(reader.color(), AUTOMATIC_FOREGROUND);
     const bgColor = notSentinel(reader.color(), AUTOMATIC_BACKGROUND);
     return {
@@ -289,10 +240,6 @@ const AUTOMATIC_BACKGROUND = 65;
 function notSentinel(color, sentinel) {
     return color?.indexed === sentinel ? undefined : color;
 }
-// Indexed by the stored `fls` value. Index 0 (`none`) is deliberately absent: an unfilled cell
-// carries no fill. Gradient fills (`fls` 0x28) are not decoded in this cut — the stop array's layout
-// is the one piece of BrtFill this reader has no Excel-authored sample to check against, and a
-// silently wrong gradient is worse than none.
 const FILL_PATTERNS = [
     undefined,
     'solid',
@@ -314,9 +261,6 @@ const FILL_PATTERNS = [
     'gray125',
     'gray0625',
 ];
-// `BrtBorder` ([MS-XLSB] 2.4.314): the two diagonal-direction bits, then five `Blxf` edges in the
-// order top, bottom, left, right, diagonal — which is *not* the model's or the schema's order, so
-// the edges are read positionally and named here.
 function readBorder(reader) {
     const flags = reader.u8();
     const top = readEdge(reader);
@@ -339,21 +283,16 @@ function readBorder(reader) {
         border.diagonalDown = true;
     if ((flags & 0b10) !== 0)
         border.diagonalUp = true;
-    // An all-default border is the empty one every unbordered cell shares; it carries nothing.
     return Object.keys(border).length > 0 ? border : undefined;
 }
-// A `Blxf` ([MS-XLSB] 2.5.5): a line style, a reserved byte, and a colour. Style 0 is "no edge",
-// which the model spells by omitting the edge rather than by a `none` value.
 function readEdge(reader) {
     const style = BORDER_STYLES[reader.u8()];
-    reader.skip(1); // reserved
+    reader.skip(1);
     const color = reader.color();
     if (style === undefined)
         return undefined;
     return color === undefined ? { style } : { style, color };
 }
-// Indexed by the stored `dg` value; index 0 (`none`) is absent, as above. The order is the binary
-// format's own and differs from `ST_BorderStyle`'s declaration order, so it cannot be shared.
 const BORDER_STYLES = [
     undefined,
     'thin',
@@ -370,13 +309,11 @@ const BORDER_STYLES = [
     'mediumDashDotDot',
     'slantDashDot',
 ];
-// `BrtStyle` ([MS-XLSB] 2.4.809): which cellStyleXfs entry this names, and how it is labelled. The
-// gallery index is only meaningful for a built-in style, which the flag word declares.
 function readStyleLabel(reader) {
     const xfId = reader.u32();
     const flags = reader.u16();
     const builtinId = reader.u8();
-    reader.skip(1); // iLevel: the outline depth of a built-in RowLevel/ColLevel style.
+    reader.skip(1);
     const name = reader.wideString();
     return {
         xfId,