@shbernal/ts-xlsx 2.0.0 → 3.0.0

package/dist/vba/cfb-writer.js

@@ -1,20 +1,11 @@
+import { DIFSECT, DIR_ENTRY_SIZE, ENDOFCHAIN, FATSECT, FREESECT, MAX_NAME_CHARS, NOSTREAM, TYPE_ROOT, TYPE_STORAGE, TYPE_STREAM, } from './cfb-format.js';
 import { VbaAuthorError } from './errors.js';
 const SECTOR = 512;
 const MINI_SECTOR = 64;
 const MINI_CUTOFF = 4096;
-const DIR_ENTRY_SIZE = 128;
 const ENTRIES_PER_DIR_SECTOR = SECTOR / DIR_ENTRY_SIZE;
 const FAT_ENTRIES_PER_SECTOR = SECTOR / 4;
 const DIFAT_HEADER_SLOTS = 109;
-const MAX_NAME_CHARS = 31;
-const FREESECT = 0xffffffff;
-const ENDOFCHAIN = 0xfffffffe;
-const FATSECT = 0xfffffffd;
-const DIFSECT = 0xfffffffc;
-const NOSTREAM = 0xffffffff;
-const TYPE_STORAGE = 1;
-const TYPE_STREAM = 2;
-const TYPE_ROOT = 5;
 const COLOR_BLACK = 1;
 function isStream(node) {
     return 'data' in node;
@@ -36,7 +27,8 @@ export function writeCompoundFile(root) {
         return entry;
     };
     const rootEntry = addEntry('Root Entry', TYPE_ROOT, ENDOFCHAIN);
-    const miniBytes = [];
+    const miniChunks = [];
+    let miniLength = 0;
     const miniFat = [];
     const bigStreams = [];
     const addNode = (node, siblings) => {
@@ -50,11 +42,14 @@ export function writeCompoundFile(root) {
                 bigStreams.push({ entry, data: node.data, sectors: Math.ceil(node.data.length / SECTOR) });
             }
             else {
-                const startMini = miniBytes.length / MINI_SECTOR;
+                const startMini = miniLength / MINI_SECTOR;
                 const numMini = Math.ceil(node.data.length / MINI_SECTOR);
                 for (let k = 0; k < numMini; k++)
                     miniFat.push(k < numMini - 1 ? startMini + k + 1 : ENDOFCHAIN);
-                miniBytes.push(...node.data, ...new Array(numMini * MINI_SECTOR - node.data.length).fill(0));
+                const padded = new Uint8Array(numMini * MINI_SECTOR);
+                padded.set(node.data);
+                miniChunks.push(padded);
+                miniLength += padded.length;
                 entry.startSector = startMini;
             }
         }
@@ -74,7 +69,7 @@ export function writeCompoundFile(root) {
     linkChildren(rootEntry, rootKids);
     const dirSectors = Math.ceil(entries.length / ENTRIES_PER_DIR_SECTOR);
     const miniFatSectors = miniFat.length > 0 ? Math.ceil((miniFat.length * 4) / FAT_ENTRIES_PER_SECTOR) : 0;
-    const miniStreamSectors = Math.ceil(miniBytes.length / SECTOR);
+    const miniStreamSectors = Math.ceil(miniLength / SECTOR);
     const baseSectors = dirSectors +
         miniFatSectors +
         miniStreamSectors +
@@ -112,7 +107,7 @@ export function writeCompoundFile(root) {
     cursor += difatSectors;
     const totalSectors = cursor;
     rootEntry.startSector = miniStreamStart;
-    rootEntry.size = miniBytes.length;
+    rootEntry.size = miniLength;
     const fat = new Array(fatSectors * FAT_ENTRIES_PER_SECTOR).fill(FREESECT);
     const chainRegion = (start, count) => {
         for (let k = 0; k < count; k++)
@@ -146,8 +141,13 @@ export function writeCompoundFile(root) {
     for (let i = 0; i < miniFatSectors * FAT_ENTRIES_PER_SECTOR; i++) {
         dv.setUint32(at(miniFatStart) + i * 4, miniFat[i] ?? FREESECT, true);
     }
-    if (miniBytes.length > 0)
-        buf.set(Uint8Array.from(miniBytes), at(miniStreamStart));
+    if (miniLength > 0) {
+        let offset = at(miniStreamStart);
+        for (const chunk of miniChunks) {
+            buf.set(chunk, offset);
+            offset += chunk.length;
+        }
+    }
     for (const big of bigStreams)
         buf.set(big.data, at(big.entry.startSector));
     for (const [i, sector] of fat.entries())

package/dist/vba/cfb.js

@@ -1,14 +1,8 @@
 import { concat, decodeUtf16le, readU16, readU32 } from './bytes.js';
+import { DIR_ENTRY_SIZE, MAX_REGULAR_SECTOR, NOSTREAM, TYPE_EMPTY, TYPE_ROOT, TYPE_STORAGE, TYPE_STREAM, } from './cfb-format.js';
 import { VbaParseError } from './errors.js';
-const MAX_REGULAR_SECTOR = 0xfffffffa;
-const NOSTREAM = 0xffffffff;
-const TYPE_EMPTY = 0;
-const TYPE_STORAGE = 1;
-const TYPE_STREAM = 2;
-const TYPE_ROOT = 5;
 const CFB_SIGNATURE_LO = 0xe011cfd0;
 const CFB_SIGNATURE_HI = 0xe11ab1a1;
-const DIR_ENTRY_SIZE = 128;
 export class CompoundFile {
     #buf;
     #sectorSize;

package/dist/vba/dir-records.d.ts

@@ -0,0 +1,53 @@
+/** PROJECTCODEPAGE: the code page every MBCS name in the project decodes through. */
+export declare const REC_PROJECT_CODEPAGE = 3;
+/** PROJECTVERSION: the record whose `Size` under-counts its payload by the trailing VersionMinor. */
+export declare const REC_PROJECT_VERSION = 9;
+/** REFERENCEREGISTERED: a reference to a registered type library, by libid. */
+export declare const REC_REFERENCE_REGISTERED = 13;
+/** PROJECTMODULES MODULES_COUNT: how many module blocks follow, and the first record after the
+ * reference array, which has no count of its own. */
+export declare const REC_MODULES_COUNT = 15;
+/** REFERENCENAME: a reference's MBCS name. */
+export declare const REC_REFERENCE_NAME = 22;
+/** MODULENAME: opens a module's record block. */
+export declare const REC_MODULE_NAME = 25;
+/** MODULESTREAMNAME: the storage name the module's p-code lives under. */
+export declare const REC_MODULE_STREAMNAME = 26;
+/** MODULETYPE for a standard module. */
+export declare const REC_MODULE_TYPE_PROCEDURAL = 33;
+/** MODULETYPE for a document module (`ThisWorkbook`, a sheet's code-behind). */
+export declare const REC_MODULE_TYPE_DOCUMENT = 34;
+/** MODULEENDOFBLOCK: closes a module's record block. */
+export declare const REC_MODULE_TERMINATOR = 43;
+/** MODULEOFFSET: where the module's source begins inside its stream. */
+export declare const REC_MODULE_OFFSET = 49;
+/**
+ * REFERENCENAME's Unicode half. A *literal* `0x003E` marker rather than a nested record id, but it is
+ * laid out as its own Id+Size+data TLV, so a generic walk sees REFERENCENAME as two chained records,
+ * exactly like MODULENAME/MODULENAME_UNICODE. Verified against a real Excel-authored dir stream
+ * (2026-07-23).
+ */
+export declare const REC_REFERENCE_NAME_UNICODE = 62;
+/** One record as the walk sees it. */
+export interface DirRecord {
+    /** The record id; one of the `REC_*` constants above, or a record this library does not consume. */
+    readonly id: number;
+    /** Offset of the record's `Id` field: where a splice that drops the record cuts from. */
+    readonly recordStart: number;
+    /** Offset of the record's payload. */
+    readonly dataStart: number;
+    /** The `Size` field, which is the payload length for every record but PROJECTVERSION. */
+    readonly size: number;
+    /** Offset of the next record, PROJECTVERSION's uncounted VersionMinor already skipped. Never
+     * recompute this from `dataStart + size`: that is the misalignment this module exists to prevent. */
+    readonly end: number;
+}
+/**
+ * Walk a decompressed `dir` stream, yielding each record in order. Consumers may stop early.
+ *
+ * @param context the phrase a truncated record's error carries, naming what the caller was doing:
+ *   the message reaches a user who has no idea what a TLV is but does know they were removing a
+ *   module.
+ * @throws {VbaParseError} when a record's payload runs past the end of the stream.
+ */
+export declare function dirRecords(dir: Uint8Array, context: string): Generator<DirRecord>;

package/dist/vba/dir-records.js

@@ -0,0 +1,28 @@
+import { readU16, readU32 } from './bytes.js';
+import { VbaParseError } from './errors.js';
+export const REC_PROJECT_CODEPAGE = 0x0003;
+export const REC_PROJECT_VERSION = 0x0009;
+export const REC_REFERENCE_REGISTERED = 0x000d;
+export const REC_MODULES_COUNT = 0x000f;
+export const REC_REFERENCE_NAME = 0x0016;
+export const REC_MODULE_NAME = 0x0019;
+export const REC_MODULE_STREAMNAME = 0x001a;
+export const REC_MODULE_TYPE_PROCEDURAL = 0x0021;
+export const REC_MODULE_TYPE_DOCUMENT = 0x0022;
+export const REC_MODULE_TERMINATOR = 0x002b;
+export const REC_MODULE_OFFSET = 0x0031;
+export const REC_REFERENCE_NAME_UNICODE = 0x003e;
+export function* dirRecords(dir, context) {
+    let pos = 0;
+    while (pos + 6 <= dir.length) {
+        const id = readU16(dir, pos);
+        const size = readU32(dir, pos + 2);
+        const dataStart = pos + 6;
+        if (dataStart + size > dir.length) {
+            throw new VbaParseError(`dir record 0x${id.toString(16)} ${context}`);
+        }
+        const end = dataStart + size + (id === REC_PROJECT_VERSION ? 2 : 0);
+        yield { id, recordStart: pos, dataStart, size, end };
+        pos = end;
+    }
+}

package/dist/vba/ms-ovba.js

@@ -11,7 +11,7 @@ export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTP
     if (buf[start] !== 0x01) {
         throw new VbaParseError(`compressed container must begin with a 0x01 signature byte, found 0x${(buf[start] ?? 0).toString(16)}`);
     }
-    const out = [];
+    const out = new DecompressedBytes(maxOutput);
     let pos = start + 1;
     while (pos + 2 <= buf.length) {
         const header = readU16(buf, pos);
@@ -28,7 +28,6 @@ export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTP
         if (!compressed) {
             for (let i = pos; i < chunkEnd; i++)
                 out.push(buf[i]);
-            guardOutput(out.length, maxOutput);
             pos = chunkEnd;
             continue;
         }
@@ -39,7 +38,6 @@ export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTP
                 const isCopy = (flagByte >> bit) & 1;
                 if (!isCopy) {
                     out.push(buf[pos++]);
-                    guardOutput(out.length, maxOutput);
                     continue;
                 }
                 if (pos + 2 > chunkEnd) {
@@ -55,13 +53,41 @@ export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTP
                     throw new VbaParseError('copy token references before the start of its chunk');
                 }
                 for (let i = 0; i < length; i++)
-                    out.push(out[src + i]);
-                guardOutput(out.length, maxOutput);
+                    out.push(out.at(src + i));
             }
         }
         pos = chunkEnd;
     }
-    return Uint8Array.from(out);
+    return out.bytes();
+}
+class DecompressedBytes {
+    #buf;
+    #length = 0;
+    #limit;
+    constructor(limit) {
+        this.#limit = limit;
+        this.#buf = new Uint8Array(Math.min(MAX_CHUNK_DECOMPRESSED, limit));
+    }
+    get length() {
+        return this.#length;
+    }
+    at(index) {
+        return this.#buf[index];
+    }
+    push(byte) {
+        if (this.#length >= this.#limit) {
+            throw new VbaParseError(`decompressed output exceeds the ${this.#limit}-byte ceiling (possible bomb)`);
+        }
+        if (this.#length === this.#buf.length) {
+            const grown = new Uint8Array(Math.min(Math.max(this.#buf.length * 2, MAX_CHUNK_DECOMPRESSED), this.#limit));
+            grown.set(this.#buf);
+            this.#buf = grown;
+        }
+        this.#buf[this.#length++] = byte;
+    }
+    bytes() {
+        return this.#buf.slice(0, this.#length);
+    }
 }
 export function compressContainer(data) {
     const out = [0x01];
@@ -119,11 +145,6 @@ function compressChunk(chunk) {
     }
     return tokens;
 }
-function guardOutput(size, maxOutput) {
-    if (size > maxOutput) {
-        throw new VbaParseError(`decompressed output exceeds the ${maxOutput}-byte ceiling (possible bomb)`);
-    }
-}
 function copyTokenHelp(decompressedSoFar) {
     const bitCount = Math.max(Math.ceil(Math.log2(Math.max(decompressedSoFar, 1))), 4);
     const lengthMask = 0xffff >> bitCount;

package/dist/vba/project-editor.js

@@ -1,7 +1,8 @@
-import { readU16, readU32 } from './bytes.js';
+import { readU16 } from './bytes.js';
 import { writeCompoundFile } from './cfb-writer.js';
 import { CompoundFile } from './cfb.js';
 import { decoderForCodePage, encoderForCodePage } from './codepage.js';
+import { dirRecords, REC_MODULE_NAME, REC_MODULE_STREAMNAME, REC_MODULE_TERMINATOR, REC_MODULES_COUNT, REC_REFERENCE_NAME, REC_REFERENCE_NAME_UNICODE, REC_REFERENCE_REGISTERED, } from './dir-records.js';
 import { VbaAuthorError, VbaParseError } from './errors.js';
 import { compressContainer, decompressContainer } from './ms-ovba.js';
 import { parseVbaProject } from './project.js';
@@ -10,14 +11,6 @@ const DIR_STREAM = 'dir';
 const PROJECT_STREAM = 'PROJECT';
 const PROJECTWM_STREAM = 'PROJECTwm';
 const VBA_STORAGE = 'VBA';
-const REC_MODULE_NAME = 0x0019;
-const REC_MODULE_STREAMNAME = 0x001a;
-const REC_MODULE_TERMINATOR = 0x002b;
-const REC_PROJECT_VERSION = 0x0009;
-const REC_MODULES_COUNT = 0x000f;
-const REC_REFERENCE_NAME = 0x0016;
-const REC_REFERENCE_NAME_UNICODE = 0x003e;
-const REC_REFERENCE_REGISTERED = 0x000d;
 export function removeVbaModule(bin, name) {
     const project = parseVbaProject(bin);
     const nameKey = name.toUpperCase();
@@ -124,18 +117,7 @@ function buildReferenceDirRecords(ref, encode) {
 }
 function insertReferenceDirRecords(dir, records) {
     let insertAt = -1;
-    let pos = 0;
-    while (pos + 6 <= dir.length) {
-        const recordStart = pos;
-        const id = readU16(dir, pos);
-        const size = readU32(dir, pos + 2);
-        const dataStart = pos + 6;
-        if (dataStart + size > dir.length) {
-            throw new VbaParseError(`dir record 0x${id.toString(16)} overruns while adding a reference`);
-        }
-        pos = dataStart + size;
-        if (id === REC_PROJECT_VERSION)
-            pos += 2;
+    for (const { id, recordStart } of dirRecords(dir, 'overruns while adding a reference')) {
         if (id === REC_MODULES_COUNT) {
             insertAt = recordStart;
             break;
@@ -157,18 +139,7 @@ function removeModuleDirRecord(dir, streamName, codePage) {
     let removeStart = -1;
     let removeEnd = -1;
     let currentStream;
-    let pos = 0;
-    while (pos + 6 <= dir.length) {
-        const recordStart = pos;
-        const id = readU16(dir, pos);
-        const size = readU32(dir, pos + 2);
-        const dataStart = pos + 6;
-        if (dataStart + size > dir.length) {
-            throw new VbaParseError(`dir record 0x${id.toString(16)} overruns while removing a module`);
-        }
-        pos = dataStart + size;
-        if (id === REC_PROJECT_VERSION)
-            pos += 2;
+    for (const { id, recordStart, dataStart, size, end } of dirRecords(dir, 'overruns while removing a module')) {
         if (id === REC_MODULES_COUNT) {
             if (size < 2)
                 throw new VbaParseError('PROJECTMODULES MODULES_COUNT record is malformed');
@@ -183,7 +154,7 @@ function removeModuleDirRecord(dir, streamName, codePage) {
         else if (id === REC_MODULE_TERMINATOR) {
             if (currentStream === streamName) {
                 removeStart = blockStart;
-                removeEnd = pos;
+                removeEnd = end;
             }
             currentStream = undefined;
             blockStart = -1;

package/dist/vba/project.js

@@ -1,27 +1,20 @@
 import { readU16, readU32 } from './bytes.js';
 import { CompoundFile } from './cfb.js';
 import { decoderForCodePage } from './codepage.js';
+import { dirRecords, REC_MODULE_NAME, REC_MODULE_OFFSET, REC_MODULE_STREAMNAME, REC_MODULE_TERMINATOR, REC_MODULE_TYPE_DOCUMENT, REC_MODULE_TYPE_PROCEDURAL, REC_PROJECT_CODEPAGE, } from './dir-records.js';
 import { VbaParseError } from './errors.js';
 import { decompressContainer } from './ms-ovba.js';
 export const VBA_PROJECT_REL_TYPE = 'http://schemas.microsoft.com/office/2006/relationships/vbaProject';
 export const VBA_PROJECT_CONTENT_TYPE = 'application/vnd.ms-office.vbaProject';
 export const VBA_PROJECT_PART_PATH = 'xl/vbaProject.bin';
-const SIGNATURE_KIND_BY_REL_SEGMENT = {
-    vbaProjectSignature: 'legacy',
-    vbaProjectSignatureAgile: 'agile',
-    vbaProjectSignatureV3: 'v3',
-};
+const SIGNATURE_KIND_BY_REL_SEGMENT = new Map([
+    ['vbaProjectSignature', 'legacy'],
+    ['vbaProjectSignatureAgile', 'agile'],
+    ['vbaProjectSignatureV3', 'v3'],
+]);
 export function vbaProjectSignatureKind(relType) {
-    return SIGNATURE_KIND_BY_REL_SEGMENT[relType.slice(relType.lastIndexOf('/') + 1)];
+    return SIGNATURE_KIND_BY_REL_SEGMENT.get(relType.slice(relType.lastIndexOf('/') + 1));
 }
-const REC_PROJECT_CODEPAGE = 0x0003;
-const REC_MODULE_NAME = 0x0019;
-const REC_MODULE_STREAMNAME = 0x001a;
-const REC_MODULE_TYPE_PROCEDURAL = 0x0021;
-const REC_MODULE_TYPE_DOCUMENT = 0x0022;
-const REC_MODULE_OFFSET = 0x0031;
-const REC_MODULE_TERMINATOR = 0x002b;
-const REC_PROJECT_VERSION = 0x0009;
 export function parseVbaProject(bin) {
     const cfb = new CompoundFile(bin);
     const dirCompressed = cfb.readStream('dir');
@@ -31,16 +24,7 @@ export function parseVbaProject(bin) {
     let codePage = 1252;
     const rawModules = [];
     let pending = {};
-    let pos = 0;
-    while (pos + 6 <= dir.length) {
-        const id = readU16(dir, pos);
-        const size = readU32(dir, pos + 2);
-        const dataStart = pos + 6;
-        if (dataStart + size > dir.length)
-            throw new VbaParseError(`dir record 0x${id.toString(16)} overruns stream`);
-        pos = dataStart + size;
-        if (id === REC_PROJECT_VERSION)
-            pos += 2;
+    for (const { id, dataStart, size } of dirRecords(dir, 'overruns stream')) {
         switch (id) {
             case REC_PROJECT_CODEPAGE:
                 if (size >= 2)
@@ -92,23 +76,23 @@ function readModuleSource(cfb, streamName, textOffset, decoder) {
         throw new VbaParseError(`module stream '${streamName}' not found in container`);
     return decoder.decode(decompressContainer(stream, textOffset));
 }
+const MODULE_KIND_BY_PROJECT_KEYWORD = new Map([
+    ['Document', 'document'],
+    ['Module', 'procedural'],
+    ['Class', 'class'],
+    ['BaseClass', 'designer'],
+]);
 function readProjectStreamKinds(cfb, decoder) {
     const kinds = new Map();
     const stream = cfb.readStream('PROJECT');
     if (!stream)
         return kinds;
     const text = decoder.decode(stream);
-    const keyword = {
-        Document: 'document',
-        Module: 'procedural',
-        Class: 'class',
-        BaseClass: 'designer',
-    };
     for (const line of text.split(/\r\n|\r|\n/)) {
         const eq = line.indexOf('=');
         if (eq < 0)
             continue;
-        const kind = keyword[line.slice(0, eq)];
+        const kind = MODULE_KIND_BY_PROJECT_KEYWORD.get(line.slice(0, eq));
         if (kind === undefined)
             continue;
         const name = (line.slice(eq + 1).split('/')[0] ?? '').trim();

package/dist/vba/vba-encoding.js

@@ -1,6 +1,6 @@
+import { MAX_NAME_CHARS } from './cfb-format.js';
 import { VbaAuthorError } from './errors.js';
 const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_]*$/;
-const MAX_NAME_CHARS = 31;
 export function validateVbaName(name, what) {
     if (!IDENTIFIER.test(name) || name.length > MAX_NAME_CHARS) {
         throw new VbaAuthorError(`invalid ${what} name '${name}' (must be a VBA identifier ≤ 31 chars)`);