@shbernal/ts-xlsx 2.1.0 → 3.1.0

package/dist/io/xlsx/write.js

@@ -1,12 +1,14 @@
 import { strToU8, zip, zipSync } from 'fflate';
-import { AuthoringError } from '../../errors.js';
-import { THEME_PART_PATH } from '../opc/part-paths.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';
 import { SharedStringTable } from './shared-strings.js';
@@ -14,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 });
 }
@@ -47,12 +48,78 @@ export function createStyleRegistry(workbook) {
         styles.addTableStyle(style);
     return styles;
 }
+function planSheet(context) {
+    const { sheet, index, media, preserved, numbering, flushed } = context;
+    const rels = new RelIdAllocator();
+    const tables = sheet.tables.map((table) => ({
+        table,
+        number: ++numbering.table,
+        relId: rels.next(),
+    }));
+    let drawing = null;
+    if (sheet.images.length > 0) {
+        const images = sheet.images.map((image, j) => {
+            const { number, image: registered } = media.resolve(image.imageId);
+            return {
+                anchor: image.anchor,
+                embedId: `rId${j + 1}`,
+                mediaNumber: number,
+                extension: registered.extension,
+            };
+        });
+        drawing = { number: ++numbering.drawing, relId: rels.next(), images };
+    }
+    const threads = sheet.commentThreads.filter((thread) => thread.comments.length > 0);
+    const sheetComments = collectComments(liveCells(sheet), threads, flushed?.notes ?? []);
+    const comments = sheetComments.length === 0
+        ? null
+        : {
+            number: index + 1,
+            comments: sheetComments,
+            vmlRelId: rels.next(),
+            commentsRelId: rels.next(),
+        };
+    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(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);
+        background = { relId: rels.next(), mediaNumber: number, extension: image.extension };
+    }
+    const preservedRefs = (preserved.perSheet[index] ?? []).map((reference) => ({ ...reference, relId: rels.next() }));
+    const pivots = sheet.pivotTables.map((table) => {
+        const number = ++numbering.pivot;
+        return { number, cacheId: String(number), table, sheetRelId: rels.next(), workbookRelId: '' };
+    });
+    return {
+        tables,
+        drawing,
+        comments,
+        threadedComments,
+        printerSettings,
+        hyperlinks,
+        background,
+        preservedRefs,
+        pivots,
+    };
+}
+function numbersOf(plans, pick) {
+    const numbers = [];
+    for (const plan of plans) {
+        const part = pick(plan);
+        if (part !== null)
+            numbers.push(part.number);
+    }
+    return numbers;
+}
 function resolveSheetReferences(plan) {
     const refs = plan.preservedRefs;
     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,
@@ -63,153 +130,153 @@ function resolveSheetReferences(plan) {
         slicerRelIds,
     };
 }
-export function buildPackageParts(workbook, options = {}) {
-    const sheets = workbook.worksheets;
-    if (sheets.length === 0) {
-        throw new AuthoringError('cannot write a workbook with no worksheets: a zero-sheet package is corrupt to Excel');
-    }
-    const sharedStrings = options.useSharedStrings ? new SharedStringTable() : null;
+function assignWorkbookRelIds(context) {
+    const { sheetCount, hasSharedStrings, hasPersons, preservedWorkbook, pivots } = context;
+    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, flushed) {
     const media = planMedia(workbook, sheets);
     const generatedDrawingCount = sheets.filter((sheet) => sheet.images.length > 0).length;
-    const preserved = planPreservedParts(workbook, generatedDrawingCount, media.parts.length);
-    let tableNumber = 0;
-    let drawingNumber = 0;
-    let pivotNumber = 0;
-    const perSheet = sheets.map((sheet, i) => {
-        const rels = new SheetRelIds();
-        const tables = sheet.tables.map((table) => ({
-            table,
-            number: ++tableNumber,
-            relId: rels.next(),
-        }));
-        let drawing = null;
-        if (sheet.images.length > 0) {
-            const images = sheet.images.map((image, j) => {
-                const registered = workbook.getImage(image.imageId);
-                return {
-                    anchor: image.anchor,
-                    embedId: `rId${j + 1}`,
-                    mediaNumber: media.numberById.get(image.imageId),
-                    extension: registered.extension,
-                };
-            });
-            drawing = { number: ++drawingNumber, relId: rels.next(), images };
-        }
-        const threads = sheet.commentThreads.filter((thread) => thread.comments.length > 0);
-        const sheetComments = collectComments(sheet, threads);
-        const comments = sheetComments.length === 0
-            ? null
-            : {
-                number: i + 1,
-                comments: sheetComments,
-                vmlRelId: rels.next(),
-                commentsRelId: rels.next(),
-            };
-        const threadedComments = threads.length === 0 ? null : { number: i + 1, threads, relId: rels.next() };
-        const printerData = sheet.pageSetup.printerSettings;
-        const printerSettings = printerData === undefined ? null : { number: i + 1, data: printerData, relId: rels.next() };
-        const hyperlinks = planHyperlinks(collectHyperlinks(sheet), rels);
-        let background = null;
-        if (sheet.backgroundImageId !== undefined) {
-            const registered = workbook.getImage(sheet.backgroundImageId);
-            if (registered === undefined) {
-                throw new AuthoringError(`sheet "${sheet.name}" sets background image id ${sheet.backgroundImageId}, which is not registered on the workbook`);
-            }
-            background = {
-                relId: rels.next(),
-                mediaNumber: media.numberById.get(sheet.backgroundImageId),
-                extension: registered.extension,
-            };
-        }
-        const preservedRefs = (preserved.perSheet[i] ?? []).map((reference) => ({ ...reference, relId: rels.next() }));
-        const pivots = sheet.pivotTables.map((table) => {
-            const number = ++pivotNumber;
-            return { number, cacheId: String(number), table, sheetRelId: rels.next(), workbookRelId: '' };
+    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, flushed: flushed?.get(sheet) }));
+    return {
+        media,
+        preserved,
+        perSheet,
+        allTables: perSheet.flatMap((plan) => plan.tables),
+        allPivots: perSheet.flatMap((plan) => plan.pivots),
+    };
+}
+function serialiseSheets(context) {
+    const { workbook, sheets, plan, styles, sharedStrings, flushed } = context;
+    return sheets.map((sheet, i) => {
+        const sheetPlan = plan.perSheet[i];
+        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),
         });
-        return {
-            tables,
-            drawing,
-            comments,
-            threadedComments,
-            printerSettings,
-            hyperlinks,
-            background,
-            preservedRefs,
-            pivots,
-        };
-    });
-    const allTables = perSheet.flatMap((plan) => plan.tables);
-    const allPivots = perSheet.flatMap((plan) => plan.pivots);
-    const styles = options.styles ?? createStyleRegistry(workbook);
-    const sheetXml = sheets.map((sheet, i) => {
-        const plan = perSheet[i];
-        return worksheetXml(sheet, plan.tables, styles, resolveSheetReferences(plan), plan.hyperlinks, sharedStrings, i === workbook.activeTabIndex, options.flushed?.get(sheet));
     });
+}
+function emitPackageParts(context) {
+    const { workbook, sheets, plan, styles, sharedStrings, sheetXml } = context;
+    const { media, preserved, perSheet, allTables, allPivots } = plan;
     const hasSharedStrings = sharedStrings !== null && !sharedStrings.isEmpty;
-    const commentNumbers = perSheet
-        .map((plan) => plan.comments)
-        .filter((c) => c !== null)
-        .map((c) => c.number);
-    const drawingNumbers = perSheet
-        .map((plan) => plan.drawing)
-        .filter((d) => d !== null)
-        .map((d) => d.number);
-    const printerSettingsNumbers = perSheet
-        .map((plan) => plan.printerSettings)
-        .filter((p) => p !== null)
-        .map((p) => p.number);
-    const threadedCommentNumbers = perSheet
-        .map((plan) => plan.threadedComments)
-        .filter((t) => t !== null)
-        .map((t) => t.number);
+    const commentNumbers = numbersOf(perSheet, (sheetPlan) => sheetPlan.comments);
+    const drawingNumbers = numbersOf(perSheet, (sheetPlan) => sheetPlan.drawing);
+    const printerSettingsNumbers = numbersOf(perSheet, (sheetPlan) => sheetPlan.printerSettings);
+    const threadedCommentNumbers = numbersOf(perSheet, (sheetPlan) => sheetPlan.threadedComments);
     const persons = threadedCommentNumbers.length === 0 ? [] : workbook.persons;
-    const modeledWorkbookRelCount = sheets.length + FIXED_WORKBOOK_REL_COUNT + (hasSharedStrings ? 1 : 0);
-    const personsRelId = persons.length === 0 ? null : `rId${modeledWorkbookRelCount + 1}`;
-    const workbookRelBase = modeledWorkbookRelCount + (personsRelId === null ? 0 : 1);
-    const preservedWorkbookRels = preserved.workbook.map((ref, i) => ({
-        ...ref,
-        relId: `rId${workbookRelBase + 1 + i}`,
-    }));
-    const pivotWorkbookRelBase = workbookRelBase + preserved.workbook.length;
-    allPivots.forEach((pivot, i) => {
-        pivot.workbookRelId = `rId${pivotWorkbookRelBase + 1 + i}`;
+    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)),
-        'docProps/core.xml': strToU8(corePropsXml(workbook.properties)),
-        'docProps/app.xml': strToU8(appPropsXml(workbook.properties)),
-        'xl/workbook.xml': strToU8(workbookXml(workbook, preservedWorkbookRels, allPivots)),
-        'xl/_rels/workbook.xml.rels': strToU8(workbookRelsXml(sheets.length, hasSharedStrings, personsRelId, preservedWorkbookRels, allPivots)),
-        'xl/styles.xml': 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['xl/sharedStrings.xml'] = strToU8(sharedStrings.toXml());
+        files.add(SHARED_STRINGS_PART, strToU8(sharedStrings.toXml()));
     }
     if (persons.length > 0)
-        files['xl/persons/person.xml'] = strToU8(personsXml(persons));
+        files.add(PERSONS_PART, strToU8(personsXml(persons)));
     for (const part of media.parts) {
-        files[`xl/media/image${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[`xl/tables/table${number}.xml`] = 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;
+    if (sheets.length === 0) {
+        throw new AuthoringError('cannot write a workbook with no worksheets: a zero-sheet package is corrupt to Excel');
+    }
+    const sharedStrings = options.useSharedStrings ? new SharedStringTable() : null;
+    const styles = options.styles ?? createStyleRegistry(workbook);
+    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[`xl/worksheets/sheet${i + 1}.xml`] = strToU8(sheetXml[i]);
+        files.add(worksheetPart(i + 1), strToU8(sheetXml[i]));
         if (tables.length > 0 ||
             drawing !== null ||
             comments !== null ||
@@ -219,49 +286,46 @@ function emitSheetParts(files, perSheet, sheetXml) {
             hasExternalHyperlink ||
             preservedRefs.length > 0 ||
             pivots.length > 0) {
-            files[`xl/worksheets/_rels/sheet${i + 1}.xml.rels`] = strToU8(worksheetRelsXml(tables, drawing, comments, threadedComments, printerSettings, background, hyperlinks, preservedRefs, pivots));
+            files.add(relsPathFor(worksheetPart(i + 1)), strToU8(worksheetRelsXml(plan)));
         }
         if (printerSettings !== null) {
-            files[`xl/printerSettings/printerSettings${printerSettings.number}.bin`] =
-                printerSettings.data;
+            files.add(printerSettingsPart(printerSettings.number), printerSettings.data);
         }
         if (drawing !== null) {
-            files[`xl/drawings/drawing${drawing.number}.xml`] = strToU8(drawingXml(drawing.images));
-            const targets = drawing.images.map((image) => `../media/image${image.mediaNumber}.${image.extension}`);
-            files[`xl/drawings/_rels/drawing${drawing.number}.xml.rels`] = strToU8(drawingRelsXml(targets));
+            const drawingPath = drawingPart(drawing.number);
+            files.add(drawingPath, strToU8(drawingXml(drawing.images)));
+            const targets = drawing.images.map((image) => relativePartPath(drawingPath, mediaPart(image.mediaNumber, image.extension)));
+            files.add(relsPathFor(drawingPath), strToU8(drawingRelsXml(targets)));
         }
         if (comments !== null) {
-            files[`xl/comments${comments.number}.xml`] = strToU8(commentsXml(comments.comments));
-            files[`xl/drawings/vmlDrawing${comments.number}.vml`] = 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[`xl/threadedComments/threadedComment${threadedComments.number}.xml`] = strToU8(threadedCommentsXml(threadedComments.threads));
+            files.add(threadedCommentsPart(threadedComments.number), strToU8(threadedCommentsXml(threadedComments.threads)));
         }
     });
 }
 function emitPivotParts(files, allPivots) {
     for (const pivot of allPivots) {
         const { number, cacheId, table } = pivot;
-        files[`xl/pivotTables/pivotTable${number}.xml`] = strToU8(pivotTableXml(table, `PivotTable${number}`, cacheId));
-        files[`xl/pivotTables/_rels/pivotTable${number}.xml.rels`] = strToU8(relsPartXml([
-            {
-                id: 'rId1',
-                type: REL.pivotCacheDefinition,
-                target: `../pivotCache/pivotCacheDefinition${number}.xml`,
-            },
-        ]));
-        files[`xl/pivotCache/pivotCacheDefinition${number}.xml`] = strToU8(pivotCacheDefinitionXml(table));
-        files[`xl/pivotCache/_rels/pivotCacheDefinition${number}.xml.rels`] = strToU8(relsPartXml([
-            { id: 'rId1', type: REL.pivotCacheRecords, target: `pivotCacheRecords${number}.xml` },
-        ]));
-        files[`xl/pivotCache/pivotCacheRecords${number}.xml`] = strToU8(pivotCacheRecordsXml(table));
+        const tablePath = pivotTablePart(number);
+        const definitionPath = pivotCacheDefinitionPart(number);
+        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

@@ -0,0 +1,28 @@
+/**
+ * Build a narrowing predicate for a closed token union.
+ *
+ * `members` is keyed by the union, so the compiler refuses a foreign member and an omitted one
+ * alike. A bare list of string literals is checked one way only: it cannot name a token the union
+ * does not, but it can quietly omit one the union does, and a guard narrower than its union
+ * silently drops a token real files legitimately carry.
+ *
+ * Deriving the union from the list instead (`(typeof TOKENS)[number]`, as `table-style.ts` does)
+ * would make divergence impossible rather than merely detected, and is the better shape for a type
+ * that is not public. It is not available to a published union: the API reference renders a
+ * declaration by slicing its own source text, so a derived alias reaches the docs as that
+ * 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

@@ -0,0 +1,7 @@
+export function tokenSet(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

@@ -0,0 +1,32 @@
+/** Sector chain markers ([MS-CFB] 2.2). */
+export declare const FREESECT = 4294967295;
+export declare const ENDOFCHAIN = 4294967294;
+export declare const FATSECT = 4294967293;
+export declare const DIFSECT = 4294967292;
+/**
+ * Sector values 0xFFFFFFFA..0xFFFFFFFF are the reserved markers above, not data-sector indices, so
+ * any value at or above this ceiling is chain-terminal. A reader walking a hostile chain tests the
+ * ceiling rather than the four markers by name: an unassigned reserved value is terminal too.
+ */
+export declare const MAX_REGULAR_SECTOR = 4294967290;
+/** Directory-tree links reuse the sector convention: NOSTREAM, and any value at or above
+ * {@link MAX_REGULAR_SECTOR}, mean "no such sibling or child". */
+export declare const NOSTREAM = 4294967295;
+/** Object types ([MS-CFB] 2.6.1). */
+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
+ * at 31: the module is a stream, and the stream's name is the module's. */
+export declare const MAX_NAME_CHARS = 31;

package/dist/vba/cfb-format.js

@@ -0,0 +1,13 @@
+export const FREESECT = 0xffffffff;
+export const ENDOFCHAIN = 0xfffffffe;
+export const FATSECT = 0xfffffffd;
+export const DIFSECT = 0xfffffffc;
+export const MAX_REGULAR_SECTOR = 0xfffffffa;
+export const NOSTREAM = 0xffffffff;
+export const TYPE_EMPTY = 0;
+export const TYPE_STORAGE = 1;
+export const TYPE_STREAM = 2;
+export const TYPE_ROOT = 5;
+export const MINI_STREAM_CUTOFF = 4096;
+export const DIR_ENTRY_SIZE = 128;
+export const MAX_NAME_CHARS = 31;

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

@@ -8,6 +8,15 @@ export interface CfbStorage {
     readonly children: readonly CfbNode[];
 }
 export type CfbNode = CfbStream | CfbStorage;
+/**
+ * Which arm of {@link CfbNode} a node is.
+ *
+ * Exported beside the union rather than kept private, because the discriminant is `'data' in node`
+ * and that is the sort of test callers re-spell inline: `project-editor.ts` had it three times, once
+ * negated. The name says what the test means, and the pair says that a node is one or the other.
+ */
+export declare function isStream(node: CfbNode): node is CfbStream;
+export declare function isStorage(node: CfbNode): node is CfbStorage;
 /**
  * Encode a hierarchy of storages and streams into a v3 compound file. The Root Entry is synthesized
  * automatically; `root` is its top-level children. Every stream becomes a directory entry reachable both