@justybase/spreadsheet-tasks 2.0.0 → 2.1.1

package/dist/cjs/index.d.ts

@@ -167,7 +167,6 @@ declare class XlsxReader extends ExcelReaderAbstract {
     open(path: string, readSharedStrings?: boolean): Promise<void>;
     close(): Promise<void>;
     private _readZipEntryContent;
-    private _unescapeXml;
     private _parseSharedStrings;
     private _parseStyles;
     getSheetNames(): string[];
@@ -175,7 +174,6 @@ declare class XlsxReader extends ExcelReaderAbstract {
     private _initSheet;
     private _readNextRow;
     private _parseRowByIndex;
-    private _columnLetterToIndex;
     getValue(i: number): CellValue;
 }
 
@@ -351,6 +349,178 @@ declare class XlsxWriter {
     private _writeRels;
 }
 
+/**
+ * Options for {@link XlsxUpdater.replaceSheetData}.
+ */
+interface ReplaceSheetDataOptions$1 {
+    /**
+     * Optional header row written into row 1 of the target sheet.
+     * When omitted, row 1 is filled with the data rows.
+     */
+    headers?: string[];
+    /**
+     * Style strategy for the new cells:
+     * - `'inherit'` (default): reuse the dominant cell style of each column from the
+     *   existing data (and the original header style for row 1), so date/number
+     *   formatting of the sheet is preserved. Falls back to General (0).
+     * - `'general'`: all new cells use style 0 (General).
+     */
+    styleFallback?: 'inherit' | 'general';
+}
+/**
+ * Update the data of a worksheet inside an existing XLSX file without rebuilding
+ * the workbook. Everything outside the target sheet's cell data — pivot tables
+ * and their caches, other sheets, styles, themes, defined names — is preserved
+ * byte-for-byte. This makes it possible to refresh a data sheet that other
+ * Excel features (pivot tables, charts, formulas) are wired to.
+ *
+ * ```ts
+ * const updater = new XlsxUpdater('report.xlsx');
+ * updater.replaceSheetData('data1', rows, { headers: ['ID', 'NAME', 'AMOUNT'] });
+ * updater.save('report_new.xlsx'); // or updater.save() to overwrite in place
+ * ```
+ */
+declare class XlsxUpdater {
+    private readonly zip;
+    private readonly sourcePath;
+    private sheetNameToPath;
+    private pivotCacheDefs;
+    private pivotTableDefPaths;
+    private sharedStringsXml;
+    private sharedStringsValues;
+    private sharedStringsOriginalLength;
+    private sharedStringsCount;
+    private stringIndexMap;
+    private readonly _oaEpoch;
+    /**
+     * @param path Path to an existing `.xlsx` file.
+     */
+    constructor(path: string);
+    /** Worksheet names in workbook order. */
+    getSheetNames(): string[];
+    /**
+     * Clear the entire cell data of the target sheet and write new rows in its place.
+     * All other parts of the workbook (pivot tables, other sheets, styles, …) are preserved.
+     *
+     * @param sheetName Name of the worksheet to replace.
+     * @param rows New data rows (`CellValue` cells; null/undefined = blank).
+     * @param options See {@link ReplaceSheetDataOptions}.
+     */
+    replaceSheetData(sheetName: string, rows: CellValue[][], options?: ReplaceSheetDataOptions$1): void;
+    /**
+     * Write the updated workbook to disk.
+     * @param outputPath Destination path; defaults to the source file (overwrites in place).
+     */
+    save(outputPath?: string): void;
+    /** The updated workbook as an in-memory ZIP buffer. */
+    toBuffer(): Buffer;
+    private _loadWorkbookStructure;
+    private _ensureSharedStringsLoaded;
+    private _commitSharedStrings;
+    private _collectExistingStyles;
+    private _findDateStyleIndex;
+    private _buildSheetData;
+    private _valueCell;
+    private _stringCell;
+    private _patchSheetXml;
+    private _updatePivotCaches;
+    private _addRefreshOnLoadToPivotTables;
+}
+
+/**
+ * Options for {@link XlsbUpdater.replaceSheetData}.
+ */
+interface ReplaceSheetDataOptions {
+    /**
+     * Optional header row written into row 1 of the target sheet.
+     * When omitted, row 1 is filled with the data rows.
+     */
+    headers?: string[];
+    /**
+     * Style strategy for the new cells:
+     * - `'inherit'` (default): reuse the dominant cell style (xf) of each column from the
+     *   existing data (and the original header style for row 1), so date/number
+     *   formatting of the sheet is preserved. Falls back to General (0).
+     * - `'general'`: all new cells use xf 0 (General).
+     */
+    styleFallback?: 'inherit' | 'general';
+}
+/**
+ * Update the data of a worksheet inside an existing XLSB file without rebuilding
+ * the workbook. Everything outside the target sheet's rows — pivot tables and
+ * their caches, other sheets, styles, column widths, views — is preserved.
+ * This makes it possible to refresh a data sheet that pivot tables are wired to.
+ *
+ * ```ts
+ * const updater = new XlsbUpdater('report.xlsb');
+ * updater.replaceSheetData('data1', rows, { headers: ['ID', 'NAME', 'AMOUNT'] });
+ * updater.save('report_new.xlsb'); // or updater.save() to overwrite in place
+ * ```
+ */
+declare class XlsbUpdater {
+    private readonly zip;
+    private readonly sourcePath;
+    private sheetNameToPath;
+    private pivotCacheDefPaths;
+    private sharedStringsBuf;
+    private sharedStringsValues;
+    private sharedStringsTotal;
+    private sharedStringsUnique;
+    private sharedStringsEndSst;
+    private stringIndexMap;
+    private readonly _oaEpoch;
+    /**
+     * @param path Path to an existing `.xlsb` file.
+     */
+    constructor(path: string);
+    /** Worksheet names in workbook order. */
+    getSheetNames(): string[];
+    /**
+     * Clear the entire cell data of the target sheet and write new rows in its place.
+     * All other parts of the workbook (pivot tables, other sheets, styles, …) are preserved.
+     *
+     * @param sheetName Name of the worksheet to replace.
+     * @param rows New data rows (`CellValue` cells; null/undefined = blank).
+     * @param options See {@link ReplaceSheetDataOptions}.
+     */
+    replaceSheetData(sheetName: string, rows: CellValue[][], options?: ReplaceSheetDataOptions): void;
+    /**
+     * Write the updated workbook to disk.
+     * @param outputPath Destination path; defaults to the source file (overwrites in place).
+     */
+    save(outputPath?: string): void;
+    /** The updated workbook as an in-memory ZIP buffer. */
+    toBuffer(): Buffer;
+    private _loadWorkbookStructure;
+    private _appendCount;
+    private _ensureSharedStringsLoaded;
+    private _commitSharedStrings;
+    private _collectStyles;
+    private _findDateXf;
+    private _buildRows;
+    private _valueCellBytes;
+    private _stringCellBytes;
+    private _findRowsRegion;
+    /**
+     * Keep the sheet dimension record (0x98) in sync with the new data.
+     * Excel uses its rwLast (payload offset 24) and colLast (payload offset 32)
+     * fields to read the full row range; stale values make the last written row
+     * invisible to Excel (and drop it from pivot refreshes).
+     */
+    private _patchDimension;
+    private _patchPivotCaches;
+}
+
+/** Options for an Excel format conversion. */
+interface ExcelConversionOptions {
+    /** Allow replacing an existing destination file. Defaults to false. */
+    overwrite?: boolean;
+}
+/** Convert an Excel Binary Workbook (.xlsb) to an Open XML Workbook (.xlsx). */
+declare function convertXlsbToXlsx(inputPath: string, outputPath: string, options?: ExcelConversionOptions): Promise<void>;
+/** Convert an Open XML Workbook (.xlsx) to an Excel Binary Workbook (.xlsb). */
+declare function convertXlsxToXlsb(inputPath: string, outputPath: string, options?: ExcelConversionOptions): Promise<void>;
+
 /** Excel sheet name characters that must be replaced. */
 declare const INVALID_SHEET_NAME_CHARS: RegExp;
 /**
@@ -396,4 +566,4 @@ declare class StreamingSheetState {
     end(): void;
 }
 
-export { BiffReaderWriter, BigBuffer, type CellValue, ExcelReaderAbstract, F, type FormattedCell, INVALID_SHEET_NAME_CHARS, type PrimitiveCellValue, ReaderFactory, StreamingSheetState, XlsbReader, XlsbWriter, XlsxReader, XlsxWriter, applyHeaderWidths, defaultColWidth, getFormat, initColWidths, isFormattedCell, sanitizeSheetName, unwrapCell, updateColWidthsFromRows };
+export { BiffReaderWriter, BigBuffer, type CellValue, type ExcelConversionOptions, ExcelReaderAbstract, F, type FormattedCell, INVALID_SHEET_NAME_CHARS, type PrimitiveCellValue, ReaderFactory, type ReplaceSheetDataOptions$1 as ReplaceSheetDataOptions, StreamingSheetState, XlsbReader, type ReplaceSheetDataOptions as XlsbReplaceSheetDataOptions, XlsbUpdater, XlsbWriter, XlsxReader, XlsxUpdater, XlsxWriter, applyHeaderWidths, convertXlsbToXlsx, convertXlsxToXlsb, defaultColWidth, getFormat, initColWidths, isFormattedCell, sanitizeSheetName, unwrapCell, updateColWidthsFromRows };