@cj-tech-master/excelts 3.1.0-canary.20260102041828.82ed571 → 3.1.0

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

@@ -0,0 +1,707 @@
+/**
+ * Utility functions for ExcelTS
+ * Provides convenient helper functions for common spreadsheet operations
+ */
+import { Workbook } from "../doc/workbook.js";
+import { colCache } from "./col-cache.js";
+import { format as cellFormat } from "./cell-format.js";
+/**
+ * Convert a Date object back to Excel serial number without timezone issues.
+ * This reverses the excelToDate conversion exactly.
+ * excelToDate uses: new Date(Math.round((v - 25569) * 24 * 3600 * 1000))
+ * So we reverse it: (date.getTime() / (24 * 3600 * 1000)) + 25569
+ */
+function dateToExcelSerial(d) {
+    return d.getTime() / (24 * 3600 * 1000) + 25569;
+}
+/**
+ * Check if format is a pure time format (no date components like y, m for month, d)
+ * Time formats only contain: h, m (minutes in time context), s, AM/PM
+ * Excludes elapsed time formats like [h]:mm:ss which should keep full serial number
+ */
+function isTimeOnlyFormat(fmt) {
+    // Remove quoted strings first
+    const cleaned = fmt.replace(/"[^"]*"/g, "");
+    // Elapsed time formats [h], [m], [s] should NOT be treated as time-only
+    // They need the full serial number to calculate total hours/minutes/seconds
+    if (/\[[hms]\]/i.test(cleaned)) {
+        return false;
+    }
+    // Remove color codes and conditions (but we already checked for [h], [m], [s])
+    const withoutBrackets = cleaned.replace(/\[[^\]]*\]/g, "");
+    // Check if it has time components (h, s, or AM/PM)
+    const hasTimeComponents = /[hs]/i.test(withoutBrackets) || /AM\/PM|A\/P/i.test(withoutBrackets);
+    // Check if it has date components (y, d, or m not adjacent to h/s which would make it minutes)
+    // In Excel: "m" after "h" or before "s" is minutes, otherwise it's month
+    const hasDateComponents = /[yd]/i.test(withoutBrackets);
+    // If it has time but no date components, it's a time-only format
+    // Also check for standalone 'm' that's not minutes (not near h or s)
+    if (hasDateComponents) {
+        return false;
+    }
+    // Check for month 'm' - if 'm' exists but not in h:m or m:s context, it's a date format
+    if (/m/i.test(withoutBrackets) && !hasTimeComponents) {
+        return false;
+    }
+    return hasTimeComponents;
+}
+/**
+ * Check if format is a date format (contains y, d, or month-m)
+ * Used to determine if dateFormat override should be applied
+ */
+function isDateFormat(fmt) {
+    // Remove quoted strings first
+    const cleaned = fmt.replace(/"[^"]*"/g, "");
+    // Elapsed time formats [h], [m], [s] are NOT date formats
+    if (/\[[hms]\]/i.test(cleaned)) {
+        return false;
+    }
+    // Remove color codes and conditions
+    const withoutBrackets = cleaned.replace(/\[[^\]]*\]/g, "");
+    // Check for year or day components
+    if (/[yd]/i.test(withoutBrackets)) {
+        return true;
+    }
+    // Check for month 'm' - only if it's NOT in time context (not near h or s)
+    // In Excel: "m" after "h" or before "s" is minutes, otherwise it's month
+    if (/m/i.test(withoutBrackets)) {
+        const hasTimeComponents = /[hs]/i.test(withoutBrackets) || /AM\/PM|A\/P/i.test(withoutBrackets);
+        // If no time components, 'm' is month
+        if (!hasTimeComponents) {
+            return true;
+        }
+        // If has time components, need to check if 'm' is month or minutes
+        // Simplified: if format has both date-like and time-like patterns, consider it a date format
+        // e.g., "m/d/yy h:mm" - has 'm' as month and 'mm' as minutes
+    }
+    return false;
+}
+/**
+ * Format a value (Date, number, boolean, string) according to the given format
+ * Handles timezone-independent conversion for Date objects
+ * @param value - The value to format
+ * @param fmt - The format string to use
+ * @param dateFormat - Optional override format for date values (not applied to time or elapsed time formats)
+ */
+function formatValue(value, fmt, dateFormat) {
+    // Date object - convert back to Excel serial number
+    if (value instanceof Date) {
+        let serial = dateToExcelSerial(value);
+        // For time-only formats, use only the fractional part (time portion)
+        if (isTimeOnlyFormat(fmt)) {
+            serial = serial % 1;
+            if (serial < 0) {
+                serial += 1;
+            }
+            return cellFormat(fmt, serial);
+        }
+        // Only apply dateFormat override to actual date formats
+        // (not elapsed time formats like [h]:mm:ss)
+        const actualFmt = dateFormat && isDateFormat(fmt) ? dateFormat : fmt;
+        return cellFormat(actualFmt, serial);
+    }
+    // Number/Boolean/String - let cellFormat handle it
+    return cellFormat(fmt, value);
+}
+/**
+ * Get formatted display text for a cell value
+ * Returns the value formatted according to the cell's numFmt
+ * This matches Excel's display exactly (timezone-independent)
+ * @param cell - The cell to get display text for
+ * @param dateFormat - Optional override format for date values
+ */
+function getCellDisplayText(cell, dateFormat) {
+    const value = cell.value;
+    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 "";
+    }
+    // Date/Number/Boolean/String - format directly
+    if (value instanceof Date ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "string") {
+        return formatValue(value, fmt, dateFormat);
+    }
+    // Formula type - use the result value
+    if (typeof value === "object" && "formula" in value) {
+        const result = value.result;
+        if (result == null) {
+            return "";
+        }
+        if (result instanceof Date ||
+            typeof result === "number" ||
+            typeof result === "boolean" ||
+            typeof result === "string") {
+            return formatValue(result, fmt, dateFormat);
+        }
+    }
+    // Fallback to cell.text for other types (rich text, hyperlink, error, etc.)
+    return cell.text;
+}
+// =============================================================================
+// Cell Address Encoding/Decoding
+// =============================================================================
+/**
+ * Decode column string to 0-indexed number
+ * @example decodeCol("A") => 0, decodeCol("Z") => 25, decodeCol("AA") => 26
+ */
+export function decodeCol(colstr) {
+    return colCache.l2n(colstr.toUpperCase()) - 1;
+}
+/**
+ * Encode 0-indexed column number to string
+ * @example encodeCol(0) => "A", encodeCol(25) => "Z", encodeCol(26) => "AA"
+ */
+export function encodeCol(col) {
+    return colCache.n2l(col + 1);
+}
+/**
+ * Decode row string to 0-indexed number
+ * @example decodeRow("1") => 0, decodeRow("10") => 9
+ */
+export function decodeRow(rowstr) {
+    return parseInt(rowstr, 10) - 1;
+}
+/**
+ * Encode 0-indexed row number to string
+ * @example encodeRow(0) => "1", encodeRow(9) => "10"
+ */
+export function encodeRow(row) {
+    return String(row + 1);
+}
+/**
+ * Decode cell address string to CellAddress object
+ * @example decodeCell("A1") => {c: 0, r: 0}, decodeCell("B2") => {c: 1, r: 1}
+ */
+export function decodeCell(cstr) {
+    const addr = colCache.decodeAddress(cstr.toUpperCase());
+    return { c: addr.col - 1, r: addr.row - 1 };
+}
+/**
+ * Encode CellAddress object to cell address string
+ * @example encodeCell({c: 0, r: 0}) => "A1", encodeCell({c: 1, r: 1}) => "B2"
+ */
+export function encodeCell(cell) {
+    return colCache.encodeAddress(cell.r + 1, cell.c + 1);
+}
+/**
+ * Decode range string to Range object
+ * @example decodeRange("A1:B2") => {s: {c: 0, r: 0}, e: {c: 1, r: 1}}
+ */
+export function decodeRange(range) {
+    const idx = range.indexOf(":");
+    if (idx === -1) {
+        const cell = decodeCell(range);
+        return { s: cell, e: { ...cell } };
+    }
+    return {
+        s: decodeCell(range.slice(0, idx)),
+        e: decodeCell(range.slice(idx + 1))
+    };
+}
+export function encodeRange(startOrRange, end) {
+    if (end === undefined) {
+        const range = startOrRange;
+        return encodeRange(range.s, range.e);
+    }
+    const start = startOrRange;
+    const startStr = encodeCell(start);
+    const endStr = encodeCell(end);
+    return startStr === endStr ? startStr : `${startStr}:${endStr}`;
+}
+/**
+ * Create a worksheet from an array of objects (xlsx compatible)
+ * @example
+ * const ws = jsonToSheet([{name: "Alice", age: 30}, {name: "Bob", age: 25}])
+ */
+export function jsonToSheet(data, opts) {
+    const o = opts || {};
+    // Create a temporary workbook to get a worksheet
+    const tempWb = new Workbook();
+    const worksheet = tempWb.addWorksheet("Sheet1");
+    if (data.length === 0) {
+        return worksheet;
+    }
+    // Determine headers - use provided header or Object.keys from first object
+    const allKeys = new Set();
+    data.forEach(row => Object.keys(row).forEach(k => allKeys.add(k)));
+    const headers = o.header ? [...o.header] : [...allKeys];
+    // Add any missing keys from data that weren't in header
+    if (o.header) {
+        allKeys.forEach(k => {
+            if (!headers.includes(k)) {
+                headers.push(k);
+            }
+        });
+    }
+    let rowNum = 1;
+    // Write header row
+    if (!o.skipHeader) {
+        headers.forEach((h, colIdx) => {
+            worksheet.getCell(rowNum, colIdx + 1).value = h;
+        });
+        rowNum++;
+    }
+    // Write data rows
+    for (const row of data) {
+        headers.forEach((key, colIdx) => {
+            const val = row[key];
+            if (val === null && o.nullError) {
+                worksheet.getCell(rowNum, colIdx + 1).value = { error: "#NULL!" };
+            }
+            else if (val !== undefined && val !== null) {
+                worksheet.getCell(rowNum, colIdx + 1).value = val;
+            }
+        });
+        rowNum++;
+    }
+    return worksheet;
+}
+/**
+ * Add data from an array of objects to an existing worksheet (xlsx compatible)
+ */
+export function sheetAddJson(worksheet, data, opts) {
+    const o = opts || {};
+    if (data.length === 0) {
+        return worksheet;
+    }
+    // Determine starting position
+    let startRow = 1;
+    let startCol = 1;
+    if (o.origin !== undefined) {
+        if (typeof o.origin === "string") {
+            const addr = decodeCell(o.origin);
+            startRow = addr.r + 1;
+            startCol = addr.c + 1;
+        }
+        else if (typeof o.origin === "number") {
+            if (o.origin === -1) {
+                // Append to bottom
+                startRow = worksheet.rowCount + 1;
+            }
+            else {
+                startRow = o.origin + 1; // 0-indexed row
+            }
+        }
+        else {
+            startRow = o.origin.r + 1;
+            startCol = o.origin.c + 1;
+        }
+    }
+    // Determine headers
+    const allKeys = new Set();
+    data.forEach(row => Object.keys(row).forEach(k => allKeys.add(k)));
+    const headers = o.header ? [...o.header] : [...allKeys];
+    if (o.header) {
+        allKeys.forEach(k => {
+            if (!headers.includes(k)) {
+                headers.push(k);
+            }
+        });
+    }
+    let rowNum = startRow;
+    // Write header row
+    if (!o.skipHeader) {
+        headers.forEach((h, colIdx) => {
+            worksheet.getCell(rowNum, startCol + colIdx).value = h;
+        });
+        rowNum++;
+    }
+    // Write data rows
+    for (const row of data) {
+        headers.forEach((key, colIdx) => {
+            const val = row[key];
+            if (val === null && o.nullError) {
+                worksheet.getCell(rowNum, startCol + colIdx).value = { error: "#NULL!" };
+            }
+            else if (val !== undefined && val !== null) {
+                worksheet.getCell(rowNum, startCol + colIdx).value = val;
+            }
+        });
+        rowNum++;
+    }
+    return worksheet;
+}
+/**
+ * Convert worksheet to JSON array (xlsx compatible)
+ * @example
+ * // Default: array of objects with first row as headers
+ * const data = sheetToJson(worksheet)
+ * // => [{name: "Alice", age: 30}, {name: "Bob", age: 25}]
+ *
+ * // Array of arrays
+ * const aoa = sheetToJson(worksheet, { header: 1 })
+ * // => [["name", "age"], ["Alice", 30], ["Bob", 25]]
+ *
+ * // Column letters as keys
+ * const cols = sheetToJson(worksheet, { header: "A" })
+ * // => [{A: "name", B: "age"}, {A: "Alice", B: 30}]
+ */
+export function sheetToJson(worksheet, opts) {
+    const o = opts || {};
+    // Determine range
+    let startRow = 1;
+    let endRow = worksheet.rowCount;
+    let startCol = 1;
+    let endCol = worksheet.columnCount;
+    if (o.range !== undefined) {
+        if (typeof o.range === "number") {
+            startRow = o.range + 1; // 0-indexed to 1-indexed
+        }
+        else if (typeof o.range === "string") {
+            const r = decodeRange(o.range);
+            startRow = r.s.r + 1;
+            endRow = r.e.r + 1;
+            startCol = r.s.c + 1;
+            endCol = r.e.c + 1;
+        }
+    }
+    if (endRow < startRow || endCol < startCol) {
+        return [];
+    }
+    // Handle header option
+    const headerOpt = o.header;
+    // header: 1 - return array of arrays
+    if (headerOpt === 1) {
+        const result = [];
+        // Default for header:1 is to include blank rows
+        const includeBlank = o.blankrows !== false;
+        for (let row = startRow; row <= endRow; row++) {
+            const rowData = [];
+            let isEmpty = true;
+            for (let col = startCol; col <= endCol; col++) {
+                const cell = worksheet.getCell(row, col);
+                const val = o.raw === false ? getCellDisplayText(cell, o.dateFormat).trim() : cell.value;
+                if (val != null && val !== "") {
+                    rowData[col - startCol] = val;
+                    isEmpty = false;
+                }
+                else if (o.defval !== undefined) {
+                    rowData[col - startCol] = o.defval;
+                }
+                else {
+                    rowData[col - startCol] = null;
+                }
+            }
+            if (!isEmpty || includeBlank) {
+                result.push(rowData);
+            }
+        }
+        return result;
+    }
+    // header: "A" - use column letters as keys
+    if (headerOpt === "A") {
+        const result = [];
+        // Default for header:"A" is to skip blank rows
+        const includeBlank = o.blankrows === true;
+        for (let row = startRow; row <= endRow; row++) {
+            const rowData = {};
+            let isEmpty = true;
+            for (let col = startCol; col <= endCol; col++) {
+                const cell = worksheet.getCell(row, col);
+                const val = o.raw === false ? getCellDisplayText(cell, o.dateFormat).trim() : cell.value;
+                const key = encodeCol(col - 1); // 0-indexed for encodeCol
+                if (val != null && val !== "") {
+                    rowData[key] = val;
+                    isEmpty = false;
+                }
+                else if (o.defval !== undefined) {
+                    rowData[key] = o.defval;
+                }
+            }
+            if (!isEmpty || includeBlank) {
+                result.push(rowData);
+            }
+        }
+        return result;
+    }
+    // header: string[] - use provided array as keys
+    if (Array.isArray(headerOpt)) {
+        const result = [];
+        const includeBlank = o.blankrows === true;
+        for (let row = startRow; row <= endRow; row++) {
+            const rowData = {};
+            let isEmpty = true;
+            for (let col = startCol; col <= endCol; col++) {
+                const colIdx = col - startCol;
+                const key = headerOpt[colIdx] ?? `__EMPTY_${colIdx}`;
+                const cell = worksheet.getCell(row, col);
+                const val = o.raw === false ? getCellDisplayText(cell, o.dateFormat).trim() : cell.value;
+                if (val != null && val !== "") {
+                    rowData[key] = val;
+                    isEmpty = false;
+                }
+                else if (o.defval !== undefined) {
+                    rowData[key] = o.defval;
+                }
+            }
+            if (!isEmpty || includeBlank) {
+                result.push(rowData);
+            }
+        }
+        return result;
+    }
+    // Default: first row as header, disambiguate duplicates
+    const headers = [];
+    const headerCounts = {};
+    for (let col = startCol; col <= endCol; col++) {
+        const cell = worksheet.getCell(startRow, col);
+        const val = cell.value;
+        let header = val != null ? String(val) : `__EMPTY_${col - startCol}`;
+        // Disambiguate duplicate headers
+        if (headerCounts[header] !== undefined) {
+            headerCounts[header]++;
+            header = `${header}_${headerCounts[header]}`;
+        }
+        else {
+            headerCounts[header] = 0;
+        }
+        headers.push(header);
+    }
+    // Read data rows (skip header row)
+    const result = [];
+    const dataStartRow = startRow + 1;
+    // Default for objects is to skip blank rows
+    const includeBlank = o.blankrows === true;
+    for (let row = dataStartRow; row <= endRow; row++) {
+        const rowData = {};
+        let isEmpty = true;
+        for (let col = startCol; col <= endCol; col++) {
+            const cell = worksheet.getCell(row, col);
+            const val = o.raw === false ? getCellDisplayText(cell, o.dateFormat).trim() : cell.value;
+            const key = headers[col - startCol];
+            if (val != null && val !== "") {
+                rowData[key] = val;
+                isEmpty = false;
+            }
+            else if (o.defval !== undefined) {
+                rowData[key] = o.defval;
+            }
+        }
+        if (!isEmpty || includeBlank) {
+            result.push(rowData);
+        }
+    }
+    return result;
+}
+/**
+ * Convert worksheet to CSV string
+ */
+export function sheetToCsv(worksheet, opts) {
+    const o = opts || {};
+    const FS = o.FS ?? ",";
+    const RS = o.RS ?? "\n";
+    const rows = [];
+    worksheet.eachRow({ includeEmpty: o.blankrows !== false }, (row, rowNumber) => {
+        const cells = [];
+        let isEmpty = true;
+        row.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+            let val = "";
+            if (cell.value != null) {
+                if (cell.value instanceof Date) {
+                    val = cell.value.toISOString();
+                }
+                else if (typeof cell.value === "object") {
+                    // Handle rich text, formula results, etc.
+                    if ("result" in cell.value) {
+                        val = String(cell.value.result ?? "");
+                    }
+                    else if ("text" in cell.value) {
+                        val = String(cell.value.text ?? "");
+                    }
+                    else if ("richText" in cell.value) {
+                        val = cell.value.richText.map(r => r.text).join("");
+                    }
+                    else {
+                        val = String(cell.value);
+                    }
+                }
+                else {
+                    val = String(cell.value);
+                }
+                isEmpty = false;
+            }
+            // Quote if necessary
+            const needsQuote = o.forceQuotes ||
+                val.includes(FS) ||
+                val.includes('"') ||
+                val.includes("\n") ||
+                val.includes("\r");
+            if (needsQuote) {
+                val = `"${val.replace(/"/g, '""')}"`;
+            }
+            cells.push(val);
+        });
+        // Pad cells to match column count
+        while (cells.length < worksheet.columnCount) {
+            cells.push("");
+        }
+        if (!isEmpty || o.blankrows !== false) {
+            rows.push(cells.join(FS));
+        }
+    });
+    return rows.join(RS);
+}
+// =============================================================================
+// Workbook Functions
+// =============================================================================
+/**
+ * Create a new workbook
+ */
+export function bookNew() {
+    return new Workbook();
+}
+/**
+ * Append worksheet to workbook (xlsx compatible)
+ * @example
+ * const wb = bookNew();
+ * const ws = jsonToSheet([{a: 1, b: 2}]);
+ * bookAppendSheet(wb, ws, "Sheet1");
+ */
+export function bookAppendSheet(workbook, worksheet, name) {
+    // Copy the worksheet data to a new sheet in the workbook
+    const newWs = workbook.addWorksheet(name);
+    // Copy all cells from source worksheet
+    worksheet.eachRow({ includeEmpty: true }, (row, rowNumber) => {
+        row.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+            const newCell = newWs.getCell(rowNumber, colNumber);
+            newCell.value = cell.value;
+            if (cell.style) {
+                newCell.style = cell.style;
+            }
+        });
+    });
+    // Copy column properties
+    worksheet.columns?.forEach((col, idx) => {
+        if (col && newWs.columns[idx]) {
+            if (col.width) {
+                newWs.getColumn(idx + 1).width = col.width;
+            }
+        }
+    });
+}
+/**
+ * Create a worksheet from an array of arrays (xlsx compatible)
+ * @example
+ * const ws = aoaToSheet([["Name", "Age"], ["Alice", 30], ["Bob", 25]])
+ */
+export function aoaToSheet(data, opts) {
+    const tempWb = new Workbook();
+    const worksheet = tempWb.addWorksheet("Sheet1");
+    if (data.length === 0) {
+        return worksheet;
+    }
+    // Determine starting position
+    let startRow = 1;
+    let startCol = 1;
+    if (opts?.origin !== undefined) {
+        if (typeof opts.origin === "string") {
+            const addr = decodeCell(opts.origin);
+            startRow = addr.r + 1;
+            startCol = addr.c + 1;
+        }
+        else if (typeof opts.origin === "number") {
+            startRow = opts.origin + 1; // 0-indexed row
+        }
+        else {
+            startRow = opts.origin.r + 1;
+            startCol = opts.origin.c + 1;
+        }
+    }
+    data.forEach((row, rowIdx) => {
+        if (!row) {
+            return;
+        }
+        row.forEach((val, colIdx) => {
+            if (val !== undefined && val !== null) {
+                worksheet.getCell(startRow + rowIdx, startCol + colIdx).value = val;
+            }
+        });
+    });
+    return worksheet;
+}
+/**
+ * Add data from an array of arrays to an existing worksheet (xlsx compatible)
+ */
+export function sheetAddAoa(worksheet, data, opts) {
+    if (data.length === 0) {
+        return worksheet;
+    }
+    // Determine starting position
+    let startRow = 1;
+    let startCol = 1;
+    if (opts?.origin !== undefined) {
+        if (typeof opts.origin === "string") {
+            const addr = decodeCell(opts.origin);
+            startRow = addr.r + 1;
+            startCol = addr.c + 1;
+        }
+        else if (typeof opts.origin === "number") {
+            if (opts.origin === -1) {
+                // Append to bottom
+                startRow = worksheet.rowCount + 1;
+            }
+            else {
+                startRow = opts.origin + 1; // 0-indexed row
+            }
+        }
+        else {
+            startRow = opts.origin.r + 1;
+            startCol = opts.origin.c + 1;
+        }
+    }
+    data.forEach((row, rowIdx) => {
+        if (!row) {
+            return;
+        }
+        row.forEach((val, colIdx) => {
+            if (val !== undefined && val !== null) {
+                worksheet.getCell(startRow + rowIdx, startCol + colIdx).value = val;
+            }
+        });
+    });
+    return worksheet;
+}
+/**
+ * Convert worksheet to array of arrays
+ */
+export function sheetToAoa(worksheet) {
+    const result = [];
+    worksheet.eachRow({ includeEmpty: true }, (row, rowNumber) => {
+        const rowData = [];
+        row.eachCell({ includeEmpty: true }, (cell, colNumber) => {
+            rowData[colNumber - 1] = cell.value;
+        });
+        result[rowNumber - 1] = rowData;
+    });
+    return result;
+}
+// =============================================================================
+// Export utils object
+// =============================================================================
+export const utils = {
+    // Cell encoding/decoding (camelCase)
+    decodeCol,
+    encodeCol,
+    decodeRow,
+    encodeRow,
+    decodeCell,
+    encodeCell,
+    decodeRange,
+    encodeRange,
+    // Sheet/JSON conversion (camelCase)
+    jsonToSheet,
+    sheetAddJson,
+    sheetToJson,
+    sheetToCsv,
+    aoaToSheet,
+    sheetAddAoa,
+    sheetToAoa,
+    // Workbook functions (camelCase)
+    bookNew,
+    bookAppendSheet
+};