@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/types/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/types/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/types/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/types/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/types/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/types/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;

package/dist/types/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/types/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>;