@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/io/xlsx/read-rows.js

@@ -1,42 +1,59 @@
-import { MAX_COLUMN, MAX_ROW } from '../../core/address.js';
-import { AuthoringError } from '../../errors.js';
-import { closeEmptyElements } from '../../xml/xml-read.js';
-import { boolStrict, localName, numInteger, xmlEvents } from '../../xml/xml-scan.js';
+import { Workbook } from '../../core/workbook.js';
+import { WorksheetMerges } from '../../core/worksheet-merges.js';
+import { AuthoringError, quoted } from '../../errors.js';
+import { numInteger } from '../../xml/xml-attrs.js';
+import { closeEmptyElements, parseXmlPasses } from '../../xml/xml-read.js';
+import { boolStrict, localName, xmlEvents } from '../../xml/xml-scan.js';
 import { openSpreadsheetPackage, readPartRelationships } from '../opc/read-opc.js';
 import { unsupportedWorkbookPart } from '../opc/sniff-format.js';
-import { CellAccumulator } from './cell-accumulator.js';
+import { ColumnRecordBudget } from '../read-policy/column-budget.js';
+import { admitting, repairedSheetNames } from '../read-policy/read-repair.js';
+import { CellStyleResolver } from '../style/cell-style-resolution.js';
+import { CellAccumulator, WORKSHEET_BODY_EMPTY_CLOSES } from './cell-accumulator.js';
+import { readCellMetadata } from './cell-metadata.js';
+import { takeColumnSpan } from './column-span.js';
 import { XlsxParseError } from './errors.js';
+import { SHARED_STRINGS_PART, STYLES_PART } from './part-names.js';
 import { parseSharedStrings } from './read-shared-strings.js';
-import { parseStyleTable, parseWorkbookSheets, } from './read.js';
+import { parseStyleTable } from './read-styles.js';
+import { definedNamesPass, workbookPropertiesPass, workbookSheetsPass, } from './read-workbook-xml.js';
+import { RowPositionTracker } from './row-position.js';
 export function* readSheetRows(data, options = {}) {
     const pkg = openPackage(data, options.maxUncompressedBytes);
     const chosen = pickSheet(pkg.sheets, options.sheet);
     const sheetXml = pkg.sheetXml(chosen.relId);
     if (sheetXml === undefined)
         return;
-    yield* scanSheet(sheetXml, pkg.sharedStrings, pkg.xfStyles, new Set(), []);
+    yield* scanSheet(sheetXml, pkg, new Set(), new WorksheetMerges());
 }
 export function* readWorkbookStream(data, options = {}) {
     const pkg = openPackage(data, options.maxUncompressedBytes);
     for (const sheet of pkg.sheets) {
         const xml = pkg.sheetXml(sheet.relId) ?? '';
-        yield new StreamedSheetReader(sheet.name, xml, pkg.sharedStrings, pkg.xfStyles);
+        yield new StreamedSheetReader(sheet.name, xml, pkg);
     }
 }
 function openPackage(data, maxUncompressedBytes) {
-    const { pkg, workbookXml } = openSpreadsheetPackage(data, maxUncompressedBytes);
-    const { partText: text } = pkg;
+    const { pkg, documentPath, workbookXml } = openSpreadsheetPackage(data, maxUncompressedBytes);
+    const { partText: text, partBytes } = pkg;
     if (workbookXml === undefined) {
-        throw unsupportedWorkbookPart(text, 'the binary .xlsb format (BIFF12) cannot be row-streamed yet; read it with readXlsx or readXlsb');
+        throw unsupportedWorkbookPart(partBytes, documentPath, 'the binary .xlsb format (BIFF12) cannot be row-streamed yet; read it with readXlsx or readXlsb');
     }
-    const sheets = parseWorkbookSheets(workbookXml);
-    const rels = readPartRelationships('xl/workbook.xml', text);
-    const sharedStrings = parseSharedStrings(text('xl/sharedStrings.xml') ?? '');
-    const { cellXfs: xfStyles } = parseStyleTable(text('xl/styles.xml') ?? '');
+    const properties = new Workbook();
+    const sheetsPass = workbookSheetsPass();
+    const namesPass = definedNamesPass();
+    parseXmlPasses(workbookXml, [sheetsPass, workbookPropertiesPass(properties), namesPass]);
+    const sheets = repairedSheetNames(sheetsPass.result());
+    const rels = readPartRelationships(documentPath, text);
+    const sharedStrings = parseSharedStrings(rels.relatedTextOrPath('sharedStrings', SHARED_STRINGS_PART));
+    const { cellXfs: xfStyles } = parseStyleTable(rels.relatedTextOrPath('styles', STYLES_PART));
     return {
         sheets,
         sharedStrings,
         xfStyles,
+        dateEpoch: properties.dateEpoch,
+        definedNames: namesPass.spellings(),
+        cellMetadata: readCellMetadata(rels),
         sheetXml(relId) {
             const target = rels.byId(relId)?.target;
             return target === undefined ? undefined : text(rels.pathOf(target));
@@ -57,28 +74,26 @@ function pickSheet(sheets, selector) {
     }
     const sheet = sheets.find((candidate) => candidate.name === selector);
     if (sheet === undefined)
-        throw new AuthoringError(`no worksheet named ${JSON.stringify(selector)}`);
+        throw new AuthoringError(`no worksheet named ${quoted(selector)}`);
     return sheet;
 }
 class StreamedSheetReader {
     name;
     #xml;
-    #sharedStrings;
-    #xfStyles;
+    #tables;
     #hiddenColumns = new Set();
-    #merges = [];
+    #merges = new WorksheetMerges();
     #scanned = false;
-    constructor(name, xml, sharedStrings, xfStyles) {
+    constructor(name, xml, tables) {
         this.name = name;
         this.#xml = xml;
-        this.#sharedStrings = sharedStrings;
-        this.#xfStyles = xfStyles;
+        this.#tables = tables;
     }
     *rows() {
         this.#hiddenColumns = new Set();
-        this.#merges = [];
+        this.#merges = new WorksheetMerges();
         this.#scanned = false;
-        yield* scanSheet(this.#xml, this.#sharedStrings, this.#xfStyles, this.#hiddenColumns, this.#merges);
+        yield* scanSheet(this.#xml, this.#tables, this.#hiddenColumns, this.#merges);
         this.#scanned = true;
     }
     get hiddenColumns() {
@@ -87,7 +102,7 @@ class StreamedSheetReader {
     }
     get merges() {
         this.#ensureScanned();
-        return [...this.#merges];
+        return [...this.#merges.ranges];
     }
     #ensureScanned() {
         if (this.#scanned)
@@ -96,25 +111,28 @@ class StreamedSheetReader {
         }
     }
 }
-const CELL_EMPTY_CLOSE = new Set(['c']);
-function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
+function* scanSheet(xml, tables, hiddenColumns, merges) {
+    const { sharedStrings, xfStyles, dateEpoch, definedNames, cellMetadata } = tables;
     let rowNumber = 0;
-    let lastRow = 0;
     let rowHidden = false;
-    let rowInGrid = true;
     let cells = [];
-    const cell = new CellAccumulator({ richRuns: false });
+    const columnBudget = new ColumnRecordBudget();
+    const styleResolution = new CellStyleResolver();
+    const rowPosition = new RowPositionTracker();
+    const cell = new CellAccumulator({ dateEpoch, definedNames, cellMetadata });
     const finalizeCell = () => {
-        if (cell.ref === '' || cell.col < 0 || !rowInGrid)
+        if (cell.ref === '')
             return;
-        const style = cell.styleIndex >= 0 ? xfStyles[cell.styleIndex] : undefined;
+        const style = styleResolution.styleFor(cell.col, cell.styleIndex, xfStyles);
         const value = cell.decode(sharedStrings, style);
         if (value !== null) {
             const { col, ref } = cell;
-            cells.push(style ? { col, address: ref, value, style } : { col, address: ref, value });
+            cells.push(style !== undefined && styleResolution.declaresFormat(col, cell.styleIndex)
+                ? { col, address: ref, value, style }
+                : { col, address: ref, value });
         }
     };
-    for (const event of closeEmptyElements(xmlEvents(xml), CELL_EMPTY_CLOSE)) {
+    for (const event of closeEmptyElements(xmlEvents(xml), WORKSHEET_BODY_EMPTY_CLOSES)) {
         if (event.kind === 'text') {
             cell.appendChunk(event.text);
             continue;
@@ -125,20 +143,22 @@ function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
                 continue;
             switch (local) {
                 case 'row': {
-                    rowNumber = numInteger(event.attrs.r, 1) ?? lastRow + 1;
-                    lastRow = rowNumber;
-                    rowInGrid = rowNumber <= MAX_ROW;
+                    const position = rowPosition.open(event.attrs);
+                    rowNumber = position.number;
                     rowHidden = boolStrict(event.attrs.hidden);
-                    cells = [];
+                    cell.openRow(position.number, position.inGrid);
+                    styleResolution.openRow(numInteger(event.attrs.s, 0) ?? -1, boolStrict(event.attrs.customFormat));
                     break;
                 }
                 case 'col':
-                    collectHiddenColumn(event.attrs, hiddenColumns);
+                    collectColumn(event.attrs, hiddenColumns, styleResolution, columnBudget);
                     break;
-                case 'mergeCell':
-                    if (event.attrs.ref !== undefined)
-                        merges.push(event.attrs.ref);
+                case 'mergeCell': {
+                    const ref = event.attrs.ref;
+                    if (ref !== undefined)
+                        admitting(() => merges.add(ref));
                     break;
+                }
                 default:
                     break;
             }
@@ -149,19 +169,23 @@ function* scanSheet(xml, sharedStrings, xfStyles, hiddenColumns, merges) {
         if (claimed === 'cell')
             finalizeCell();
         else if (claimed === 'other' && local === 'row') {
-            if (rowInGrid)
+            styleResolution.closeRow();
+            const inGrid = cell.rowOpen;
+            cell.closeRow();
+            if (inGrid)
                 yield { number: rowNumber, hidden: rowHidden, cells };
+            cells = [];
         }
     }
 }
-function collectHiddenColumn(attrs, hiddenColumns) {
-    if (!boolStrict(attrs.hidden))
+function collectColumn(attrs, hiddenColumns, styleResolution, budget) {
+    const span = takeColumnSpan(attrs, budget);
+    if (span === undefined)
         return;
-    const min = numInteger(attrs.min, 1);
-    const max = numInteger(attrs.max, 1);
-    if (min === undefined || max === undefined)
+    const { first: min, last } = span;
+    styleResolution.noteColumnSpan(min, last, numInteger(attrs.style, 0) ?? -1);
+    if (!boolStrict(attrs.hidden))
         return;
-    const last = Math.min(max, MAX_COLUMN);
     for (let index = min; index <= last; index++)
         hiddenColumns.add(index);
 }

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

@@ -1,6 +1,7 @@
 import { parseXml } from '../../xml/xml-read.js';
 import { localName } from '../../xml/xml-scan.js';
-import { RunAccumulator } from './rich-runs.js';
+import { RunAccumulator } from './read-rich-runs.js';
+const SHARED_STRING_EMPTY_CLOSES = new Set(['si']);
 export function parseSharedStrings(xml) {
     if (xml === '')
         return [];
@@ -18,6 +19,6 @@ export function parseSharedStrings(xml) {
                 return;
             strings.push(runs.isRich ? { richText: runs.runs } : runs.plainText);
         },
-    });
+    }, { closeEmptyElements: SHARED_STRING_EMPTY_CLOSES });
     return strings;
 }

package/dist/io/xlsx/read-styles.d.ts

@@ -1,32 +1,2 @@
-import { type Font, type TableStyleTable } from '../../core/style.ts';
-import { type XmlAttributes } from '../../xml/xml-scan.ts';
 import { type StyleTable } from '../style/xf-style.ts';
-export type FontDraft = {
-    -readonly [K in keyof Font]?: Font[K];
-};
 export declare function parseStyleTable(xml: string): StyleTable;
-export declare function applyFontChild(draft: FontDraft, local: string, attrs: XmlAttributes): void;
-/**
- * Extract the custom indexed-color palette (`<colors><indexedColors>`) from styles.xml as verbatim
- * `<rgbColor rgb="…"/>` fragments, or an empty list when the file rides the default palette. Kept raw
- * rather than parsed into RGB and re-serialised, so the exact entries (count, order, casing) a
- * source file declared survive a round-trip and every `indexed="…"` reference keeps its RGB.
- */
-export declare function parseIndexedColors(stylesXml: string): string[];
-/**
- * Extract the most-recently-used colour swatches (`<colors><mruColors>`) from styles.xml as verbatim
- * `<color .../>` fragments, or an empty list when the file declares none. Kept raw for the same reason
- * the indexed palette is: the list is the author's own working set of colours and the model has no
- * use for its contents, only for not losing them.
- */
-export declare function parseMruColors(stylesXml: string): string[];
-/**
- * Extract the `<tableStyles>` block from styles.xml: each `<tableStyle>` definition verbatim, plus the
- * container's nominated `defaultTableStyle`/`defaultPivotStyle`. See {@link TableStyleTable} for why
- * the definitions stay raw while the two names are decoded.
- *
- * A file with no such block, or with the self-closing `count="0"` container Excel writes when it has
- * only defaults to state, yields an empty {@link TableStyleTable.styles} and whichever names it did
- * carry.
- */
-export declare function parseTableStyles(stylesXml: string): TableStyleTable;

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

@@ -1,14 +1,17 @@
-import { ALIGNMENT_FACETS, isBorderStyle, isFillPatternType, isFontScheme, isFontVerticalAlignment, isNamedUnderlineStyle, } from '../../core/style.js';
+import { ALIGNMENT_FACETS, isBorderStyle, isFillPatternType, } from '../../core/style.js';
+import { numFinite, numInteger } from '../../xml/xml-attrs.js';
 import { closeEmptyElements, elementSubtrees, openElements, } from '../../xml/xml-read.js';
-import { boolPresent, boolStrict, boolTristate, localName, numFinite, numInteger, xmlEvents, } from '../../xml/xml-scan.js';
-import { NO_PRESERVED_STYLE_TABLES, numFmtCodeFor, resolveStyleTable, } from '../style/xf-style.js';
+import { boolStrict, boolTristate, localName, xmlEvents, } from '../../xml/xml-scan.js';
+import { NO_PRESERVED_STYLE_TABLES, numFmtCodeFor, protectionFrom, resolveStyleTable, } from '../style/xf-style.js';
 import { parseColor } from './color-xml.js';
+import { applyFontChild } from './font-xml.js';
 const BORDER_EDGE_NAMES = ['left', 'right', 'top', 'bottom', 'diagonal'];
 const BORDER_EDGES = new Set(BORDER_EDGE_NAMES);
 const isBorderEdgeName = (name) => BORDER_EDGES.has(name);
 const STYLE_EMPTY_CLOSES = new Set([
     'font',
     'border',
+    'fill',
     'patternFill',
     'gradientFill',
     'xf',
@@ -109,30 +112,37 @@ function parseFonts(events) {
 }
 function parseFills(events) {
     const fills = [];
-    let pattern = '';
-    let fgColor;
-    let bgColor;
+    let fillDraft = null;
+    let patternDraft = null;
     let gradientDraft = null;
-    let fillSlotAt = -1;
     for (const event of until(events, 'fills')) {
         if (event.kind === 'open') {
             const attrs = event.attrs;
+            const bodyExpected = fillDraft !== null && !fillDraft.bodyRead;
             switch (localName(event.name)) {
                 case 'fill':
-                    fillSlotAt = fills.length;
+                    fillDraft = { body: undefined, bodyRead: false };
                     break;
                 case 'patternFill':
-                    pattern = attrs.patternType ?? 'none';
-                    fgColor = undefined;
-                    bgColor = undefined;
+                    if (!bodyExpected)
+                        break;
+                    patternDraft = {
+                        pattern: attrs.patternType ?? 'none',
+                        fgColor: undefined,
+                        bgColor: undefined,
+                    };
                     break;
                 case 'fgColor':
-                    fgColor = parseColor(attrs);
+                    if (patternDraft !== null)
+                        patternDraft.fgColor = parseColor(attrs);
                     break;
                 case 'bgColor':
-                    bgColor = parseColor(attrs);
+                    if (patternDraft !== null)
+                        patternDraft.bgColor = parseColor(attrs);
                     break;
                 case 'gradientFill':
+                    if (!bodyExpected)
+                        break;
                     gradientDraft = {
                         fill: {
                             type: 'gradient',
@@ -159,7 +169,12 @@ function parseFills(events) {
         else if (event.kind === 'close') {
             switch (localName(event.name)) {
                 case 'patternFill':
-                    fills.push(toFill(pattern, fgColor, bgColor));
+                    if (fillDraft !== null && patternDraft !== null) {
+                        const { pattern, fgColor, bgColor } = patternDraft;
+                        fillDraft.body = toFill(pattern, fgColor, bgColor);
+                        fillDraft.bodyRead = true;
+                        patternDraft = null;
+                    }
                     break;
                 case 'stop':
                     if (gradientDraft !== null && gradientDraft.stopPosition !== null) {
@@ -173,14 +188,18 @@ function parseFills(events) {
                     }
                     break;
                 case 'gradientFill':
-                    if (gradientDraft !== null) {
-                        fills.push(gradientDraft.fill);
+                    if (fillDraft !== null && gradientDraft !== null) {
+                        fillDraft.body = gradientDraft.fill;
+                        fillDraft.bodyRead = true;
                         gradientDraft = null;
                     }
                     break;
                 case 'fill':
-                    if (fills.length === fillSlotAt)
-                        fills.push(undefined);
+                    if (fillDraft !== null)
+                        fills.push(fillDraft.body);
+                    fillDraft = null;
+                    patternDraft = null;
+                    gradientDraft = null;
                     break;
             }
         }
@@ -309,68 +328,6 @@ function parseCellStyles(events) {
     }
     return names;
 }
-export function applyFontChild(draft, local, attrs) {
-    switch (local) {
-        case 'b':
-            draft.bold = boolPresent(attrs.val);
-            break;
-        case 'i':
-            draft.italic = boolPresent(attrs.val);
-            break;
-        case 'strike':
-            draft.strike = boolPresent(attrs.val);
-            break;
-        case 'outline':
-            draft.outline = boolPresent(attrs.val);
-            break;
-        case 'u':
-            draft.underline =
-                attrs.val === undefined
-                    ? true
-                    : attrs.val === 'none'
-                        ? false
-                        : isNamedUnderlineStyle(attrs.val)
-                            ? attrs.val
-                            : true;
-            break;
-        case 'vertAlign':
-            if (attrs.val !== undefined && isFontVerticalAlignment(attrs.val))
-                draft.vertAlign = attrs.val;
-            break;
-        case 'sz': {
-            const size = numFinite(attrs.val);
-            if (size !== undefined)
-                draft.size = size;
-            break;
-        }
-        case 'color':
-            draft.color = parseColor(attrs);
-            break;
-        case 'name':
-        case 'rFont':
-            if (attrs.val !== undefined)
-                draft.name = attrs.val;
-            break;
-        case 'family': {
-            const family = numInteger(attrs.val);
-            if (family !== undefined)
-                draft.family = family;
-            break;
-        }
-        case 'charset': {
-            const charset = numInteger(attrs.val);
-            if (charset !== undefined)
-                draft.charset = charset;
-            break;
-        }
-        case 'scheme':
-            if (attrs.val !== undefined && isFontScheme(attrs.val))
-                draft.scheme = attrs.val;
-            break;
-        default:
-            break;
-    }
-}
 function resolveNumFmt(raw, custom) {
     const id = numInteger(raw, 1);
     return id === undefined ? undefined : numFmtCodeFor(id, custom);
@@ -426,36 +383,26 @@ function assignAlignmentToken(out, key, raw) {
     out[key] = raw;
 }
 function parseProtection(attrs) {
-    const out = {};
-    if (boolTristate(attrs.locked) === false)
-        out.locked = false;
-    if (boolStrict(attrs.hidden))
-        out.hidden = true;
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-export function parseIndexedColors(stylesXml) {
-    return capturedFragments(stylesXml, 'indexedColors');
-}
-export function parseMruColors(stylesXml) {
-    return capturedFragments(stylesXml, 'mruColors');
-}
-export function parseTableStyles(stylesXml) {
-    const { fragments, attributes } = elementSubtrees(stylesXml, new Map([['tableStyles', 'tableStyle']]));
-    return buildTableStyleTable(stylesXml, fragments.get('tableStyles') ?? [], attributes.get('tableStyles'));
+    return protectionFrom({ locked: boolTristate(attrs.locked), hidden: boolStrict(attrs.hidden) });
 }
 function buildTableStyleTable(stylesXml, styles, containerAttrs) {
-    const table = { styles: [...styles] };
+    const table = { styles: styles.map((xml) => ({ name: tableStyleNameOf(xml), xml })) };
     if (containerAttrs?.defaultTableStyle !== undefined) {
         table.defaultTableStyle = containerAttrs.defaultTableStyle;
     }
     if (containerAttrs?.defaultPivotStyle !== undefined) {
         table.defaultPivotStyle = containerAttrs.defaultPivotStyle;
     }
-    const namespaces = fragmentNamespaces(stylesXml, table.styles);
+    const namespaces = fragmentNamespaces(stylesXml, styles);
     if (namespaces.length > 0)
         table.namespaces = namespaces;
     return table;
 }
+function tableStyleNameOf(fragment) {
+    for (const { attrs } of openElements(fragment, 'tableStyle'))
+        return attrs.name ?? '';
+    return '';
+}
 function fragmentNamespaces(stylesXml, fragments) {
     if (fragments.length === 0)
         return [];
@@ -492,10 +439,3 @@ const PRESERVED_SUBTREES = new Map([
     ['mruColors', 'color'],
     ['tableStyles', 'tableStyle'],
 ]);
-function capturedFragments(xml, container) {
-    const child = PRESERVED_SUBTREES.get(container);
-    if (child === undefined)
-        return [];
-    const { fragments } = elementSubtrees(xml, new Map([[container, child]]));
-    return [...(fragments.get(container) ?? [])];
-}

package/dist/io/xlsx/read-workbook-xml.d.ts

@@ -0,0 +1,42 @@
+import { type WorkbookProtection } from '../../core/workbook-protection.ts';
+import type { DefinedName, Workbook, WorkbookView } from '../../core/workbook.ts';
+import { type WorksheetState } from '../../core/worksheet.ts';
+import { type CollectingPass, type SaxPass } from '../../xml/xml-read.ts';
+export interface SheetEntry {
+    readonly name: string;
+    readonly relId: string;
+    readonly state?: WorksheetState['state'];
+}
+export declare function workbookSheetsPass(): CollectingPass<SheetEntry[]>;
+export declare function workbookProtectionPass(): CollectingPass<WorkbookProtection | undefined>;
+/**
+ * Apply `<workbookPr>`: the workbook's date system and its VBA code name.
+ *
+ * Both are read for the same reason and it is not that the model computes anything from them. The
+ * date system is what every serial in every sheet counts from, so a workbook read without it is read
+ * with every date four years and a day out; the code name is what the VBA project means by
+ * `ThisWorkbook`, so a `.xlsm` written back without it has had its macros unbound from its document.
+ * Neither has any signal in the file other than this element.
+ */
+export declare function workbookPropertiesPass(workbook: Workbook): SaxPass;
+export declare function workbookViewPass(view: WorkbookView): SaxPass;
+export interface DefinedNamesPass extends SaxPass {
+    /**
+     * The names, scoped against the sheet order.
+     *
+     * The order is supplied here rather than to the pass, and that is what lets the names ride the same
+     * scan as everything else this part carries. A scoped name's `localSheetId` indexes the sheets in
+     * declaration order, and the model's answer for index n is known only after the sheet loop has run
+     * and repaired the names it had to; resolving during the scan would have forced a second one.
+     */
+    result(sheetOrder: readonly string[]): DefinedName[];
+    /**
+     * Every name the part defines, whatever its scope, as `definedNameKeys` spells them. Known once the
+     * scan ends, before any sheet is read, and needed then: whether a function a formula passes as a value
+     * sheds its `_xleta.` depends on them.
+     */
+    spellings(): ReadonlySet<string>;
+}
+export declare function definedNamesPass(): DefinedNamesPass;
+export declare function applyCoreProperties(workbook: Workbook, xml: string): void;
+export declare function applyAppProperties(workbook: Workbook, xml: string): void;