@shbernal/ts-xlsx 3.0.0 → 3.1.0

package/dist/io/xlsx/write-stream.js

@@ -6,9 +6,12 @@ import { encodeAddress, tryDecodeCellRef } from '../../core/address.js';
 import { INTERNAL } from '../../core/internal.js';
 import { isSharedFormulaValue } from '../../core/value.js';
 import { Workbook } from '../../core/workbook.js';
-import { AuthoringError } from '../../errors.js';
+import { AuthoringError, quoted } from '../../errors.js';
 import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
-import { buildColumnDefaults, buildPackageParts, createStyleRegistry, Extent, renderRow, } from './write.js';
+import { collectNotes } from './comments.js';
+import { collectHyperlinks } from './hyperlinks.js';
+import { buildColumnDefaults, Extent, renderRow, } from './row-xml.js';
+import { buildPackageParts, createStyleRegistry } from './write.js';
 export class StreamedRow {
     #cells;
     #sheet;
@@ -26,7 +29,7 @@ export class StreamedRow {
         if (this.#committed)
             return;
         this.#committed = true;
-        this.#sheet?.flushRow(this.#number, this.#cells);
+        this.#sheet?.[INTERNAL].flushRow(this.#number, this.#cells);
     }
 }
 export class WorksheetStreamWriter {
@@ -39,12 +42,21 @@ export class WorksheetStreamWriter {
     #flushedRows = [];
     #flushedNumbers = new Set();
     #extent = new Extent();
-    #maxRowOutlineLevel = 0;
-    constructor(sheet, eager, styles) {
+    #rowOutline = new Map();
+    #hyperlinks = [];
+    #notes = [];
+    #dateEpoch;
+    constructor(sheet, eager, styles, dateEpoch) {
         this.#sheet = sheet;
         this.#eager = eager;
         this.#styles = styles;
+        this.#dateEpoch = dateEpoch;
     }
+    static [INTERNAL] = {
+        create(sheet, eager, styles, dateEpoch) {
+            return new WorksheetStreamWriter(sheet, eager, styles, dateEpoch);
+        },
+    };
     get name() {
         return this.#sheet.name;
     }
@@ -77,45 +89,53 @@ export class WorksheetStreamWriter {
         });
         return cells;
     }
-    flushRow(number, cells) {
+    #flushRow(number, cells) {
         for (const cell of cells) {
             if (isSharedFormulaValue(cell.value)) {
-                throw new AuthoringError(`row ${number} of streamed sheet "${this.#sheet.name}" carries a shared-formula cell; a ` +
+                throw new AuthoringError(`row ${number} of streamed sheet ${quoted(this.#sheet.name)} carries a shared-formula cell; a ` +
                     'committed row is finalised before the sheet is planned, so author shared formulas through ' +
                     'getCell (leaving the row uncommitted) instead');
             }
         }
         this.#columnDefaults ??= buildColumnDefaults(this.#sheet);
         const properties = this.#sheet.getRow(number).properties;
-        this.#maxRowOutlineLevel = Math.max(this.#maxRowOutlineLevel, properties?.outlineLevel ?? 0);
-        const { xml, minCol, maxCol } = renderRow({ number, cells, properties }, {
+        this.#rowOutline.set(number, {
+            outlineLevel: properties?.outlineLevel ?? 0,
+            hidden: properties?.hidden ?? false,
+        });
+        this.#hyperlinks.push(...collectHyperlinks(cells));
+        this.#notes.push(...collectNotes(cells));
+        const { xml, attrs, minCol, maxCol } = renderRow({ number, cells, properties }, {
             columnDefaults: this.#columnDefaults,
             styles: this.#styles,
             sharedStrings: null,
             sharedRoles: new Map(),
             collapsedSummaries: new Set(),
+            dateEpoch: this.#dateEpoch,
         });
         if (xml !== '') {
-            this.#flushedRows.push({ number, xml });
+            this.#flushedRows.push({ number, xml, attrs });
             this.#extent.add(number, minCol, maxCol);
         }
         this.#flushedNumbers.add(number);
         this.#sheet[INTERNAL].evictRow(number);
     }
-    flushedSheet() {
+    #flushedSheet() {
         if (this.#flushedRows.length === 0)
             return undefined;
         return {
             rows: this.#flushedRows,
             extent: this.#extent,
-            maxRowOutlineLevel: this.#maxRowOutlineLevel,
+            rowOutline: this.#rowOutline,
+            hyperlinks: this.#hyperlinks,
+            notes: this.#notes,
         };
     }
     getCell(reference) {
         this.#assertOpen();
         const target = tryDecodeCellRef(reference);
         if (target !== undefined && this.#flushedNumbers.has(target.row)) {
-            throw new AuthoringError(`cell ${reference} of streamed sheet "${this.#sheet.name}" is in row ${target.row}, which is ` +
+            throw new AuthoringError(`cell ${reference} of streamed sheet ${quoted(this.#sheet.name)} is in row ${target.row}, which is ` +
                 'already committed: its bytes are written and its cells released, so this value could only ' +
                 'be emitted as a second row with that number. Style a row before committing it.');
         }
@@ -153,9 +173,15 @@ export class WorksheetStreamWriter {
     get model() {
         return this.#sheet;
     }
+    [INTERNAL] = {
+        flushRow: (number, cells) => {
+            this.#flushRow(number, cells);
+        },
+        flushedSheet: () => this.#flushedSheet(),
+    };
     #assertOpen() {
         if (this.#committed) {
-            throw new AuthoringError(`worksheet "${this.#sheet.name}" is already committed: its rows are finalised and no more can be added`);
+            throw new AuthoringError(`worksheet ${quoted(this.#sheet.name)} is already committed: its rows are finalised and no more can be added`);
         }
     }
 }
@@ -172,6 +198,8 @@ export class WorkbookStreamWriter {
     constructor(options = {}) {
         this.#writeOptions = { useSharedStrings: options.useSharedStrings ?? false };
         this.#eager = !this.#writeOptions.useSharedStrings;
+        if (options.dateEpoch !== undefined)
+            this.#workbook.dateEpoch = options.dateEpoch;
         this.#styles = createStyleRegistry(this.#workbook);
         if (options.stream && options.filename) {
             throw new AuthoringError('provide either a stream or a filename to the streaming writer, not both');
@@ -192,7 +220,7 @@ export class WorkbookStreamWriter {
     }
     addWorksheet(name, options = {}) {
         this.#assertOpen('no more worksheets can be added');
-        const sheet = new WorksheetStreamWriter(this.#workbook.addWorksheet(name, options), this.#eager, this.#styles);
+        const sheet = WorksheetStreamWriter[INTERNAL].create(this.#workbook.addWorksheet(name, options), this.#eager, this.#styles, this.#workbook.dateEpoch);
         this.#sheets.push(sheet);
         return sheet;
     }
@@ -205,12 +233,13 @@ export class WorkbookStreamWriter {
             this.#workbook.fullCalcOnLoad = true;
         const flushed = new Map();
         for (const sheet of this.#sheets) {
-            const sheetFlushed = sheet.flushedSheet();
+            const sheetFlushed = sheet[INTERNAL].flushedSheet();
             if (sheetFlushed)
                 flushed.set(sheet.model, sheetFlushed);
         }
         const owned = this.#stream;
         const sink = this.#sink;
+        const collect = sink === undefined || owned !== undefined;
         const sinkSettled = sink ? settleOnFinish(sink) : undefined;
         try {
             const parts = buildPackageParts(this.#workbook, {
@@ -221,7 +250,7 @@ export class WorkbookStreamWriter {
             const bytes = await streamZipPackage(parts, (chunk) => {
                 owned?.write(chunk);
                 sink?.write(chunk);
-            });
+            }, collect);
             owned?.end();
             sink?.end();
             await sinkSettled;
@@ -247,7 +276,7 @@ function settleOnFinish(sink) {
         sink.once('error', reject);
     });
 }
-function streamZipPackage(parts, onChunk) {
+function streamZipPackage(parts, onChunk, collect) {
     return new Promise((resolve, reject) => {
         const collected = [];
         const zip = new Zip((err, chunk, final) => {
@@ -255,10 +284,11 @@ function streamZipPackage(parts, onChunk) {
                 reject(err);
                 return;
             }
-            collected.push(chunk);
+            if (collect)
+                collected.push(chunk);
             onChunk(chunk);
             if (final)
-                resolve(concat(collected));
+                resolve(collect ? concat(collected) : undefined);
         });
         for (const [name, data] of Object.entries(parts)) {
             const entry = new ZipDeflate(name, { level: 6 });

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

@@ -1,8 +1,7 @@
 import type { Workbook } from '../../core/workbook.ts';
 import type { Worksheet } from '../../core/worksheet.ts';
+import type { FlushedSheet } from './row-xml.ts';
 import { StyleRegistry } from './styles.ts';
-import { type FlushedSheet } from './worksheet-xml.ts';
-export { buildColumnDefaults, Extent, type FlushedSheet, type RowRenderContext, renderRow, } from './worksheet-xml.ts';
 /** Options controlling how {@link writeXlsx} serialises a workbook. */
 export interface WriteOptions {
     /**

package/dist/io/xlsx/write.js

@@ -1,12 +1,13 @@
 import { strToU8, zip, zipSync } from 'fflate';
-import { AuthoringError } from '../../errors.js';
+import { AuthoringError, InternalError, quoted } from '../../errors.js';
+import { isRelType } from '../../rel-type.js';
 import { relativePartPath, relsPathFor, THEME_PART_PATH } from '../opc/part-paths.js';
 import { relsPartXml } from '../opc/rels.js';
 import { FIXED_ENTRY_MTIME } from '../opc/zip-mtime.js';
 import { collectComments, commentsXml, vmlDrawingXml } from './comments.js';
-import { collectHyperlinks, planHyperlinks } from './hyperlinks.js';
+import { collectHyperlinks, liveCells, planHyperlinks } from './hyperlinks.js';
 import { drawingRelsXml, drawingXml } from './images.js';
-import { planMedia, planPreservedParts, SheetRelIds, } from './package-plan.js';
+import { planMedia, planPreservedParts, RelIdAllocator, } from './package-plan.js';
 import { APP_PROPS_PART, commentsPart, CORE_PROPS_PART, drawingPart, mediaPart, PERSONS_PART, pivotCacheDefinitionPart, pivotCacheRecordsPart, pivotTablePart, printerSettingsPart, SHARED_STRINGS_PART, STYLES_PART, tablePart, threadedCommentsPart, vmlDrawingPart, WORKBOOK_PART, worksheetPart, } from './part-names.js';
 import { pivotCacheDefinitionXml, pivotCacheRecordsXml, pivotTableXml } from './pivot.js';
 import { REL } from './relationships.js';
@@ -15,9 +16,8 @@ import { StyleRegistry } from './styles.js';
 import { tableXml } from './tables.js';
 import { applyThemeOverrides, DEFAULT_THEME_XML } from './theme-xml.js';
 import { personsXml, threadedCommentsXml } from './threaded-comments.js';
-import { appPropsXml, contentTypesXml, corePropsXml, FIXED_WORKBOOK_REL_COUNT, rootRelsXml, workbookRelsXml, workbookXml, } from './workbook-xml.js';
-import { worksheetRelsXml, worksheetXml, } from './worksheet-xml.js';
-export { buildColumnDefaults, Extent, renderRow, } from './worksheet-xml.js';
+import { appPropsXml, contentTypesXml, corePropsXml, rootRelsXml, workbookRelsXml, workbookXml, } from './workbook-xml.js';
+import { worksheetRelsXml, worksheetXml } from './worksheet-xml.js';
 export function writeXlsx(workbook, options = {}) {
     return zipSync(buildPackageParts(workbook, options), { level: 6, mtime: FIXED_ENTRY_MTIME });
 }
@@ -49,8 +49,8 @@ export function createStyleRegistry(workbook) {
     return styles;
 }
 function planSheet(context) {
-    const { sheet, index, media, preserved, numbering } = context;
-    const rels = new SheetRelIds();
+    const { sheet, index, media, preserved, numbering, flushed } = context;
+    const rels = new RelIdAllocator();
     const tables = sheet.tables.map((table) => ({
         table,
         number: ++numbering.table,
@@ -70,7 +70,7 @@ function planSheet(context) {
         drawing = { number: ++numbering.drawing, relId: rels.next(), images };
     }
     const threads = sheet.commentThreads.filter((thread) => thread.comments.length > 0);
-    const sheetComments = collectComments(sheet, threads);
+    const sheetComments = collectComments(liveCells(sheet), threads, flushed?.notes ?? []);
     const comments = sheetComments.length === 0
         ? null
         : {
@@ -82,7 +82,7 @@ function planSheet(context) {
     const threadedComments = threads.length === 0 ? null : { number: index + 1, threads, relId: rels.next() };
     const printerData = sheet.pageSetup.printerSettings;
     const printerSettings = printerData === undefined ? null : { number: index + 1, data: printerData, relId: rels.next() };
-    const hyperlinks = planHyperlinks(collectHyperlinks(sheet), rels);
+    const hyperlinks = planHyperlinks([...collectHyperlinks(liveCells(sheet)), ...(flushed?.hyperlinks ?? [])].sort((a, b) => a.row - b.row || a.col - b.col), rels);
     let background = null;
     if (sheet.backgroundImageId !== undefined) {
         const { number, image } = media.resolve(sheet.backgroundImageId);
@@ -119,7 +119,7 @@ function resolveSheetReferences(plan) {
     const preservedDrawingRelId = refs.find((ref) => ref.element === 'drawing')?.relId ?? null;
     const legacyDrawingHFRelId = refs.find((ref) => ref.element === 'legacyDrawingHF')?.relId ?? null;
     const slicerRelIds = refs
-        .filter((ref) => ref.relType.endsWith('/slicer'))
+        .filter((ref) => isRelType(ref.relType, 'slicer'))
         .map((ref) => ref.relId);
     return {
         drawingRelId: plan.drawing?.relId ?? preservedDrawingRelId,
@@ -132,25 +132,31 @@ function resolveSheetReferences(plan) {
 }
 function assignWorkbookRelIds(context) {
     const { sheetCount, hasSharedStrings, hasPersons, preservedWorkbook, pivots } = context;
-    const modeledCount = sheetCount + FIXED_WORKBOOK_REL_COUNT + (hasSharedStrings ? 1 : 0);
-    const personsRelId = hasPersons ? `rId${modeledCount + 1}` : null;
-    const preservedBase = modeledCount + (personsRelId === null ? 0 : 1);
-    const preservedWorkbookRels = preservedWorkbook.map((ref, i) => ({
-        ...ref,
-        relId: `rId${preservedBase + 1 + i}`,
-    }));
-    const pivotBase = preservedBase + preservedWorkbook.length;
-    pivots.forEach((pivot, i) => {
-        pivot.workbookRelId = `rId${pivotBase + 1 + i}`;
-    });
-    return { personsRelId, preservedWorkbookRels };
+    const ids = new RelIdAllocator();
+    const sheetRelIds = Array.from({ length: sheetCount }, () => ids.next());
+    const stylesRelId = ids.next();
+    const themeRelId = ids.next();
+    const sharedStringsRelId = hasSharedStrings ? ids.next() : null;
+    const personsRelId = hasPersons ? ids.next() : null;
+    const preservedWorkbookRels = preservedWorkbook.map((ref) => ({ ...ref, relId: ids.next() }));
+    for (const pivot of pivots)
+        pivot.workbookRelId = ids.next();
+    return {
+        sheetRelIds,
+        stylesRelId,
+        themeRelId,
+        sharedStringsRelId,
+        personsRelId,
+        preservedWorkbookRels,
+    };
 }
-function planPackage(workbook, sheets) {
+function planPackage(workbook, sheets, flushed) {
     const media = planMedia(workbook, sheets);
     const generatedDrawingCount = sheets.filter((sheet) => sheet.images.length > 0).length;
-    const preserved = planPreservedParts(workbook, generatedDrawingCount, media.parts.length);
+    const generatedPivotCount = sheets.reduce((total, sheet) => total + sheet.pivotTables.length, 0);
+    const preserved = planPreservedParts(workbook, generatedDrawingCount, media.parts.length, generatedPivotCount);
     const numbering = { table: 0, drawing: 0, pivot: 0 };
-    const perSheet = sheets.map((sheet, index) => planSheet({ sheet, index, media, preserved, numbering }));
+    const perSheet = sheets.map((sheet, index) => planSheet({ sheet, index, media, preserved, numbering, flushed: flushed?.get(sheet) }));
     return {
         media,
         preserved,
@@ -159,10 +165,21 @@ function planPackage(workbook, sheets) {
         allPivots: perSheet.flatMap((plan) => plan.pivots),
     };
 }
-function serialiseSheets(workbook, sheets, plan, styles, sharedStrings, flushed) {
+function serialiseSheets(context) {
+    const { workbook, sheets, plan, styles, sharedStrings, flushed } = context;
     return sheets.map((sheet, i) => {
         const sheetPlan = plan.perSheet[i];
-        return worksheetXml(sheet, sheetPlan.tables, styles, resolveSheetReferences(sheetPlan), sheetPlan.hyperlinks, sharedStrings, i === workbook.activeTabIndex, flushed?.get(sheet));
+        return worksheetXml({
+            sheet,
+            tables: sheetPlan.tables,
+            styles,
+            references: resolveSheetReferences(sheetPlan),
+            hyperlinks: sheetPlan.hyperlinks,
+            sharedStrings,
+            dateEpoch: workbook.dateEpoch,
+            active: i === workbook.activeTabIndex,
+            flushed: flushed?.get(sheet),
+        });
     });
 }
 function emitPackageParts(context) {
@@ -174,43 +191,56 @@ function emitPackageParts(context) {
     const printerSettingsNumbers = numbersOf(perSheet, (sheetPlan) => sheetPlan.printerSettings);
     const threadedCommentNumbers = numbersOf(perSheet, (sheetPlan) => sheetPlan.threadedComments);
     const persons = threadedCommentNumbers.length === 0 ? [] : workbook.persons;
-    const { personsRelId, preservedWorkbookRels } = assignWorkbookRelIds({
+    const workbookRels = assignWorkbookRelIds({
         sheetCount: sheets.length,
         hasSharedStrings,
         hasPersons: persons.length > 0,
         preservedWorkbook: preserved.workbook,
         pivots: allPivots,
     });
-    const files = {
-        '[Content_Types].xml': strToU8(contentTypesXml(sheets.length, allTables, commentNumbers, drawingNumbers, printerSettingsNumbers, media.extensions, hasSharedStrings, preserved.parts, allPivots, preservedWorkbookRels, threadedCommentNumbers, persons.length > 0)),
-        '_rels/.rels': strToU8(rootRelsXml(preserved.root)),
-        [CORE_PROPS_PART]: strToU8(corePropsXml(workbook.properties)),
-        [APP_PROPS_PART]: strToU8(appPropsXml(workbook.properties)),
-        [WORKBOOK_PART]: strToU8(workbookXml(workbook, preservedWorkbookRels, allPivots)),
-        [relsPathFor(WORKBOOK_PART)]: strToU8(workbookRelsXml(sheets.length, hasSharedStrings, personsRelId, preservedWorkbookRels, allPivots)),
-        [STYLES_PART]: strToU8(styles.toXml()),
-    };
+    const { preservedWorkbookRels } = workbookRels;
+    const files = new PackageFiles();
+    files.add('[Content_Types].xml', strToU8(contentTypesXml({
+        sheetCount: sheets.length,
+        tables: allTables,
+        commentNumbers,
+        drawingNumbers,
+        printerSettingsNumbers,
+        mediaExtensions: media.extensions,
+        hasSharedStrings,
+        preservedParts: preserved.parts,
+        pivots: allPivots,
+        preservedWorkbookRefs: preservedWorkbookRels,
+        threadedCommentNumbers,
+        hasPersons: persons.length > 0,
+    })));
+    files.add('_rels/.rels', strToU8(rootRelsXml(preserved.root)));
+    files.add(CORE_PROPS_PART, strToU8(corePropsXml(workbook.properties)));
+    files.add(APP_PROPS_PART, strToU8(appPropsXml(workbook.properties)));
+    files.add(WORKBOOK_PART, strToU8(workbookXml(workbook, workbookRels, allPivots)));
+    files.add(relsPathFor(WORKBOOK_PART), strToU8(workbookRelsXml(workbookRels, allPivots)));
+    files.add(STYLES_PART, strToU8(styles.toXml()));
     if (!preserved.themeEmitted) {
         const overrides = workbook.themeOverrides;
-        files[THEME_PART_PATH] = strToU8(overrides === undefined
+        files.add(THEME_PART_PATH, strToU8(overrides === undefined
             ? DEFAULT_THEME_XML
-            : applyThemeOverrides(DEFAULT_THEME_XML, overrides));
+            : applyThemeOverrides(DEFAULT_THEME_XML, overrides)));
     }
     if (hasSharedStrings) {
-        files[SHARED_STRINGS_PART] = strToU8(sharedStrings.toXml());
+        files.add(SHARED_STRINGS_PART, strToU8(sharedStrings.toXml()));
     }
     if (persons.length > 0)
-        files[PERSONS_PART] = strToU8(personsXml(persons));
+        files.add(PERSONS_PART, strToU8(personsXml(persons)));
     for (const part of media.parts) {
-        files[mediaPart(part.number, part.extension)] = part.data;
+        files.add(mediaPart(part.number, part.extension), part.data);
     }
     emitSheetParts(files, perSheet, sheetXml);
     for (const { table, number } of allTables) {
-        files[tablePart(number)] = strToU8(tableXml(table, number));
+        files.add(tablePart(number), strToU8(tableXml(table, number)));
     }
     emitPivotParts(files, allPivots);
     emitPreservedParts(files, preserved.parts);
-    return files;
+    return files.toRecord();
 }
 export function buildPackageParts(workbook, options = {}) {
     const sheets = workbook.worksheets;
@@ -219,15 +249,34 @@ export function buildPackageParts(workbook, options = {}) {
     }
     const sharedStrings = options.useSharedStrings ? new SharedStringTable() : null;
     const styles = options.styles ?? createStyleRegistry(workbook);
-    const plan = planPackage(workbook, sheets);
-    const sheetXml = serialiseSheets(workbook, sheets, plan, styles, sharedStrings, options.flushed);
+    const plan = planPackage(workbook, sheets, options.flushed);
+    const sheetXml = serialiseSheets({
+        workbook,
+        sheets,
+        plan,
+        styles,
+        sharedStrings,
+        flushed: options.flushed,
+    });
     return emitPackageParts({ workbook, sheets, plan, styles, sharedStrings, sheetXml });
 }
+class PackageFiles {
+    #files = Object.create(null);
+    add(path, bytes) {
+        if (path in this.#files) {
+            throw new InternalError(`two package parts claim the path ${quoted(path)}`);
+        }
+        this.#files[path] = bytes;
+    }
+    toRecord() {
+        return this.#files;
+    }
+}
 function emitSheetParts(files, perSheet, sheetXml) {
     perSheet.forEach((plan, i) => {
         const { tables, drawing, comments, threadedComments, printerSettings, background, hyperlinks, preservedRefs, pivots, } = plan;
         const hasExternalHyperlink = hyperlinks.some((link) => link.relId !== undefined);
-        files[worksheetPart(i + 1)] = strToU8(sheetXml[i]);
+        files.add(worksheetPart(i + 1), strToU8(sheetXml[i]));
         if (tables.length > 0 ||
             drawing !== null ||
             comments !== null ||
@@ -237,23 +286,23 @@ function emitSheetParts(files, perSheet, sheetXml) {
             hasExternalHyperlink ||
             preservedRefs.length > 0 ||
             pivots.length > 0) {
-            files[relsPathFor(worksheetPart(i + 1))] = strToU8(worksheetRelsXml(tables, drawing, comments, threadedComments, printerSettings, background, hyperlinks, preservedRefs, pivots));
+            files.add(relsPathFor(worksheetPart(i + 1)), strToU8(worksheetRelsXml(plan)));
         }
         if (printerSettings !== null) {
-            files[printerSettingsPart(printerSettings.number)] = printerSettings.data;
+            files.add(printerSettingsPart(printerSettings.number), printerSettings.data);
         }
         if (drawing !== null) {
             const drawingPath = drawingPart(drawing.number);
-            files[drawingPath] = strToU8(drawingXml(drawing.images));
+            files.add(drawingPath, strToU8(drawingXml(drawing.images)));
             const targets = drawing.images.map((image) => relativePartPath(drawingPath, mediaPart(image.mediaNumber, image.extension)));
-            files[relsPathFor(drawingPath)] = strToU8(drawingRelsXml(targets));
+            files.add(relsPathFor(drawingPath), strToU8(drawingRelsXml(targets)));
         }
         if (comments !== null) {
-            files[commentsPart(comments.number)] = strToU8(commentsXml(comments.comments));
-            files[vmlDrawingPart(comments.number)] = strToU8(vmlDrawingXml(comments.comments));
+            files.add(commentsPart(comments.number), strToU8(commentsXml(comments.comments)));
+            files.add(vmlDrawingPart(comments.number), strToU8(vmlDrawingXml(comments.comments)));
         }
         if (threadedComments !== null) {
-            files[threadedCommentsPart(threadedComments.number)] = strToU8(threadedCommentsXml(threadedComments.threads));
+            files.add(threadedCommentsPart(threadedComments.number), strToU8(threadedCommentsXml(threadedComments.threads)));
         }
     });
 }
@@ -262,30 +311,21 @@ function emitPivotParts(files, allPivots) {
         const { number, cacheId, table } = pivot;
         const tablePath = pivotTablePart(number);
         const definitionPath = pivotCacheDefinitionPart(number);
-        files[tablePath] = strToU8(pivotTableXml(table, `PivotTable${number}`, cacheId));
-        files[relsPathFor(tablePath)] = strToU8(relsPartXml([
-            {
-                id: 'rId1',
-                type: REL.pivotCacheDefinition,
-                target: relativePartPath(tablePath, definitionPath),
-            },
-        ]));
-        files[definitionPath] = strToU8(pivotCacheDefinitionXml(table));
-        files[relsPathFor(definitionPath)] = strToU8(relsPartXml([
-            {
-                id: 'rId1',
-                type: REL.pivotCacheRecords,
-                target: relativePartPath(definitionPath, pivotCacheRecordsPart(number)),
-            },
-        ]));
-        files[pivotCacheRecordsPart(number)] = strToU8(pivotCacheRecordsXml(table));
+        files.add(tablePath, strToU8(pivotTableXml(table, `PivotTable${number}`, cacheId)));
+        addSingleRelPart(files, tablePath, REL.pivotCacheDefinition, definitionPath);
+        files.add(definitionPath, strToU8(pivotCacheDefinitionXml(table)));
+        addSingleRelPart(files, definitionPath, REL.pivotCacheRecords, pivotCacheRecordsPart(number));
+        files.add(pivotCacheRecordsPart(number), strToU8(pivotCacheRecordsXml(table)));
     }
 }
+function addSingleRelPart(files, from, type, to) {
+    files.add(relsPathFor(from), strToU8(relsPartXml([{ id: 'rId1', type, target: relativePartPath(from, to) }])));
+}
 function emitPreservedParts(files, parts) {
     for (const part of parts) {
-        files[part.path] = part.bytes;
+        files.add(part.path, part.bytes);
         if (part.relsPath !== null && part.relsXml !== null) {
-            files[part.relsPath] = strToU8(part.relsXml);
+            files.add(part.relsPath, strToU8(part.relsXml));
         }
     }
 }

package/dist/rel-type.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Does a relationship Type name this class of part?
+ *
+ * A Type is a URI whose last segment names the part class, and the namespace in front of it varies by
+ * relationship family and by the schema version a producer wrote against. So the match is on that
+ * last segment.
+ *
+ * **The separator is the load-bearing character.** `/slicer` and `slicer` are not the same test:
+ * without the slash, `slicer` matches `slicerCache`, `table` matches `pivotTable`, and a lookup
+ * quietly gathers a part class nobody asked for. Every caller used to spell the slash itself, ten
+ * times over, with nowhere to say why it was there.
+ */
+export declare function isRelType(type: string, name: string): boolean;
+/** {@link isRelType} against several part classes at once, for the predicates that partition
+ * relationships into "modeled", "preserved verbatim", and "dropped". */
+export declare function isAnyRelType(type: string, ...names: readonly string[]): boolean;

package/dist/rel-type.js

@@ -0,0 +1,6 @@
+export function isRelType(type, name) {
+    return type.endsWith(`/${name}`);
+}
+export function isAnyRelType(type, ...names) {
+    return names.some((name) => isRelType(type, name));
+}

package/dist/token-set.d.ts

@@ -13,3 +13,16 @@
  * expression instead of as its members.
  */
 export declare function tokenSet<T extends string>(members: Record<T, true>): (value: string) => value is T;
+/**
+ * {@link tokenSet} for a union whose members are also needed as an ordered *list*, because a binary
+ * serialisation indexes one.
+ *
+ * The record form's whole guarantee is that a member cannot be omitted, and a list gives that up: it
+ * can name only members of the union, but it can name fewer. So a caller here owes an explicit proof
+ * of set equality in both directions, which is what `FILL_PATTERNS_IN_SCHEMA_ORDER` carries beside
+ * itself. That is a worse guarantee than the record's, taken deliberately: the alternative is the
+ * arrangement it replaced, where the union, the guard's table and the binary codec's index list were
+ * three hand-maintained copies of one enumeration and only two of them were checked against each
+ * other.
+ */
+export declare function tokenSetOf<T extends string>(members: readonly T[]): (value: string) => value is T;

package/dist/token-set.js

@@ -1,4 +1,7 @@
 export function tokenSet(members) {
-    const set = new Set(Object.keys(members));
+    return tokenSetOf(Object.keys(members));
+}
+export function tokenSetOf(members) {
+    const set = new Set(members);
     return (value) => set.has(value);
 }

package/dist/vba/bytes.d.ts

@@ -1,11 +1,20 @@
-export { concat } from '../bytes.ts';
+export { concat, decodeUtf16le } from '../bytes.ts';
 /** Read a little-endian `uint16`. @throws {VbaParseError} if the two bytes are not both in `buf`. */
 export declare function readU16(buf: Uint8Array, at: number): number;
 /** Read a little-endian `uint32`. @throws {VbaParseError} if the four bytes are not all in `buf`. */
 export declare function readU32(buf: Uint8Array, at: number): number;
 /**
- * Decode UTF-16LE code units: the encoding [MS-CFB] uses for directory-entry names and [MS-OVBA] for
- * every "Unicode" name field. A trailing odd byte is dropped: these fields are length-prefixed by the
- * producer and a half code unit carries nothing to decode.
+ * Write a little-endian `uint16` over bytes already in `buf`. The value is asserted rather than
+ * masked: a caller that arrived at `-1` or `0x1_0000` has miscounted something, and silently storing
+ * `0xffff` turns that into a `dir` stream declaring 65,535 modules.
  */
-export declare function decodeUtf16le(bytes: Uint8Array): string;
+export declare function writeU16(buf: Uint8Array, at: number, value: number): void;
+/**
+ * Replace `src[start..end)` with `insert`, returning a new array.
+ *
+ * The three record edits the project editor makes are all this shape: splice a MODULE record block in,
+ * cut one out, cut a PROJECTwm entry out. Each was an allocate-and-copy-around written out longhand,
+ * and each had to get the same three offsets right; saying it once means the arithmetic is checked
+ * once. Passing no `insert` is a pure deletion, and `start === end` a pure insertion.
+ */
+export declare function spliceBytes(src: Uint8Array, start: number, end: number, insert?: Uint8Array): Uint8Array;

package/dist/vba/bytes.js

@@ -1,4 +1,4 @@
-export { concat } from '../bytes.js';
+export { concat, decodeUtf16le } from '../bytes.js';
 import { VbaParseError } from './errors.js';
 function truncated(at, need, length) {
     return new VbaParseError(`read of ${need} bytes at offset ${at} runs past the end of a ${length}-byte buffer`);
@@ -20,10 +20,20 @@ export function readU32(buf, at) {
     }
     return (b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)) >>> 0;
 }
-export function decodeUtf16le(bytes) {
-    let s = '';
-    for (let i = 0; i + 1 < bytes.length; i += 2) {
-        s += String.fromCharCode(readU16(bytes, i));
+export function writeU16(buf, at, value) {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
+        throw new VbaParseError(`${value} does not fit the uint16 at offset ${at}`);
     }
-    return s;
+    if (at + 1 >= buf.length)
+        throw truncated(at, 2, buf.length);
+    buf[at] = value & 0xff;
+    buf[at + 1] = (value >> 8) & 0xff;
+}
+export function spliceBytes(src, start, end, insert = EMPTY) {
+    const out = new Uint8Array(src.length - (end - start) + insert.length);
+    out.set(src.subarray(0, start), 0);
+    out.set(insert, start);
+    out.set(src.subarray(end), start + insert.length);
+    return out;
 }
+const EMPTY = new Uint8Array(0);

package/dist/vba/cfb-format.d.ts

@@ -17,6 +17,14 @@ export declare const TYPE_EMPTY = 0;
 export declare const TYPE_STORAGE = 1;
 export declare const TYPE_STREAM = 2;
 export declare const TYPE_ROOT = 5;
+/**
+ * The stream size at or above which a stream lives in the regular FAT rather than the mini stream
+ * ([MS-CFB] 2.2, header offset 56). The spec fixes it at 4096, so the reader checks the header's value
+ * against this rather than believing it: a crafted 0 or 0xFFFFFFFF routes every stream through the
+ * wrong allocator, and since both destinations are bounds-checked the result is a module's source read
+ * back as something nobody wrote rather than a clean rejection.
+ */
+export declare const MINI_STREAM_CUTOFF = 4096;
 /** A directory entry is a fixed 128 bytes ([MS-CFB] 2.6.1), whatever the sector size. */
 export declare const DIR_ENTRY_SIZE = 128;
 /** 32 UTF-16 code units including the NUL terminator. This is also why a VBA module name is capped