@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/esm/modules/excel/utils/workbook-protection.js

@@ -0,0 +1,30 @@
+import { Encryptor } from "./encryptor.js";
+import { uint8ArrayToBase64 } from "../../../utils/utils.js";
+/**
+ * Build a workbook-protection object with optional password hashing.
+ *
+ * This is the shared implementation used by both `Workbook.protect()` and
+ * `WorkbookWriter.protect()`. The caller is responsible for assigning the
+ * result to its own `protection` field.
+ *
+ * @param password - Optional password to hash
+ * @param options  - Optional protection flags (lockStructure, lockWindows, lockRevision, spinCount)
+ * @returns A fully-populated workbook-protection object
+ */
+export async function buildWorkbookProtection(password, options) {
+    const protection = {
+        lockStructure: options?.lockStructure ?? true,
+        lockWindows: options?.lockWindows,
+        lockRevision: options?.lockRevision
+    };
+    if (password) {
+        protection.algorithmName = "SHA-512";
+        protection.saltValue = uint8ArrayToBase64(Encryptor.randomBytes(16));
+        protection.spinCount =
+            options?.spinCount != null && Number.isFinite(options.spinCount)
+                ? Math.round(Math.max(0, options.spinCount))
+                : 100000;
+        protection.hashValue = await Encryptor.convertPasswordToHash(password, "SHA-512", protection.saltValue, protection.spinCount);
+    }
+    return protection;
+}

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

@@ -17,8 +17,10 @@ import { DefinedNames } from "./defined-names.js";
 import { ExcelDownloadError, ExcelNotSupportedError } from "./errors.js";
 import { WorkbookReader } from "./stream/workbook-reader.js";
 import { WorkbookWriter } from "./stream/workbook-writer.js";
+import { buildWorkbookProtection } from "./utils/workbook-protection.js";
 import { Worksheet } from "./worksheet.js";
 import { XLSX } from "./xlsx/xlsx.js";
+import { invokeFormulaEngine } from "../formula/host-registry.js";
 import { formatMarkdown } from "../markdown/format/index.js";
 import { parseMarkdown, parseMarkdownAll } from "../markdown/parse/index.js";
 import { pipeline } from "../stream/index.js";
@@ -70,48 +72,80 @@ function createDefaultValueMapper(dateFormats, options) {
                 return datumNumber;
             }
         }
-        const date = dateParser.parse(datum);
-        if (date) {
-            return date;
-        }
-        const special = SpecialValues[datum];
-        if (special !== undefined) {
-            return special;
+        if (typeof datum === "string") {
+            const date = dateParser.parse(datum);
+            if (date) {
+                return date;
+            }
+            const special = SpecialValues[datum];
+            if (special !== undefined) {
+                return special;
+            }
         }
         return datum;
     };
 }
 /**
  * Create a value mapper for writing Excel values to CSV format.
- * Handles hyperlinks, formulas, rich text, dates, errors, and objects.
+ *
+ * Branches below correspond to each member of the `CellValue` union, in an
+ * order that prefers the most specific shape:
+ *   1. Hyperlink   — emit the URL (falling back to display text)
+ *   2. Formula / SharedFormula / ArrayFormula — emit the evaluated `result`
+ *   3. RichText    — flatten runs to plain text
+ *   4. Checkbox    — emit the boolean state
+ *   5. Error       — emit the Excel error token (e.g. "#N/A")
+ *   6. Date        — format via the configured DateFormatter
+ *   7. Primitive   — pass through (`string | number | boolean | null | undefined`)
+ *
+ * An object that does not match any of the above is stringified as JSON so
+ * the CSV remains round-trippable rather than producing `[object Object]`.
  */
 function createDefaultWriteMapper(dateFormat, dateUTC) {
     const formatter = dateFormat
         ? DateFormatter.create(dateFormat, { utc: dateUTC })
         : DateFormatter.iso(dateUTC);
     return function mapValue(value) {
-        if (value) {
-            if (value.text || value.hyperlink) {
-                return value.hyperlink || value.text || "";
-            }
-            if (value.formula || value.result) {
-                return value.result || "";
-            }
-            // Handle rich text - extract and concatenate all text fragments
-            if (value.richText && Array.isArray(value.richText)) {
-                return value.richText.map((r) => r.text).join("");
-            }
-            if (value instanceof Date) {
-                return formatter.format(value);
-            }
-            if (value.error) {
-                return value.error;
-            }
-            if (typeof value === "object") {
-                return JSON.stringify(value);
-            }
+        if (value === null || value === undefined) {
+            return value;
+        }
+        if (value instanceof Date) {
+            return formatter.format(value);
+        }
+        if (typeof value !== "object") {
+            // string | number | boolean
+            return value;
+        }
+        // --- Object variants of CellValue ---
+        // Hyperlink: prefer URL, fall back to display text.
+        // Accepts objects carrying either `hyperlink` or just `text` — the latter
+        // is a historical input shape some callers use to denote a "link-like"
+        // cell value without an actual URL; preserving it maintains backward
+        // compatibility with pre-existing CSV output.
+        const maybeLink = value;
+        if (typeof maybeLink.hyperlink === "string" || typeof maybeLink.text === "string") {
+            const url = typeof maybeLink.hyperlink === "string" ? maybeLink.hyperlink : "";
+            const text = typeof maybeLink.text === "string" ? maybeLink.text : "";
+            return url || text || "";
+        }
+        // Formula / SharedFormula / ArrayFormula — all carry an evaluated `result`
+        if ("formula" in value || "sharedFormula" in value) {
+            return value.result ?? "";
+        }
+        // Rich text — flatten runs
+        if ("richText" in value && Array.isArray(value.richText)) {
+            return value.richText.map(r => r.text).join("");
+        }
+        // Checkbox
+        if ("checkbox" in value && typeof value.checkbox === "boolean") {
+            return value.checkbox;
         }
-        return value;
+        // Error
+        if ("error" in value && typeof value.error === "string") {
+            return value.error;
+        }
+        // Unknown object shape — round-trippable fallback
+        return JSON.stringify(value);
     };
 }
 // =============================================================================
@@ -238,7 +272,18 @@ class Workbook {
     // ===========================================================================
     // Constructor
     // ===========================================================================
-    constructor() {
+    /**
+     * @param options Optional construction options.
+     *   - `formulaSyntaxProbe`: An explicit tokenizer+parser probe used to
+     *     classify defined-name text during XLSX load. Providing this makes
+     *     classification deterministic for *this* workbook regardless of
+     *     whether `installFormulaEngine()` has been called. Most callers
+     *     don't need it — `installFormulaEngine()` registers a
+     *     process-wide default probe that is picked up automatically.
+     */
+    constructor(options) {
+        /** Global registry of table names (lowercase) for cross-worksheet uniqueness checks. */
+        this._tableNames = new Set();
         this.category = "";
         this.company = "";
         this.created = new Date();
@@ -254,9 +299,33 @@ class Workbook {
         this.views = [];
         this.media = [];
         this.pivotTables = [];
+        this.externalLinks = [];
         this._passthrough = {};
         this._rawDrawings = {};
-        this._definedNames = new DefinedNames();
+        this._writerExternalLinkCache = new Map();
+        this._definedNames = new DefinedNames(options?.formulaSyntaxProbe);
+    }
+    // ===========================================================================
+    // Default Font
+    // ===========================================================================
+    /**
+     * The default font for the workbook (fontId=0 / "Normal" style).
+     * Cells without explicit font styles will inherit this font in Excel.
+     *
+     * @example
+     * ```ts
+     * wb.defaultFont = { name: "Arial", size: 12 };
+     * ```
+     *
+     * When reading an existing XLSX file, this preserves the original default font
+     * for round-trip fidelity. Setting it on a new workbook changes the default
+     * from Calibri 11 to your chosen font.
+     */
+    get defaultFont() {
+        return this._defaultFont;
+    }
+    set defaultFont(font) {
+        this._defaultFont = font;
     }
     // ===========================================================================
     // Sheet Import
@@ -285,6 +354,25 @@ class Workbook {
         return newWs;
     }
     // ===========================================================================
+    // Workbook Protection
+    // ===========================================================================
+    /**
+     * Protect the workbook structure with an optional password.
+     * Prevents users from adding, deleting, renaming, moving, or copying worksheets.
+     *
+     * @param password - Optional password to protect the structure
+     * @param options  - Optional protection flags (lockStructure, lockWindows, lockRevision)
+     */
+    async protect(password, options) {
+        this.protection = await buildWorkbookProtection(password, options);
+    }
+    /**
+     * Remove workbook structure protection.
+     */
+    unprotect() {
+        this.protection = undefined;
+    }
+    // ===========================================================================
     // Format Operations (xlsx)
     // ===========================================================================
     /**
@@ -431,7 +519,10 @@ class Workbook {
             });
         }
         parser.on("data", (row) => {
-            // When headers: true, CsvParserStream emits objects; otherwise arrays
+            // When headers: true, CsvParserStream emits objects; otherwise arrays.
+            // The CSV parser only ever emits primitive CellValue-compatible shapes
+            // (string/number/boolean/Date/null). Narrow once here so the rest of
+            // the pipeline — including the user-supplied `map` — sees CellValue.
             if (useHeaders && headerRow && row && typeof row === "object" && !Array.isArray(row)) {
                 // Convert object row to array using header order
                 const rowObj = row;
@@ -498,7 +589,8 @@ class Workbook {
                 });
             }
             parser.on("data", (row) => {
-                // When headers: true, CsvParserStream emits objects; otherwise arrays
+                // When headers: true, CsvParserStream emits objects; otherwise arrays.
+                // See createCsvReadStream for the rationale on narrowing to CellValue.
                 if (useHeaders && headerRow && row && typeof row === "object" && !Array.isArray(row)) {
                     // Convert object row to array using header order
                     const rowObj = row;
@@ -925,6 +1017,50 @@ class Workbook {
         return this._definedNames;
     }
     // ===========================================================================
+    // Formula Calculation
+    // ===========================================================================
+    /**
+     * Recalculate all formula cells in this workbook.
+     *
+     * Evaluates every formula cell using the built-in calculation engine and updates
+     * each cell's cached `result` value in-place. Formulas are evaluated with
+     * recursive dependency resolution, memoization, and circular reference detection.
+     *
+     * Call this after programmatically modifying cell values that are referenced by
+     * formulas, to ensure formula results reflect the latest data.
+     *
+     * Unsupported functions preserve their original cached result if one exists.
+     *
+     * ## Tree-shaking note
+     *
+     * The formula engine ships ~200KB of code (433 Excel functions, parser,
+     * evaluator, dependency graph, spill materialiser). To keep it out of
+     * bundles that don't need it, the engine is registered at runtime
+     * rather than imported by the core `Workbook` module. Call
+     * {@link installFormulaEngine} once at startup before the first call
+     * to this method, or a clear error will be thrown explaining what to do.
+     *
+     * ```ts
+     * import { installFormulaEngine } from "@cj-tech-master/excelts/formula";
+     *
+     * installFormulaEngine();                   // once, at startup
+     *
+     * sheet.getCell("A1").value = 100;
+     * workbook.calculateFormulas();             // now works
+     * ```
+     *
+     * Callers who prefer a zero-side-effect, tree-shakeable surface can
+     * use the functional equivalent directly:
+     *
+     * ```ts
+     * import { calculateFormulas } from "@cj-tech-master/excelts/formula";
+     * calculateFormulas(workbook);
+     * ```
+     */
+    calculateFormulas() {
+        invokeFormulaEngine(this);
+    }
+    // ===========================================================================
     // Themes
     // ===========================================================================
     clearThemes() {
@@ -946,6 +1082,145 @@ class Workbook {
         return this.media[Number(id)];
     }
     // ===========================================================================
+    // External Workbook Links
+    // ===========================================================================
+    /**
+     * Declare that formulas in this workbook may reference an external
+     * workbook. Registers the target so the output file contains the required
+     * `xl/externalLinks/externalLink{N}.xml` part plus its `.rels` sibling
+     * and Office/WPS can resolve the reference correctly.
+     *
+     * When Office opens the file, it resolves a relative `target` like
+     * `"测试.xlsx"` **relative to the current workbook's directory** — which
+     * is the exact behaviour the user expects when they write
+     * `=[测试.xlsx]Sheet1!A1`. Absolute `file:///…` or `http(s)://…` URIs
+     * are accepted and written through unchanged.
+     *
+     * @returns the registered {@link ExternalLinkModel}. Its `index` field is
+     *   the 1-based number used inside the `[N]` prefix of on-disk formula
+     *   strings (the library rewrites `[target]` forms to `[index]` at write
+     *   time automatically).
+     *
+     * @example
+     * ```ts
+     * const wb = new Workbook();
+     * const ws = wb.addWorksheet("Main");
+     *
+     * // Declare the link once — sheet names and cached values are optional
+     * // but improve interoperability (Excel displays cached values when the
+     * // external file is unavailable).
+     * wb.addExternalLink({
+     *   target: "测试.xlsx",
+     *   sheetNames: ["Sheet1"],
+     *   cachedValues: { Sheet1: { A1: 42 } }
+     * });
+     *
+     * // Write the formula using either the target name OR the numeric index;
+     * // the library normalises both to the on-disk `[N]` form.
+     * ws.getCell("A1").value = { formula: "=[测试.xlsx]Sheet1!A1", result: 42 };
+     * ```
+     */
+    addExternalLink(input) {
+        const link = {
+            index: this.externalLinks.length + 1,
+            target: input.target,
+            targetMode: input.targetMode ?? "External",
+            sheetNames: input.sheetNames ? [...input.sheetNames] : [],
+            cachedValues: input.cachedValues ? { ...input.cachedValues } : {}
+        };
+        this.externalLinks.push(link);
+        return link;
+    }
+    /**
+     * Retrieve an external link by its 1-based on-disk index (the number
+     * inside the `[N]` formula prefix) or by matching target path.
+     */
+    getExternalLink(indexOrTarget) {
+        if (typeof indexOrTarget === "number") {
+            return this.externalLinks[indexOrTarget - 1];
+        }
+        const lower = indexOrTarget.toLowerCase();
+        return this.externalLinks.find(link => link.target.toLowerCase() === lower);
+    }
+    /**
+     * @internal — used by the writer to obtain the full list of external
+     * links to serialise, including entries auto-discovered from formula
+     * strings during earlier writes. User-visible `externalLinks` always
+     * comes first (in declaration order) so explicit `addExternalLink()`
+     * indices are stable across writes.
+     */
+    _collectExternalLinksForWrite() {
+        const userLower = new Set(this.externalLinks.map(l => l.target.toLowerCase()));
+        const combined = this.externalLinks.map((link, i) => ({
+            ...link,
+            index: i + 1,
+            sheetNames: [...(link.sheetNames ?? [])],
+            cachedValues: { ...(link.cachedValues ?? {}) },
+            targetMode: link.targetMode ?? "External"
+        }));
+        for (const cached of this._writerExternalLinkCache.values()) {
+            if (userLower.has(cached.target.toLowerCase())) {
+                // User explicitly added a link with the same target after an
+                // auto-discovery pass — prefer the user's definition, drop the
+                // cached one.
+                continue;
+            }
+            combined.push({
+                ...cached,
+                index: combined.length + 1,
+                sheetNames: [...cached.sheetNames],
+                cachedValues: { ...cached.cachedValues }
+            });
+        }
+        return combined;
+    }
+    /**
+     * @internal — record an auto-discovered external link (seen in a
+     * formula but not explicitly declared). Idempotent by target; the
+     * sheet name is upserted onto the existing cached entry when present.
+     * Returns the 1-based index the link will carry in the output file.
+     */
+    _recordAutoExternalLink(target, sheetName) {
+        const lower = target.toLowerCase();
+        // If the user explicitly declared a link with this target, we respect
+        // their definition verbatim: no sheetName upserts, no cache entry.
+        // Excel needs the user-declared sheetNames to match the refs, and
+        // augmenting them on the user's behalf could silently hide a typo.
+        const existingUserIdx = this.externalLinks.findIndex(l => l.target.toLowerCase() === lower);
+        if (existingUserIdx !== -1) {
+            return existingUserIdx + 1;
+        }
+        let cached = this._writerExternalLinkCache.get(lower);
+        if (!cached) {
+            cached = {
+                // Index is provisional — the real on-disk index is recomputed by
+                // `_collectExternalLinksForWrite()` at serialisation time.
+                index: 0,
+                target,
+                targetMode: "External",
+                sheetNames: [],
+                cachedValues: {}
+            };
+            this._writerExternalLinkCache.set(lower, cached);
+        }
+        if (sheetName && !cached.sheetNames.includes(sheetName)) {
+            cached.sheetNames.push(sheetName);
+        }
+        // Recompute final index: user entries first, then cache entries in
+        // insertion order. The caller needs the *on-disk* index so that the
+        // formula it's rewriting matches the link that will be serialised.
+        const userCount = this.externalLinks.length;
+        let cacheIdx = 0;
+        for (const key of this._writerExternalLinkCache.keys()) {
+            cacheIdx++;
+            if (key === lower) {
+                return userCount + cacheIdx;
+            }
+        }
+        // Unreachable — we just inserted.
+        return userCount + this._writerExternalLinkCache.size;
+    }
+    // ===========================================================================
     // Model (Serialization)
     // ===========================================================================
     get model() {
@@ -956,6 +1231,7 @@ class Workbook {
             created: this.created,
             modified: this.modified,
             properties: this.properties,
+            protection: this.protection,
             worksheets: this.worksheets.map(worksheet => worksheet.model),
             sheets: this.worksheets.map(ws => ws.model).filter(Boolean),
             definedNames: this._definedNames.model,
@@ -976,7 +1252,8 @@ class Workbook {
             calcProperties: this.calcProperties,
             passthrough: this._passthrough,
             rawDrawings: this._rawDrawings,
-            defaultFont: this._defaultFont
+            defaultFont: this._defaultFont,
+            externalLinks: this.externalLinks
         };
     }
     set model(value) {
@@ -996,8 +1273,10 @@ class Workbook {
         this.revision = value.revision;
         this.contentStatus = value.contentStatus;
         this.properties = value.properties;
+        this.protection = value.protection;
         this.calcProperties = value.calcProperties;
         this._worksheets = [];
+        this._tableNames.clear();
         value.worksheets.forEach(worksheetModel => {
             const { id, name, state } = worksheetModel;
             const orderNo = value.sheets && value.sheets.findIndex(ws => ws.id === id);
@@ -1023,6 +1302,11 @@ class Workbook {
         this._rawDrawings = value.rawDrawings || {};
         // Preserve default font for round-trip fidelity
         this._defaultFont = value.defaultFont;
+        // Preserve external workbook references (empty array if none)
+        this.externalLinks = value.externalLinks ? [...value.externalLinks] : [];
+        // Reset the writer-scoped auto-discovery cache — loading a fresh
+        // workbook replaces any accumulated state from previous writes.
+        this._writerExternalLinkCache = new Map();
     }
 }
 // ===========================================================================

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

@@ -1,7 +1,7 @@
 import { Column } from "./column.js";
 import { DataValidations } from "./data-validations.js";
 import { Enums } from "./enums.js";
-import { WorksheetNameError, MergeConflictError } from "./errors.js";
+import { WorksheetNameError, MergeConflictError, TableError } from "./errors.js";
 import { FormCheckbox } from "./form-control.js";
 import { Image } from "./image.js";
 import { makePivotTable } from "./pivot-table.js";
@@ -104,6 +104,8 @@ class Worksheet {
         this.conditionalFormattings = [];
         // for form controls (legacy checkboxes, etc.)
         this.formControls = [];
+        // ignored errors (suppress green triangles in Excel)
+        this.ignoredErrors = [];
         // watermark configuration
         this._watermark = null;
     }
@@ -1107,8 +1109,19 @@ class Worksheet {
      */
     addTable(model) {
         const table = new Table(this, model);
-        // Use table.name (sanitized by Table.validate()) as the key
+        // table.name is sanitized by Table.validate() — check against the
+        // sanitized name so that e.g. "My Table" and "My_Table" (which both
+        // sanitize to "My_Table") are correctly detected as duplicates.
+        const nameKey = table.name.toLowerCase();
+        if (this.tables[table.name]) {
+            throw new TableError(`Table name "${table.name}" already exists in worksheet "${this.name}".`);
+        }
+        if (this.workbook._tableNames.has(nameKey)) {
+            throw new TableError(`Table name "${table.name}" already exists in another worksheet. ` +
+                `Table names must be unique across the entire workbook (case-insensitive).`);
+        }
         this.tables[table.name] = table;
+        this.workbook._tableNames.add(nameKey);
         return table;
     }
     /**
@@ -1121,6 +1134,9 @@ class Worksheet {
      * Delete table by name
      */
     removeTable(name) {
+        if (this.tables[name]) {
+            this.workbook._tableNames.delete(name.toLowerCase());
+        }
         delete this.tables[name];
     }
     /**
@@ -1368,6 +1384,7 @@ class Worksheet {
             pivotTables: this.pivotTables,
             conditionalFormattings: this.conditionalFormattings,
             formControls: this.formControls.map(fc => fc.model),
+            ignoredErrors: this.ignoredErrors,
             watermark: this._watermark,
             drawing: this._drawing
         };
@@ -1452,10 +1469,12 @@ class Worksheet {
             const t = new Table(this, table);
             t.model = table;
             tables[table.name] = t;
+            this.workbook._tableNames.add(table.name.toLowerCase());
             return tables;
         }, {});
         this.pivotTables = value.pivotTables;
         this.conditionalFormattings = value.conditionalFormattings;
+        this.ignoredErrors = value.ignoredErrors ?? [];
         // Form controls are currently write-only (not parsed from XLSX)
         this.formControls = [];
         // Preserve loaded drawing data (charts, etc.)

package/dist/esm/modules/excel/xlsx/rel-type.js

@@ -16,6 +16,21 @@ const RelType = {
     PivotCacheRecords: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheRecords",
     PivotTable: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotTable",
     FeaturePropertyBag: "http://schemas.microsoft.com/office/2022/11/relationships/FeaturePropertyBag",
-    CtrlProp: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/ctrlProp"
+    CtrlProp: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/ctrlProp",
+    SheetMetadata: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sheetMetadata",
+    /**
+     * Relationship type for the externalLink part referenced from
+     * xl/_rels/workbook.xml.rels. Target is an internal path like
+     * `externalLinks/externalLink1.xml`.
+     */
+    ExternalLink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/externalLink",
+    /**
+     * Relationship type used *inside* xl/externalLinks/_rels/externalLinkN.xml.rels
+     * to point at the actual external workbook. When `TargetMode="External"` and
+     * `Target` is a bare relative path (e.g. `"测试.xlsx"`), Office resolves it
+     * relative to the current workbook's directory — exactly the behaviour users
+     * expect from `=[测试.xlsx]Sheet1!A1`.
+     */
+    ExternalLinkPath: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/externalLinkPath"
 };
 export { RelType };