@cj-tech-master/excelts 9.2.1 → 9.3.0

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

@@ -22,15 +22,28 @@ export interface IParseStream extends EmitterLike {
     pipe(dest: any): any;
     [Symbol.asyncIterator]?: () => AsyncIterator<Uint8Array | string>;
 }
-export interface IStreamBuf extends EmitterLike {
-    write(data: any): boolean | void | Promise<boolean>;
+/**
+ * Minimal write-side shape required to receive XLSX bytes. Anything that
+ * behaves like a Node `WritableStream` (a `write()` method plus `end()` and
+ * event emitter basics) satisfies this — including Node's `fs.WriteStream`,
+ * `PassThrough`, and our `@stream` Writable class.
+ */
+export interface IWritableStream extends EmitterLike {
+    write(data: string | Uint8Array): boolean | void | Promise<boolean>;
     end(): void;
-    read(): any;
-    toBuffer?(): any;
     pipe?(dest: any): any;
 }
+/**
+ * An in-memory buffered stream. Extends the write-side shape with `read()`
+ * and optional `toBuffer()` for callers that use the stream as a sink and
+ * then harvest the accumulated bytes (e.g. `writeBuffer()`'s internal buffer).
+ */
+export interface IStreamBuf extends IWritableStream {
+    read(): Uint8Array | null;
+    toBuffer?(): Uint8Array | null;
+}
 export interface IZipWriter extends EmitterLike {
-    append(data: any, options: {
+    append(data: string | Uint8Array, options: {
         name: string;
         base64?: boolean;
     }): void;
@@ -39,13 +52,46 @@ export interface IZipWriter extends EmitterLike {
         write(chunk: string): void;
         end(): void;
     };
-    pipe(stream: any): void;
+    pipe(stream: IWritableStream): void;
     finalize(): void;
     /** Wait for downstream backpressure to clear. Resolves immediately if no backpressure. */
     waitForDrain(): Promise<void>;
 }
+/**
+ * Options for reading (loading) an XLSX workbook.
+ *
+ * All officially supported options are declared below with proper types so
+ * callers get IDE completion and type-checking. Additional fields are
+ * permitted via the index signature for forward compatibility and for
+ * callers who subclass `XLSX` to pass through private flags.
+ */
 export interface XlsxReadOptions {
+    /**
+     * When the input to `load()` is a string, interpret it as a base64-encoded
+     * zip archive instead of a binary buffer. Defaults to `false`.
+     */
     base64?: boolean;
+    /**
+     * Maximum number of rows to parse from each worksheet. Rows beyond this
+     * limit are silently skipped. Useful for previewing very large sheets
+     * without loading everything into memory.
+     */
+    maxRows?: number;
+    /**
+     * Maximum number of columns to parse from each worksheet. Columns beyond
+     * this limit are silently skipped. Useful for previewing very wide sheets.
+     */
+    maxCols?: number;
+    /**
+     * List of worksheet XML node names to skip while parsing (e.g.
+     * `"dataValidations"`, `"conditionalFormatting"`). Use for workbooks that
+     * contain corrupted or unsupported elements you want to ignore.
+     */
+    ignoreNodes?: string[];
+    /**
+     * Forward-compatibility / subclass extension escape hatch. Unknown keys are
+     * passed through to internal loaders; unrecognised keys are ignored.
+     */
     [key: string]: unknown;
 }
 export interface ZipWriterOptions {
@@ -55,8 +101,33 @@ export interface ZipWriterOptions {
     /** Timestamp writing strategy for ZIP entry metadata (optional). */
     timestamps?: ZipTimestampMode;
 }
+/**
+ * Options for writing an XLSX workbook.
+ *
+ * All officially supported options are declared below with proper types so
+ * callers get IDE completion and type-checking. Additional fields are
+ * permitted via the index signature for forward compatibility and for
+ * callers who subclass `XLSX` to pass through private flags.
+ */
 export interface XlsxWriteOptions {
+    /** ZIP archive options (compression level, timestamps, ...). */
     zip?: ZipWriterOptions;
+    /**
+     * Use a shared-string table for cell text values. Defaults to `true`.
+     * Set to `false` to write string values inline (larger file, but streams
+     * better for very large sheets).
+     */
+    useSharedStrings?: boolean;
+    /**
+     * Emit style definitions (fonts, fills, borders, number formats, …).
+     * Defaults to `true`. Set to `false` to skip style blocks for maximum
+     * compatibility with minimal readers.
+     */
+    useStyles?: boolean;
+    /**
+     * Forward-compatibility / subclass extension escape hatch. Unknown keys are
+     * passed through to internal writers; unrecognised keys are ignored.
+     */
     [key: string]: unknown;
 }
 export type XlsxOptions = XlsxReadOptions & XlsxWriteOptions;
@@ -73,7 +144,7 @@ export interface MediaModel {
 }
 interface ZipEntryLike {
     name: string;
-    type: "Directory" | "File";
+    type: "Directory" | "File" | "Symlink";
     stream: IParseStream;
     drain: () => Promise<void>;
 }
@@ -102,6 +173,9 @@ declare class XLSX {
         PivotTable: string;
         FeaturePropertyBag: string;
         CtrlProp: string;
+        SheetMetadata: string;
+        ExternalLink: string;
+        ExternalLinkPath: string;
     };
     constructor(workbook: Workbook);
     /**
@@ -133,19 +207,28 @@ declare class XLSX {
     /**
      * Read workbook from a stream
      */
-    read(stream: IParseStream, options?: XlsxReadOptions): Promise<any>;
+    read(stream: IParseStream, options?: XlsxReadOptions): Promise<Workbook>;
     /**
      * Write workbook to a stream
      */
-    write(stream: any, options?: XlsxWriteOptions): Promise<XLSX>;
+    write(stream: IWritableStream, options?: XlsxWriteOptions): Promise<XLSX>;
     /**
-     * Load workbook from buffer/ArrayBuffer/Uint8Array
+     * Load a workbook from binary data.
+     *
+     * Accepted inputs:
+     *  - `Uint8Array` (and `Buffer`, which is a Uint8Array at runtime)
+     *  - `ArrayBuffer` / `SharedArrayBuffer`
+     *  - Any `ArrayBufferView` (DataView, Int8Array, Float32Array, …) — the
+     *    underlying bytes are reinterpreted as a zip archive
+     *  - `string` — treated as base64-encoded data when `options.base64 === true`;
+     *    raw binary cannot be round-tripped through a JS string and is rejected
+     *    to prevent silent corruption.
      */
-    load(data: any, options?: XlsxReadOptions): Promise<any>;
+    load(data: Uint8Array | ArrayBuffer | ArrayBufferView | string, options?: XlsxReadOptions): Promise<Workbook>;
     /**
      * Internal: Load from Uint8Array buffer
      */
-    protected loadBuffer(buffer: Uint8Array, options?: XlsxReadOptions): Promise<any>;
+    protected loadBuffer(buffer: Uint8Array, options?: XlsxReadOptions): Promise<Workbook>;
     /**
      * Internal: Load workbook from an async stream of ZIP entries.
      *
@@ -194,6 +277,53 @@ declare class XLSX {
     parseWorkbook(stream: IParseStream): Promise<any>;
     parseSharedStrings(stream: IParseStream): Promise<any>;
     reconcile(model: any, options?: XlsxOptions): void;
+    /**
+     * Join the three on-disk sources that together describe external workbook
+     * references into a single dense `model.externalLinks: ExternalLinkModel[]`.
+     *
+     * Sources:
+     *   - `<externalReferences>` list in workbook.xml (declaration order)
+     *   - `xl/_rels/workbook.xml.rels` (rId → internal path)
+     *   - `xl/externalLinks/externalLink{N}.xml` (sheet names, cached values)
+     *   - `xl/externalLinks/_rels/externalLink{N}.xml.rels` (target, TargetMode)
+     *
+     * The 1-based index of each resulting ExternalLinkModel matches the `[N]`
+     * used in formula strings — this is the single source of truth formula
+     * code should rely on.
+     */
+    protected _reconcileExternalLinks(model: any): void;
+    /**
+     * Write-time pass that brings the workbook model into a shape the writer
+     * can serialise cleanly. Two concerns:
+     *
+     *   1. Build the final external-link list for this write, combining
+     *      user-declared links (`wb.externalLinks`) with auto-discovered
+     *      ones from previous writes (cached on the Workbook). The result
+     *      is assigned to `model.externalLinks` and consumed by the writer;
+     *      `wb.externalLinks` is **not** modified.
+     *
+     *   2. Scan every formula cell for `[Book]Sheet!` prefixes. Filename-form
+     *      references that don't match an existing link trigger
+     *      `_recordAutoExternalLink()` on the Workbook, which adds the target
+     *      to the private writer cache (so subsequent writes are fixed-point
+     *      stable) but leaves `wb.externalLinks` untouched.
+     *
+     *   3. Rewrite every external-ref formula so it uses the numeric `[N]`
+     *      form, the canonical OOXML storage form. This mutation lands on
+     *      the cell's model object — matching the library's existing
+     *      write-time pattern for `ssId`, `styleId`, `si`, and `cm`.
+     *      Subsequent writes see the `[N]` form directly and resolve it
+     *      against `model.externalLinks`, giving idempotent output.
+     */
+    protected _normaliseExternalLinks(model: any): void;
+    /**
+     * Rewrite a single formula so every external-ref prefix uses the numeric
+     * `[N]` form. When an unknown filename-form reference is found we record
+     * it on the workbook's private writer cache (so the next write can still
+     * resolve it) and append a local link to `scratch.links` so subsequent
+     * refs in the same formula see the freshly-assigned index.
+     */
+    private _normaliseFormulaExternalRefs;
     /**
      * Reconcile pivot tables by linking them to worksheets and their cache data.
      */
@@ -229,7 +359,21 @@ declare class XLSX {
     _processPivotTableRelsEntry(stream: IParseStream, model: any, name: string): Promise<void>;
     _processPivotCacheDefinitionEntry(stream: IParseStream, model: any, name: string): Promise<void>;
     _processPivotCacheRecordsEntry(stream: IParseStream, model: any, name: string): Promise<void>;
-    loadFromFiles(zipData: Record<string, Uint8Array>, options?: any): Promise<any>;
+    /**
+     * Parse `xl/externalLinks/externalLink{N}.xml` into the intermediate
+     * ParsedExternalLink shape. Reconciliation (joining with the rels file
+     * and the workbook's `<externalReferences>` list) happens later in
+     * {@link reconcile}.
+     */
+    _processExternalLinkEntry(stream: IParseStream, model: any, index: number): Promise<void>;
+    /**
+     * Parse `xl/externalLinks/_rels/externalLink{N}.xml.rels`. The Target /
+     * TargetMode carried here is what Excel uses to locate the actual external
+     * file at open time, so we must preserve it verbatim (including relative
+     * paths like `"测试.xlsx"`).
+     */
+    _processExternalLinkRelsEntry(stream: IParseStream, model: any, index: number): Promise<void>;
+    loadFromFiles(zipData: Record<string, Uint8Array>, options?: XlsxReadOptions): Promise<Workbook>;
     /**
      * Process default entries (drawings, comments, tables, etc.)
      * @param rawData Optional raw entry data for passthrough preservation (used by loadFromFiles)
@@ -253,12 +397,27 @@ declare class XLSX {
     addOfficeRels(zip: IZipWriter, _model: any): Promise<void>;
     addWorkbookRels(zip: IZipWriter, model: any): Promise<void>;
     addFeaturePropertyBag(zip: IZipWriter, model: any): Promise<void>;
+    addMetadata(zip: IZipWriter, model: any): Promise<void>;
     addSharedStrings(zip: IZipWriter, model: any): Promise<void>;
     addStyles(zip: IZipWriter, model: any): Promise<void>;
     addWorkbook(zip: IZipWriter, model: any): Promise<void>;
     addWorksheets(zip: IZipWriter, model: any): Promise<void>;
     addDrawings(zip: IZipWriter, model: any): Promise<void>;
     addTables(zip: IZipWriter, model: any): Promise<void>;
+    /**
+     * Write every external workbook reference into the archive. For each
+     * {@link ExternalLinkModel} in `model.externalLinks` we emit two files:
+     *
+     *   xl/externalLinks/externalLink{index}.xml          — sheet names + cache
+     *   xl/externalLinks/_rels/externalLink{index}.xml.rels — target path
+     *
+     * The target-path rel carries `TargetMode="External"` with a **bare
+     * relative** `Target` whenever the user supplied one. This is the single
+     * line that makes Office / WPS resolve the referenced workbook relative
+     * to the current file's directory (not the `%USERPROFILE%\Documents`
+     * fallback) — the root of the behaviour reported in exceljs#3039.
+     */
+    addExternalLinks(zip: IZipWriter, model: any): Promise<void>;
     /**
      * Write passthrough files (charts, etc.) that were preserved during read.
      * These files are written back unchanged to preserve unsupported features.