@shbernal/ts-xlsx 1.0.0

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

@@ -0,0 +1,73 @@
+// 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,
+    CellError: 3,
+    CellBool: 4,
+    CellReal: 5,
+    CellSt: 6,
+    CellIsst: 7,
+    FmlaString: 8,
+    FmlaNum: 9,
+    FmlaBool: 10,
+    FmlaError: 11,
+    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,
+    Border: 46,
+    XF: 47,
+    Style: 48,
+    BeginFmts: 615,
+    EndFmts: 616,
+    BeginFonts: 611,
+    EndFonts: 612,
+    BeginFills: 603,
+    EndFills: 604,
+    BeginBorders: 613,
+    EndBorders: 614,
+    BeginCellStyleXFs: 626,
+    EndCellStyleXFs: 627,
+    BeginCellXFs: 617,
+    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,
+    BeginSheetData: 145,
+    EndSheetData: 146,
+    ArrFmla: 426,
+};

package/dist/io/xlsx/cell-accumulator.d.ts

@@ -0,0 +1,25 @@
+import type { CellValue } from '../../core/value.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
+import { type XmlAttributes } from '../../xml/xml-read.ts';
+import { type XfStyle } from '../style/xf-style.ts';
+import { type SharedString } from './cell-value.ts';
+import { RunAccumulator } from './rich-runs.ts';
+export declare class CellAccumulator {
+    #private;
+    /** This cell's `<c r>` address (`"B3"`), or '' when it carried none. */
+    get ref(): string;
+    /** This cell's own `<c s>` style index, or -1 when it carries none. */
+    get styleIndex(): number;
+    /** This cell's 1-based column, or -1 when its address was absent or unparseable. */
+    get col(): number;
+    /** The rich-text run accumulator, driven by the surrounding parser's `<r>`/`<rPr>` handling. */
+    get runs(): RunAccumulator;
+    beginCell(attrs: XmlAttributes): void;
+    beginFormula(attrs: XmlAttributes, selfClosing: boolean): void;
+    setFormula(text: string): void;
+    setValue(text: string): void;
+    beginInlineString(): void;
+    appendText(text: string, inInlineString: boolean): void;
+    finalize(sheet: Worksheet, sharedStrings: readonly SharedString[], style: XfStyle | undefined): void;
+    decode(sharedStrings: readonly SharedString[], style: XfStyle | undefined): CellValue;
+}

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

@@ -0,0 +1,172 @@
+// 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";
+import { applyXfToCell } from "../style/xf-style.js";
+import { decodeCellContent, decodeFormulaResult, } from "./cell-value.js";
+import { RunAccumulator } from "./rich-runs.js";
+export class CellAccumulator {
+    #ref = '';
+    #type = '';
+    #style = -1;
+    #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;
+    #dataTable = null;
+    #valueText = '';
+    #inlineText = '';
+    #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 ?? '';
+        this.#style = attrs.s !== undefined ? Number(attrs.s) : -1;
+        this.#col = this.#ref === '' ? -1 : (decodeAddress(this.#ref).col ?? -1);
+        this.#row = this.#ref === '' ? -1 : (decodeAddress(this.#ref).row ?? -1);
+        this.#formula = '';
+        this.#valueText = '';
+        this.#inlineText = '';
+        this.#runs.reset();
+        this.#hasFormula = false;
+        this.#hasValue = false;
+        this.#formulaShared = false;
+        this.#formulaSi = -1;
+        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;
+        if (selfClosing && this.#formulaShared)
+            this.#sharedClone = true;
+        if (attrs.t === 'dataTable' && attrs.ref !== undefined) {
+            this.#dataTable = {
+                ref: attrs.ref,
+                dt2D: attrs.dt2D,
+                dtr: attrs.dtr,
+                r1: attrs.r1,
+                r2: attrs.r2,
+            };
+        }
+    }
+    setFormula(text) {
+        this.#formula = text;
+        this.#hasFormula = true;
+    }
+    setValue(text) {
+        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;
+        if (this.#dataTable !== null) {
+            const value = {
+                shareType: 'dataTable',
+                ref: this.#dataTable.ref,
+                ...(boolPresent(this.#dataTable.dt2D ?? '0') ? { dataTable2D: true } : {}),
+                ...(boolPresent(this.#dataTable.dtr ?? '0') ? { dataTableRow: true } : {}),
+                ...(this.#dataTable.r1 !== undefined ? { r1: this.#dataTable.r1 } : {}),
+                ...(this.#dataTable.r2 !== undefined ? { r2: this.#dataTable.r2 } : {}),
+                ...(this.#hasValue
+                    ? { result: decodeFormulaResult(this.#type, this.#valueText, style?.numFmt) }
+                    : {}),
+            };
+            const cell = sheet.getCell(this.#ref);
+            applyXfToCell(cell, style);
+            cell.value = value;
+            return;
+        }
+        if (this.#hasFormula && this.#formulaShared && this.#formulaSi >= 0) {
+            this.#masters.set(this.#formulaSi, { formula: this.#formula, col: this.#col, row: this.#row });
+        }
+        else if (this.#sharedClone && this.#formulaSi >= 0) {
+            const master = this.#masters.get(this.#formulaSi);
+            if (master !== undefined) {
+                const translated = translateFormula(master.formula, this.#col - master.col, this.#row - master.row);
+                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) }
+                        : {}),
+                };
+                const cell = sheet.getCell(this.#ref);
+                applyXfToCell(cell, style);
+                cell.value = value;
+                return;
+            }
+        }
+        const cell = sheet.getCell(this.#ref);
+        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,
+            hasFormula: this.#hasFormula,
+            formula: this.#formula,
+            hasValue: this.#hasValue,
+            valueText: this.#valueText,
+            inlineText: this.#inlineText,
+            richTextRuns: this.#runs.runs,
+        };
+        return decodeCellContent(raw, sharedStrings, style?.numFmt);
+    }
+}

package/dist/io/xlsx/cell-value.d.ts

@@ -0,0 +1,32 @@
+import { type CellValue, type FormulaResult, type RichTextRun, type RichTextValue } from '../../core/value.ts';
+/**
+ * One entry of the shared-strings pool. A `<si>` built from a bare `<t>` is a plain string; a `<si>`
+ * built from `<r>` runs is rich text — so a `t="s"` cell can resolve to either kind, and rich text
+ * that Excel pooled reads back with its per-run formatting intact rather than flattened to text.
+ */
+export type SharedString = string | RichTextValue;
+/** The raw, still-textual pieces of a `<c>` element the SAX pass has gathered. */
+export interface RawCell {
+    /** The `t` attribute (`s`, `str`, `inlineStr`, `b`, `e`, `d`, or '' for a number). */
+    readonly type: string;
+    readonly hasFormula: boolean;
+    readonly formula: string;
+    readonly hasValue: boolean;
+    readonly valueText: string;
+    readonly inlineText: string;
+    /** The formatted runs of a rich inline string, when the `<is>` held `<r>` elements rather than a
+     * bare `<t>`. Absent (or empty) for a plain inline string, which decodes to `inlineText`. */
+    readonly richTextRuns?: readonly RichTextRun[];
+}
+/**
+ * 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 declare function decodeCellContent(raw: RawCell, sharedStrings: readonly SharedString[], numFmt: string | undefined): CellValue;
+/** 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 declare function decodeFormulaResult(type: string, valueText: string, numFmt?: string): FormulaResult;

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

@@ -0,0 +1,85 @@
+// 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;
+}
+function decodeValue(type, valueText, inlineText, hasValue, sharedStrings) {
+    switch (type) {
+        case 'inlineStr':
+            return inlineText;
+        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] ?? '') : '';
+        }
+        case 'b':
+            return boolStrict(valueText);
+        case 'e':
+            return isErrorCode(valueText) ? { error: valueText } : valueText;
+        default:
+            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':
+            return valueText;
+        case 'b':
+            return boolStrict(valueText);
+        case 'e':
+            return isErrorCode(valueText) ? { error: valueText } : valueText;
+        default:
+            return Number(valueText);
+    }
+}

package/dist/io/xlsx/comments.d.ts

@@ -0,0 +1,74 @@
+import type { CommentThread } from '../../core/comment-thread.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
+/** A comment bound for `comments{n}.xml`, paired with the coordinates the VML anchor needs. */
+export interface CommentCell {
+    readonly ref: string;
+    /** 1-based row of the commented cell. */
+    readonly row: number;
+    /** 1-based column of the commented cell. */
+    readonly col: number;
+    readonly text: string;
+    /**
+     * The {@link CommentThread} head id this comment is the legacy fallback for, absent for a user's own
+     * note. Present means the comment is emitted with a synthetic `tc={id}` author and an `xr:uid`, the
+     * pair Excel resolves the cell's thread through.
+     */
+    readonly threadId?: string;
+}
+/**
+ * Gather every comment a sheet must write: its cells' notes, plus one legacy fallback per conversation
+ * in `threads`. A comment anchors to its cell regardless of the cell's value, so a note (or a thread) on
+ * an otherwise-empty cell is collected too.
+ *
+ * `threads` is the conversations the *package* will carry, not simply the ones the sheet holds — the
+ * caller decides, because a fallback beside a thread whose `threadedComment` part is missing is worse
+ * than no fallback at all: verified against desktop Excel, such a comment shows as neither a thread nor
+ * a note, so the text disappears entirely.
+ *
+ * Ordered by cell, row-major, the way Excel writes the list — so a fallback lands interleaved among the
+ * notes rather than appended after them, and the VML shapes follow the same order.
+ */
+export declare function collectComments(sheet: Worksheet, threads: readonly CommentThread[]): CommentCell[];
+/**
+ * The `xl/comments{n}.xml` part.
+ *
+ * Authors are laid out the way Excel lays them out: one synthetic `tc={headId}` entry per threaded
+ * conversation first, then a single anonymous author shared by every note (the model carries no note
+ * author). Each comment points at its own author by index, and a fallback additionally carries the
+ * `xr:uid` naming its thread — the pair that keeps Excel treating the cell as threaded.
+ */
+export declare function commentsXml(comments: readonly CommentCell[]): string;
+/** The `xl/drawings/vmlDrawing{n}.vml` companion: one hidden text-box shape per comment, in the same
+ * order as the comments part. Anchor coordinates place the box a couple of cells down-and-right of its
+ * owner; Excel refines them on open, so the values are a sensible starting geometry rather than a
+ * pixel-exact layout. A thread's fallback shape is `ObjectType="Note"` like any other — Excel draws the
+ * threaded-comment card itself and only needs the shape to exist. */
+export declare function vmlDrawingXml(comments: readonly CommentCell[]): string;
+/** One `<comment>` read back from a comments part. */
+export interface ParsedComment {
+    readonly text: string;
+    /**
+     * The thread head id this comment is the legacy fallback for, read off its synthetic `tc={headId}`
+     * author; absent for a user's own note.
+     */
+    readonly threadId?: string;
+}
+/**
+ * Parse a `comments{n}.xml` part into a map of A1 reference → comment. Text runs within one comment are
+ * concatenated; an author-name run is Excel's own convention and is not stripped, so a note reads back
+ * as exactly the text that was written.
+ */
+export declare function parseComments(xml: string): Map<string, ParsedComment>;
+/**
+ * Apply a parsed comments part onto a sheet's cells as notes, addressing each by its A1 reference.
+ *
+ * A thread's legacy fallback is not a note and does not become one: its text is boilerplate wrapping a
+ * copy of the conversation, so surfacing it as `cell.note` hands the caller garbage — and on write it
+ * would be re-emitted as a plain note, destroying the `tc=`/`xr:uid` binding and leaving Excel unable to
+ * see the thread at all.
+ *
+ * Suppressed only for a conversation the reader actually holds: a file whose thread part is missing or
+ * damaged has nothing else left, so there the boilerplate is kept rather than the content lost. Call
+ * after the sheet's threads are restored, since that is what this reads to decide.
+ */
+export declare function applyNotes(sheet: Worksheet, comments: ReadonlyMap<string, ParsedComment>): void;