@cj-tech-master/excelts 1.4.5 → 1.5.0

package/dist/esm/doc/worksheet.js

@@ -125,19 +125,26 @@ class Worksheet {
             }
             name = name.substring(0, 31);
         }
-        if (this._workbook._worksheets.find((ws) => ws && ws.name.toLowerCase() === name.toLowerCase())) {
+        if (this._workbook.worksheets.find(ws => ws && ws.name.toLowerCase() === name.toLowerCase())) {
             throw new Error(`Worksheet name already exists: ${name}`);
         }
         this._name = name;
     }
+    /**
+     * The workbook that contains this worksheet
+     */
     get workbook() {
         return this._workbook;
     }
-    // when you're done with this worksheet, call this to remove from workbook
+    /**
+     * When you're done with this worksheet, call this to remove from workbook
+     */
     destroy() {
         this._workbook.removeWorksheetEx(this);
     }
-    // Get the bounding range of the cells in this worksheet
+    /**
+     * Get the bounding range of the cells in this worksheet
+     */
     get dimensions() {
         const dimensions = new Range();
         this._rows.forEach(row => {
@@ -152,16 +159,22 @@ class Worksheet {
     }
     // =========================================================================
     // Columns
-    // get the current columns array.
+    /**
+     * Get the current columns array
+     */
     get columns() {
         return this._columns;
     }
-    // set the columns from an array of column definitions.
-    // Note: any headers defined will overwrite existing values.
+    /**
+     * Add column headers and define column keys and widths.
+     *
+     * Note: these column structures are a workbook-building convenience only,
+     * apart from the column width, they will not be fully persisted.
+     */
     set columns(value) {
         // calculate max header row count
         this._headerRowCount = value.reduce((pv, cv) => {
-            const headerCount = (cv.header && 1) || (cv.headers && cv.headers.length) || 0;
+            const headerCount = Array.isArray(cv.header) ? cv.header.length : cv.header ? 1 : 0;
             return Math.max(pv, headerCount);
         }, 0);
         // construct Column objects
@@ -185,7 +198,9 @@ class Worksheet {
     eachColumnKey(f) {
         Object.keys(this._keys).forEach(key => f(this._keys[key], key));
     }
-    // get a single column by col number. If it doesn't exist, create it and any gaps before it
+    /**
+     * Access an individual column by key, letter and 1-based column number
+     */
     getColumn(c) {
         let colNum;
         if (typeof c === "string") {
@@ -211,18 +226,26 @@ class Worksheet {
         }
         return this._columns[colNum - 1];
     }
+    /**
+     * Cut one or more columns (columns to the right are shifted left)
+     * and optionally insert more
+     *
+     * If column properties have been defined, they will be cut or moved accordingly
+     *
+     * Known Issue: If a splice causes any merged cells to move, the results may be unpredictable
+     *
+     * Also: If the worksheet has more rows than values in the column inserts,
+     * the rows will still be shifted as if the values existed
+     */
     spliceColumns(start, count, ...inserts) {
         const rows = this._rows;
         const nRows = rows.length;
         if (inserts.length > 0) {
             // must iterate over all rows whether they exist yet or not
             for (let i = 0; i < nRows; i++) {
-                const rowArguments = [start, count];
-                inserts.forEach(insert => {
-                    rowArguments.push(insert[i] || null);
-                });
+                const insertValues = inserts.map(insert => insert[i] || null);
                 const row = this.getRow(i + 1);
-                row.splice(...rowArguments);
+                row.splice(start, count, ...insertValues);
             }
         }
         else {
@@ -248,26 +271,35 @@ class Worksheet {
             }
         }
         for (let i = start; i < start + inserts.length; i++) {
-            this.getColumn(i).defn = null;
+            this.getColumn(i).defn = undefined;
         }
         // account for defined names
         this.workbook.definedNames.spliceColumns(this.name, start, count, inserts.length);
     }
+    /**
+     * Get the last column in a worksheet
+     */
     get lastColumn() {
         return this.getColumn(this.columnCount);
     }
+    /**
+     * The total column size of the document. Equal to the maximum cell count from all of the rows
+     */
     get columnCount() {
         let maxCount = 0;
-        this.eachRow((row) => {
+        this.eachRow(row => {
             maxCount = Math.max(maxCount, row.cellCount);
         });
         return maxCount;
     }
+    /**
+     * A count of the number of columns that have values
+     */
     get actualColumnCount() {
         // performance nightmare - for each row, counts all the columns used
         const counts = [];
         let count = 0;
-        this.eachRow((row) => {
+        this.eachRow(row => {
             row.eachCell(({ col }) => {
                 if (!counts[col]) {
                     counts[col] = true;
@@ -294,23 +326,41 @@ class Worksheet {
     get _nextRow() {
         return this._lastRowNumber + 1;
     }
+    /**
+     * Get the last editable row in a worksheet (or undefined if there are none)
+     */
     get lastRow() {
         if (this._rows.length) {
             return this._rows[this._rows.length - 1];
         }
         return undefined;
     }
-    // find a row (if exists) by row number
+    /**
+     * Tries to find and return row for row number, else undefined
+     *
+     * @param r - The 1-indexed row number
+     */
     findRow(r) {
         return this._rows[r - 1];
     }
-    // find multiple rows (if exists) by row number
+    /**
+     * Tries to find and return rows for row number start and length, else undefined
+     *
+     * @param start - The 1-indexed starting row number
+     * @param length - The length of the expected array
+     */
     findRows(start, length) {
         return this._rows.slice(start - 1, start - 1 + length);
     }
+    /**
+     * The total row size of the document. Equal to the row number of the last row that has values.
+     */
     get rowCount() {
         return this._lastRowNumber;
     }
+    /**
+     * A count of the number of rows that have values. If a mid-document row is empty, it will not be included in the count.
+     */
     get actualRowCount() {
         // counts actual rows that have actual data
         let count = 0;
@@ -319,7 +369,9 @@ class Worksheet {
         });
         return count;
     }
-    // get a row by row number.
+    /**
+     * Get or create row by 1-based index
+     */
     getRow(r) {
         let row = this._rows[r - 1];
         if (!row) {
@@ -327,7 +379,9 @@ class Worksheet {
         }
         return row;
     }
-    // get multiple rows by row number.
+    /**
+     * Get or create rows by 1-based index
+     */
     getRows(start, length) {
         if (length < 1) {
             return undefined;
@@ -338,6 +392,10 @@ class Worksheet {
         }
         return rows;
     }
+    /**
+     * Add a couple of Rows by key-value, after the last current row, using the column keys,
+     * or add a row by contiguous Array (assign to columns A, B & C)
+     */
     addRow(value, style = "n") {
         const rowNo = this._nextRow;
         const row = this.getRow(rowNo);
@@ -345,6 +403,9 @@ class Worksheet {
         this._setStyleOption(rowNo, style[0] === "i" ? style : "n");
         return row;
     }
+    /**
+     * Add multiple rows by providing an array of arrays or key-value pairs
+     */
     addRows(value, style = "n") {
         const rows = [];
         value.forEach(row => {
@@ -352,11 +413,19 @@ class Worksheet {
         });
         return rows;
     }
+    /**
+     * Insert a Row by key-value, at the position (shifting down all rows from position),
+     * using the column keys, or add a row by contiguous Array (assign to columns A, B & C)
+     */
     insertRow(pos, value, style = "n") {
         this.spliceRows(pos, 0, value);
         this._setStyleOption(pos, style);
         return this.getRow(pos);
     }
+    /**
+     * Insert multiple rows at position (shifting down all rows from position)
+     * by providing an array of arrays or key-value pairs
+     */
     insertRows(pos, values, style = "n") {
         this.spliceRows(pos, 0, ...values);
         if (style !== "n") {
@@ -390,6 +459,9 @@ class Worksheet {
         });
         rDst.height = rSrc.height;
     }
+    /**
+     * Duplicate rows and insert new rows
+     */
     duplicateRow(rowNum, count, insert = false) {
         // create count duplicates of rowNum
         // either inserting new or overwriting existing rows
@@ -406,6 +478,12 @@ class Worksheet {
             });
         }
     }
+    /**
+     * Cut one or more rows (rows below are shifted up)
+     * and optionally insert more
+     *
+     * Known Issue: If a splice causes any merged cells to move, the results may be unpredictable
+     */
     spliceRows(start, count, ...inserts) {
         // same problem as row.splice, except worse.
         const nKeep = start + count;
@@ -448,10 +526,10 @@ class Worksheet {
                     rSrc.eachCell({ includeEmpty: true }, (cell, colNumber) => {
                         rDst.getCell(colNumber).style = cell.style;
                         // remerge cells accounting for insert offset
-                        if (cell._value.constructor.name === "MergeValue") {
-                            const cellToBeMerged = this.getRow(cell._row._number + nInserts).getCell(colNumber);
-                            const prevMaster = cell._value._master;
-                            const newMaster = this.getRow(prevMaster._row._number + nInserts).getCell(prevMaster._column._number);
+                        if (cell.type === Enums.ValueType.Merge) {
+                            const cellToBeMerged = this.getRow(cell.row + nInserts).getCell(colNumber);
+                            const prevMaster = cell.master;
+                            const newMaster = this.getRow(prevMaster.row + nInserts).getCell(prevMaster.col);
                             cellToBeMerged.merge(newMaster);
                         }
                     });
@@ -470,31 +548,33 @@ class Worksheet {
         // account for defined names
         this.workbook.definedNames.spliceRows(this.name, start, count, nInserts);
     }
-    eachRow(optionsOrIteratee, maybeIteratee) {
+    eachRow(optOrCallback, maybeCallback) {
         let options;
-        let iteratee;
-        if (typeof optionsOrIteratee === "function") {
-            iteratee = optionsOrIteratee;
+        let callback;
+        if (typeof optOrCallback === "function") {
+            callback = optOrCallback;
         }
         else {
-            options = optionsOrIteratee;
-            iteratee = maybeIteratee;
+            options = optOrCallback;
+            callback = maybeCallback;
         }
         if (options && options.includeEmpty) {
             const n = this._rows.length;
             for (let i = 1; i <= n; i++) {
-                iteratee(this.getRow(i), i);
+                callback(this.getRow(i), i);
             }
         }
         else {
             this._rows.forEach(row => {
                 if (row && row.hasValues) {
-                    iteratee(row, row.number);
+                    callback(row, row.number);
                 }
             });
         }
     }
-    // return all rows as sparse array
+    /**
+     * Return all rows as sparse array
+     */
     getSheetValues() {
         const rows = [];
         this._rows.forEach(row => {
@@ -506,13 +586,17 @@ class Worksheet {
     }
     // =========================================================================
     // Cells
-    // returns the cell at [r,c] or address given by r. If not found, return undefined
+    /**
+     * Returns the cell at [r,c] or address given by r. If not found, return undefined
+     */
     findCell(r, c) {
         const address = colCache.getAddress(r, c);
         const row = this._rows[address.row - 1];
         return row ? row.findCell(address.col) : undefined;
     }
-    // return the cell at [r,c] or address given by r. If not found, create a new one.
+    /**
+     * Get or create cell at [r,c] or address given by r
+     */
     getCell(r, c) {
         const address = colCache.getAddress(r, c);
         const row = this.getRow(address.row);
@@ -520,7 +604,15 @@ class Worksheet {
     }
     // =========================================================================
     // Merge
-    // convert the range defined by ['tl:br'], [tl,br] or [t,l,b,r] into a single 'merged' cell
+    /**
+     * Merge cells, either:
+     *
+     * tlbr string, e.g. `'A4:B5'`
+     *
+     * tl string, br string, e.g. `'G10', 'H11'`
+     *
+     * t, l, b, r numbers, e.g. `10,11,12,13`
+     */
     mergeCells(...cells) {
         const dimensions = new Range(cells);
         this._mergeCellsInternal(dimensions);
@@ -565,9 +657,11 @@ class Worksheet {
         // return true if this._merges has a merge object
         return Object.values(this._merges).some(Boolean);
     }
-    // scan the range defined by ['tl:br'], [tl,br] or [t,l,b,r] and if any cell is part of a merge,
-    // un-merge the group. Note this function can affect multiple merges and merge-blocks are
-    // atomic - either they're all merged or all un-merged.
+    /**
+     * Scan the range and if any cell is part of a merge, un-merge the group.
+     * Note this function can affect multiple merges and merge-blocks are
+     * atomic - either they're all merged or all un-merged.
+     */
     unMergeCells(...cells) {
         const dimensions = new Range(cells);
         // find any cells in that range and unmerge them
@@ -616,12 +710,14 @@ class Worksheet {
         for (let r = top; r <= bottom; r++) {
             for (let c = left; c <= right; c++) {
                 if (first) {
-                    this.getCell(r, c).value = {
+                    const cell = this.getCell(r, c);
+                    const formulaValue = {
                         shareType,
                         formula,
                         ref: range,
                         result: getResult(r, c)
                     };
+                    cell.value = formulaValue;
                     first = false;
                 }
                 else {
@@ -637,6 +733,10 @@ class Worksheet {
     }
     // =========================================================================
     // Images
+    /**
+     * Using the image id from `Workbook.addImage`,
+     * embed an image within the worksheet to cover a range
+     */
     addImage(imageId, range) {
         const model = {
             type: "image",
@@ -648,6 +748,9 @@ class Worksheet {
     getImages() {
         return this._media.filter(m => m.type === "image");
     }
+    /**
+     * Using the image id from `Workbook.addImage`, set the background to the worksheet
+     */
     addBackgroundImage(imageId) {
         const model = {
             type: "background",
@@ -661,6 +764,9 @@ class Worksheet {
     }
     // =========================================================================
     // Worksheet Protection
+    /**
+     * Protect the worksheet with optional password and options
+     */
     protect(password, options) {
         // TODO: make this function truly async
         // perhaps marshal to worker thread or something
@@ -695,17 +801,29 @@ class Worksheet {
     }
     // =========================================================================
     // Tables
+    /**
+     * Add a new table and return a reference to it
+     */
     addTable(model) {
         const table = new Table(this, model);
         this.tables[model.name] = table;
         return table;
     }
+    /**
+     * Fetch table by name
+     */
     getTable(name) {
         return this.tables[name];
     }
+    /**
+     * Delete table by name
+     */
     removeTable(name) {
         delete this.tables[name];
     }
+    /**
+     * Fetch all tables in the worksheet
+     */
     getTables() {
         return Object.values(this.tables);
     }
@@ -721,9 +839,15 @@ Please leave feedback at https://github.com/excelts/excelts/discussions/2575`);
     }
     // ===========================================================================
     // Conditional Formatting
+    /**
+     * Add conditional formatting rules
+     */
     addConditionalFormatting(cf) {
         this.conditionalFormattings.push(cf);
     }
+    /**
+     * Delete conditional formatting rules
+     */
     removeConditionalFormatting(filter) {
         if (typeof filter === "number") {
             this.conditionalFormattings.splice(filter, 1);
@@ -757,7 +881,7 @@ Please leave feedback at https://github.com/excelts/excelts/discussions/2575`);
         };
         // =================================================
         // columns
-        model.cols = Column.toModel(this.columns);
+        model.cols = Column.toModel(this.columns || []);
         // ==========================================================
         // Rows
         const rows = (model.rows = []);

package/dist/esm/utils/sheet-utils.js

@@ -112,7 +112,9 @@ function formatValue(value, fmt, dateFormat) {
  */
 function getCellDisplayText(cell, dateFormat) {
     const value = cell.value;
-    const fmt = cell.numFmt || "General";
+    const numFmt = cell.numFmt;
+    // Extract format code string from numFmt (which can be string or NumFmt object)
+    const fmt = typeof numFmt === "string" ? numFmt : (numFmt?.formatCode ?? "General");
     // Null/undefined
     if (value == null) {
         return "";

package/dist/esm/utils/unzip/extract.js

@@ -1,13 +1,13 @@
 /**
  * Simple ZIP extraction utilities
  * Provides easy-to-use Promise-based API for extracting ZIP files
+ * Works in both Node.js and browser environments
  */
-import { Readable } from "stream";
-import { createParse } from "./parse.js";
+import { ZipParser } from "./zip-parser.js";
 /**
  * Extract all files from a ZIP buffer
  *
- * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
  * @returns Map of file paths to their content
  *
  * @example
@@ -24,40 +24,24 @@ import { createParse } from "./parse.js";
  */
 export async function extractAll(zipData) {
     const files = new Map();
-    const buffer = Buffer.isBuffer(zipData) ? zipData : Buffer.from(zipData);
-    const parse = createParse({ forceStream: true });
-    const stream = Readable.from([buffer]);
-    stream.pipe(parse);
-    for await (const entry of parse) {
-        const zipEntry = entry;
-        const isDirectory = zipEntry.type === "Directory";
-        if (isDirectory) {
-            files.set(zipEntry.path, {
-                path: zipEntry.path,
-                data: Buffer.alloc(0),
-                isDirectory: true,
-                size: 0
-            });
-            zipEntry.autodrain();
-        }
-        else {
-            const data = await zipEntry.buffer();
-            files.set(zipEntry.path, {
-                path: zipEntry.path,
-                data,
-                isDirectory: false,
-                size: data.length
-            });
-        }
+    const parser = new ZipParser(zipData);
+    for (const entry of parser.getEntries()) {
+        const data = await parser.extract(entry.path);
+        files.set(entry.path, {
+            path: entry.path,
+            data: data || new Uint8Array(0),
+            isDirectory: entry.isDirectory,
+            size: entry.uncompressedSize
+        });
     }
     return files;
 }
 /**
  * Extract a single file from a ZIP buffer
  *
- * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
  * @param filePath - Path of the file to extract
- * @returns File content as Buffer, or null if not found
+ * @returns File content as Uint8Array, or null if not found
  *
  * @example
  * ```ts
@@ -66,31 +50,18 @@ export async function extractAll(zipData) {
  * const zipData = fs.readFileSync("archive.zip");
  * const content = await extractFile(zipData, "readme.txt");
  * if (content) {
- *   console.log(content.toString("utf-8"));
+ *   console.log(new TextDecoder().decode(content));
  * }
  * ```
  */
 export async function extractFile(zipData, filePath) {
-    const buffer = Buffer.isBuffer(zipData) ? zipData : Buffer.from(zipData);
-    const parse = createParse({ forceStream: true });
-    const stream = Readable.from([buffer]);
-    stream.pipe(parse);
-    for await (const entry of parse) {
-        const zipEntry = entry;
-        if (zipEntry.path === filePath) {
-            if (zipEntry.type === "Directory") {
-                return Buffer.alloc(0);
-            }
-            return zipEntry.buffer();
-        }
-        zipEntry.autodrain();
-    }
-    return null;
+    const parser = new ZipParser(zipData);
+    return parser.extract(filePath);
 }
 /**
  * List all file paths in a ZIP buffer (without extracting content)
  *
- * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
  * @returns Array of file paths
  *
  * @example
@@ -103,22 +74,13 @@ export async function extractFile(zipData, filePath) {
  * ```
  */
 export async function listFiles(zipData) {
-    const paths = [];
-    const buffer = Buffer.isBuffer(zipData) ? zipData : Buffer.from(zipData);
-    const parse = createParse({ forceStream: true });
-    const stream = Readable.from([buffer]);
-    stream.pipe(parse);
-    for await (const entry of parse) {
-        const zipEntry = entry;
-        paths.push(zipEntry.path);
-        zipEntry.autodrain();
-    }
-    return paths;
+    const parser = new ZipParser(zipData);
+    return parser.listFiles();
 }
 /**
  * Iterate over ZIP entries with a callback (memory efficient for large ZIPs)
  *
- * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
  * @param callback - Async callback for each entry, return false to stop iteration
  *
  * @example
@@ -128,33 +90,17 @@ export async function listFiles(zipData) {
  * await forEachEntry(zipData, async (path, getData) => {
  *   if (path.endsWith(".xml")) {
  *     const content = await getData();
- *     console.log(content.toString("utf-8"));
+ *     console.log(new TextDecoder().decode(content));
  *   }
  *   return true; // continue iteration
  * });
  * ```
  */
 export async function forEachEntry(zipData, callback) {
-    const buffer = Buffer.isBuffer(zipData) ? zipData : Buffer.from(zipData);
-    const parse = createParse({ forceStream: true });
-    const stream = Readable.from([buffer]);
-    stream.pipe(parse);
-    for await (const entry of parse) {
-        const zipEntry = entry;
-        let dataPromise = null;
-        const getData = () => {
-            if (!dataPromise) {
-                dataPromise = zipEntry.buffer();
-            }
-            return dataPromise;
-        };
-        const shouldContinue = await callback(zipEntry.path, getData, zipEntry);
-        // If callback didn't read data, drain it
-        if (!dataPromise) {
-            zipEntry.autodrain();
-        }
-        if (shouldContinue === false) {
-            break;
-        }
-    }
+    const parser = new ZipParser(zipData);
+    await parser.forEach(async (entry, getData) => {
+        return callback(entry.path, getData, entry);
+    });
 }
+// Re-export ZipParser for advanced usage
+export { ZipParser } from "./zip-parser.js";

package/dist/esm/utils/unzip/index.js

@@ -1,8 +1,23 @@
 /**
  * Unzip utilities for parsing ZIP archives
+ *
+ * Two APIs are provided:
+ *
+ * 1. **Stream-based API** (Node.js only):
+ *    - `Parse`, `createParse` - Parse ZIP files as a stream
+ *    - Best for large files where you don't want to load entire file into memory
+ *    - Requires Node.js `stream` module
+ *
+ * 2. **Buffer-based API** (Browser + Node.js):
+ *    - `extractAll`, `extractFile`, `listFiles`, `forEachEntry`, `ZipParser`
+ *    - Works in both Node.js and browser environments
+ *    - Uses native `DecompressionStream` in browser, `zlib` in Node.js
+ *    - Best for files already loaded into memory (ArrayBuffer, Uint8Array)
+ *
  * Original source: https://github.com/ZJONSSON/node-unzipper
  * License: MIT
  */
+// Stream-based API (Node.js only - requires stream module)
 export { Parse, createParse } from "./parse.js";
 export { PullStream } from "./pull-stream.js";
 export { NoopStream } from "./noop-stream.js";
@@ -10,5 +25,5 @@ export { bufferStream } from "./buffer-stream.js";
 export { parse as parseBuffer } from "./parse-buffer.js";
 export { parseDateTime } from "./parse-datetime.js";
 export { parseExtraField } from "./parse-extra-field.js";
-// Simple extraction API
-export { extractAll, extractFile, listFiles, forEachEntry } from "./extract.js";
+// Buffer-based API (Browser + Node.js - cross-platform)
+export { extractAll, extractFile, listFiles, forEachEntry, ZipParser } from "./extract.js";