@shbernal/ts-xlsx 3.0.0 → 3.1.0

package/dist/vba/cfb-format.js

@@ -8,5 +8,6 @@ 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

package/dist/vba/cfb-writer.js

@@ -1,15 +1,18 @@
-import { DIFSECT, DIR_ENTRY_SIZE, ENDOFCHAIN, FATSECT, FREESECT, MAX_NAME_CHARS, NOSTREAM, TYPE_ROOT, TYPE_STORAGE, TYPE_STREAM, } from './cfb-format.js';
+import { quoted } from '../errors.js';
+import { DIFSECT, DIR_ENTRY_SIZE, ENDOFCHAIN, FATSECT, FREESECT, MAX_NAME_CHARS, MINI_STREAM_CUTOFF, NOSTREAM, TYPE_ROOT, TYPE_STORAGE, TYPE_STREAM, } from './cfb-format.js';
 import { VbaAuthorError } from './errors.js';
+export function isStream(node) {
+    return 'data' in node;
+}
+export function isStorage(node) {
+    return !isStream(node);
+}
 const SECTOR = 512;
 const MINI_SECTOR = 64;
-const MINI_CUTOFF = 4096;
 const ENTRIES_PER_DIR_SECTOR = SECTOR / DIR_ENTRY_SIZE;
 const FAT_ENTRIES_PER_SECTOR = SECTOR / 4;
 const DIFAT_HEADER_SLOTS = 109;
 const COLOR_BLACK = 1;
-function isStream(node) {
-    return 'data' in node;
-}
 export function writeCompoundFile(root) {
     const entries = [];
     const addEntry = (name, type, startSector) => {
@@ -38,7 +41,7 @@ export function writeCompoundFile(root) {
             siblings.push(entry);
             if (node.data.length === 0) {
             }
-            else if (node.data.length >= MINI_CUTOFF) {
+            else if (node.data.length >= MINI_STREAM_CUTOFF) {
                 bigStreams.push({ entry, data: node.data, sectors: Math.ceil(node.data.length / SECTOR) });
             }
             else {
@@ -168,10 +171,10 @@ function validateSiblingNames(storageName, siblings) {
         if (node.name.length === 0)
             throw new VbaAuthorError('entry name must not be empty');
         if (node.name.length > MAX_NAME_CHARS) {
-            throw new VbaAuthorError(`entry name '${node.name}' exceeds the ${MAX_NAME_CHARS}-character CFB limit`);
+            throw new VbaAuthorError(`entry name ${quoted(node.name)} exceeds the ${MAX_NAME_CHARS}-character CFB limit`);
         }
         if (seen.has(node.name)) {
-            throw new VbaAuthorError(`duplicate entry name '${node.name}' under storage '${storageName}'`);
+            throw new VbaAuthorError(`duplicate entry name ${quoted(node.name)} under storage ${quoted(storageName)}`);
         }
         seen.add(node.name);
         if (!isStream(node))
@@ -207,7 +210,7 @@ function writeHeader(dv, p) {
     dv.setUint16(32, 6, true);
     dv.setUint32(44, p.fatSectors, true);
     dv.setUint32(48, p.dirStart, true);
-    dv.setUint32(56, MINI_CUTOFF, true);
+    dv.setUint32(56, MINI_STREAM_CUTOFF, true);
     dv.setUint32(60, p.miniFatStart, true);
     dv.setUint32(64, p.miniFatSectors, true);
     dv.setUint32(68, p.difatSectors > 0 ? p.difatStart : ENDOFCHAIN, true);

package/dist/vba/cfb.d.ts

@@ -4,13 +4,25 @@ export declare class CompoundFile {
     constructor(buf: Uint8Array);
     /** List every stream/storage name in the directory (order as stored). */
     names(): string[];
-    /** Read a stream's raw bytes by exact entry name, or `undefined` if absent. */
+    /**
+     * Read a stream's raw bytes by exact entry name, or `undefined` if absent.
+     *
+     * @returns bytes that may be a **view onto the caller's buffer** rather than a copy. A stream small
+     *   enough to fit in one sector is assembled by `concat` from a single chunk, and `concat` hands a
+     *   lone chunk straight back; anything larger is copied into a fresh buffer. So whether the result
+     *   aliases the source depends on the stream's size, which is a rule no caller should have to know
+     *   and none here relies on: nothing mutates what this returns. Stated because it is the sort of
+     *   thing that is true until someone writes the first mutation, and then true only for large
+     *   streams. Copy before mutating.
+     */
     readStream(name: string): Uint8Array | undefined;
     /**
      * Reconstruct the container's top-level children as the writer's node shape, recursing into every
      * storage, so a caller can swap one stream and re-emit the whole hierarchy with {@link writeCompoundFile}.
      * Walks the red-black sibling tree each storage navigates (not the linear directory scan), so any part
      * a host reaches is carried through. Cycle- and bounds-guarded like every other chain walk here.
+     *
+     * @returns nodes whose stream bytes carry {@link readStream}'s aliasing caveat.
      */
     tree(): CfbNode[];
 }

package/dist/vba/cfb.js

@@ -1,8 +1,10 @@
+import { quoted } from '../errors.js';
 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 { DIR_ENTRY_SIZE, MAX_REGULAR_SECTOR, MINI_STREAM_CUTOFF, NOSTREAM, TYPE_EMPTY, TYPE_ROOT, TYPE_STORAGE, TYPE_STREAM, } from './cfb-format.js';
 import { VbaParseError } from './errors.js';
 const CFB_SIGNATURE_LO = 0xe011cfd0;
 const CFB_SIGNATURE_HI = 0xe11ab1a1;
+const MAX_TREE_DEPTH = 256;
 export class CompoundFile {
     #buf;
     #sectorSize;
@@ -33,6 +35,9 @@ export class CompoundFile {
         const numFatSectors = readU32(this.#buf, 44);
         const firstDirSector = readU32(this.#buf, 48);
         this.#miniCutoff = readU32(this.#buf, 56);
+        if (this.#miniCutoff !== MINI_STREAM_CUTOFF) {
+            throw new VbaParseError(`unsupported mini-stream cutoff ${this.#miniCutoff}`);
+        }
         const firstMiniFatSector = readU32(this.#buf, 60);
         const firstDifatSector = readU32(this.#buf, 68);
         const numDifatSectors = readU32(this.#buf, 72);
@@ -63,11 +68,15 @@ export class CompoundFile {
         const root = this.#dir[rootIdx];
         return this.#buildSiblings(root.child, new Set([rootIdx]));
     }
-    #buildSiblings(firstChild, seen) {
+    #buildSiblings(firstChild, seen, depth = 0) {
+        if (depth > MAX_TREE_DEPTH)
+            throw new VbaParseError('directory tree nests too deep');
         const nodes = [];
-        const walk = (idx) => {
+        const walk = (idx, siblingDepth) => {
             if (idx >= MAX_REGULAR_SECTOR)
                 return;
+            if (siblingDepth > MAX_TREE_DEPTH)
+                throw new VbaParseError('directory tree nests too deep');
             if (idx >= this.#dir.length)
                 throw new VbaParseError('directory sibling index out of range');
             if (seen.has(idx))
@@ -76,16 +85,16 @@ export class CompoundFile {
             const e = this.#dir[idx];
             if (e.type === TYPE_EMPTY)
                 throw new VbaParseError('directory tree links an empty entry');
-            walk(e.left);
+            walk(e.left, siblingDepth + 1);
             if (e.type === TYPE_STORAGE) {
-                nodes.push({ name: e.name, children: this.#buildSiblings(e.child, seen) });
+                nodes.push({ name: e.name, children: this.#buildSiblings(e.child, seen, depth + 1) });
             }
             else {
                 nodes.push({ name: e.name, data: this.#readEntryData(e) });
             }
-            walk(e.right);
+            walk(e.right, siblingDepth + 1);
         };
-        walk(firstChild);
+        walk(firstChild, depth);
         return nodes;
     }
     #readEntryData(entry) {
@@ -94,8 +103,9 @@ export class CompoundFile {
         return this.#readViaMiniFat(entry.startSector, entry.size);
     }
     #readDifat(numFatSectors, firstDifat, numDifat) {
+        const wanted = Math.min(numFatSectors, this.#maxSector);
         const ids = [];
-        for (let i = 0; i < 109 && ids.length < numFatSectors; i++) {
+        for (let i = 0; i < 109 && ids.length < wanted; i++) {
             const v = readU32(this.#buf, 76 + i * 4);
             if (v >= MAX_REGULAR_SECTOR)
                 break;
@@ -104,12 +114,12 @@ export class CompoundFile {
         const seen = new Set();
         let sector = firstDifat;
         const perSector = this.#sectorSize / 4 - 1;
-        for (let s = 0; s < numDifat && sector < MAX_REGULAR_SECTOR; s++) {
+        for (let s = 0; s < numDifat && sector < MAX_REGULAR_SECTOR && ids.length < wanted; s++) {
             if (seen.has(sector))
                 throw new VbaParseError('cycle in DIFAT sector chain');
             seen.add(sector);
             const base = this.#dataSectorOffset(sector);
-            for (let i = 0; i < perSector; i++) {
+            for (let i = 0; i < perSector && ids.length < wanted; i++) {
                 const v = readU32(this.#buf, base + i * 4);
                 if (v < MAX_REGULAR_SECTOR)
                     ids.push(v);
@@ -123,23 +133,28 @@ export class CompoundFile {
         const perSector = this.#sectorSize / 4;
         for (const sid of fatSectorIds) {
             const base = this.#dataSectorOffset(sid);
-            for (let i = 0; i < perSector; i++)
+            for (let i = 0; i < perSector && fat.length < this.#maxSector; i++) {
                 fat.push(readU32(this.#buf, base + i * 4));
+            }
+            if (fat.length >= this.#maxSector)
+                break;
         }
         return fat;
     }
     #readChainValues(firstSector) {
         const values = [];
         const perSector = this.#sectorSize / 4;
+        const cap = this.#maxSector * (this.#sectorSize / this.#miniSectorSize);
         const seen = new Set();
         let sector = firstSector;
-        while (sector < MAX_REGULAR_SECTOR) {
+        while (sector < MAX_REGULAR_SECTOR && values.length < cap) {
             if (seen.has(sector))
                 throw new VbaParseError('cycle in mini-FAT sector chain');
             seen.add(sector);
             const base = this.#dataSectorOffset(sector);
-            for (let i = 0; i < perSector; i++)
+            for (let i = 0; i < perSector && values.length < cap; i++) {
                 values.push(readU32(this.#buf, base + i * 4));
+            }
             sector = this.#nextInFat(sector);
         }
         return values;
@@ -177,63 +192,70 @@ export class CompoundFile {
             const name = decodeUtf16le(raw.subarray(off, off + Math.max(0, nameLen - 2)));
             const startSector = readU32(raw, off + 116);
             const size = readU32(raw, off + 120);
+            if (readU32(raw, off + 124) !== 0) {
+                throw new VbaParseError(`directory entry ${quoted(name)} declares a stream larger than 4 GiB`);
+            }
             entries.push({ name, type, startSector, size, left, right, child });
         }
         return entries;
     }
     #readChainFull(startSector) {
-        const chunks = [];
-        const seen = new Set();
-        let sector = startSector;
-        while (sector < MAX_REGULAR_SECTOR) {
-            if (seen.has(sector))
-                throw new VbaParseError('cycle in FAT sector chain');
-            seen.add(sector);
-            const base = this.#dataSectorOffset(sector);
-            chunks.push(this.#buf.subarray(base, base + this.#sectorSize));
-            sector = this.#nextInFat(sector);
-        }
-        return concat(chunks);
+        return this.#walkChain(startSector, undefined, this.#fatChain('FAT sector chain'));
     }
     #readViaFat(startSector, size) {
-        const chunks = [];
-        const seen = new Set();
-        let sector = startSector;
-        let remaining = size;
-        while (sector < MAX_REGULAR_SECTOR && remaining > 0) {
-            if (seen.has(sector))
-                throw new VbaParseError('cycle in stream FAT chain');
-            seen.add(sector);
-            const base = this.#dataSectorOffset(sector);
-            const take = Math.min(this.#sectorSize, remaining);
-            chunks.push(this.#buf.subarray(base, base + take));
-            remaining -= take;
-            sector = this.#nextInFat(sector);
-        }
-        return concat(chunks);
+        return this.#walkChain(startSector, size, this.#fatChain('stream FAT chain'));
     }
     #readViaMiniFat(startSector, size) {
+        return this.#walkChain(startSector, size, this.#miniFatChain());
+    }
+    #walkChain(startSector, size, chain) {
         const chunks = [];
         const seen = new Set();
         let sector = startSector;
-        let remaining = size;
+        let remaining = size ?? Infinity;
         while (sector < MAX_REGULAR_SECTOR && remaining > 0) {
             if (seen.has(sector))
-                throw new VbaParseError('cycle in stream mini-FAT chain');
+                throw new VbaParseError(`cycle in ${chain.what}`);
             seen.add(sector);
-            const base = sector * this.#miniSectorSize;
-            const take = Math.min(this.#miniSectorSize, remaining);
-            if (base + take > this.#miniStream.length) {
-                throw new VbaParseError('mini-stream sector runs past end of the mini stream');
-            }
-            chunks.push(this.#miniStream.subarray(base, base + take));
+            const take = Math.min(chain.sectorSize, remaining);
+            chunks.push(chain.sliceAt(sector, take));
             remaining -= take;
-            if (sector >= this.#miniFat.length)
-                throw new VbaParseError('mini-FAT index out of range');
-            sector = this.#miniFat[sector];
+            sector = chain.next(sector);
+        }
+        if (size !== undefined && remaining > 0) {
+            throw new VbaParseError(`${chain.what} ends after ${size - remaining} bytes, but ${size} were declared`);
         }
         return concat(chunks);
     }
+    #fatChain(what) {
+        return {
+            what,
+            sectorSize: this.#sectorSize,
+            sliceAt: (sector, take) => {
+                const base = this.#dataSectorOffset(sector);
+                return this.#buf.subarray(base, base + take);
+            },
+            next: (sector) => this.#nextInFat(sector),
+        };
+    }
+    #miniFatChain() {
+        return {
+            what: 'stream mini-FAT chain',
+            sectorSize: this.#miniSectorSize,
+            sliceAt: (sector, take) => {
+                const base = sector * this.#miniSectorSize;
+                if (base + take > this.#miniStream.length) {
+                    throw new VbaParseError('mini-stream sector runs past end of the mini stream');
+                }
+                return this.#miniStream.subarray(base, base + take);
+            },
+            next: (sector) => {
+                if (sector >= this.#miniFat.length)
+                    throw new VbaParseError('mini-FAT index out of range');
+                return this.#miniFat[sector];
+            },
+        };
+    }
     #nextInFat(sector) {
         if (sector >= this.#fat.length)
             throw new VbaParseError('FAT index out of range');

package/dist/vba/codepage.js

@@ -1,3 +1,4 @@
+import { hex } from '../hex.js';
 import { VbaAuthorError, VbaParseError } from './errors.js';
 const CODEPAGE_LABEL = new Map([
     [1250, 'windows-1250'],
@@ -56,7 +57,7 @@ export function encoderForCodePage(codePage) {
             const code = text.charCodeAt(i);
             const byte = charToByte.get(code);
             if (byte === undefined) {
-                throw new VbaAuthorError(`character U+${code.toString(16).toUpperCase().padStart(4, '0')} is not representable in code page ${codePage}`);
+                throw new VbaAuthorError(`character U+${hex(code, 4)} is not representable in code page ${codePage}`);
             }
             out[i] = byte;
         }

package/dist/vba/errors.d.ts

@@ -17,6 +17,13 @@ export declare class VbaParseError extends XlsxError {
  * [MS-CFB] 31-character limit, a duplicate stream name, or a project so large it would exceed the
  * writer's single-header DIFAT bound. This is a caller-side contract violation, distinct from
  * {@link VbaParseError} (which reports a malformed blob *read* from an untrusted file).
+ *
+ * It shares `code: 'authoring'` with `AuthoringError` rather than being one, and it is the only
+ * subsystem in the tree that got its own authoring class. The reason is symmetry with
+ * {@link VbaParseError} and not the VBA subsystem's importance: a caller who catches the parse error
+ * to skip a macro project it cannot read is the same caller who catches the author error to skip one
+ * it cannot write, and the two halves of that pair have to be nameable the same way. A CSV or table
+ * authoring failure has no read-side twin to pair with, which is why those stay `AuthoringError`.
  */
 export declare class VbaAuthorError extends XlsxError {
     readonly name = "VbaAuthorError";

package/dist/vba/ms-ovba.js

@@ -3,6 +3,9 @@ import { VbaParseError } from './errors.js';
 const MAX_CHUNK_DECOMPRESSED = 4096;
 const CHUNK_SIGNATURE = 0b011 << 12;
 const CHUNK_COMPRESSED_FLAG = 0x8000;
+const MAX_MATCH_CANDIDATES = 64;
+const HASH_BITS = 12;
+const NO_CANDIDATE = -1;
 const DEFAULT_MAX_OUTPUT = 64 * 1024 * 1024;
 export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTPUT) {
     if (start >= buf.length) {
@@ -11,7 +14,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 = new DecompressedBytes(maxOutput);
+    const out = new ByteSink(maxOutput);
     let pos = start + 1;
     while (pos + 2 <= buf.length) {
         const header = readU16(buf, pos);
@@ -55,16 +58,19 @@ export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTP
                 for (let i = 0; i < length; i++)
                     out.push(out.at(src + i));
             }
+            if (out.length - chunkStart > MAX_CHUNK_DECOMPRESSED) {
+                throw new VbaParseError(`chunk decompressed to more than ${MAX_CHUNK_DECOMPRESSED} bytes, which [MS-OVBA] forbids`);
+            }
         }
         pos = chunkEnd;
     }
     return out.bytes();
 }
-class DecompressedBytes {
+class ByteSink {
     #buf;
     #length = 0;
     #limit;
-    constructor(limit) {
+    constructor(limit = Infinity) {
         this.#limit = limit;
         this.#buf = new Uint8Array(Math.min(MAX_CHUNK_DECOMPRESSED, limit));
     }
@@ -74,6 +80,9 @@ class DecompressedBytes {
     at(index) {
         return this.#buf[index];
     }
+    set(index, byte) {
+        this.#buf[index] = byte;
+    }
     push(byte) {
         if (this.#length >= this.#limit) {
             throw new VbaParseError(`decompressed output exceeds the ${this.#limit}-byte ceiling (possible bomb)`);
@@ -85,26 +94,40 @@ class DecompressedBytes {
         }
         this.#buf[this.#length++] = byte;
     }
+    pushAll(bytes) {
+        for (const byte of bytes)
+            this.push(byte);
+    }
     bytes() {
         return this.#buf.slice(0, this.#length);
     }
 }
 export function compressContainer(data) {
-    const out = [0x01];
+    const out = new ByteSink();
+    out.push(0x01);
     for (let start = 0; start < data.length; start += MAX_CHUNK_DECOMPRESSED) {
         const chunk = data.subarray(start, Math.min(start + MAX_CHUNK_DECOMPRESSED, data.length));
         const tokens = compressChunk(chunk);
         const compressed = tokens.length < chunk.length;
         const body = compressed ? tokens : chunk;
         const header = (compressed ? CHUNK_COMPRESSED_FLAG : 0) | CHUNK_SIGNATURE | ((body.length - 1) & 0x0fff);
-        out.push(header & 0xff, (header >> 8) & 0xff);
-        for (const b of body)
-            out.push(b);
+        out.push(header & 0xff);
+        out.push((header >> 8) & 0xff);
+        out.pushAll(body);
     }
-    return Uint8Array.from(out);
+    return out.bytes();
 }
 function compressChunk(chunk) {
-    const tokens = [];
+    const tokens = new ByteSink();
+    const heads = new Int32Array(1 << HASH_BITS).fill(NO_CANDIDATE);
+    const prev = new Int32Array(MAX_CHUNK_DECOMPRESSED).fill(NO_CANDIDATE);
+    const remember = (at) => {
+        if (at + 2 >= chunk.length)
+            return;
+        const bucket = hash3(chunk, at);
+        prev[at] = heads[bucket];
+        heads[bucket] = at;
+    };
     let pos = 0;
     while (pos < chunk.length) {
         const flagIndex = tokens.length;
@@ -116,37 +139,49 @@ function compressChunk(chunk) {
             const windowStart = Math.max(0, pos - (1 << bitCount));
             let bestLength = 0;
             let bestOffset = 0;
-            for (let cand = pos - 1; cand >= windowStart; cand--) {
+            let candidate = pos + 2 < chunk.length ? heads[hash3(chunk, pos)] : NO_CANDIDATE;
+            for (let tried = 0; candidate >= windowStart && tried < MAX_MATCH_CANDIDATES; tried++) {
                 let len = 0;
                 while (len < maxLength &&
                     pos + len < chunk.length &&
-                    chunk[cand + len] === chunk[pos + len]) {
+                    chunk[candidate + len] === chunk[pos + len]) {
                     len++;
                 }
                 if (len > bestLength) {
                     bestLength = len;
-                    bestOffset = pos - cand;
+                    bestOffset = pos - candidate;
                     if (bestLength === maxLength)
                         break;
                 }
+                candidate = prev[candidate];
             }
             if (bestLength >= 3) {
                 const token = ((bestOffset - 1) << (16 - bitCount)) | (bestLength - 3);
-                tokens.push(token & 0xff, (token >> 8) & 0xff);
+                tokens.push(token & 0xff);
+                tokens.push((token >> 8) & 0xff);
                 flags |= 1 << bit;
+                for (let i = 0; i < bestLength; i++)
+                    remember(pos + i);
                 pos += bestLength;
             }
             else {
                 tokens.push(chunk[pos]);
+                remember(pos);
                 pos++;
             }
         }
-        tokens[flagIndex] = flags;
+        tokens.set(flagIndex, flags);
     }
-    return tokens;
+    return tokens.bytes();
+}
+function hash3(chunk, pos) {
+    const first = chunk[pos];
+    const second = chunk[pos + 1];
+    const third = chunk[pos + 2];
+    return ((first << 8) ^ (second << 4) ^ third) & ((1 << HASH_BITS) - 1);
 }
 function copyTokenHelp(decompressedSoFar) {
-    const bitCount = Math.max(Math.ceil(Math.log2(Math.max(decompressedSoFar, 1))), 4);
+    const bitCount = Math.min(Math.max(Math.ceil(Math.log2(Math.max(decompressedSoFar, 1))), 4), Math.log2(MAX_CHUNK_DECOMPRESSED));
     const lengthMask = 0xffff >> bitCount;
     return { lengthMask, bitCount };
 }