@devmm/puredocs-excel 1.0.6 → 1.0.7

package/dist/index.d.cts

@@ -236,6 +236,8 @@ declare class ExcelBorderEdge {
         }>;
     }): ExcelBorderEdge;
     cacheKey(): string;
+    /** An independent copy. ExcelColor is immutable, so it is shared. */
+    clone(): ExcelBorderEdge;
 }
 declare class ExcelBorder {
     left: ExcelBorderEdge;
@@ -252,7 +254,21 @@ declare class ExcelBorder {
     static topOnly(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
     static leftOnly(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
     static rightOnly(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
-    static readonly none: ExcelBorder;
+    /**
+     * A border with no edges set.
+     *
+     * A fresh instance per access, not a shared singleton. `ExcelBorder` is mutable
+     * (`border.left.style = …` is the normal way to use it), so a shared instance
+     * handed to two styles let an edit through one of them reach the other — and,
+     * once anything had assigned `none` and then modified it, every later
+     * `ExcelBorder.none` came back already carrying that edge.
+     */
+    static get none(): ExcelBorder;
+    /**
+     * A deep copy: the edges are new objects, so mutating the copy cannot reach the
+     * original. {@link CellStyle.clone} relies on this.
+     */
+    clone(): ExcelBorder;
     toXml(): string;
     static fromXmlChildren(children: Array<{
         tagName: string;
@@ -449,6 +465,17 @@ declare class StyleManager {
      * Used by Cell.style getter.
      */
     getCellStyle(styleIndex: number): CellStyle;
+    /**
+     * Whether the cellXf at `styleIndex` formats its value as a date. This is the
+     * one style question the value-reading path has to ask, so it is answered
+     * without reconstructing a CellStyle: the result is derived from the stored
+     * format id/code and memoised per index.
+     *
+     * Equivalent to `getCellStyle(i).numberFormat` being date-like, by
+     * construction — both read the same `applyNumFmt`/`numFmtId` pair through
+     * {@link ExcelNumberFormat.fromFormatId}.
+     */
+    isDateStyle(styleIndex: number): boolean;
     /** Builds the complete xl/styles.xml string. */
     buildStylesXml(): string;
     /** Loads an existing styles.xml, rebuilding all caches. */
@@ -477,11 +504,31 @@ interface CellData {
     /** Spill range for a dynamic-array formula anchor, e.g. "A1:A3". */
     arrayRef?: string;
     styleIndex: number;
+    /**
+     * Shared-formula group id (`<f t="shared" si="…">`) as read from the file.
+     *
+     * Only meaningful while a sheet is loading, where it links the cells of one
+     * fill-down to the single copy of the formula text Excel stored. Once the group
+     * is resolved every cell carries its own `formula`, and this is not written
+     * back out — see {@link Worksheet.loadFromXml}.
+     */
+    sharedIndex?: number;
+}
+/**
+ * A mutation counter shared by a worksheet and the {@link Cell} views it hands
+ * out. A Cell writes straight into the sheet's stored {@link CellData}, so the
+ * sheet cannot otherwise tell that it changed — and both the used-range memo and
+ * the saved-XML reuse depend on knowing.
+ *
+ * @internal
+ */
+interface SheetVersion {
+    v: number;
 }
 declare class Cell {
     #private;
     /** @internal */
-    constructor(data: CellData, sharedStrings: SharedStringManager, styles: StyleManager);
+    constructor(data: CellData, sharedStrings: SharedStringManager, styles: StyleManager, version?: SheetVersion);
     /** Cell reference string e.g. "A1". */
     get reference(): string;
     /** 1-based row index. */
@@ -846,6 +893,8 @@ interface StructuralEditResult {
 }
 declare class Worksheet {
     #private;
+    /** @internal Current mutation count — see {@link #version}. */
+    get version(): number;
     /** @internal */
     constructor(name: string, sharedStrings: SharedStringManager, styles: StyleManager);
     get name(): string;
@@ -869,6 +918,13 @@ declare class Worksheet {
     getRange(rangeReference: string): Range;
     /** Gets the raw value of a cell (for formula evaluation). */
     getCellValue(reference: string): unknown;
+    /**
+     * Value of a cell addressed by 1-based row/column. The reference-string
+     * overload has to build (and the callee re-parse) a string per cell; a range
+     * read walking a rectangle already knows the coordinates, and on a real
+     * workbook that is tens of millions of strings per recalculation.
+     */
+    getCellValueAt(row: number, column: number): unknown;
     /** Formula text (without leading '=') of a cell, or null if it has none. */
     getCellFormula(reference: string): string | null;
     /** Spill range (e.g. "A1:A3") of a dynamic-array anchor, or null. Supports A1#. */
@@ -1361,6 +1417,16 @@ declare class Workbook {
      * Works in browser and Node.js.
      */
     saveAsBuffer(): Uint8Array;
+    /**
+     * Same output as {@link saveAsBuffer}, without blocking the calling thread on
+     * compression — for an editor that autosaves, this is the difference between a
+     * visible stall on every save and none.
+     *
+     * The XML for sheets that have not changed since the last save is reused, so a
+     * save after a one-cell edit re-serialises one sheet rather than all of them.
+     * That reuse applies to the synchronous path too; only the compression differs.
+     */
+    saveAsBufferAsync(): Promise<Uint8Array>;
     /**
      * Saves the workbook to a file (Node.js only).
      * Mirrors workbook.SaveAs(filePath) in C#.
@@ -1370,6 +1436,20 @@ declare class Workbook {
     close(): void;
     /** Symbol.dispose support for `using` keyword (TypeScript 5.2+). */
     [Symbol.dispose](): void;
+    /**
+     * The calculation order Excel recorded for this workbook, oldest-first as
+     * stored in `xl/calcChain.xml`, or an empty array when the source file had
+     * none (a freshly created workbook, or one saved by a tool that omits it).
+     *
+     * Excel has already done the topological sort that produced this order, so
+     * evaluating in it avoids repeating that work. Treat it as a hint, not a
+     * guarantee: it reflects the file as opened, and edits made since are not
+     * reflected here.
+     */
+    get calcChain(): readonly {
+        readonly sheet: string;
+        readonly ref: string;
+    }[];
 }
 
 /**
@@ -1631,6 +1711,7 @@ declare const REL_TYPES: {
     readonly hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
     readonly comments: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
     readonly vmlDrawing: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing";
+    readonly calcChain: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/calcChain";
 };
 declare const CONTENT_TYPES: {
     readonly workbook: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml";
@@ -1643,6 +1724,7 @@ declare const CONTENT_TYPES: {
     readonly coreProperties: "application/vnd.openxmlformats-package.core-properties+xml";
     readonly comments: "application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml";
     readonly vmlDrawing: "application/vnd.openxmlformats-officedocument.vmlDrawing";
+    readonly calcChain: "application/vnd.openxmlformats-officedocument.spreadsheetml.calcChain+xml";
 };
 
 /**

package/dist/index.d.ts

@@ -236,6 +236,8 @@ declare class ExcelBorderEdge {
         }>;
     }): ExcelBorderEdge;
     cacheKey(): string;
+    /** An independent copy. ExcelColor is immutable, so it is shared. */
+    clone(): ExcelBorderEdge;
 }
 declare class ExcelBorder {
     left: ExcelBorderEdge;
@@ -252,7 +254,21 @@ declare class ExcelBorder {
     static topOnly(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
     static leftOnly(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
     static rightOnly(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
-    static readonly none: ExcelBorder;
+    /**
+     * A border with no edges set.
+     *
+     * A fresh instance per access, not a shared singleton. `ExcelBorder` is mutable
+     * (`border.left.style = …` is the normal way to use it), so a shared instance
+     * handed to two styles let an edit through one of them reach the other — and,
+     * once anything had assigned `none` and then modified it, every later
+     * `ExcelBorder.none` came back already carrying that edge.
+     */
+    static get none(): ExcelBorder;
+    /**
+     * A deep copy: the edges are new objects, so mutating the copy cannot reach the
+     * original. {@link CellStyle.clone} relies on this.
+     */
+    clone(): ExcelBorder;
     toXml(): string;
     static fromXmlChildren(children: Array<{
         tagName: string;
@@ -449,6 +465,17 @@ declare class StyleManager {
      * Used by Cell.style getter.
      */
     getCellStyle(styleIndex: number): CellStyle;
+    /**
+     * Whether the cellXf at `styleIndex` formats its value as a date. This is the
+     * one style question the value-reading path has to ask, so it is answered
+     * without reconstructing a CellStyle: the result is derived from the stored
+     * format id/code and memoised per index.
+     *
+     * Equivalent to `getCellStyle(i).numberFormat` being date-like, by
+     * construction — both read the same `applyNumFmt`/`numFmtId` pair through
+     * {@link ExcelNumberFormat.fromFormatId}.
+     */
+    isDateStyle(styleIndex: number): boolean;
     /** Builds the complete xl/styles.xml string. */
     buildStylesXml(): string;
     /** Loads an existing styles.xml, rebuilding all caches. */
@@ -477,11 +504,31 @@ interface CellData {
     /** Spill range for a dynamic-array formula anchor, e.g. "A1:A3". */
     arrayRef?: string;
     styleIndex: number;
+    /**
+     * Shared-formula group id (`<f t="shared" si="…">`) as read from the file.
+     *
+     * Only meaningful while a sheet is loading, where it links the cells of one
+     * fill-down to the single copy of the formula text Excel stored. Once the group
+     * is resolved every cell carries its own `formula`, and this is not written
+     * back out — see {@link Worksheet.loadFromXml}.
+     */
+    sharedIndex?: number;
+}
+/**
+ * A mutation counter shared by a worksheet and the {@link Cell} views it hands
+ * out. A Cell writes straight into the sheet's stored {@link CellData}, so the
+ * sheet cannot otherwise tell that it changed — and both the used-range memo and
+ * the saved-XML reuse depend on knowing.
+ *
+ * @internal
+ */
+interface SheetVersion {
+    v: number;
 }
 declare class Cell {
     #private;
     /** @internal */
-    constructor(data: CellData, sharedStrings: SharedStringManager, styles: StyleManager);
+    constructor(data: CellData, sharedStrings: SharedStringManager, styles: StyleManager, version?: SheetVersion);
     /** Cell reference string e.g. "A1". */
     get reference(): string;
     /** 1-based row index. */
@@ -846,6 +893,8 @@ interface StructuralEditResult {
 }
 declare class Worksheet {
     #private;
+    /** @internal Current mutation count — see {@link #version}. */
+    get version(): number;
     /** @internal */
     constructor(name: string, sharedStrings: SharedStringManager, styles: StyleManager);
     get name(): string;
@@ -869,6 +918,13 @@ declare class Worksheet {
     getRange(rangeReference: string): Range;
     /** Gets the raw value of a cell (for formula evaluation). */
     getCellValue(reference: string): unknown;
+    /**
+     * Value of a cell addressed by 1-based row/column. The reference-string
+     * overload has to build (and the callee re-parse) a string per cell; a range
+     * read walking a rectangle already knows the coordinates, and on a real
+     * workbook that is tens of millions of strings per recalculation.
+     */
+    getCellValueAt(row: number, column: number): unknown;
     /** Formula text (without leading '=') of a cell, or null if it has none. */
     getCellFormula(reference: string): string | null;
     /** Spill range (e.g. "A1:A3") of a dynamic-array anchor, or null. Supports A1#. */
@@ -1361,6 +1417,16 @@ declare class Workbook {
      * Works in browser and Node.js.
      */
     saveAsBuffer(): Uint8Array;
+    /**
+     * Same output as {@link saveAsBuffer}, without blocking the calling thread on
+     * compression — for an editor that autosaves, this is the difference between a
+     * visible stall on every save and none.
+     *
+     * The XML for sheets that have not changed since the last save is reused, so a
+     * save after a one-cell edit re-serialises one sheet rather than all of them.
+     * That reuse applies to the synchronous path too; only the compression differs.
+     */
+    saveAsBufferAsync(): Promise<Uint8Array>;
     /**
      * Saves the workbook to a file (Node.js only).
      * Mirrors workbook.SaveAs(filePath) in C#.
@@ -1370,6 +1436,20 @@ declare class Workbook {
     close(): void;
     /** Symbol.dispose support for `using` keyword (TypeScript 5.2+). */
     [Symbol.dispose](): void;
+    /**
+     * The calculation order Excel recorded for this workbook, oldest-first as
+     * stored in `xl/calcChain.xml`, or an empty array when the source file had
+     * none (a freshly created workbook, or one saved by a tool that omits it).
+     *
+     * Excel has already done the topological sort that produced this order, so
+     * evaluating in it avoids repeating that work. Treat it as a hint, not a
+     * guarantee: it reflects the file as opened, and edits made since are not
+     * reflected here.
+     */
+    get calcChain(): readonly {
+        readonly sheet: string;
+        readonly ref: string;
+    }[];
 }
 
 /**
@@ -1631,6 +1711,7 @@ declare const REL_TYPES: {
     readonly hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
     readonly comments: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
     readonly vmlDrawing: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing";
+    readonly calcChain: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/calcChain";
 };
 declare const CONTENT_TYPES: {
     readonly workbook: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml";
@@ -1643,6 +1724,7 @@ declare const CONTENT_TYPES: {
     readonly coreProperties: "application/vnd.openxmlformats-package.core-properties+xml";
     readonly comments: "application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml";
     readonly vmlDrawing: "application/vnd.openxmlformats-officedocument.vmlDrawing";
+    readonly calcChain: "application/vnd.openxmlformats-officedocument.spreadsheetml.calcChain+xml";
 };
 
 /**