@justybase/spreadsheet-tasks 3.1.1 → 3.2.0

package/dist/cjs/index.d.ts

@@ -9,7 +9,7 @@ declare class BigBuffer {
     ensureCapacity(size: number): void;
     private _ensureCapacity;
     private _flush;
-    write(buffer: Buffer$1): void;
+    write(buffer: Uint8Array): void;
     writeByte(val: number): void;
     writeUnsafeByte(val: number): void;
     writeInt32LE(val: number): void;
@@ -19,15 +19,117 @@ declare class BigBuffer {
     writeString(str: string): void;
     writeUtf16LE(str: string): void;
     getChunks(): Buffer$1[];
+    /** Overwrite a previously written 32-bit integer at an absolute offset. */
+    patchInt32LE(offset: number, value: number): boolean;
     reset(): void;
 }
 
-type PrimitiveCellValue = string | number | boolean | Date | bigint | null | undefined;
+/**
+ * An Excel error value (`#DIV/0!`, `#N/A`, ...). Strings are always text, so
+ * writing an error requires this marker; readers return the display text
+ * (`"#DIV/0!"`) for compatibility with plain value consumers.
+ */
+declare class ExcelError {
+    readonly code: string;
+    constructor(code: string);
+    toString(): string;
+}
+type PrimitiveCellValue = string | number | boolean | Date | bigint | ExcelError | null | undefined;
+/** RGB/ARGB hex (`'FF0000'`, `'#FF0000'`, `'FFFF0000'`) or an indexed/theme color. */
+type StyleColor = string | {
+    indexed: number;
+} | {
+    theme: number;
+    tint?: number;
+};
+type FontUnderline = 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
+interface FontStyle {
+    name?: string;
+    size?: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: FontUnderline | boolean;
+    strike?: boolean;
+    color?: StyleColor;
+    family?: number;
+    scheme?: 'major' | 'minor';
+    vertAlign?: 'baseline' | 'superscript' | 'subscript';
+    outline?: boolean;
+    shadow?: boolean;
+    condense?: boolean;
+    extend?: boolean;
+    charset?: number;
+}
+type PatternType = 'none' | 'solid' | 'mediumGray' | 'darkGray' | 'lightGray' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis' | 'gray125' | 'gray0625';
+interface FillStyle {
+    patternType?: PatternType;
+    fgColor?: StyleColor;
+    bgColor?: StyleColor;
+}
+type BorderLineStyle = 'thin' | 'medium' | 'dashed' | 'dotted' | 'thick' | 'double' | 'hair' | 'mediumDashed' | 'dashDot' | 'mediumDashDot' | 'dashDotDot' | 'mediumDashDotDot' | 'slantDashDot';
+interface BorderSide {
+    style?: BorderLineStyle;
+    color?: StyleColor;
+}
+interface BorderStyle {
+    top?: BorderSide;
+    bottom?: BorderSide;
+    left?: BorderSide;
+    right?: BorderSide;
+    diagonal?: BorderSide;
+    diagonalUp?: boolean;
+    diagonalDown?: boolean;
+    outline?: boolean;
+}
+interface AlignmentStyle {
+    horizontal?: 'general' | 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
+    vertical?: 'top' | 'center' | 'bottom' | 'justify' | 'distributed';
+    wrapText?: boolean;
+    shrinkToFit?: boolean;
+    indent?: number;
+    textRotation?: number;
+    justifyLastLine?: boolean;
+    readingOrder?: 0 | 1 | 2;
+}
+interface ProtectionStyle {
+    locked?: boolean;
+    hidden?: boolean;
+}
+/** Full cell style. Only the properties that are set are applied. */
+interface CellStyle {
+    numFmt?: string;
+    font?: FontStyle;
+    fill?: FillStyle;
+    border?: BorderStyle;
+    alignment?: AlignmentStyle;
+    protection?: ProtectionStyle;
+}
+interface StyledCell {
+    value: PrimitiveCellValue | RichText;
+    style: CellStyle;
+}
+/** A formula and an optional cached value. The formula text may start with `=`. */
+interface FormulaCell {
+    formula: string;
+    value?: PrimitiveCellValue;
+    style?: CellStyle;
+}
+interface RichTextRun {
+    text: string;
+    /** Run formatting; only font properties are used. */
+    style?: CellStyle;
+}
+/** Rich text split into formatting runs. */
+declare class RichText {
+    readonly runs: RichTextRun[];
+    constructor(runs: RichTextRun[]);
+    toString(): string;
+}
 interface FormattedCell {
     value: PrimitiveCellValue;
     format: string;
 }
-type CellValue = PrimitiveCellValue | FormattedCell;
+type CellValue = PrimitiveCellValue | RichText | FormattedCell | StyledCell | FormulaCell;
 /** Built-in Excel number-format strings for {@link FormattedCell}. */
 declare const F: {
     THOUSANDS_SEP: string;
@@ -56,7 +158,18 @@ declare const F: {
     TIME_MS: string;
 };
 declare function isFormattedCell(val: unknown): val is FormattedCell;
-declare function unwrapCell(val: CellValue): PrimitiveCellValue;
+declare function isRichText(val: unknown): val is RichText;
+declare function isStyledCell(val: unknown): val is StyledCell;
+declare function isFormulaCell(val: unknown): val is FormulaCell;
+/**
+ * Style carried by a cell. `FormattedCell` maps to `{ numFmt }`; every other
+ * value has no style.
+ */
+declare function getCellStyle(val: CellValue): CellStyle | null;
+/** Style with the legacy `FormattedCell.format` merged into `numFmt`. */
+declare function mergeCellStyle(base: CellStyle | null | undefined, extra: CellStyle | null | undefined): CellStyle | null;
+declare function getFormula(val: CellValue): string | null;
+declare function unwrapCell(val: CellValue): PrimitiveCellValue | RichText;
 declare function getFormat(val: CellValue): string | null;
 
 /**
@@ -145,59 +258,136 @@ declare class XlsbReader extends ExcelReaderAbstract {
     private sheetNames;
     private sheets;
     private _currentSheetIndex;
-    private _reader;
+    private _sheetBuffer;
+    private _pos;
     private _currentRow;
+    private _currentStyles;
     private _pendingRowIndex;
     private _nextExpectedRow;
     private _eof;
+    private readonly _rkScratch;
     xfIdToNumFmtId: number[];
     customDateFormats: Set<number> | null;
+    /** One flag per xf id: 1 when its number format is a date. */
+    private _dateXf;
+    private _xfStyles;
     constructor();
     open(path: string, readSharedStrings?: boolean): Promise<void>;
-    private _readSharedStrings;
-    private _readStyles;
+    /** Open a workbook already held in memory (ZIP bytes). */
+    openBuffer(buffer: Buffer, readSharedStrings?: boolean): Promise<void>;
+    private _resetState;
+    private _load;
+    private _buildDateXf;
+    private _isDateStyle;
     getSheetNames(): string[];
     selectSheet(nameOrIndex: string | number): Promise<void>;
     nextResult(): Promise<boolean>;
     read(): Promise<boolean>;
+    /**
+     * Synchronous row access for batch consumers. Returns the internal row
+     * array, valid until the next call; `readAll`/`rows` return copies.
+     * Select a sheet (or call `read()` once) before using it.
+     */
+    readRow(): CellValue[] | null;
+    /** Collect every remaining row of the current sheet. */
+    readAll(): Promise<CellValue[][]>;
+    /** Stream every remaining row of the current sheet. */
+    rows(): AsyncGenerator<CellValue[]>;
+    private _readNext;
+    private _finishEof;
+    private _numberValue;
+    private _doubleValue;
+    private _asDate;
     private _initSheet;
+    /** Style of the current row cell at column `i`, or null for the default style. */
+    getStyle(i: number): CellStyle | null;
     getValue(i: number): CellValue;
 }
 
 declare class XlsxReader extends ExcelReaderAbstract {
     private zipfile;
+    /** Keeps the yauzl source buffer alive when opened from memory. */
+    private _zipBuffer;
     private sharedStrings;
     private sheetNames;
     private sheets;
     private entries;
     private _currentSheetIndex;
+    /** Buffer-based fast path for the current sheet. */
+    private _sheetBuffer;
+    /** String fallback for unusual markup (prefixed tags, etc.). */
     private _sheetXml;
     private _xmlPos;
-    /** End of the sheetData element; row tags must not be searched past it. */
     private _xmlEnd;
     private _currentRow;
+    private _currentFormulas;
+    private _currentStyleIndices;
+    private _currentSharedIndices;
+    private _currentRichTexts;
     private _expectedRowNum;
     private _pendingEmptyCount;
+    private _xfStyles;
+    private _sharedRichTexts;
     xfIdToNumFmtId: number[];
     customDateFormats: Set<number>;
+    /** One flag per xf id: 1 when the style's number format is a date. */
+    private _dateXf;
     constructor();
     open(path: string, readSharedStrings?: boolean): Promise<void>;
+    /** Open a workbook already held in memory (ZIP bytes). */
+    openBuffer(buffer: Buffer, readSharedStrings?: boolean): Promise<void>;
+    private _openWith;
+    private _resetState;
+    private _loadWorkbookStructure;
     close(): Promise<void>;
     private _readZipEntryContent;
+    /**
+     * Read one ZIP member into a Buffer. The uncompressed size from the
+     * central directory is used to allocate once instead of concatenating
+     * stream chunks.
+     */
+    private _readZipEntryBuffer;
     private _parseSharedStrings;
     private _parseStyles;
+    private _isDateNumFmt;
+    private _isDateStyle;
     getSheetNames(): string[];
+    /** Advance to the next row. Always use `await`. */
     read(): Promise<boolean>;
+    /**
+     * Synchronous row access for batch consumers. Returns the internal row
+     * array, valid until the next call; `readAll`/`rows` return copies.
+     * Select a sheet (or call `read()` once) before using it.
+     */
+    readRow(): CellValue[] | null;
+    /** Collect every remaining row of the current sheet. */
+    readAll(): Promise<CellValue[][]>;
+    /** Stream every remaining row of the current sheet. */
+    rows(): AsyncGenerator<CellValue[]>;
     selectSheet(nameOrIndex: string | number): Promise<void>;
     nextResult(): Promise<boolean>;
     private _initSheet;
-    private _readNextRow;
-    /**
-     * Find the next `<row …>` start, ignoring similarly named elements such as
-     * `<rowBreaks>` that follow `</sheetData>`.
-     */
-    private _findRowTagStart;
-    private _parseRowByIndex;
+    /** Set `_xmlPos/_xmlEnd` for the buffer fast path; false when unsupported. */
+    private _initBufferSheet;
+    private _initStringSheetRange;
+    private _readNextRowBuffer;
+    private _findRowTagStartBuffer;
+    private _parseRowBuffer;
+    /** Concatenated `<t>` runs of an inline-string cell body. */
+    private _decodeInlineBuffer;
+    private _extractFormulaBuffer;
+    private _decodeCellValue;
+    private _readNextRowString;
+    private _findRowTagStartString;
+    private _parseRowString;
+    private _extractFormulaString;
+    /** Style of the current row cell at column `i`, or null for the default style. */
+    getStyle(i: number): CellStyle | null;
+    /** Formula text of the current row cell at column `i`, or null. */
+    getFormula(i: number): string | null;
+    /** Rich-text runs of the current row cell at column `i`, or null. */
+    getRichText(i: number): RichText | null;
+    private _resetCurrentRow;
     getValue(i: number): CellValue;
 }
 
@@ -212,6 +402,128 @@ declare class ReaderFactory {
     static create(filePath: string): ExcelReaderAbstract;
 }
 
+/** Sink used by the XLSX core; XML is always written as UTF-8 text. */
+interface TextByteSink {
+    writeString(str: string): void;
+}
+
+/**
+ * Shared XLSX package serialization.
+ *
+ * Everything in this module is pure string/byte generation with no Node or
+ * browser imports: the Node writer and the browser writer both call it, which
+ * is what keeps their unpacked parts identical.
+ */
+
+type SharedStringValue = string | RichText;
+interface HyperlinkSpec {
+    /** Cell reference, e.g. `A1`. */
+    ref: string;
+    /** External URL (needs a worksheet relationship). */
+    target?: string;
+    /** Internal location, e.g. `Other!A1`. */
+    location?: string;
+    tooltip?: string;
+    display?: string;
+}
+interface DataValidationSpec {
+    sqref: string;
+    type: 'whole' | 'decimal' | 'list' | 'date' | 'time' | 'textLength' | 'custom';
+    operator?: 'between' | 'notBetween' | 'equal' | 'notEqual' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual';
+    formula1?: string;
+    formula2?: string;
+    /** For `type: 'list'`: literal values, emitted as a quoted comma list. */
+    values?: string[];
+    allowBlank?: boolean;
+    showDropdown?: boolean;
+    showInputMessage?: boolean;
+    promptTitle?: string;
+    prompt?: string;
+    showErrorMessage?: boolean;
+    errorTitle?: string;
+    error?: string;
+    errorStyle?: 'stop' | 'warning' | 'information';
+}
+type ConditionalFormatRule = {
+    type: 'cellIs';
+    operator: 'between' | 'notBetween' | 'equal' | 'notEqual' | 'lessThan' | 'lessThanOrEqual' | 'greaterThan' | 'greaterThanOrEqual';
+    formula: string[];
+    style?: CellStyle;
+    stopIfTrue?: boolean;
+} | {
+    type: 'expression';
+    formula: string;
+    style?: CellStyle;
+    stopIfTrue?: boolean;
+} | {
+    type: 'colorScale';
+    cfvo: Array<{
+        type: 'min' | 'max' | 'num' | 'percent' | 'percentile' | 'formula';
+        value?: string;
+    }>;
+    colors: string[];
+} | {
+    type: 'dataBar';
+    cfvo: Array<{
+        type: 'min' | 'max' | 'num' | 'percent' | 'percentile' | 'formula';
+        value?: string;
+    }>;
+    color: string;
+    showValue?: boolean;
+} | {
+    type: 'iconSet';
+    iconSet?: '3Arrows' | '3ArrowsGray' | '3Flags' | '3TrafficLights1' | '3TrafficLights2' | '3Signs' | '3Symbols' | '3Symbols2' | '4Arrows' | '4ArrowsGray' | '4RedToBlack' | '4Rating' | '4TrafficLights' | '5Arrows' | '5ArrowsGray' | '5Rating' | '5Quarters';
+    cfvo?: Array<{
+        type: 'percent' | 'num' | 'percentile';
+        value?: string;
+    }>;
+    showValue?: boolean;
+    reverse?: boolean;
+} | {
+    type: 'top10';
+    rank?: number;
+    percent?: boolean;
+    bottom?: boolean;
+    style?: CellStyle;
+} | {
+    type: 'duplicateValues' | 'uniqueValues';
+    style?: CellStyle;
+} | {
+    type: 'containsText' | 'notContainsText' | 'beginsWith' | 'endsWith';
+    text: string;
+    style?: CellStyle;
+};
+interface ConditionalFormatSpec {
+    sqref: string;
+    rules: ConditionalFormatRule[];
+}
+interface CommentSpec {
+    ref: string;
+    text: string;
+    author?: string;
+    /** Server-side comment GUID, when the comment came from another system. */
+    guid?: string;
+}
+interface XlsxSheetFeatures {
+    merges?: string[];
+    hyperlinks?: HyperlinkSpec[];
+    dataValidations?: DataValidationSpec[];
+    conditionalFormats?: ConditionalFormatSpec[];
+    comments?: CommentSpec[];
+}
+
+/** Options accepted by the XLSB streaming and batch sheet APIs. */
+interface XlsbSheetOptions extends XlsxSheetFeatures {
+    hidden?: boolean;
+    doAutofilter?: boolean;
+    sampleRows?: unknown[][];
+    /** Conservative autofit from headers and the first rows (default true). */
+    autofit?: boolean;
+    /** Rows measured by autofit (default 200); 0 measures only headers/samples. */
+    autofitRows?: number;
+    /** Fixed widths in Excel character units; skips autofit when provided. */
+    columnWidths?: Array<number | null | undefined>;
+}
 /**
  * High-performance XLSB (Excel Binary Workbook) writer.
  * Prefer this format for large datasets — typically faster and smaller than XLSX.
@@ -230,9 +542,8 @@ declare class XlsbWriter {
     private sstCntAll;
     private _autofilterIsOn;
     private _oaEpoch;
-    private _nextFmtId;
-    private _nextXfIdx;
-    private _stFmtRecords;
+    private readonly _useSharedStrings;
+    private readonly _styles;
     /** Worksheet binary template (BrtBeginSheet … dimension / views / cols placeholders). */
     private _sheet1Bytes;
     private _workbookBinStart;
@@ -251,6 +562,11 @@ declare class XlsbWriter {
     private _magicFilterExcel2016Fix1;
     private _magicFilterExcel2016Fix2;
     private readonly stream;
+    private _streamPending;
+    private _streamHeadFlushed;
+    private _streamHasHeaders;
+    private _streamDataRows;
+    private _streamAutofitRows;
     /**
      * @param filePath Destination `.xlsb` path on disk.
      */
@@ -260,20 +576,27 @@ declare class XlsbWriter {
      */
     constructor(filePath: string, options?: {
         compressionLevel?: number;
+        useSharedStrings?: boolean;
     });
     /** @deprecated Internal; kept for unit-test access. Prefer sanitizeSheetName(). */
     private _sanitizeSheetName;
-    private _registerFormat;
-    private static _buildBrtRecord;
-    private static _encodeVlq;
-    private static _buildStFmtRecord;
-    private static _buildXfRecord;
     private _buildStylesBin;
     /**
-     * Register a worksheet (metadata only). Prefer `writeSheet` / `startSheet` for data.
-     * @param sheetName Display name (sanitized to Excel rules)
-     * @param hidden Whether the sheet is hidden in Excel
+     * Resolve column widths: explicit `columnWidths` win, otherwise plain
+     * autofit from headers and up to 200 sample rows, capped at 200.
      */
+    private _resolveColumnWidths;
+    /** Store supported sheet features; reject the ones XLSB does not emit yet. */
+    private _applySheetFeatures;
+    /** Merged cells, validations and hyperlinks go after the autoFilter. */
+    private _writeFeatureRecords;
+    /** Write one cell using the current style registry and formula compiler. */
+    private _writeCell;
+    /**
+         * Register a worksheet (metadata only). Prefer `writeSheet` / `startSheet` for data.
+         * @param sheetName Display name (sanitized to Excel rules)
+         * @param hidden Whether the sheet is hidden in Excel
+         */
     addSheet(sheetName: string, hidden?: boolean): void;
     /**
      * Start a new sheet in streaming mode. Call writeRow() for each row, then endSheet() when done.
@@ -282,11 +605,10 @@ declare class XlsbWriter {
      * @param headers Optional header row
      * @param options Optional settings (hidden, doAutofilter)
      */
-    startSheet(sheetName: string, columnCount: number, headers?: string[], options?: {
-        hidden?: boolean;
-        doAutofilter?: boolean;
-        sampleRows?: unknown[][];
-    }): void;
+    startSheet(sheetName: string, columnCount: number, headers?: string[], options?: XlsbSheetOptions): void;
+    /** Write the delayed sheet head and everything buffered before it. */
+    private _flushStreamHead;
+    private _writeStreamRow;
     /**
      * Write a single row in streaming mode. Must be called between startSheet() and endSheet().
      * @param row Array of cell values
@@ -299,17 +621,19 @@ declare class XlsbWriter {
     endSheet(): void;
     /**
      * Write an entire sheet in one call (batch mode).
-     * @param rows Data rows (`CellValue` cells; null/undefined = blank)
-     * @param headers Optional header row (bold + frozen + autofilter when enabled)
-     * @param doAutofilter Enable autofilter when headers are present (default true)
+     *
+     * The third argument keeps the legacy `doAutofilter` boolean; pass
+     * {@link XlsbSheetOptions} instead to add merges, hyperlinks, validations
+     * and width control.
      */
-    writeSheet(rows: CellValue[][], headers?: string[] | null, doAutofilter?: boolean): void;
+    writeSheet(rows: CellValue[][], headers?: string[] | null, doAutofilterOrOptions?: boolean | XlsbSheetOptions, extraOptions?: XlsbSheetOptions): void;
     createRowHeader(bigBuf: BigBuffer, rowNumber: number, startCol: number, endCol: number): void;
     writeRkNumberInteger(bigBuf: BigBuffer, val: number, colNum: number, styleNum?: number): void;
     writeDouble(bigBuf: BigBuffer, val: number, colNum: number, styleNum?: number): void;
-    writeBool(bigBuf: BigBuffer, val: boolean, colNum: number): void;
+    writeBool(bigBuf: BigBuffer, val: boolean, colNum: number, styleNum?: number): void;
+    /** BrtCellError: column, style (24-bit) and the BIFF12 error code. */
+    writeError(bigBuf: BigBuffer, code: string, colNum: number, styleNum?: number): void;
     writeDateTime(bigBuf: BigBuffer, date: Date, colNum: number): void;
-    private _getDateWidth;
     writeString(bigBuf: BigBuffer, val: string, colNum: number, bolded?: boolean, styleOverride?: number): void;
     private saveSst;
     private _writeFilterDefinedName;
@@ -320,6 +644,17 @@ declare class XlsbWriter {
     finalize(): Promise<void>;
 }
 
+interface XlsxSheetOptions extends XlsxSheetFeatures {
+    hidden?: boolean;
+    doAutofilter?: boolean;
+    sampleRows?: unknown[][];
+    /** Conservative autofit from headers and the first rows (default true). */
+    autofit?: boolean;
+    /** Rows measured by autofit (default 200); 0 measures only headers/samples. */
+    autofitRows?: number;
+    /** Fixed widths in Excel character units; skips autofit when provided. */
+    columnWidths?: Array<number | null | undefined>;
+}
 /**
  * XLSX (Office Open XML) writer with streaming ZIP output.
  */
@@ -334,15 +669,18 @@ declare class XlsxWriter {
     private sheetList;
     private sstArray;
     private sstMap;
+    private readonly _styles;
     private sstCntAll;
     private _autofilterIsOn;
     private _oaEpoch;
-    private _formatRegistry;
-    private _formatXfMap;
-    private _nextNumfmtId;
-    private _nextXfIndex;
+    private readonly _useSharedStrings;
     private readonly stream;
     private currentColLetters;
+    private _streamPending;
+    private _streamHeadFlushed;
+    private _streamHasHeaders;
+    private _streamDataRows;
+    private _streamAutofitRows;
     /**
      * @param filePath Destination `.xlsx` path on disk.
      */
@@ -352,39 +690,47 @@ declare class XlsxWriter {
      */
     constructor(filePath: string, options?: {
         compressionLevel?: number;
+        useSharedStrings?: boolean;
     });
     private _getColumnLetter;
     /** @deprecated Internal; kept for unit-test access. Prefer sanitizeSheetName(). */
     private _sanitizeSheetName;
-    private _escapeSheetNameForXml;
-    private _formatSheetNameForFormula;
     /**
      * Register a worksheet (metadata only). Prefer `writeSheet` / `startSheet` for data.
      */
     addSheet(sheetName: string, hidden?: boolean): void;
-    private _needsEscape;
-    private _escape;
     /**
-     * Start streaming a sheet. Call `writeRow` for each row, then `endSheet`.
+     * Resolve column widths with the conservative autofit: header text and up
+     * to 200 sample rows, calibrated character costs plus padding, capped at
+     * 200. Fixed `columnWidths` win over autofit.
      */
-    startSheet(sheetName: string, columnCount: number, headers?: string[], options?: {
-        hidden?: boolean;
-        doAutofilter?: boolean;
-        sampleRows?: unknown[][];
-    }): void;
+    private _resolveColumnWidths;
+    /** Store sheet features and build the worksheet rels/comments parts. */
+    private _applySheetFeatures;
+    private _appendExtraParts;
+    startSheet(sheetName: string, columnCount: number, headers?: string[], options?: XlsxSheetOptions): void;
+    /** Write the delayed sheet head and everything buffered before it. */
+    private _flushStreamHead;
+    private _writeStreamRow;
     /** Write one data row in streaming mode. */
     writeRow(row: CellValue[]): void;
     /** Finish the current streaming sheet and append it to the archive. */
     endSheet(): void;
     /**
      * Write an entire sheet in one call (batch mode).
+     *
+     * The third argument keeps the legacy `doAutofilter` boolean; pass
+     * {@link XlsxSheetOptions} instead to add features (merges, hyperlinks,
+     * validations, conditional formats, comments) and width control.
      */
-    writeSheet(rows: CellValue[][], headers?: string[] | null, doAutofilter?: boolean): void;
+    writeSheet(rows: CellValue[][], headers?: string[] | null, doAutofilterOrOptions?: boolean | XlsxSheetOptions, extraOptions?: XlsxSheetOptions): void;
     /** `ref` is the cell's `r` attribute from `cellRefAttr`, or '' when omitted. */
     private _writeStringCell;
-    private _registerFormat;
+    writeStringCell(bigBuf: TextByteSink, val: SharedStringValue, ref: string, styleOverride?: number): void;
+    registerStyle(style: CellStyle): number;
+    registerFormat(fmtString: string): number;
+    toOaDate(date: Date): number;
     private _toOADate;
-    private _getDateWidth;
     /** Finalize the ZIP package and close the output stream. */
     finalize(): Promise<void>;
     private _writeSharedStrings;
@@ -675,18 +1021,63 @@ declare function assertRowFitsColumns(kind: string, length: number, columnCount:
 declare function assertRowCount(totalRows: number): void;
 /** Create column-width scratch array filled with -1 (unknown). */
 declare function initColWidths(columnCount: number): number[];
+/** Excel's default column width in characters (Calibri 11, 96 DPI). */
+declare const DEFAULT_COLUMN_WIDTH = 8.43;
+/** Hard cap for automatic column widths, in Excel character units. */
+declare const MAX_AUTOFIT_WIDTH = 200;
+/**
+ * Excel stores the column width plus the 5-pixel cell padding, i.e. 5/7 of a
+ * character in Calibri 11 at 96 DPI. Automatic widths include it; explicit
+ * `columnWidths` are written unchanged.
+ */
+declare const COLUMN_WIDTH_PADDING: number;
+/** Room Excel reserves for the autofilter drop-down button, in characters. */
+declare const AUTOFILTER_BUTTON_WIDTH = 2.4;
+/**
+ * Rows measured by automatic widths. xlspy defaults to 1000; 200 keeps the
+ * width estimate representative while cutting the write-time cost and the
+ * streaming buffer (measured widths are dominated by the header and the first
+ * rows anyway).
+ */
+declare const AUTOFIT_SAMPLE_ROWS = 200;
+/** Validate the `autofitRows` option (undefined: 200). */
+declare function resolveAutofitRows(value?: number): number;
+/**
+ * Conservative displayed-width units for `text`, calibrated so that the
+ * resulting autofit width is not below xlspy's for the same text and font
+ * (up to the 200-character cap). CJK/fullwidth characters count as 2.2 units,
+ * emoji as 3.4, combining marks and control characters as zero. The optional
+ * `fontName` selects the narrow (Calibri-like) or worst-case cost table.
+ */
+declare function textDisplayUnits(text: string, fontName?: string | null): number;
+/** Conservative autofit width in Excel character units (before file padding). */
+declare function autofitWidth(text: string, font?: FontStyle | null, indentChars?: number): number;
+/** Autofit width as stored in the file: displayed width plus cell padding. */
+declare function autofitFileWidth(text: string, font?: FontStyle | null, indentChars?: number): number;
+/** Options for {@link applyHeaderWidths}. */
+interface HeaderWidthOptions {
+    /** Header cells use a bold font. */
+    bold?: boolean;
+    /** Add room for the autofilter drop-down button. */
+    filterButton?: boolean;
+}
 /** Apply autofit widths from header labels. */
-declare function applyHeaderWidths(colWidths: number[], headers: string[], columnCount: number): void;
+declare function applyHeaderWidths(colWidths: number[], headers: string[], columnCount: number, options?: HeaderWidthOptions): void;
 /**
  * Sample up to `sampleLimit` rows and expand column widths (autofit).
- * Skips null/undefined cells; Dates use a fixed display length of 20.
+ * Skips null/undefined cells; understands styled, formula and rich-text cells.
  */
 declare function updateColWidthsFromRows(colWidths: number[], rows: unknown[][], sampleLimit?: number): void;
 /**
- * Resolve a stored autofit width to the value written into the file.
- * XLSB uses floored integers; XLSX keeps the float.
+ * Resolve a stored width to the value written into the file. The fallback is
+ * Excel's default width plus cell padding, matching the old 10-character
+ * default while staying close to xlspy/Excel.
  */
 declare function defaultColWidth(width: number, floor?: boolean): number;
+/** Validate one explicit column width (xlspy accepts 0.5..255 characters). */
+declare function assertColumnWidth(width: number, index: number): number;
+/** Compact XML attribute value for an XLSX column width (2 decimals max). */
+declare function formatColumnWidth(width: number): string;
 
 /**
  * Shared streaming-sheet session state for Node writers.
@@ -750,5 +1141,13 @@ declare function trimTrailingEmptyRows<T>(rows: T[][]): T[][];
  * Phonetic `<rPh>` blocks are skipped (xlspy parity) and self-closing `<si/>` yields "".
  */
 declare function parseSharedStringsXml(xml: string): string[];
+/**
+ * Buffer-based equivalent of {@link parseSharedStringsXml} for the common
+ * Excel markup: unprefixed `<si>`/`<t>`, plain or rich runs, self-closing
+ * `<si/>`, and `<rPh>` blocks that must be skipped. Falls back to the regex
+ * parser for anything it does not recognise (CDATA, comments, prefixes,
+ * attributes on `<si>`).
+ */
+declare function parseSharedStringsBuffer(buf: Buffer): string[];
 
-export { BiffReaderWriter, BigBuffer, type CellValue, type ExcelConversionOptions, ExcelReaderAbstract, F, type FormattedCell, INVALID_SHEET_NAME_CHARS, MAX_CELL_CHARS, MAX_COLS, MAX_ROWS, type PrimitiveCellValue, ReaderFactory, type ReplaceSheetDataOptions$1 as ReplaceSheetDataOptions, type RowSource$1 as RowSource, StreamingSheetState, XlsbReader, type ReplaceSheetDataOptions as XlsbReplaceSheetDataOptions, XlsbUpdater, XlsbWriter, XlsxUpdater as XlsmUpdater, XlsxReader, XlsxUpdater, XlsxWriter, applyHeaderWidths, assertCellTextLength, assertColumnCount, assertRowCount, assertRowFitsColumns, columnIndexToLetter, columnLetterToIndex, convertXlsbToXlsx, convertXlsxToXlsb, defaultColWidth, escapeXlsxText, escapeXmlText, getFormat, initColWidths, isFormattedCell, parseSharedStringsXml, parseTagAttributes, resolveRelTarget, sanitizeSheetName, trimTrailingEmptyRows, unescapeXml, unescapeXmlText, unwrapCell, updateColWidthsFromRows };
+export { AUTOFILTER_BUTTON_WIDTH, AUTOFIT_SAMPLE_ROWS, type AlignmentStyle, BiffReaderWriter, BigBuffer, type BorderLineStyle, type BorderSide, type BorderStyle, COLUMN_WIDTH_PADDING, type CellStyle, type CellValue, type CommentSpec, type ConditionalFormatRule, type ConditionalFormatSpec, DEFAULT_COLUMN_WIDTH, type DataValidationSpec, type ExcelConversionOptions, ExcelError, ExcelReaderAbstract, F, type FillStyle, type FontStyle, type FontUnderline, type FormattedCell, type FormulaCell, type HeaderWidthOptions, type HyperlinkSpec, INVALID_SHEET_NAME_CHARS, MAX_AUTOFIT_WIDTH, MAX_CELL_CHARS, MAX_COLS, MAX_ROWS, type PatternType, type PrimitiveCellValue, type ProtectionStyle, ReaderFactory, type ReplaceSheetDataOptions$1 as ReplaceSheetDataOptions, RichText, type RichTextRun, type RowSource$1 as RowSource, StreamingSheetState, type StyleColor, type StyledCell, XlsbReader, type ReplaceSheetDataOptions as XlsbReplaceSheetDataOptions, type XlsbSheetOptions, XlsbUpdater, XlsbWriter, XlsxUpdater as XlsmUpdater, XlsxReader, type XlsxSheetFeatures, type XlsxSheetOptions, XlsxUpdater, XlsxWriter, applyHeaderWidths, assertCellTextLength, assertColumnCount, assertColumnWidth, assertRowCount, assertRowFitsColumns, autofitFileWidth, autofitWidth, columnIndexToLetter, columnLetterToIndex, convertXlsbToXlsx, convertXlsxToXlsb, defaultColWidth, escapeXlsxText, escapeXmlText, formatColumnWidth, getCellStyle, getFormat, getFormula, initColWidths, isFormattedCell, isFormulaCell, isRichText, isStyledCell, mergeCellStyle, parseSharedStringsBuffer, parseSharedStringsXml, parseTagAttributes, resolveAutofitRows, resolveRelTarget, sanitizeSheetName, textDisplayUnits, trimTrailingEmptyRows, unescapeXml, unescapeXmlText, unwrapCell, updateColWidthsFromRows };