@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/excel/utils/ooxml-paths.js

@@ -8,7 +8,8 @@ export const OOXML_PATHS = {
     xlSharedStrings: "xl/sharedStrings.xml",
     xlStyles: "xl/styles.xml",
     xlTheme1: "xl/theme/theme1.xml",
-    xlFeaturePropertyBag: "xl/featurePropertyBag/featurePropertyBag.xml"
+    xlFeaturePropertyBag: "xl/featurePropertyBag/featurePropertyBag.xml",
+    xlMetadata: "xl/metadata.xml"
 };
 const worksheetXmlRegex = /^xl\/worksheets\/sheet(\d+)[.]xml$/;
 const worksheetRelsXmlRegex = /^xl\/worksheets\/_rels\/sheet(\d+)[.]xml[.]rels$/;
@@ -25,6 +26,9 @@ const pivotTableRelsXmlRegex = /^xl\/pivotTables\/_rels\/(pivotTable\d+)[.]xml[.
 const pivotCacheDefinitionXmlRegex = /^xl\/pivotCache\/(pivotCacheDefinition\d+)[.]xml$/;
 const pivotCacheDefinitionRelsXmlRegex = /^xl\/pivotCache\/_rels\/(pivotCacheDefinition\d+)[.]xml[.]rels$/;
 const pivotCacheRecordsXmlRegex = /^xl\/pivotCache\/(pivotCacheRecords\d+)[.]xml$/;
+// External workbook links (xl/externalLinks/externalLink{n}.xml and its rels)
+const externalLinkXmlRegex = /^xl\/externalLinks\/externalLink(\d+)[.]xml$/;
+const externalLinkRelsXmlRegex = /^xl\/externalLinks\/_rels\/externalLink(\d+)[.]xml[.]rels$/;
 export function normalizeZipPath(path) {
     return path.startsWith("/") ? path.slice(1) : path;
 }
@@ -105,6 +109,22 @@ export function getPivotCacheRecordsNameFromPath(path) {
     const match = pivotCacheRecordsXmlRegex.exec(path);
     return match ? match[1] : undefined;
 }
+/**
+ * Extract the 1-based index `N` from `xl/externalLinks/externalLink{N}.xml`.
+ * Returns the raw integer (e.g. `1` for externalLink1.xml) or undefined.
+ */
+export function getExternalLinkIndexFromPath(path) {
+    const match = externalLinkXmlRegex.exec(path);
+    return match ? parseInt(match[1], 10) : undefined;
+}
+/**
+ * Extract the 1-based index `N` from
+ * `xl/externalLinks/_rels/externalLink{N}.xml.rels`.
+ */
+export function getExternalLinkIndexFromRelsPath(path) {
+    const match = externalLinkRelsXmlRegex.exec(path);
+    return match ? parseInt(match[1], 10) : undefined;
+}
 export function toContentTypesPartName(zipPath) {
     // ContentTypes uses leading slash PartName (e.g. "/xl/workbook.xml").
     return zipPath.startsWith("/") ? zipPath : `/${zipPath}`;
@@ -167,6 +187,20 @@ export function pivotTablePath(n) {
 export function pivotTableRelsPath(n) {
     return `xl/pivotTables/_rels/pivotTable${n}.xml.rels`;
 }
+// -------- External links --------
+export function externalLinkPath(n) {
+    return `xl/externalLinks/externalLink${n}.xml`;
+}
+export function externalLinkRelsPath(n) {
+    return `xl/externalLinks/_rels/externalLink${n}.xml.rels`;
+}
+/**
+ * Build the `Target` value for an externalLink relationship inside
+ * `xl/_rels/workbook.xml.rels` (base: `xl/`).
+ */
+export function externalLinkRelTargetFromWorkbook(n) {
+    return `externalLinks/externalLink${n}.xml`;
+}
 export function pivotCacheDefinitionRelTargetFromPivotTable(n) {
     return `../pivotCache/pivotCacheDefinition${n}.xml`;
 }
@@ -175,7 +209,8 @@ export const OOXML_REL_TARGETS = {
     workbookStyles: "styles.xml",
     workbookSharedStrings: "sharedStrings.xml",
     workbookTheme1: "theme/theme1.xml",
-    workbookFeaturePropertyBag: "featurePropertyBag/featurePropertyBag.xml"
+    workbookFeaturePropertyBag: "featurePropertyBag/featurePropertyBag.xml",
+    workbookMetadata: "metadata.xml"
 };
 export function pivotCacheDefinitionRelTargetFromWorkbook(n) {
     // Target inside xl/_rels/workbook.xml.rels (base: xl/)

package/dist/browser/modules/excel/utils/shared-strings.d.ts

@@ -1,12 +1,17 @@
+import type { RichText } from "../types.js";
+/** A shared-string entry may be a plain string or a rich-text payload. */
+export type SharedStringValue = string | {
+    richText: RichText[];
+};
 declare class SharedStrings {
     private _values;
     private _totalRefs;
     private _hash;
     constructor();
     get count(): number;
-    get values(): any[];
+    get values(): SharedStringValue[];
     get totalRefs(): number;
-    getString(index: number): any;
-    add(value: any): number;
+    getString(index: number): SharedStringValue;
+    add(value: SharedStringValue): number;
 }
 export { SharedStrings };

package/dist/browser/modules/excel/utils/shared-strings.js

@@ -1,3 +1,21 @@
+/**
+ * Canonical JSON serializer with sorted object keys.
+ *
+ * Used to derive an insertion-order-independent dedupe key for rich-text
+ * shared-string entries. Two semantically identical run/font objects must
+ * map to the same key regardless of the order their properties were assigned.
+ */
+function canonicalStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalStringify).join(",")}]`;
+    }
+    const keys = Object.keys(value).sort();
+    const obj = value;
+    return `{${keys.map(k => `${JSON.stringify(k)}:${canonicalStringify(obj[k])}`).join(",")}}`;
+}
 class SharedStrings {
     constructor() {
         this._values = [];
@@ -17,9 +35,10 @@ class SharedStrings {
         return this._values[index];
     }
     add(value) {
-        let index = this._hash[value];
+        const key = typeof value === "string" ? `s:${value}` : `r:${canonicalStringify(value.richText)}`;
+        let index = this._hash[key];
         if (index === undefined) {
-            index = this._hash[value] = this._values.length;
+            index = this._hash[key] = this._values.length;
             this._values.push(value);
         }
         this._totalRefs++;

package/dist/browser/modules/excel/utils/workbook-protection.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Result of applying workbook protection — contains the fields that both
+ * Workbook and WorkbookWriter need to persist.
+ */
+export interface WorkbookProtectionHash {
+    lockStructure?: boolean;
+    lockWindows?: boolean;
+    lockRevision?: boolean;
+    algorithmName?: string;
+    hashValue?: string;
+    saltValue?: string;
+    spinCount?: number;
+}
+/**
+ * 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 declare function buildWorkbookProtection(password?: string, options?: {
+    lockStructure?: boolean;
+    lockWindows?: boolean;
+    lockRevision?: boolean;
+    spinCount?: number;
+}): Promise<WorkbookProtectionHash>;

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

@@ -0,0 +1,30 @@
+import { Encryptor } from "./encryptor.browser.js";
+import { uint8ArrayToBase64 } from "../../../utils/utils.browser.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/browser/modules/excel/workbook.browser.d.ts

@@ -14,9 +14,10 @@ import { DefinedNames, type DefinedNameModel } from "./defined-names.js";
 import type { PivotTable } from "./pivot-table.js";
 import { WorkbookReader, type WorkbookReaderOptions } from "./stream/workbook-reader.js";
 import { WorkbookWriter, type WorkbookWriterOptions } from "./stream/workbook-writer.js";
-import type { AddWorksheetOptions, CalculationProperties, ImageData, WorkbookProperties, WorkbookView, Buffer as ExcelBuffer } from "./types.js";
+import type { AddWorksheetOptions, CalculationProperties, CellValue, Font, ImageData, WorkbookProperties, WorkbookProtection, WorkbookView, Buffer as ExcelBuffer } from "./types.js";
 import { Worksheet, type WorksheetModel } from "./worksheet.js";
 import { XLSX } from "./xlsx/xlsx.js";
+import type { SyntaxProbe } from "../formula/default-syntax-probe.js";
 import type { MarkdownOptions } from "../markdown/types.js";
 import type { Readable } from "../stream/index.js";
 import type { IReadable, IWritable } from "../stream/types.js";
@@ -38,6 +39,7 @@ export interface WorkbookModel {
     created: Date;
     modified: Date;
     properties: Partial<WorkbookProperties>;
+    protection?: WorkbookProtectionModel;
     worksheets: WorksheetModel[];
     sheets?: WorksheetModel[];
     definedNames: DefinedNameModel[];
@@ -56,14 +58,101 @@ export interface WorkbookModel {
     media: WorkbookMedia[];
     pivotTables: PivotTable[];
     /** Loaded pivot tables from file - used during reconciliation */
-    loadedPivotTables?: any[];
+    loadedPivotTables?: PivotTable[];
     calcProperties: Partial<CalculationProperties>;
     /** Passthrough files (charts, etc.) preserved for round-trip */
     passthrough?: Record<string, Uint8Array>;
     /** Raw drawing XML data for passthrough (when drawing contains chart references) */
     rawDrawings?: Record<string, Uint8Array>;
     /** Default font preserved from the original file for round-trip fidelity */
-    defaultFont?: any;
+    defaultFont?: Partial<Font>;
+    /**
+     * External workbook references in declaration order. Matches the on-disk
+     * `[N]Sheet!Ref` indexing (1-based). Empty or undefined when the workbook
+     * has no external references.
+     */
+    externalLinks?: ExternalLinkModel[];
+}
+/** Internal model for workbook-level protection (serialized to <workbookProtection>) */
+export interface WorkbookProtectionModel {
+    lockStructure?: boolean;
+    lockWindows?: boolean;
+    lockRevision?: boolean;
+    workbookPassword?: string;
+    revisionsPassword?: string;
+    algorithmName?: string;
+    hashValue?: string;
+    saltValue?: string;
+    spinCount?: number;
+}
+/**
+ * Cached values for a single sheet of an external workbook. Keys are the
+ * A1-notation cell addresses *in uppercase* (e.g. `"A1"`, `"B12"`). Values
+ * are the cached primitives Excel displays when the external file is not
+ * currently available — must be JSON primitives: string, number, boolean, or
+ * null for an explicitly blank cell.
+ */
+export type ExternalLinkCachedSheet = Record<string, string | number | boolean | null>;
+/**
+ * A single external workbook reference. Each entry corresponds to one
+ * `xl/externalLinks/externalLink{N}.xml` part in the output file, and to
+ * one `<externalReference r:id="...">` entry in `xl/workbook.xml`.
+ *
+ * The on-disk formula syntax for referring to this workbook is `[N]Sheet!A1`
+ * where `N` is the 1-based `index` below.
+ */
+export interface ExternalLinkModel {
+    /**
+     * The 1-based index used in `[N]Sheet!A1` formulas. This is the position
+     * in the workbook's `<externalReferences>` list (in declaration order).
+     * Assigned automatically on read/write; treat as read-only when produced
+     * by the library.
+     */
+    index: number;
+    /**
+     * The rel Target that will be written into
+     * `xl/externalLinks/_rels/externalLink{N}.xml.rels`. For relative paths
+     * (which is what users almost always want), pass the bare filename or a
+     * path relative to the current workbook: `"测试.xlsx"`, `"data/ref.xlsx"`.
+     * Office resolves bare relative paths from the current workbook's
+     * directory — *that* is the fix for the "Office goes to the Documents
+     * folder" problem described in exceljs#3039.
+     *
+     * Absolute `file:///` or `http(s)://` URIs are accepted and written
+     * through unchanged.
+     */
+    target: string;
+    /**
+     * Almost always `"External"`. `"Internal"` is for embedded workbooks
+     * (rare) and is preserved on round-trip when present in the source file.
+     */
+    targetMode: "External" | "Internal";
+    /**
+     * The relationship id inside `xl/_rels/workbook.xml.rels` pointing to this
+     * external link's XML part. Populated automatically on read and
+     * re-assigned on write. Callers should leave this undefined.
+     */
+    rId?: string;
+    /**
+     * The sheet names exposed by the external workbook, in declaration order.
+     * Excel writes one `<sheetName val="..."/>` per entry under
+     * `<sheetNames>` inside the externalLink part.
+     *
+     * At minimum you must declare every sheet that appears in a formula
+     * targeting this external workbook, otherwise Excel will fail to link
+     * the cached values and show `#REF!`.
+     */
+    sheetNames: string[];
+    /**
+     * Cached primitive values per sheet. Key is the *sheet name* (matching an
+     * entry in `sheetNames`), value is a map from A1 address to primitive.
+     *
+     * Cached values are what Excel displays when the referenced external file
+     * is not available (e.g. freshly-downloaded workbook on another machine).
+     * Writing them turns your file from "opens with errors" into "opens,
+     * shows values, offers to update links".
+     */
+    cachedValues?: Record<string, ExternalLinkCachedSheet>;
 }
 /**
  * Supported input types for CSV parsing
@@ -94,7 +183,19 @@ interface CsvOptionsExtras {
     dateFormats?: readonly DateFormat[];
     dateFormat?: string;
     dateUTC?: boolean;
-    map?(value: any, index: number): any;
+    /**
+     * Transform each cell value as rows are parsed from CSV or formatted for
+     * CSV output.
+     *
+     * - During parse: `value` is the raw JS value produced by the CSV parser
+     *   (string, number, boolean, Date, ...) and already narrows to `CellValue`.
+     * - During format: `value` is the worksheet cell's `CellValue`.
+     *
+     * The function should return a `CellValue`; returning non-`CellValue`
+     * types (functions, symbols, ...) is unsupported and will break downstream
+     * serialization.
+     */
+    map?(value: CellValue, index: number): CellValue;
     includeEmptyRows?: boolean;
     requestHeaders?: Record<string, string>;
     requestBody?: BodyInit;
@@ -145,6 +246,17 @@ declare class Workbook {
     views: WorkbookView[];
     media: WorkbookMedia[];
     pivotTables: PivotTable[];
+    protection?: WorkbookProtectionModel;
+    /**
+     * External workbook references, in declaration order. The 1-based index
+     * of each entry matches the `[N]` prefix used inside formula strings
+     * (e.g. the first entry is referenced as `[1]Sheet1!A1` on disk).
+     *
+     * Prefer {@link addExternalLink} for appending — it handles index
+     * assignment and sheet-name deduplication. Direct mutation of this array
+     * is supported but callers must keep indices contiguous starting at 1.
+     */
+    externalLinks: ExternalLinkModel[];
     protected _worksheets: Worksheet[];
     protected _definedNames: DefinedNames;
     protected _themes?: unknown;
@@ -153,9 +265,50 @@ declare class Workbook {
     /** Raw drawing XML data for passthrough (when drawing contains chart references) */
     protected _rawDrawings: Record<string, Uint8Array>;
     /** Default font preserved from original file for round-trip fidelity */
-    protected _defaultFont?: any;
+    protected _defaultFont?: Partial<Font>;
+    /**
+     * Cache of external-workbook references auto-discovered from formula
+     * strings during previous `writeBuffer()` calls. This is an internal
+     * stash used to keep subsequent writes fixed-point stable: once a
+     * formula has been normalised to `[N]Sheet!A1`, the writer needs the
+     * corresponding link metadata on the next write too, but we don't want
+     * those auto-discovered entries to appear on the user-facing
+     * `externalLinks` list. Indexed by lower-cased target path.
+     *
+     * Entries explicitly added via `addExternalLink()` live on `externalLinks`
+     * instead — the writer combines both at serialisation time.
+     */
+    protected _writerExternalLinkCache: Map<string, ExternalLinkModel>;
+    /** Global registry of table names (lowercase) for cross-worksheet uniqueness checks. */
+    readonly _tableNames: Set<string>;
     private _xlsx?;
-    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?: {
+        formulaSyntaxProbe?: SyntaxProbe;
+    });
+    /**
+     * 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(): Partial<Font> | undefined;
+    set defaultFont(font: Partial<Font> | undefined);
     /**
      * Import a worksheet from another workbook (or a standalone worksheet).
      * Deep-copies all worksheet properties via the model getter/setter, including
@@ -168,6 +321,18 @@ declare class Workbook {
      * @returns The newly created worksheet
      */
     importSheet(source: Worksheet, name?: string): Worksheet;
+    /**
+     * 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)
+     */
+    protect(password?: string, options?: Partial<WorkbookProtection>): Promise<void>;
+    /**
+     * Remove workbook structure protection.
+     */
+    unprotect(): void;
     /**
      * xlsx file format operations
      * Node.js: readFile, writeFile, read (stream), write (stream), load (buffer), writeBuffer
@@ -399,12 +564,98 @@ declare class Workbook {
      */
     eachSheet(callback: (sheet: Worksheet, id: number) => void): void;
     get definedNames(): DefinedNames;
+    /**
+     * 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(): void;
     clearThemes(): void;
     /**
      * Add Image to Workbook and return the id
      */
     addImage(image: ImageData): number;
     getImage(id: number | string): WorkbookMedia | undefined;
+    /**
+     * 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: {
+        target: string;
+        sheetNames?: string[];
+        cachedValues?: ExternalLinkModel["cachedValues"];
+        targetMode?: ExternalLinkModel["targetMode"];
+    }): ExternalLinkModel;
+    /**
+     * 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: number | string): ExternalLinkModel | undefined;
     get model(): WorkbookModel;
     set model(value: WorkbookModel);
 }