@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/browser/modules/excel/types.d.ts

@@ -239,11 +239,23 @@ export interface WorkbookView {
 export interface WorkbookProperties {
     date1904: boolean;
 }
+export interface WorkbookProtection {
+    lockStructure: boolean;
+    lockWindows: boolean;
+    lockRevision: boolean;
+    spinCount: number;
+}
 export interface CalculationProperties {
     fullCalcOnLoad: boolean;
+    /** Enable iterative calculation for circular references */
+    iterate?: boolean;
+    /** Maximum number of iterations (default 100) */
+    iterateCount?: number;
+    /** Convergence threshold (default 0.001) */
+    iterateDelta?: number;
 }
 export interface CellErrorValue {
-    error: "#N/A" | "#REF!" | "#NAME?" | "#DIV/0!" | "#NULL!" | "#VALUE!" | "#NUM!";
+    error: "#N/A" | "#REF!" | "#NAME?" | "#DIV/0!" | "#NULL!" | "#VALUE!" | "#NUM!" | "#SPILL!" | "#CALC!";
 }
 export interface RichText {
     text: string;
@@ -253,7 +265,58 @@ export interface CellRichTextValue {
     richText: RichText[];
 }
 export interface CellHyperlinkValue {
+    /**
+     * Plain-text display for the hyperlink. Always a string.
+     *
+     * When `richText` is also set, this field mirrors the concatenated
+     * `.text` of every run in `richText` (flattened representation).
+     */
+    text: string;
+    /**
+     * Optional rich-text runs providing formatted display for the hyperlink.
+     * When present, `text` must equal the concatenation of each run's `.text`.
+     */
+    richText?: RichText[];
+    hyperlink: string;
+    tooltip?: string;
+}
+/**
+ * Input shape for assigning a hyperlink cell value.
+ *
+ * Accepts either:
+ *   - a plain-text hyperlink (`text + hyperlink`), OR
+ *   - a rich-text hyperlink (`richText + hyperlink`) — `text` is auto-derived
+ *     by flattening the runs, so callers do not have to repeat it.
+ *
+ * The output shape (`CellHyperlinkValue` returned from `cell.value`) always
+ * has `text: string` populated.
+ */
+export type CellHyperlinkValueInput = {
     text: string;
+    richText?: RichText[];
+    hyperlink: string;
+    tooltip?: string;
+} | {
+    text?: string;
+    richText: RichText[];
+    hyperlink: string;
+    tooltip?: string;
+};
+/**
+ * Input shape for assigning a formula cell that also carries a hyperlink.
+ *
+ * Loaded workbooks may present a formula cell with an attached hyperlink
+ * (e.g. `=HYPERLINK(...)` style or a `<hyperlink ref="..."/>` entry pointing
+ * at a formula cell). On the public surface such cells are classified as
+ * Hyperlink (`cell.type === ValueType.Hyperlink`) with the formula's result
+ * as display text, while `cell.model.formula` is preserved for round-trip.
+ *
+ * Use this shape to construct that combination directly without going
+ * through `cell.model`.
+ */
+export interface CellFormulaHyperlinkValue {
+    formula: string;
+    result?: number | string | boolean | Date | CellErrorValue;
     hyperlink: string;
     tooltip?: string;
 }
@@ -270,6 +333,14 @@ export interface CellArrayFormulaValue {
     shareType: "array";
     /** The range this array formula applies to, e.g. "A1:B2" */
     ref: string;
+    /**
+     * Mark this as an Excel 365 dynamic array formula (FILTER, SORT, UNIQUE, etc.).
+     * Dynamic array formulas differ from legacy CSE (Ctrl+Shift+Enter) array formulas:
+     * - The `ref` typically points to the formula cell itself (spill is dynamic)
+     * - Excel writes a `cm` attribute on the `<c>` element linking to `xl/metadata.xml`
+     * - The metadata marks the formula with `<xda:dynamicArrayProperties fDynamic="1"/>`
+     */
+    isDynamicArray?: boolean;
 }
 export interface CellSharedFormulaValue {
     sharedFormula: string;
@@ -282,6 +353,18 @@ export interface CellCheckboxValue {
     checkbox: boolean;
 }
 export type CellValue = null | number | string | boolean | Date | undefined | CellErrorValue | CellRichTextValue | CellHyperlinkValue | CellFormulaValue | CellArrayFormulaValue | CellSharedFormulaValue | CellCheckboxValue;
+/**
+ * Input variant of {@link CellValue} used when assigning to `cell.value`.
+ *
+ * Accepts the same shapes as `CellValue` plus more permissive forms that
+ * the runtime normalizes:
+ *   - `CellHyperlinkValueInput` — rich-text hyperlinks may omit `text`
+ *     (it will be derived from `richText`).
+ *   - `CellFormulaHyperlinkValue` — formula cells may carry a `hyperlink`.
+ *
+ * `cell.value` (the getter) still returns the canonical `CellValue` shape.
+ */
+export type CellValueInput = null | number | string | boolean | Date | undefined | CellErrorValue | CellRichTextValue | CellHyperlinkValueInput | CellFormulaValue | CellArrayFormulaValue | CellSharedFormulaValue | CellCheckboxValue | CellFormulaHyperlinkValue;
 export interface CommentMargins {
     insetmode: "auto" | "custom";
     inset: number[];
@@ -363,6 +446,22 @@ export type AddImageRange = string | {
         hyperlink?: string;
         tooltip?: string;
     };
+} | {
+    /** Absolute position in pixels — mutually exclusive with tl/br. */
+    pos: {
+        x: number;
+        y: number;
+    };
+    /** Image dimensions in pixels (required for absolute positioning). */
+    ext: {
+        width: number;
+        height: number;
+    };
+    /** Hyperlink for the image */
+    hyperlinks?: {
+        hyperlink?: string;
+        tooltip?: string;
+    };
 };
 export interface ImageHyperlinkValue {
     hyperlink: string;
@@ -521,6 +620,10 @@ export interface DataBarRuleType extends ConditionalFormattingBaseRule {
     direction?: "context" | "leftToRight" | "rightToLeft";
     cfvo?: Cvfo[];
     color?: Partial<Color>;
+    negativeFillColor?: Partial<Color>;
+    borderColor?: Partial<Color>;
+    negativeBorderColor?: Partial<Color>;
+    axisColor?: Partial<Color>;
 }
 export type ConditionalFormattingRule = ExpressionRuleType | CellIsRuleType | Top10RuleType | AboveAverageRuleType | ColorScaleRuleType | IconSetRuleType | ContainsTextRuleType | TimePeriodRuleType | DataBarRuleType;
 export interface ConditionalFormattingOptions {
@@ -563,7 +666,13 @@ export interface TableProperties {
     qualifyImplicitStructuredReferences?: boolean;
     style?: TableStyleProperties;
     columns: TableColumnProperties[];
-    rows: any[][];
+    /**
+     * Table data rows. Each row is an array of cell values aligned with
+     * `columns`. A cell may be any `CellValue` (scalars, dates, rich text,
+     * hyperlinks, error values, ...) or a `CellFormulaValue` when the cell
+     * stores a formula.
+     */
+    rows: Array<Array<CellValue | CellFormulaValue>>;
 }
 export type TableColumn = Required<TableColumnProperties>;
 export interface Media {
@@ -600,4 +709,26 @@ export interface ColBreak {
     min?: number;
     man: number;
 }
+export interface IgnoredError {
+    /** Cell reference range, e.g. "A1:B10" or "A1:XFD1048576" */
+    ref: string;
+    /** Ignore "Number Stored as Text" errors (green triangle) */
+    numberStoredAsText?: boolean;
+    /** Ignore formula errors */
+    formula?: boolean;
+    /** Ignore formula range errors */
+    formulaRange?: boolean;
+    /** Ignore unlocked formula errors */
+    unlockedFormula?: boolean;
+    /** Ignore empty cell reference errors */
+    emptyCellReference?: boolean;
+    /** Ignore list data validation errors */
+    listDataValidation?: boolean;
+    /** Ignore calculated column errors */
+    calculatedColumn?: boolean;
+    /** Ignore eval errors */
+    evalError?: boolean;
+    /** Ignore two-digit text year errors */
+    twoDigitTextYear?: boolean;
+}
 export {};

package/dist/browser/modules/excel/utils/col-cache.d.ts

@@ -31,6 +31,7 @@ interface ColCache {
     decodeEx(value: string): DecodeExResult;
     encodeAddress(row: number, col: number): string;
     encode(...args: number[]): string;
+    compareAddress(a: string, b: string): number;
     inRange(range: number[], address: number[]): boolean;
 }
 declare const colCache: ColCache;

package/dist/browser/modules/excel/utils/col-cache.js

@@ -299,6 +299,21 @@ const colCache = {
                 throw new InvalidAddressError(String(args.length), "Can only encode with 2 or 4 arguments");
         }
     },
+    /**
+     * Compare two cell addresses by column then row (numeric order).
+     *
+     * Returns a negative number if `a` should come before `b`,
+     * a positive number if `a` should come after `b`, or zero if equal.
+     *
+     * This avoids the pitfalls of `localeCompare` which treats addresses
+     * as strings (e.g. "C10" < "C2") instead of comparing their numeric
+     * column and row components.
+     */
+    compareAddress(a, b) {
+        const addrA = colCache.decodeAddress(a);
+        const addrB = colCache.decodeAddress(b);
+        return addrA.col - addrB.col || addrA.row - addrB.row;
+    },
     // return true if address is contained within range
     inRange(range, address) {
         const [left, top, , right, bottom] = range;

package/dist/browser/modules/excel/utils/drawing-utils.d.ts

@@ -5,7 +5,7 @@
  * This eliminates the duplicated anchor/rel building logic and provides
  * a single, correct image-rel deduplication strategy.
  */
-interface DrawingAnchor {
+export interface DrawingAnchor {
     picture: {
         rId: string;
         hyperlinks?: {
@@ -17,13 +17,13 @@ interface DrawingAnchor {
     };
     range: any;
 }
-interface DrawingRel {
+export interface DrawingRel {
     Id: string;
     Type: string;
     Target: string;
     TargetMode?: string;
 }
-interface DrawingModel {
+export interface DrawingModel {
     anchors: DrawingAnchor[];
     rels: DrawingRel[];
 }

package/dist/browser/modules/excel/utils/drawing-utils.js

@@ -101,6 +101,10 @@ export function filterDrawingAnchors(anchors) {
         if (a == null) {
             return false;
         }
+        // Absolute anchors need a valid picture
+        if (a.range?.pos !== undefined) {
+            return !!a.picture;
+        }
         // Form controls have range.br and shape properties
         if (a.range?.br && a.shape) {
             return true;

package/dist/browser/modules/excel/utils/external-link-formula.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Utilities for manipulating the external-workbook prefix in formula strings.
+ *
+ * Excel formula strings containing external workbook references have the
+ * shape `[<workbook>]Sheet!Ref` where `<workbook>` is either
+ *
+ *   - a 1-based numeric index  — `[1]Sheet1!A1`  (the canonical on-disk form
+ *     stored inside `<f>` elements of worksheet XML), or
+ *   - a filename / relative path — `[测试.xlsx]Sheet1!A1`  (what Excel
+ *     displays in the formula bar; not part of the OOXML storage contract,
+ *     but produced by hand-written formulas and some older tools).
+ *
+ * When writing, excelts always emits the numeric form — indices map
+ * positionally into the workbook's `<externalReferences>` list. When a
+ * formula arrives with the filename form, the writer assigns (or reuses) an
+ * ExternalLinkModel with that filename as its `target` and rewrites the
+ * formula to the numeric form. This matches how Excel itself stores formulas
+ * and makes them round-trippable.
+ *
+ * The quoted variant `'[file.xlsx]Sheet with space'!A1` is handled too — Excel
+ * wraps the `[name]Sheet` segment in single quotes when the sheet name needs
+ * quoting. The matching logic here recognises both the unquoted and quoted
+ * forms, rewriting inside the quotes when needed.
+ *
+ * Edge cases we explicitly *do not* treat as external refs:
+ *   - `[@Column]`, `[#Headers]`, `[Column Name]` — table structured refs
+ *     (no `]Sheet!` tail). The regex requires the `]<sheet>!` follow-up,
+ *     which structured refs never have.
+ *   - Array literals `{1,2;3,4}` use `{}`, not `[]`.
+ *   - String literals `"[Book]Sheet!A1"` — handled by scanning only outside
+ *     string literal regions.
+ */
+/**
+ * A single match of an external reference inside a formula string. The
+ * writer uses `workbook` to find/create an ExternalLinkModel and `sheet`
+ * for reporting / sheet-name upsert. `replacement` is the substring that
+ * should replace `match` in the final formula (with the workbook token
+ * rewritten to a numeric index).
+ */
+export interface ExternalRefMatch {
+    /** Full matched prefix including trailing `!`, e.g. `[测试.xlsx]Sheet1!`. */
+    match: string;
+    /** The workbook token inside `[]` — either numeric or a filename/path. */
+    workbook: string;
+    /** Whether the workbook token was already a numeric index. */
+    numeric: boolean;
+    /** The 1-based numeric index parsed from the workbook token, if numeric. */
+    index: number | null;
+    /** The sheet name (unquoted). */
+    sheet: string;
+    /** Whether the match came from the quoted variant `'[..]..'!`. */
+    quoted: boolean;
+    /** Start offset in the source formula. */
+    start: number;
+    /** End offset (exclusive) in the source formula. */
+    end: number;
+}
+/**
+ * Scan a formula string for all external-workbook references. String
+ * literals (inside `"..."`) are skipped so that a string value like
+ * `"[Book]Sheet!A1"` is not misidentified as a ref.
+ *
+ * The returned matches are in source order. If a formula contains no
+ * external refs, the array is empty.
+ */
+export declare function findExternalRefs(formula: string): ExternalRefMatch[];
+/**
+ * Replace every external-workbook token in `formula` using the supplied
+ * resolver. The resolver is called once per match and returns the numeric
+ * index to substitute; returning `null` leaves the match unchanged (useful
+ * when the caller cannot resolve a particular filename).
+ *
+ * Returns the rewritten formula. Offsets inside the original formula are
+ * adjusted correctly even when multiple rewrites change the total length.
+ */
+export declare function rewriteExternalRefs(formula: string, resolve: (match: ExternalRefMatch) => number | null): string;

package/dist/browser/modules/excel/utils/external-link-formula.js

@@ -0,0 +1,208 @@
+/**
+ * Utilities for manipulating the external-workbook prefix in formula strings.
+ *
+ * Excel formula strings containing external workbook references have the
+ * shape `[<workbook>]Sheet!Ref` where `<workbook>` is either
+ *
+ *   - a 1-based numeric index  — `[1]Sheet1!A1`  (the canonical on-disk form
+ *     stored inside `<f>` elements of worksheet XML), or
+ *   - a filename / relative path — `[测试.xlsx]Sheet1!A1`  (what Excel
+ *     displays in the formula bar; not part of the OOXML storage contract,
+ *     but produced by hand-written formulas and some older tools).
+ *
+ * When writing, excelts always emits the numeric form — indices map
+ * positionally into the workbook's `<externalReferences>` list. When a
+ * formula arrives with the filename form, the writer assigns (or reuses) an
+ * ExternalLinkModel with that filename as its `target` and rewrites the
+ * formula to the numeric form. This matches how Excel itself stores formulas
+ * and makes them round-trippable.
+ *
+ * The quoted variant `'[file.xlsx]Sheet with space'!A1` is handled too — Excel
+ * wraps the `[name]Sheet` segment in single quotes when the sheet name needs
+ * quoting. The matching logic here recognises both the unquoted and quoted
+ * forms, rewriting inside the quotes when needed.
+ *
+ * Edge cases we explicitly *do not* treat as external refs:
+ *   - `[@Column]`, `[#Headers]`, `[Column Name]` — table structured refs
+ *     (no `]Sheet!` tail). The regex requires the `]<sheet>!` follow-up,
+ *     which structured refs never have.
+ *   - Array literals `{1,2;3,4}` use `{}`, not `[]`.
+ *   - String literals `"[Book]Sheet!A1"` — handled by scanning only outside
+ *     string literal regions.
+ */
+// Matches an external-ref prefix in a formula:
+//   Group 1 captures the workbook token inside [...], which is either
+//   digits-only (numeric form) or a filename that may include path separators
+//   when the whole prefix is single-quoted.
+//
+// Two variants:
+//   1. Unquoted: [Book]Sheet!A1       — Windows-filename-safe chars only in
+//      workbook token, then identifier sheet name, then !
+//   2. Quoted:   '[path/to/Book]Sheet name'!A1    — quoted segment allows
+//      paths / spaces / most punctuation inside the brackets; the sheet
+//      name inside the quotes can contain anything except `'` (escaped as '')
+//
+// The regex matches through and including the trailing `!` so callers don't
+// have to re-parse the A1/range part.
+// Unquoted form: workbook token must not contain characters that would
+// make the formula string ambiguous ( ] / \ space). This matches what Excel
+// itself writes for the bare-filename case — anything more exotic is
+// written in the quoted form by Excel.
+const UNQUOTED_EXTERNAL_REF = /\[([^\]\\/:*?"<>|\s]+)\]([A-Za-z_\u00A1-\uFFFF][A-Za-z0-9_\u00A1-\uFFFF.]*)!/g;
+// Quoted form: everything inside [] is permissive (any char except `]`),
+// since the outer `'..'` quotes absorb the surrounding formula
+// delimiters. Sheet name inside quotes is likewise permissive (any char
+// except `'`, with `''` representing an escaped quote).
+const QUOTED_EXTERNAL_REF = /'\[([^\]]+)\]((?:''|[^'])+)'!/g;
+/**
+ * Scan a formula string for all external-workbook references. String
+ * literals (inside `"..."`) are skipped so that a string value like
+ * `"[Book]Sheet!A1"` is not misidentified as a ref.
+ *
+ * The returned matches are in source order. If a formula contains no
+ * external refs, the array is empty.
+ */
+export function findExternalRefs(formula) {
+    // Fast-fail: external refs always include a `[`. Skipping the
+    // string-literal scan + two regex passes for plain cell refs (A1+B1,
+    // SUM(A1:A5), 99% of real workbooks) saves noticeable time on large
+    // sheets with thousands of formulas.
+    if (formula.indexOf("[") === -1) {
+        return [];
+    }
+    const matches = [];
+    const safeRegions = stringLiteralRegions(formula);
+    const addMatch = (start, end, workbook, sheet, quoted, match) => {
+        if (insideAnyRegion(start, safeRegions)) {
+            return;
+        }
+        const numeric = /^\d+$/.test(workbook);
+        matches.push({
+            match,
+            workbook,
+            numeric,
+            index: numeric ? parseInt(workbook, 10) : null,
+            sheet: unquoteSheetName(sheet),
+            quoted,
+            start,
+            end
+        });
+    };
+    UNQUOTED_EXTERNAL_REF.lastIndex = 0;
+    let m;
+    while ((m = UNQUOTED_EXTERNAL_REF.exec(formula)) !== null) {
+        addMatch(m.index, m.index + m[0].length, m[1], m[2], false, m[0]);
+    }
+    QUOTED_EXTERNAL_REF.lastIndex = 0;
+    while ((m = QUOTED_EXTERNAL_REF.exec(formula)) !== null) {
+        addMatch(m.index, m.index + m[0].length, m[1], m[2], true, m[0]);
+    }
+    // Sort matches by start offset so callers can process them in source
+    // order (needed when rewriting with offset bookkeeping).
+    matches.sort((a, b) => a.start - b.start);
+    // Deduplicate overlapping matches (the unquoted regex can technically
+    // match a prefix of a quoted sheet name in pathological inputs). Take
+    // the first of any overlap.
+    const out = [];
+    let lastEnd = -1;
+    for (const ref of matches) {
+        if (ref.start >= lastEnd) {
+            out.push(ref);
+            lastEnd = ref.end;
+        }
+    }
+    return out;
+}
+/**
+ * Replace every external-workbook token in `formula` using the supplied
+ * resolver. The resolver is called once per match and returns the numeric
+ * index to substitute; returning `null` leaves the match unchanged (useful
+ * when the caller cannot resolve a particular filename).
+ *
+ * Returns the rewritten formula. Offsets inside the original formula are
+ * adjusted correctly even when multiple rewrites change the total length.
+ */
+export function rewriteExternalRefs(formula, resolve) {
+    const refs = findExternalRefs(formula);
+    if (refs.length === 0) {
+        return formula;
+    }
+    let out = "";
+    let cursor = 0;
+    for (const ref of refs) {
+        const index = resolve(ref);
+        if (index === null) {
+            continue; // leave this ref alone; cursor stays put
+        }
+        out += formula.slice(cursor, ref.start);
+        // Construct the replacement: keep the quoted/unquoted shape, swap the
+        // workbook token for [N], preserve the sheet segment exactly.
+        if (ref.quoted) {
+            // The quoted variant surrounds `[Book]Sheet` with single quotes,
+            // followed by `!`. We swap the [Book] part for [N] and keep the
+            // rest (including the closing `'!`) unchanged so sheet-name
+            // quoting is preserved exactly.
+            const inner = formula.slice(ref.start + 1, ref.end - 2); // between quotes, excluding trailing '!
+            out += "'" + inner.replace(/^\[[^\]]*\]/, `[${index}]`) + "'!";
+        }
+        else {
+            out += `[${index}]${ref.match.slice(ref.match.indexOf("]") + 1)}`;
+        }
+        cursor = ref.end;
+    }
+    out += formula.slice(cursor);
+    return out;
+}
+// ===========================================================================
+// Internal helpers
+// ===========================================================================
+/**
+ * Return the spans of string literal regions in a formula, as half-open
+ * [start, end) intervals (exclusive of the surrounding quotes themselves).
+ * Used to skip external-ref matches that fall inside a string value.
+ */
+function stringLiteralRegions(formula) {
+    // Fast-fail when the formula has no double-quote at all — very common
+    // for pure arithmetic / reference formulas.
+    if (formula.indexOf('"') === -1) {
+        return [];
+    }
+    const regions = [];
+    const len = formula.length;
+    let i = 0;
+    while (i < len) {
+        if (formula[i] === '"') {
+            const start = i;
+            i++;
+            while (i < len) {
+                if (formula[i] === '"') {
+                    if (i + 1 < len && formula[i + 1] === '"') {
+                        i += 2; // escaped quote inside string — keep scanning
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            regions.push([start, i]);
+        }
+        else {
+            i++;
+        }
+    }
+    return regions;
+}
+function insideAnyRegion(pos, regions) {
+    for (const [a, b] of regions) {
+        if (pos >= a && pos < b) {
+            return true;
+        }
+    }
+    return false;
+}
+function unquoteSheetName(sheet) {
+    // The quoted form captured inside `'..'` may have doubled single quotes
+    // that represent a single quote in the logical sheet name.
+    return sheet.replace(/''/g, "'");
+}

package/dist/browser/modules/excel/utils/iterate-stream.d.ts

@@ -3,12 +3,18 @@ interface EventEmitterLike {
     on(event: string, listener: Listener): this;
     removeListener(event: string, listener: Listener): this;
 }
-interface Readable extends EventEmitterLike {
+/**
+ * Minimal readable-stream shape consumed by {@link iterateStream}.
+ * Intentionally structural so it matches Node `Readable`, zip entry streams,
+ * object-mode streams that yield zip entries, and any third-party emitter
+ * that raises `data`/`end`/`error`.
+ */
+export interface IterableStreamLike<T = unknown> extends EventEmitterLike {
     resume(): void;
     pause(): void;
-    on(event: "data", listener: (chunk: any) => void): this;
+    on(event: "data", listener: (chunk: T) => void): this;
     on(event: "end", listener: () => void): this;
     on(event: "error", listener: (err: Error) => void): this;
 }
-declare function iterateStream(stream: Readable): AsyncGenerator<any>;
+declare function iterateStream<T = Uint8Array | string>(stream: IterableStreamLike<T>): AsyncGenerator<T>;
 export { iterateStream };

package/dist/browser/modules/excel/utils/iterate-stream.js

@@ -39,7 +39,9 @@ async function* iterateStream(stream) {
             else {
                 stream.pause();
                 const data = contents.shift();
-                yield data;
+                if (data !== undefined) {
+                    yield data;
+                }
             }
             if (error) {
                 throw toError(error);

package/dist/browser/modules/excel/utils/ooxml-paths.d.ts

@@ -9,6 +9,7 @@ export declare const OOXML_PATHS: {
     readonly xlStyles: "xl/styles.xml";
     readonly xlTheme1: "xl/theme/theme1.xml";
     readonly xlFeaturePropertyBag: "xl/featurePropertyBag/featurePropertyBag.xml";
+    readonly xlMetadata: "xl/metadata.xml";
 };
 export declare function normalizeZipPath(path: string): string;
 export declare function getWorksheetNoFromWorksheetPath(path: string): number | undefined;
@@ -29,6 +30,16 @@ export declare function getPivotTableNameFromRelsPath(path: string): string | un
 export declare function getPivotCacheDefinitionNameFromPath(path: string): string | undefined;
 export declare function getPivotCacheDefinitionNameFromRelsPath(path: string): string | undefined;
 export declare function getPivotCacheRecordsNameFromPath(path: string): string | 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 declare function getExternalLinkIndexFromPath(path: string): number | undefined;
+/**
+ * Extract the 1-based index `N` from
+ * `xl/externalLinks/_rels/externalLink{N}.xml.rels`.
+ */
+export declare function getExternalLinkIndexFromRelsPath(path: string): number | undefined;
 export declare function toContentTypesPartName(zipPath: string): string;
 export declare function themePath(themeName: string): string;
 export declare function mediaPath(filename: string): string;
@@ -49,12 +60,20 @@ export declare function pivotCacheRecordsPath(n: number | string): string;
 export declare function pivotCacheRecordsRelTarget(n: number | string): string;
 export declare function pivotTablePath(n: number | string): string;
 export declare function pivotTableRelsPath(n: number | string): string;
+export declare function externalLinkPath(n: number | string): string;
+export declare function externalLinkRelsPath(n: number | string): string;
+/**
+ * Build the `Target` value for an externalLink relationship inside
+ * `xl/_rels/workbook.xml.rels` (base: `xl/`).
+ */
+export declare function externalLinkRelTargetFromWorkbook(n: number | string): string;
 export declare function pivotCacheDefinitionRelTargetFromPivotTable(n: number | string): string;
 export declare const OOXML_REL_TARGETS: {
     readonly workbookStyles: "styles.xml";
     readonly workbookSharedStrings: "sharedStrings.xml";
     readonly workbookTheme1: "theme/theme1.xml";
     readonly workbookFeaturePropertyBag: "featurePropertyBag/featurePropertyBag.xml";
+    readonly workbookMetadata: "metadata.xml";
 };
 export declare function pivotCacheDefinitionRelTargetFromWorkbook(n: number | string): string;
 export declare function commentsRelTargetFromWorksheet(sheetId: number | string): string;