@devmm/puredocs-excel 1.0.5 → 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. */
@@ -513,11 +560,13 @@ declare class Cell {
     getText(): string;
     /**
      * Returns the display text with the cell's number format applied, e.g. a
-     * value of 4.5 under `$#,##0.00` renders as `$4.50`.
+     * value of 4.5 under `$#,##0.00` renders as `$4.50`, and a date under
+     * `dd/mm/yyyy` as `31/01/2025`.
      *
-     * Falls back to {@link getText} for non-numeric values and for format codes
-     * outside the supported subset (fractions, scientific notation, conditional
-     * sections) — so the result is never a misleading rendering.
+     * Falls back to {@link getText} for values with no format and for format
+     * codes outside the supported subset (fractions, scientific notation,
+     * conditional sections, elapsed time) — so the result is never a misleading
+     * rendering.
      */
     getFormattedText(): string;
     /**
@@ -588,6 +637,45 @@ declare class Cell {
     }, ref: string): CellData;
 }
 
+/** Describes one structural edit on a sheet. */
+interface RefShift {
+    readonly dim: 'row' | 'col';
+    readonly kind: 'insert' | 'delete';
+    /** 1-based index of the first inserted/deleted row or column. */
+    readonly at: number;
+    /** Number of rows/columns inserted or deleted (>= 1). */
+    readonly count: number;
+    /** Name of the sheet the structural edit happened on. */
+    readonly sheetName: string;
+}
+/**
+ * Shifts one 1-based index. Returns `null` when the index falls inside a
+ * delete band (the row/column it pointed at no longer exists).
+ */
+declare function shiftIndex(index: number, shift: RefShift): number | null;
+/**
+ * Shifts an inclusive 1-based [start, end] span, clamping it against a delete
+ * band the way Excel does (endpoints move independently; a partially deleted
+ * span shrinks). Returns `null` when the span is entirely deleted.
+ */
+declare function shiftSpan(start: number, end: number, shift: RefShift): {
+    start: number;
+    end: number;
+} | null;
+/**
+ * Shifts a plain "A1" or "A1:B2" reference (no `$` markers — this is for
+ * model metadata such as merges, autofilter and validation sqref parts, which
+ * never carry them). Returns `null` when the referenced area is entirely
+ * deleted.
+ */
+declare function shiftRangeRef(ref: string, shift: RefShift): string | null;
+/**
+ * Shifts a space-separated list of range references (the OOXML `sqref` shape
+ * used by data validations). Parts that are entirely deleted are dropped;
+ * returns `null` when nothing survives.
+ */
+declare function shiftSqref(sqref: string, shift: RefShift): string | null;
+
 /** A part that a drawing anchor references (e.g. `xl/charts/chart1.xml`). */
 interface DrawingDependentPart {
     /** Package-relative path, no leading slash — e.g. `xl/charts/chart1.xml`. */
@@ -701,7 +789,23 @@ declare class Range {
     getValues(): CellValue[][];
     /** Clears all cells in the range (values only, preserves style). */
     clear(): void;
-    /** Auto-fits all columns in the range. */
+    /** Clears values AND styles of all cells in the range. */
+    clearAll(): void;
+    /**
+     * Moves the whole range so its top-left cell lands on `destTopLeft`,
+     * carrying values, formulas, styles and spill anchors. The vacated cells
+     * are cleared and the destination block is fully replaced (empty source
+     * cells clear their destination). Overlapping source/destination is safe.
+     * Formula text is NOT adjusted for the new position.
+     *
+     * @example
+     * ws.getRange('A1:B3').moveTo('D1');
+     */
+    moveTo(destTopLeft: string): void;
+    /**
+     * Auto-fits all columns in the range. Measures every column in one sparse
+     * sweep rather than re-scanning the sheet per column.
+     */
     autoFit(): void;
     /** Applies a CellStyle to all cells in the range. Returns this for chaining. */
     setStyle(style: CellStyle): this;
@@ -734,8 +838,63 @@ declare class Range {
  */
 
 type SheetVisibility = 'visible' | 'hidden' | 'veryHidden';
+/**
+ * What users may still do on a protected sheet. Named from the user's point of
+ * view — the same way Excel's "Protect Sheet" dialog lists its checkboxes —
+ * because the underlying OOXML attributes are inverted (`formatCells="1"` means
+ * formatting is *blocked*), which is a reliable source of bugs.
+ *
+ * Defaults match Excel: selecting cells stays allowed, everything else does not.
+ */
+interface SheetProtection {
+    allowSelectLockedCells: boolean;
+    allowSelectUnlockedCells: boolean;
+    allowFormatCells: boolean;
+    allowFormatColumns: boolean;
+    allowFormatRows: boolean;
+    allowInsertRows: boolean;
+    allowInsertColumns: boolean;
+    allowInsertHyperlinks: boolean;
+    allowDeleteRows: boolean;
+    allowDeleteColumns: boolean;
+    allowSort: boolean;
+    allowAutoFilter: boolean;
+    allowPivotTables: boolean;
+    allowEditObjects: boolean;
+    allowEditScenarios: boolean;
+}
+/** A hyperlink attached to a cell or range. */
+interface Hyperlink {
+    /** The cell or range the link covers, e.g. "A1" or "A1:B2". */
+    readonly ref: string;
+    /** External target, e.g. "https://example.com" or "mailto:a@b.c". */
+    readonly target?: string;
+    /** In-workbook destination, e.g. "Sheet2!A1" or a defined name. */
+    readonly location?: string;
+    /** Text to show instead of the cell's own value. */
+    readonly display?: string;
+    /** Hover tooltip. */
+    readonly tooltip?: string;
+}
+/** A classic cell comment (a "note" in current Excel versions). */
+interface CellComment {
+    /** The cell the comment is attached to, e.g. "B4". */
+    readonly ref: string;
+    readonly text: string;
+    readonly author: string;
+}
+/** Outcome of a structural edit (insert/delete rows or columns). */
+interface StructuralEditResult {
+    /**
+     * References (post-shift, on this sheet) of formula cells that now contain
+     * `#REF!` because something they pointed at was deleted.
+     */
+    readonly refErrors: readonly string[];
+}
 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;
@@ -759,14 +918,57 @@ 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#. */
     getSpillRange(reference: string): string | null;
+    /**
+     * Iterates the populated rows of the sheet in ascending row order, yielding
+     * each row's 1-based index and its cells (left to right). Rows and cells
+     * that were never written are skipped, so a sparse sheet iterates in
+     * O(populated cells) regardless of its bounds.
+     *
+     * @example
+     * for (const { rowIndex, cells } of ws.rows()) {
+     *   for (const cell of cells) console.log(rowIndex, cell.reference, cell.getValue());
+     * }
+     */
+    rows(): IterableIterator<{
+        rowIndex: number;
+        cells: Cell[];
+    }>;
+    /**
+     * Iterates every populated cell of the sheet in row-major order. Sparse
+     * counterpart to scanning {@link usedBounds} with {@link tryGetCell}.
+     *
+     * @example
+     * for (const cell of ws.cells()) console.log(cell.reference, cell.getValue());
+     */
+    cells(): IterableIterator<Cell>;
+    /**
+     * @internal Visits the populated cells inside a rectangle, passing the
+     * coordinates it already knows so the callback never has to parse a
+     * reference. Backs the Range operations that must not create cells; probing
+     * every coordinate would cost O(area) even on an empty sheet.
+     */
+    forEachCellIn(startRow: number, startColumn: number, endRow: number, endColumn: number, action: (cell: Cell, row: number, column: number) => void): void;
+    /**
+     * @internal Moves a cell by coordinates, skipping the reference parsing that
+     * the public {@link moveCell} has to do. Used by bulk range moves.
+     */
+    moveCellRC(fromRow: number, fromColumn: number, toRow: number, toColumn: number): void;
     /**
      * Returns the 1-based extent of populated cells (largest row and column that
      * contain data). Returns zeros for an empty sheet. Useful for snapshotting a
-     * sheet into a dense 2D array.
+     * sheet into a dense 2D array — though {@link rows} and {@link cells} are
+     * cheaper when a dense shape is not actually required.
      */
     get usedBounds(): {
         rowCount: number;
@@ -774,6 +976,19 @@ declare class Worksheet {
     };
     /** Sets the width of a column (1-based index). */
     setColumnWidth(columnIndex: number, width: number): void;
+    /**
+     * Removes the explicit width of a column so it falls back to the sheet
+     * default. Counterpart to {@link setColumnWidth}; afterwards
+     * {@link getColumnWidth} returns `undefined`. A hidden column stays hidden.
+     */
+    resetColumnWidth(columnIndex: number): void;
+    /**
+     * Shows or hides a column (1-based index). Hidden columns round-trip to the
+     * file as `<col hidden="1">` and keep any explicit width.
+     */
+    setColumnHidden(columnIndex: number, hidden?: boolean): void;
+    /** True if the given 1-based column is hidden. */
+    isColumnHidden(columnIndex: number): boolean;
     /**
      * Returns the explicit width of a column (1-based index), or `undefined` when
      * the column uses the sheet default. Counterpart to {@link setColumnWidth};
@@ -783,6 +998,11 @@ declare class Worksheet {
     getColumnWidth(columnIndex: number): number | undefined;
     /** Auto-fits column width based on content (approximate). */
     autoFitColumn(columnIndex: number): void;
+    /**
+     * Auto-fits an inclusive span of columns (1-based) in a single pass over the
+     * populated cells, instead of re-scanning the sheet once per column.
+     */
+    autoFitColumns(firstColumn: number, lastColumn: number): void;
     /** Sets the height of a row (1-based index). */
     setRowHeight(rowIndex: number, height: number): void;
     /**
@@ -790,10 +1010,90 @@ declare class Worksheet {
      * the row uses the sheet default. Counterpart to {@link setRowHeight}.
      */
     getRowHeight(rowIndex: number): number | undefined;
+    /**
+     * Removes the explicit height of a row so it falls back to the sheet
+     * default. Counterpart to {@link setRowHeight}; afterwards
+     * {@link getRowHeight} returns `undefined`. A hidden row stays hidden.
+     */
+    resetRowHeight(rowIndex: number): void;
     /** Shows or hides a row (1-based index). Hidden rows affect SUBTOTAL(101-111). */
     setRowHidden(rowIndex: number, hidden?: boolean): void;
     /** True if the given 1-based row is hidden. */
     isRowHidden(rowIndex: number): boolean;
+    /**
+     * The 1-based indices of every hidden row, ascending. Sparse counterpart to
+     * probing {@link isRowHidden} across {@link usedBounds}.
+     */
+    get hiddenRows(): readonly number[];
+    /**
+     * The 1-based indices of every hidden column, ascending. Counterpart to
+     * {@link isColumnHidden}, in the same spirit as {@link hiddenRows}.
+     */
+    get hiddenColumns(): readonly number[];
+    /**
+     * Inserts `count` empty rows starting at row `at` (1-based). Everything at
+     * or below `at` moves down: cell values, formulas (references are rewritten
+     * the way Excel does), styles, row heights, hidden flags, merges,
+     * autofilter and data-validation ranges.
+     *
+     * Frozen panes are a view property and stay put. Drawing/chart anchors
+     * preserved from a loaded file are opaque XML and do NOT shift — images
+     * keep their absolute position (known limitation).
+     *
+     * When formulas on OTHER sheets reference this sheet, use the
+     * Workbook-level counterpart so they are rewritten too, or call
+     * `applyExternalShift` on each sheet yourself. If a RecalcEngine is
+     * attached, notify it afterwards (e.g. `engine.onRowsInserted(...)`).
+     *
+     * @example
+     * ws.insertRows(3, 2); // pushes row 3 and below down by two rows
+     */
+    insertRows(at: number, count?: number): StructuralEditResult;
+    /**
+     * Deletes `count` rows starting at row `at` (1-based). Rows below move up;
+     * formulas referencing the deleted band get `#REF!` (fully inside) or
+     * shrink (partially inside), exactly like Excel. See {@link insertRows}
+     * for the shifting rules and known limitations.
+     */
+    deleteRows(at: number, count?: number): StructuralEditResult;
+    /**
+     * Inserts `count` empty columns starting at column `at` (1-based).
+     * Column-level counterpart to {@link insertRows}; widths and hidden flags
+     * shift with the columns.
+     */
+    insertColumns(at: number, count?: number): StructuralEditResult;
+    /**
+     * Deletes `count` columns starting at column `at` (1-based).
+     * Column-level counterpart to {@link deleteRows}.
+     */
+    deleteColumns(at: number, count?: number): StructuralEditResult;
+    /**
+     * @internal Rewrites formulas on THIS sheet after a structural edit on a
+     * DIFFERENT sheet (named by `shift.sheetName`), so qualified references
+     * like `'Data'!A5` stay correct. Cell positions here do not change.
+     */
+    applyExternalShift(shift: RefShift): StructuralEditResult;
+    /**
+     * Moves a cell's full contents — value, formula, style and spill anchor —
+     * to another cell, overwriting the destination and clearing the source.
+     * A missing source clears the destination. This is a literal move: formula
+     * text is NOT adjusted for the new position.
+     *
+     * @example
+     * ws.moveCell('A1', 'C5');
+     */
+    moveCell(from: string, to: string): void;
+    /**
+     * Copies a cell's value, formula and style to another cell, overwriting the
+     * destination and leaving the source untouched. A missing source clears the
+     * destination. This is a literal copy: formula references are NOT adjusted,
+     * and the spill anchor (`arrayRef`) is not copied — a recalc engine
+     * re-establishes it.
+     *
+     * @example
+     * ws.copyCell('A1', 'C5');
+     */
+    copyCell(from: string, to: string): void;
     /** Merges cells in the given range (e.g. "A1:B2"). */
     mergeCells(rangeReference: string): void;
     /** Removes a merge for the given range reference. */
@@ -821,6 +1121,82 @@ declare class Worksheet {
     /** Sets the visibility state of this worksheet. */
     setVisibility(state: SheetVisibility): void;
     get visibility(): SheetVisibility;
+    /**
+     * Turns on sheet protection, optionally relaxing individual permissions.
+     * Cells are locked by default in Excel, so protecting a sheet makes all of
+     * them read-only; clear a cell style's `locked` flag to leave a cell editable.
+     *
+     * Excel's sheet protection is a UI guard, **not** security: the contents stay
+     * readable to anything that opens the file. This library therefore never
+     * creates a protection password. A password read from an existing file is
+     * preserved so the sheet round-trips unchanged.
+     *
+     * @example
+     * ws.protect();                                  // lock everything
+     * ws.protect({ allowSort: true, allowAutoFilter: true });
+     */
+    protect(options?: Partial<SheetProtection>): void;
+    /** Turns off sheet protection, discarding any password read from a file. */
+    unprotect(): void;
+    /** True when this sheet is protected. */
+    get isProtected(): boolean;
+    /** The active permissions, or `undefined` when the sheet is not protected. */
+    get protection(): Readonly<SheetProtection> | undefined;
+    /**
+     * Attaches a hyperlink to a cell or range. Give `target` for an external
+     * destination or `location` for one inside the workbook; passing both keeps
+     * the external target and uses the location as its fragment, which is how
+     * Excel links to an anchor within a document.
+     *
+     * A cell's displayed text still comes from its own value — set that
+     * separately; `display` only overrides what Excel shows in the edit bar.
+     *
+     * @example
+     * ws.getCell('A1').setValue('Anthropic');
+     * ws.setHyperlink('A1', { target: 'https://anthropic.com', tooltip: 'Open site' });
+     * ws.setHyperlink('B1', { location: "'Sheet2'!A1" });
+     */
+    setHyperlink(ref: string, link: {
+        target?: string;
+        location?: string;
+        display?: string;
+        tooltip?: string;
+    }): void;
+    /** The hyperlink covering exactly this ref, or undefined. */
+    getHyperlink(ref: string): Hyperlink | undefined;
+    /** Removes the hyperlink on this ref. Returns true if one was there. */
+    removeHyperlink(ref: string): boolean;
+    /** Every hyperlink on the sheet, including ones read from a file. */
+    get hyperlinks(): readonly Hyperlink[];
+    /**
+     * Attaches a comment (a "note" in current Excel versions) to a cell,
+     * replacing any comment already there.
+     *
+     * Note that writing comments makes this sheet regenerate its comment and
+     * legacy-drawing parts on save. If the file was opened with other legacy
+     * drawing content on the same sheet — form controls, for instance — that
+     * content is not reproduced. Reading comments has no such effect.
+     *
+     * @example
+     * ws.setComment('B4', 'Check this figure', { author: 'Bill' });
+     */
+    setComment(ref: string, text: string, options?: {
+        author?: string;
+    }): void;
+    /** The comment on a cell, or undefined. */
+    getComment(ref: string): CellComment | undefined;
+    /** Removes the comment on a cell. Returns true if one was there. */
+    removeComment(ref: string): boolean;
+    /** Every comment on the sheet, including ones read from a file. */
+    get comments(): readonly CellComment[];
+    /** @internal True when this sheet must write its own comment parts. */
+    get ownsCommentParts(): boolean;
+    /**
+     * @internal True when the sheet took over its comment parts and any preserved
+     * originals must be dropped — including the case where every comment was
+     * deleted and nothing replaces them.
+     */
+    get commentPartsReplaced(): boolean;
     /**
      * Attaches a drawing provider (e.g. a chart) to this worksheet.
      * Satellite packages such as `@devmm/puredocs-excel-charts` call this; the core
@@ -858,12 +1234,47 @@ declare class Worksheet {
      * clear every preserved id so the two sets cannot collide.
      */
     get drawingRelId(): string;
+    /**
+     * @internal Relationship ids for the parts this sheet generates itself.
+     *
+     * Derived purely from the model so the worksheet XML and the sheet's rels part
+     * — which are written by different code — cannot disagree about an id. Order is
+     * fixed: drawing, then external hyperlinks in insertion order, then the
+     * comments part and its legacy VML drawing.
+     */
+    generatedRels(): {
+        drawing?: string;
+        hyperlinks: Map<string, string>;
+        comments?: string;
+        vmlDrawing?: string;
+    };
     /** @internal Captures round-trip state from the source package. */
     loadPreservedState(worksheetXml: string, relationships: readonly Relationship[]): void;
+    /**
+     * @internal Package paths of the comment parts this sheet read at load time.
+     * The save pipeline drops them from the preserved set once the sheet takes
+     * ownership, so they are not written twice.
+     */
+    commentPartPaths(): string[];
+    /**
+     * @internal The relationship pointing at this sheet's comments part, if the
+     * sheet was loaded from a file that had one.
+     */
+    commentsPartPath(): string | undefined;
     /** Builds the xl/worksheets/sheetN.xml string. */
     buildXml(): string;
     /** Parses xl/worksheets/sheetN.xml and loads cells into memory. */
     loadFromXml(xml: string): void;
+    /** @internal Parses an `xl/comments*.xml` part into this sheet's comments. */
+    loadCommentsXml(xml: string): void;
+    /** @internal The comments part content, when this sheet owns it. */
+    buildCommentsXml(): string;
+    /**
+     * @internal The legacy VML drawing that positions the comment boxes. Excel
+     * needs it to draw the note indicator and popup; the comments part alone
+     * carries only the text.
+     */
+    buildCommentsVml(): string;
 }
 
 /**
@@ -959,6 +1370,23 @@ declare class Workbook {
      * Returns a worksheet by name. Throws if not found.
      */
     getWorksheet(name: string): Worksheet;
+    /**
+     * Inserts rows on one sheet and keeps the whole workbook consistent:
+     * formulas on OTHER sheets that reference the edited sheet, and defined
+     * names, are rewritten too. Prefer this over `Worksheet.insertRows` in a
+     * multi-sheet workbook.
+     *
+     * @returns The edited sheet's result; `refErrors` additionally includes
+     *          sheet-qualified refs (e.g. `"Other!B2"`) for affected formula
+     *          cells on other sheets.
+     */
+    insertRows(sheetName: string, at: number, count?: number): StructuralEditResult;
+    /** Workbook-wide counterpart to `Worksheet.deleteRows`. See {@link insertRows}. */
+    deleteRows(sheetName: string, at: number, count?: number): StructuralEditResult;
+    /** Workbook-wide counterpart to `Worksheet.insertColumns`. See {@link insertRows}. */
+    insertColumns(sheetName: string, at: number, count?: number): StructuralEditResult;
+    /** Workbook-wide counterpart to `Worksheet.deleteColumns`. See {@link insertRows}. */
+    deleteColumns(sheetName: string, at: number, count?: number): StructuralEditResult;
     /**
      * Defines (or replaces) a named range.
      *
@@ -989,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#.
@@ -998,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;
+    }[];
 }
 
 /**
@@ -1006,6 +1458,10 @@ declare class Workbook {
  *
  * Port of TVE.PureDocs.Excel.CellReference (C#)
  */
+/** Largest 1-based row index a worksheet can have (Excel limit). */
+declare const EXCEL_MAX_ROWS = 1048576;
+/** Largest 1-based column index a worksheet can have (column XFD). */
+declare const EXCEL_MAX_COLUMNS = 16384;
 interface ParsedCellRef {
     readonly row: number;
     readonly column: number;
@@ -1047,6 +1503,15 @@ declare function columnLetter(column: number): string;
  * columnNumber("AA") // 27
  */
 declare function columnNumber(letters: string): number;
+/**
+ * Formats start/end coordinates as a range reference string. Collapses to a
+ * single cell reference when start and end are the same cell.
+ *
+ * @example
+ * formatRangeRef(1, 1, 10, 2) // "A1:B10"
+ * formatRangeRef(1, 1, 1, 1)  // "A1"
+ */
+declare function formatRangeRef(startRow: number, startColumn: number, endRow: number, endColumn: number): string;
 /**
  * Parses a range reference string like "A1:B10" into start/end coordinates.
  */
@@ -1057,6 +1522,24 @@ declare function parseRangeRef(rangeReference: string): {
     endColumn: number;
 };
 
+interface FormulaRewriteResult {
+    /** The rewritten formula text (without leading '='). */
+    readonly text: string;
+    /** True when any reference was actually rewritten. */
+    readonly changed: boolean;
+    /** True when at least one reference was replaced by `#REF!`. */
+    readonly hasRefError: boolean;
+}
+/**
+ * Rewrites the references in one formula for a structural edit.
+ *
+ * @param formula      Formula text without the leading '='.
+ * @param shift        The structural edit that happened.
+ * @param formulaSheet Name of the sheet this formula lives on — unqualified
+ *                     references resolve against it.
+ */
+declare function shiftFormulaRefs(formula: string, shift: RefShift, formulaSheet: string): FormulaRewriteResult;
+
 /**
  * OLE Automation Date (OADate) helpers.
  *
@@ -1102,8 +1585,8 @@ declare function isDateFormatCode(formatCode: string): boolean;
  * raw value rather than display something wrong.
  *
  * Not handled (returns null): fractions (`# ?/?`), scientific (`0.00E+00`),
- * date/time codes (handled by the date path in Cell), and conditional sections
- * such as `[<=9999999]###-####`.
+ * date/time codes (see date-format-renderer.ts, which Cell routes Date values
+ * to), and conditional sections such as `[<=9999999]###-####`.
  */
 /**
  * Applies `formatCode` to `value`.
@@ -1113,6 +1596,30 @@ declare function isDateFormatCode(formatCode: string): boolean;
  */
 declare function formatNumberWithCode(value: number, formatCode: string): string | null;
 
+/**
+ * Renders a Date through an OOXML date/time format code.
+ *
+ * Deliberately a *subset* of the full spec, mirroring the philosophy of
+ * number-format-renderer: it covers the codes an editor actually round-trips
+ * (`yyyy`, `yy`, `m`→`mmmm`, `d`→`dddd`, `h`/`hh`, `s`/`ss`, `AM/PM`, quoted
+ * literals, separators) and returns `null` for anything it does not
+ * understand — elapsed-time brackets (`[h]`), fractional seconds (`ss.00`),
+ * era codes — so callers can fall back rather than display something wrong.
+ *
+ * The `m` month-vs-minute ambiguity uses the standard OOXML rule: `m`/`mm`
+ * means minutes when the previous time token is hours or the next one is
+ * seconds; otherwise it means month.
+ */
+/**
+ * Formats a Date with an OOXML date/time format code, e.g. a value of
+ * 2025-01-31 under `dd/mm/yyyy` renders as `31/01/2025`.
+ *
+ * Returns `null` when the code uses constructs outside the supported subset
+ * (elapsed time `[h]`, fractional seconds, era codes) — callers should fall
+ * back to a locale default rather than render something misleading.
+ */
+declare function formatDateCode(date: Date, formatCode: string): string | null;
+
 /**
  * Cross-platform XML parser.
  *
@@ -1131,6 +1638,12 @@ type XmlElement = {
 /**
  * Parses an XML string into a simple XmlElement tree.
  */
+/**
+ * Decodes the five predefined XML entities. `&amp;` is expanded last so that an
+ * escaped entity such as `&amp;lt;` decodes to the literal text `&lt;` rather
+ * than being expanded twice.
+ */
+declare function decodeXmlEntities(value: string): string;
 declare function parseXml(xmlString: string): XmlElement;
 /**
  * Decodes a Uint8Array to a UTF-8 string.
@@ -1196,6 +1709,9 @@ declare const REL_TYPES: {
     readonly chart: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart";
     readonly drawing: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing";
     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";
@@ -1206,6 +1722,9 @@ declare const CONTENT_TYPES: {
     readonly chart: "application/vnd.openxmlformats-officedocument.drawingml.chart+xml";
     readonly relationships: "application/vnd.openxmlformats-package.relationships+xml";
     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";
 };
 
 /**
@@ -1229,4 +1748,4 @@ declare function setXmlEntry(entries: ZipInput, path: string, xml: string): void
  */
 declare function setBinaryEntry(entries: ZipInput, path: string, bytes: Uint8Array): void;
 
-export { CONTENT_TYPES, Cell, type CellData, CellStyle, type CellValue, type ColorXmlAttrs, type DefinedName, DefinedNameManager, type DrawingDependentPart, type DrawingProvider, ExcelAlignment, ExcelBorder, ExcelBorderEdge, ExcelBorderStyle, ExcelColor, ExcelFill, ExcelFont, type ExcelFontOptions, ExcelHorizontalAlignment, ExcelNumberFormat, ExcelPatternType, ExcelReadingOrder, ExcelUnderline, ExcelVerticalAlignRun, ExcelVerticalAlignment, NS, type ParsedCellRef, REL_TYPES, Range, type SheetVisibility, StyleManager, WORKSHEET_DRAWING_REL_ID, Workbook, Worksheet, type XmlAttrs, XmlBuilder, type XmlElement, type ZipEntries, type ZipInput, buildDrawingXml, buildRelsXml, cellRefFromRowCol, columnLetter, columnNumber, decodeUtf8, encodeUtf8, escapeXml, formatNumberWithCode, fromOADate, getAttr, getElementsByTagName, isDateFormatCode, isDateFormatId, listEntries, parseCellRef, parseRangeRef, parseXml, readXmlEntry, requireXmlEntry, setBinaryEntry, setXmlEntry, toOADate, unzipXlsx, xml, zipXlsx };
+export { CONTENT_TYPES, Cell, type CellComment, type CellData, CellStyle, type CellValue, type ColorXmlAttrs, type DefinedName, DefinedNameManager, type DrawingDependentPart, type DrawingProvider, EXCEL_MAX_COLUMNS, EXCEL_MAX_ROWS, ExcelAlignment, ExcelBorder, ExcelBorderEdge, ExcelBorderStyle, ExcelColor, ExcelFill, ExcelFont, type ExcelFontOptions, ExcelHorizontalAlignment, ExcelNumberFormat, ExcelPatternType, ExcelReadingOrder, ExcelUnderline, ExcelVerticalAlignRun, ExcelVerticalAlignment, type FormulaRewriteResult, type Hyperlink, NS, type ParsedCellRef, REL_TYPES, Range, type RefShift, type SheetProtection, type SheetVisibility, type StructuralEditResult, StyleManager, WORKSHEET_DRAWING_REL_ID, Workbook, Worksheet, type XmlAttrs, XmlBuilder, type XmlElement, type ZipEntries, type ZipInput, buildDrawingXml, buildRelsXml, cellRefFromRowCol, columnLetter, columnNumber, decodeUtf8, decodeXmlEntities, encodeUtf8, escapeXml, formatDateCode, formatNumberWithCode, formatRangeRef, fromOADate, getAttr, getElementsByTagName, isDateFormatCode, isDateFormatId, listEntries, parseCellRef, parseRangeRef, parseXml, readXmlEntry, requireXmlEntry, setBinaryEntry, setXmlEntry, shiftFormulaRefs, shiftIndex, shiftRangeRef, shiftSpan, shiftSqref, toOADate, unzipXlsx, xml, zipXlsx };