@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/esm/modules/excel/xlsx/xlsx.browser.js

@@ -10,18 +10,21 @@
  */
 import { ZipParser } from "../../archive/unzip/zip-parser.js";
 import { StreamingZip, ZipDeflateFile } from "../../archive/zip/stream.js";
-import { ExcelStreamStateError, ExcelFileError, ImageError, ExcelNotSupportedError, XmlParseError } from "../errors.js";
+import { ExcelStreamStateError, ExcelFileError, ImageError, ExcelNotSupportedError, XmlParseError, TableError } from "../errors.js";
 import { filterDrawingAnchors } from "../utils/drawing-utils.js";
-import { commentsPath, commentsRelTargetFromWorksheetName, ctrlPropPath, drawingPath, drawingRelsPath, OOXML_REL_TARGETS, pivotTableRelTargetFromWorksheetName, pivotCacheDefinitionRelTargetFromWorkbook, getCommentsIndexFromPath, getDrawingNameFromPath, getDrawingNameFromRelsPath, getMediaFilenameFromPath, mediaPath, getPivotCacheDefinitionNameFromPath, getPivotCacheDefinitionNameFromRelsPath, getPivotCacheRecordsNameFromPath, getPivotTableNameFromPath, getPivotTableNameFromRelsPath, pivotCacheDefinitionPath, pivotCacheDefinitionRelsPath, pivotCacheDefinitionRelTargetFromPivotTable, pivotCacheRecordsPath, pivotCacheRecordsRelTarget, pivotTablePath, pivotTableRelsPath, getTableNameFromPath, tablePath, tableRelTargetFromWorksheetName, themePath, getThemeNameFromPath, getVmlDrawingNameFromPath, getVmlDrawingHFNameFromPath, getWorksheetNoFromWorksheetPath, getWorksheetNoFromWorksheetRelsPath, isBinaryEntryPath, normalizeZipPath, OOXML_PATHS, vmlDrawingRelTargetFromWorksheetName, vmlDrawingPath, vmlDrawingHFPath, vmlDrawingHFRelsPath, worksheetPath, worksheetRelsPath, worksheetRelTarget } from "../utils/ooxml-paths.js";
+import { rewriteExternalRefs } from "../utils/external-link-formula.js";
+import { commentsPath, commentsRelTargetFromWorksheetName, ctrlPropPath, drawingPath, drawingRelsPath, externalLinkPath, externalLinkRelsPath, externalLinkRelTargetFromWorkbook, OOXML_REL_TARGETS, pivotTableRelTargetFromWorksheetName, pivotCacheDefinitionRelTargetFromWorkbook, getCommentsIndexFromPath, getDrawingNameFromPath, getDrawingNameFromRelsPath, getExternalLinkIndexFromPath, getExternalLinkIndexFromRelsPath, getMediaFilenameFromPath, mediaPath, getPivotCacheDefinitionNameFromPath, getPivotCacheDefinitionNameFromRelsPath, getPivotCacheRecordsNameFromPath, getPivotTableNameFromPath, getPivotTableNameFromRelsPath, pivotCacheDefinitionPath, pivotCacheDefinitionRelsPath, pivotCacheDefinitionRelTargetFromPivotTable, pivotCacheRecordsPath, pivotCacheRecordsRelTarget, pivotTablePath, pivotTableRelsPath, getTableNameFromPath, tablePath, tableRelTargetFromWorksheetName, themePath, getThemeNameFromPath, getVmlDrawingNameFromPath, getVmlDrawingHFNameFromPath, getWorksheetNoFromWorksheetPath, getWorksheetNoFromWorksheetRelsPath, isBinaryEntryPath, normalizeZipPath, OOXML_PATHS, vmlDrawingRelTargetFromWorksheetName, vmlDrawingPath, vmlDrawingHFPath, vmlDrawingHFRelsPath, worksheetPath, worksheetRelsPath, worksheetRelTarget } from "../utils/ooxml-paths.js";
 import { PassthroughManager } from "../utils/passthrough-manager.js";
 import { StreamBuf } from "../utils/stream-buf.js";
 import { RelType } from "./rel-type.js";
+import { ExternalLinkXform } from "./xform/book/external-link-xform.js";
 import { WorkbookXform } from "./xform/book/workbook-xform.js";
 import { CommentsXform } from "./xform/comment/comments-xform.js";
 import { AppXform } from "./xform/core/app-xform.js";
 import { ContentTypesXform } from "./xform/core/content-types-xform.js";
 import { CoreXform } from "./xform/core/core-xform.js";
 import { FeaturePropertyBagXform } from "./xform/core/feature-property-bag-xform.js";
+import { MetadataXform } from "./xform/core/metadata-xform.js";
 import { RelationshipsXform } from "./xform/core/relationships-xform.js";
 import { CtrlPropXform } from "./xform/drawing/ctrl-prop-xform.js";
 import { DrawingXform } from "./xform/drawing/drawing-xform.js";
@@ -242,6 +245,31 @@ class StreamingZipWriterAdapter {
     }
 }
 StreamingZipWriterAdapter.textEncoder = new TextEncoder();
+/**
+ * Extract the trailing integer from a workbook-rels Target like
+ * `"externalLinks/externalLink12.xml"` (a path relative to `xl/`). Mirror
+ * of {@link getExternalLinkIndexFromPath} which takes the full
+ * `xl/externalLinks/…` form. Used during reconcile to bridge the
+ * workbook.xml.rels entry to the parsed externalLinkN.xml part.
+ */
+function externalLinkIndexFromRelTarget(target) {
+    const match = /(?:^|\/)externalLink(\d+)[.]xml$/.exec(target);
+    return match ? parseInt(match[1], 10) : undefined;
+}
+/**
+ * Add `sheetName` to an ExternalLinkModel's `sheetNames` list if it isn't
+ * already present. Ordering is preserved — the first-seen sheet wins
+ * position 0, which matches what Excel does when writing externalLinks
+ * itself.
+ */
+function upsertSheet(link, sheetName) {
+    if (!sheetName) {
+        return;
+    }
+    if (!link.sheetNames.includes(sheetName)) {
+        link.sheetNames.push(sheetName);
+    }
+}
 /**
  * XLSX class - handles Excel file operations
  * Works in both Node.js and Browser environments
@@ -310,10 +338,12 @@ class XLSX {
         await this.addDrawings(zip, model);
         await this.addTables(zip, model);
         await this.addPivotTables(zip, model);
+        await this.addExternalLinks(zip, model);
         this.addPassthrough(zip, model);
         await this.addThemes(zip, model);
         await this.addStyles(zip, model);
         await this.addFeaturePropertyBag(zip, model);
+        await this.addMetadata(zip, model);
         await this.addMedia(zip, model);
         await this.addApp(zip, model);
         await this.addCore(zip, model);
@@ -363,32 +393,44 @@ class XLSX {
         return this._finalize(zip);
     }
     /**
-     * Load workbook from buffer/ArrayBuffer/Uint8Array
+     * Load a workbook from binary data.
+     *
+     * Accepted inputs:
+     *  - `Uint8Array` (and `Buffer`, which is a Uint8Array at runtime)
+     *  - `ArrayBuffer` / `SharedArrayBuffer`
+     *  - Any `ArrayBufferView` (DataView, Int8Array, Float32Array, …) — the
+     *    underlying bytes are reinterpreted as a zip archive
+     *  - `string` — treated as base64-encoded data when `options.base64 === true`;
+     *    raw binary cannot be round-tripped through a JS string and is rejected
+     *    to prevent silent corruption.
      */
     async load(data, options) {
-        let buffer;
-        // Validate input
-        const isBuffer = typeof Buffer !== "undefined" ? Buffer.isBuffer(data) : false;
-        if (!data ||
-            (typeof data === "object" &&
-                !isBuffer &&
-                !(data instanceof Uint8Array) &&
-                !(data instanceof ArrayBuffer))) {
+        if (data === null || data === undefined) {
             throw new ExcelFileError("<input>", "read", "Can't read the data of 'the loaded zip file'. Is it in a supported JavaScript type (String, Blob, ArrayBuffer, etc) ?");
         }
-        // Handle base64 input
-        if (options && options.base64) {
-            buffer = base64ToUint8Array(data.toString());
+        let buffer;
+        if (typeof data === "string") {
+            // Strings must be base64-encoded — binary zip bytes cannot be round-tripped
+            // through a JS string without corruption. Require the explicit opt-in.
+            if (!options?.base64) {
+                throw new ExcelFileError("<input>", "read", "Can't read the data of 'the loaded zip file'. Is it in a supported JavaScript type (String, Blob, ArrayBuffer, etc) ? " +
+                    "String input requires options.base64 === true (base64-encoded zip archive).");
+            }
+            buffer = base64ToUint8Array(data);
+        }
+        else if (data instanceof Uint8Array) {
+            // Covers Buffer (Node) and any typed-array view whose element size is 1.
+            buffer = data;
         }
         else if (data instanceof ArrayBuffer) {
             buffer = new Uint8Array(data);
         }
-        else if (data instanceof Uint8Array) {
-            buffer = data;
+        else if (ArrayBuffer.isView(data)) {
+            // DataView, Int8Array, Float32Array, … — view onto an underlying buffer.
+            buffer = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
         }
         else {
-            // Node.js Buffer or other array-like
-            buffer = new Uint8Array(data);
+            throw new ExcelFileError("<input>", "read", "Can't read the data of 'the loaded zip file'. Is it in a supported JavaScript type (String, Blob, ArrayBuffer, etc) ?");
         }
         return this.loadBuffer(buffer, options);
     }
@@ -435,7 +477,15 @@ class XLSX {
             pivotCacheDefinitions: {},
             pivotCacheRecords: {},
             // Passthrough storage for unknown/unsupported files (charts, etc.)
-            passthrough: {}
+            passthrough: {},
+            // External workbook links — parsed from xl/externalLinks/externalLinkN.xml
+            // during _processDefaultEntry, then reconciled into a dense
+            // ExternalLinkModel[] by reconcile() using workbookRels + <externalReferences>.
+            externalLinksByIndex: {},
+            // Raw rels from each externalLinkN.rels file, keyed by index.
+            // Contains the actual Target path (e.g. "测试.xlsx", "file:///...")
+            // and TargetMode ("External" / "Internal").
+            externalLinkRelsByIndex: {}
         };
     }
     /**
@@ -495,8 +545,12 @@ class XLSX {
                 model.definedNames = workbook.definedNames;
                 model.views = workbook.views;
                 model.properties = workbook.properties;
+                model.protection = workbook.protection;
                 model.calcProperties = workbook.calcProperties;
                 model.pivotCaches = workbook.pivotCaches;
+                // Pass-through the ordered list of <externalReference> rIds. These
+                // get resolved into a dense externalLinks[] during reconcile().
+                model.externalReferences = workbook.externalReferences;
                 return true;
             }
             case OOXML_PATHS.xlSharedStrings:
@@ -525,6 +579,14 @@ class XLSX {
                 model.styles = new StylesXform();
                 await model.styles.parseStream(stream);
                 return true;
+            case OOXML_PATHS.xlMetadata: {
+                const metadataXform = new MetadataXform();
+                const metadataResult = await metadataXform.parseStream(stream);
+                if (metadataResult) {
+                    model.metadata = metadataResult;
+                }
+                return true;
+            }
             default:
                 return false;
         }
@@ -695,12 +757,21 @@ class XLSX {
             comments: model.comments,
             tables: model.tables,
             vmlDrawings: model.vmlDrawings,
-            pivotTables: model.pivotTablesIndexed
+            pivotTables: model.pivotTablesIndexed,
+            hasDynamicArrayMetadata: !!model.metadata?.hasDynamicArrays,
+            dynamicArrayCmIndices: model.metadata?.dynamicArrayCmIndices
         };
         model.worksheets.forEach((worksheet) => {
             worksheet.relationships = model.worksheetRels[worksheet.sheetNo];
             worksheetXform.reconcile(worksheet, sheetOptions);
         });
+        // Reconcile external workbook links before workbookRels / externalReferences
+        // are dropped. Joins 3 sources:
+        //   1. model.externalReferences  — ordered list of { rId } from workbook.xml
+        //   2. model.workbookRels        — maps rId → target path (inside xl/)
+        //   3. model.externalLinksByIndex — parsed externalLinkN.xml parts
+        //   4. model.externalLinkRelsByIndex — parsed externalLinkN.xml.rels parts
+        this._reconcileExternalLinks(model);
         // delete unnecessary parts
         delete model.worksheetHash;
         delete model.worksheetRels;
@@ -716,6 +787,180 @@ class XLSX {
         delete model.drawingRels;
         delete model.vmlDrawings;
         delete model.pivotTableRels;
+        delete model.metadata;
+        // Internal-only scratch fields consumed by _reconcileExternalLinks.
+        delete model.externalReferences;
+        delete model.externalLinksByIndex;
+        delete model.externalLinkRelsByIndex;
+    }
+    /**
+     * Join the three on-disk sources that together describe external workbook
+     * references into a single dense `model.externalLinks: ExternalLinkModel[]`.
+     *
+     * Sources:
+     *   - `<externalReferences>` list in workbook.xml (declaration order)
+     *   - `xl/_rels/workbook.xml.rels` (rId → internal path)
+     *   - `xl/externalLinks/externalLink{N}.xml` (sheet names, cached values)
+     *   - `xl/externalLinks/_rels/externalLink{N}.xml.rels` (target, TargetMode)
+     *
+     * The 1-based index of each resulting ExternalLinkModel matches the `[N]`
+     * used in formula strings — this is the single source of truth formula
+     * code should rely on.
+     */
+    _reconcileExternalLinks(model) {
+        const refs = model.externalReferences;
+        if (!refs || refs.length === 0) {
+            // Even when workbook.xml has no <externalReferences>, we may still
+            // have parsed externalLink parts (e.g. orphaned files); those are
+            // dropped silently rather than generating synthesised indices.
+            if (!model.externalLinks) {
+                model.externalLinks = [];
+            }
+            return;
+        }
+        const rels = (model.workbookRels ?? []);
+        const relById = new Map();
+        for (const rel of rels) {
+            if (rel.Type === RelType.ExternalLink) {
+                relById.set(rel.Id, rel);
+            }
+        }
+        const externalLinks = [];
+        for (let i = 0; i < refs.length; i++) {
+            const ref = refs[i];
+            const rel = relById.get(ref.rId);
+            if (!rel) {
+                // Broken reference — <externalReference> points at an rId that is
+                // not of type ExternalLink. We skip silently; the formula engine
+                // will see the now-missing index and fall back to #REF! as before.
+                continue;
+            }
+            // The rel Target is a path inside xl/ like "externalLinks/externalLink1.xml".
+            // Extract the trailing index to look up the parsed part.
+            const partIndex = externalLinkIndexFromRelTarget(rel.Target);
+            if (partIndex === undefined) {
+                continue;
+            }
+            const parsed = model.externalLinksByIndex[partIndex];
+            const partRels = (model.externalLinkRelsByIndex[partIndex] ?? []);
+            // Locate the externalLinkPath rel (should be unique within a part).
+            const pathRel = partRels.find(r => r.Type === RelType.ExternalLinkPath) ??
+                partRels.find(r => r.TargetMode === "External");
+            externalLinks.push({
+                index: i + 1,
+                rId: ref.rId,
+                target: pathRel?.Target ?? "",
+                targetMode: pathRel?.TargetMode ?? "External",
+                sheetNames: parsed?.sheetNames ?? [],
+                cachedValues: parsed?.cachedValues ?? {}
+            });
+        }
+        model.externalLinks = externalLinks;
+    }
+    /**
+     * Write-time pass that brings the workbook model into a shape the writer
+     * can serialise cleanly. Two concerns:
+     *
+     *   1. Build the final external-link list for this write, combining
+     *      user-declared links (`wb.externalLinks`) with auto-discovered
+     *      ones from previous writes (cached on the Workbook). The result
+     *      is assigned to `model.externalLinks` and consumed by the writer;
+     *      `wb.externalLinks` is **not** modified.
+     *
+     *   2. Scan every formula cell for `[Book]Sheet!` prefixes. Filename-form
+     *      references that don't match an existing link trigger
+     *      `_recordAutoExternalLink()` on the Workbook, which adds the target
+     *      to the private writer cache (so subsequent writes are fixed-point
+     *      stable) but leaves `wb.externalLinks` untouched.
+     *
+     *   3. Rewrite every external-ref formula so it uses the numeric `[N]`
+     *      form, the canonical OOXML storage form. This mutation lands on
+     *      the cell's model object — matching the library's existing
+     *      write-time pattern for `ssId`, `styleId`, `si`, and `cm`.
+     *      Subsequent writes see the `[N]` form directly and resolve it
+     *      against `model.externalLinks`, giving idempotent output.
+     */
+    _normaliseExternalLinks(model) {
+        // Start from user-declared links, honouring their declaration order.
+        const links = this.workbook._collectExternalLinksForWrite();
+        // Fast lookup: case-insensitive target → link object in `links`.
+        const byTarget = new Map();
+        for (const link of links) {
+            if (link.target) {
+                byTarget.set(link.target.toLowerCase(), link);
+            }
+        }
+        const scratch = { links, byTarget, workbook: this.workbook };
+        for (const worksheet of model.worksheets ?? []) {
+            for (const row of worksheet.rows ?? []) {
+                for (const cell of row.cells ?? []) {
+                    if (typeof cell?.formula === "string" && cell.formula.length > 0) {
+                        cell.formula = this._normaliseFormulaExternalRefs(cell.formula, scratch);
+                    }
+                    if (typeof cell?.sharedFormula === "string" && cell.sharedFormula.length > 0) {
+                        // Shared-formula clones typically carry the master's *address*
+                        // here, not a formula body — they won't match the ref regex.
+                        // Masters carry the formula on `.formula` (handled above).
+                        // We rewrite defensively in case a caller stored an actual
+                        // formula string here.
+                        cell.sharedFormula = this._normaliseFormulaExternalRefs(cell.sharedFormula, scratch);
+                    }
+                }
+            }
+        }
+        model.externalLinks = links;
+    }
+    /**
+     * Rewrite a single formula so every external-ref prefix uses the numeric
+     * `[N]` form. When an unknown filename-form reference is found we record
+     * it on the workbook's private writer cache (so the next write can still
+     * resolve it) and append a local link to `scratch.links` so subsequent
+     * refs in the same formula see the freshly-assigned index.
+     */
+    _normaliseFormulaExternalRefs(formula, scratch) {
+        // rewriteExternalRefs internally calls findExternalRefs and returns
+        // the original string unchanged when there are no matches — no need
+        // for a separate guard scan here.
+        return rewriteExternalRefs(formula, ref => {
+            // Numeric ref: accept if it resolves, otherwise preserve verbatim so
+            // Excel surfaces `#REF!` at load time — same as the old behaviour
+            // for truly broken references.
+            if (ref.numeric) {
+                if (ref.index !== null && ref.index >= 1 && ref.index <= scratch.links.length) {
+                    upsertSheet(scratch.links[ref.index - 1], ref.sheet);
+                    return ref.index;
+                }
+                return null;
+            }
+            // Filename form — look up or auto-register.
+            const key = ref.workbook.toLowerCase();
+            let link = scratch.byTarget.get(key);
+            if (!link) {
+                const index = scratch.workbook._recordAutoExternalLink(ref.workbook, ref.sheet);
+                link = {
+                    index,
+                    target: ref.workbook,
+                    targetMode: "External",
+                    sheetNames: ref.sheet ? [ref.sheet] : [],
+                    cachedValues: {}
+                };
+                // Keep the local writer list dense: insert at its future position.
+                // `_recordAutoExternalLink` guarantees `index` is user.length + cache.size
+                // at the time of insertion, which equals `scratch.links.length + 1`
+                // whenever we walk formulas sequentially.
+                scratch.links.push(link);
+                scratch.byTarget.set(key, link);
+            }
+            else {
+                upsertSheet(link, ref.sheet);
+                // Keep the workbook cache's sheetNames in sync so subsequent
+                // writes see the accumulated set.
+                if (ref.sheet) {
+                    scratch.workbook._recordAutoExternalLink(ref.workbook, ref.sheet);
+                }
+            }
+            return link.index;
+        });
     }
     /**
      * Reconcile pivot tables by linking them to worksheets and their cache data.
@@ -971,6 +1216,29 @@ class XLSX {
             model.pivotCacheRecords[name] = cacheRecords;
         }
     }
+    /**
+     * Parse `xl/externalLinks/externalLink{N}.xml` into the intermediate
+     * ParsedExternalLink shape. Reconciliation (joining with the rels file
+     * and the workbook's `<externalReferences>` list) happens later in
+     * {@link reconcile}.
+     */
+    async _processExternalLinkEntry(stream, model, index) {
+        const xform = new ExternalLinkXform();
+        const parsed = await xform.parseStream(stream);
+        if (parsed) {
+            model.externalLinksByIndex[index] = parsed;
+        }
+    }
+    /**
+     * Parse `xl/externalLinks/_rels/externalLink{N}.xml.rels`. The Target /
+     * TargetMode carried here is what Excel uses to locate the actual external
+     * file at open time, so we must preserve it verbatim (including relative
+     * paths like `"测试.xlsx"`).
+     */
+    async _processExternalLinkRelsEntry(stream, model, index) {
+        const relationships = await this.parseRels(stream);
+        model.externalLinkRelsByIndex[index] = relationships ?? [];
+    }
     // ===========================================================================
     // loadFromFiles - shared logic for loading from pre-extracted ZIP data
     // ===========================================================================
@@ -1082,6 +1350,20 @@ class XLSX {
             await this._processPivotCacheRecordsEntry(stream, model, pivotCacheRecordsName);
             return true;
         }
+        // External workbook links: xl/externalLinks/externalLinkN.xml and its
+        // sibling _rels file. Both parts are required to reconstruct the
+        // ExternalLinkModel (the .xml carries sheet names + cached values; the
+        // .rels carries the target path and TargetMode).
+        const externalLinkIndex = getExternalLinkIndexFromPath(entryName);
+        if (externalLinkIndex !== undefined) {
+            await this._processExternalLinkEntry(stream, model, externalLinkIndex);
+            return true;
+        }
+        const externalLinkRelsIndex = getExternalLinkIndexFromRelsPath(entryName);
+        if (externalLinkRelsIndex !== undefined) {
+            await this._processExternalLinkRelsEntry(stream, model, externalLinkRelsIndex);
+            return true;
+        }
         // Store passthrough files (charts, etc.) for preservation
         if (PassthroughManager.isPassthroughPath(entryName)) {
             // If raw data is available (loadFromFiles path), use it directly
@@ -1163,6 +1445,14 @@ class XLSX {
                 Target: OOXML_REL_TARGETS.workbookFeaturePropertyBag
             });
         }
+        // Add metadata relationship for dynamic array formulas
+        if (model.hasDynamicArrayFormulas) {
+            relationships.push({
+                Id: `rId${count++}`,
+                Type: XLSX.RelType.SheetMetadata,
+                Target: OOXML_REL_TARGETS.workbookMetadata
+            });
+        }
         // R9-B6: Deduplicate pivot cache relationships by cacheId. When multiple pivot
         // tables share the same cache, only one workbook relationship should be created.
         // Also assigns rId to each pivot table (R9-B7: typed on PivotTable interface).
@@ -1192,6 +1482,26 @@ class XLSX {
                 Target: worksheetRelTarget(worksheet.fileIndex)
             });
         });
+        // External workbook link rels are written AFTER worksheets on purpose:
+        // Excel tolerates either order, but stable ordering (worksheets then
+        // externalLinks) keeps the emitted workbook.xml.rels diff-friendly for
+        // round-trip tests. Each external link becomes a regular Relationship
+        // entry targeting `externalLinks/externalLinkN.xml` inside `xl/`; the
+        // actual external file path is pointed at by the nested
+        // externalLinkN.xml.rels part written by addExternalLinks().
+        //
+        // The list items here are the deep-copies produced by
+        // `_normaliseExternalLinks` — assigning `link.rId` is safe and does not
+        // leak into the user's Workbook.externalLinks.
+        const externalLinks = (model.externalLinks ?? []);
+        for (const link of externalLinks) {
+            link.rId = `rId${count++}`;
+            relationships.push({
+                Id: link.rId,
+                Type: XLSX.RelType.ExternalLink,
+                Target: externalLinkRelTargetFromWorkbook(link.index)
+            });
+        }
         const xform = new RelationshipsXform();
         await this._renderToZip(zip, OOXML_PATHS.xlWorkbookRels, xform, relationships);
     }
@@ -1201,6 +1511,14 @@ class XLSX {
         }
         await this._renderToZip(zip, OOXML_PATHS.xlFeaturePropertyBag, new FeaturePropertyBagXform(), {});
     }
+    async addMetadata(zip, model) {
+        if (!model.hasDynamicArrayFormulas) {
+            return;
+        }
+        await this._renderToZip(zip, OOXML_PATHS.xlMetadata, new MetadataXform(), {
+            dynamicArrayCount: model.dynamicArrayCount
+        });
+    }
     async addSharedStrings(zip, model) {
         if (model.sharedStrings && model.sharedStrings.count) {
             await this._renderToZip(zip, OOXML_PATHS.xlSharedStrings, model.sharedStrings, model.sharedStrings.model);
@@ -1316,6 +1634,41 @@ class XLSX {
             }
         }
     }
+    /**
+     * Write every external workbook reference into the archive. For each
+     * {@link ExternalLinkModel} in `model.externalLinks` we emit two files:
+     *
+     *   xl/externalLinks/externalLink{index}.xml          — sheet names + cache
+     *   xl/externalLinks/_rels/externalLink{index}.xml.rels — target path
+     *
+     * The target-path rel carries `TargetMode="External"` with a **bare
+     * relative** `Target` whenever the user supplied one. This is the single
+     * line that makes Office / WPS resolve the referenced workbook relative
+     * to the current file's directory (not the `%USERPROFILE%\Documents`
+     * fallback) — the root of the behaviour reported in exceljs#3039.
+     */
+    async addExternalLinks(zip, model) {
+        const externalLinks = (model.externalLinks ?? []);
+        if (externalLinks.length === 0) {
+            return;
+        }
+        const externalLinkXform = new ExternalLinkXform();
+        const relsXform = new RelationshipsXform();
+        for (const link of externalLinks) {
+            await this._renderToZip(zip, externalLinkPath(link.index), externalLinkXform, link);
+            // Always rId1 — the externalLink part only ever has a single rel.
+            // `TargetMode="External"` is what flags Office to look the file up
+            // at workbook-open time rather than embed it.
+            await this._renderToZip(zip, externalLinkRelsPath(link.index), relsXform, [
+                {
+                    Id: "rId1",
+                    Type: XLSX.RelType.ExternalLinkPath,
+                    Target: link.target,
+                    TargetMode: link.targetMode ?? "External"
+                }
+            ]);
+        }
+    }
     /**
      * Write passthrough files (charts, etc.) that were preserved during read.
      * These files are written back unchanged to preserve unsupported features.
@@ -1409,6 +1762,18 @@ class XLSX {
         const workbookXform = new WorkbookXform();
         const worksheetXform = new WorkSheetXform();
         workbookXform.prepare(model);
+        // Normalise external-workbook references before any formula rendering.
+        // Two jobs:
+        //   1. Scan every formula cell and make sure each referenced workbook
+        //      has a matching ExternalLinkModel in `model.externalLinks`, with
+        //      a stable 1-based index.
+        //   2. Rewrite formula strings from `[filename.xlsx]Sheet!A1` to
+        //      `[N]Sheet!A1`, which is the canonical on-disk form Excel
+        //      expects inside `<f>` elements.
+        //
+        // Done once up-front (not per cell) so the index assignment is
+        // deterministic and every cell sees the final externalLinks list.
+        this._normaliseExternalLinks(model);
         const worksheetOptions = {
             sharedStrings: model.sharedStrings,
             styles: model.styles,
@@ -1422,6 +1787,7 @@ class XLSX {
         model.hasHeaderWatermark = false;
         let tableCount = 0;
         model.tables = [];
+        const tableNameMap = new Map(); // name (lowercase) → worksheet name
         model.worksheets.forEach((worksheet, index) => {
             // Assign fileIndex early so that worksheet-xform.prepare() can use it
             // for comment/VML relationship targets and content type names.
@@ -1429,6 +1795,16 @@ class XLSX {
             // using the same fileIndex.
             worksheet.fileIndex = index + 1;
             worksheet.tables.forEach((table) => {
+                // OOXML requires table names to be unique across the entire workbook
+                // (case-insensitive). Detect duplicates early to produce a clear error
+                // instead of generating a corrupt file that Excel must repair.
+                const nameKey = table.name.toLowerCase();
+                const existingSheet = tableNameMap.get(nameKey);
+                if (existingSheet !== undefined) {
+                    throw new TableError(`Duplicate table name "${table.name}": already used in worksheet "${existingSheet}". ` +
+                        `Table names must be unique across the entire workbook (case-insensitive).`);
+                }
+                tableNameMap.set(nameKey, worksheet.name);
                 tableCount++;
                 table.target = `table${tableCount}.xml`;
                 table.id = tableCount;
@@ -1438,6 +1814,20 @@ class XLSX {
         });
         // ContentTypesXform expects this flag
         model.hasCheckboxes = model.styles.hasCheckboxes;
+        // Scan all worksheets for dynamic array formulas.
+        // cm=1 is assigned later by cell-xform.prepare() during worksheet rendering.
+        let dynamicArrayCount = 0;
+        model.worksheets.forEach((worksheet) => {
+            (worksheet.rows ?? []).forEach((row) => {
+                (row.cells ?? []).forEach((cell) => {
+                    if (cell.isDynamicArray) {
+                        dynamicArrayCount++;
+                    }
+                });
+            });
+        });
+        model.hasDynamicArrayFormulas = dynamicArrayCount > 0;
+        model.dynamicArrayCount = dynamicArrayCount;
         // Propagate header watermark flag from worksheet prepare options
         if (worksheetOptions.hasHeaderWatermark) {
             model.hasHeaderWatermark = true;

package/dist/esm/modules/excel/xlsx/xlsx.js

@@ -100,7 +100,7 @@ class XLSX extends XLSXBase {
                     }
                 }
                 catch (e) {
-                    callback(e);
+                    callback(toError(e));
                 }
             },
             final(callback) {
@@ -109,13 +109,13 @@ class XLSX extends XLSXBase {
                     callback();
                 }
                 catch (e) {
-                    callback(e);
+                    callback(toError(e));
                 }
             }
         });
         const onParserError = (err) => {
             try {
-                sink.destroy(err);
+                sink.destroy(toError(err));
             }
             catch {
                 // ignore
@@ -127,8 +127,7 @@ class XLSX extends XLSXBase {
             for await (const entry of XLSX.iterateZipEntries(parser)) {
                 entry.on("error", swallowError);
                 const drain = async () => {
-                    const anyEntry = entry;
-                    if (anyEntry?.readableEnded || anyEntry?.destroyed) {
+                    if (entry.readableEnded || entry.destroyed) {
                         return;
                     }
                     const draining = entry.autodrain();