@js-ak/excel-toolbox 1.8.3 → 1.9.0

package/build/cjs/lib/workbook-builder/utils/build-workbook-rels-xml.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWorkbookRels = buildWorkbookRels;
+const constants_js_1 = require("./constants.js");
+const build_xml_js_1 = require("./build-xml.js");
+/**
+ * Builds the `_rels/workbook.xml.rels` content for the given number of sheets.
+ *
+ * Relationships are created for each worksheet and then for styles, theme, and shared strings.
+ *
+ * @param sheetsCount - Number of worksheets in the workbook
+ * @returns XML string for the workbook relationships part
+ */
+function buildWorkbookRels(sheetsCount) {
+    // Create relationships for each worksheet
+    const sheetRels = Array.from({ length: sheetsCount }, (_, i) => ({
+        attrs: {
+            Id: `rId${i + 1}`,
+            Target: `worksheets/sheet${i + 1}.xml`,
+            Type: constants_js_1.RELATIONSHIP_TYPES.WORKSHEET,
+        },
+        tag: "Relationship",
+    }));
+    // Ids for styles, theme, and sharedStrings follow after the worksheets
+    const stylesRel = {
+        attrs: {
+            Id: `rId${sheetsCount + 1}`,
+            Target: "styles.xml",
+            Type: constants_js_1.RELATIONSHIP_TYPES.STYLES,
+        },
+        tag: "Relationship",
+    };
+    const themeRel = {
+        attrs: {
+            Id: `rId${sheetsCount + 2}`,
+            Target: "theme/theme1.xml",
+            Type: constants_js_1.RELATIONSHIP_TYPES.THEME,
+        },
+        tag: "Relationship",
+    };
+    const sharedStringsRel = {
+        attrs: {
+            Id: `rId${sheetsCount + 3}`,
+            Target: "sharedStrings.xml",
+            Type: constants_js_1.RELATIONSHIP_TYPES.SHARED_STRINGS,
+        },
+        tag: "Relationship",
+    };
+    const allRels = [...sheetRels, stylesRel, themeRel, sharedStringsRel];
+    return [
+        constants_js_1.XML_DECLARATION,
+        (0, build_xml_js_1.buildXml)({
+            attrs: { xmlns: constants_js_1.XML_NAMESPACES.PACKAGE_RELATIONSHIPS },
+            children: allRels,
+            tag: "Relationships",
+        }),
+    ].join("\n");
+}

package/build/cjs/lib/workbook-builder/utils/build-workbook-xml.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWorkbookXml = buildWorkbookXml;
+const constants_js_1 = require("./constants.js");
+const build_xml_js_1 = require("./build-xml.js");
+function buildWorkbookXml(sheets) {
+    return [
+        constants_js_1.XML_DECLARATION,
+        (0, build_xml_js_1.buildXml)({
+            attrs: {
+                xmlns: constants_js_1.XML_NAMESPACES.SPREADSHEET_ML,
+                "xmlns:r": constants_js_1.XML_NAMESPACES.OFFICE_DOCUMENT,
+            },
+            children: [
+                {
+                    children: sheets.map((sheet, i) => ({
+                        attrs: { name: sheet.name, "r:id": `rId${i + 1}`, sheetId: (i + 1).toString() },
+                        tag: "sheet",
+                    })),
+                    tag: "sheets",
+                },
+            ],
+            tag: "workbook",
+        }),
+    ].join("\n");
+}

package/build/cjs/lib/workbook-builder/utils/build-worksheet-xml.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildWorksheetXml = buildWorksheetXml;
+const constants_js_1 = require("./constants.js");
+const build_cell_children_js_1 = require("./build-cell-children.js");
+const build_xml_js_1 = require("./build-xml.js");
+function buildWorksheetXml(rows = new Map(), merges = []) {
+    const typeSetSkipping = new Set(["n"]);
+    const children = [
+        {
+            attrs: { ref: "A1:A1" },
+            tag: "dimension",
+        },
+        {
+            children: [{ attrs: { workbookViewId: "0" }, tag: "sheetView" }],
+            tag: "sheetViews",
+        },
+        {
+            attrs: { defaultRowHeight: "15" },
+            tag: "sheetFormatPr",
+        },
+        {
+            children: Array.from(rows.entries()).map(([rowNumber, row]) => ({
+                attrs: { r: rowNumber.toString() },
+                children: Array.from(row.cells.entries()).map(([colNumber, cell]) => {
+                    const cellRef = `${colNumber}${rowNumber}`;
+                    const attrT = (cell.type && typeSetSkipping.has(cell.type))
+                        ? undefined
+                        : cell.type;
+                    return {
+                        attrs: {
+                            r: cellRef,
+                            s: cell.style?.index,
+                            t: attrT,
+                        },
+                        children: (0, build_cell_children_js_1.buildCellChildren)(cell),
+                        tag: "c",
+                    };
+                }),
+                tag: "row",
+            })),
+            tag: "sheetData",
+        },
+    ];
+    if (merges.length > 0) {
+        children.push({
+            attrs: { count: merges.length.toString() },
+            children: merges.map((ref) => ({
+                attrs: { ref },
+                tag: "mergeCell",
+            })),
+            tag: "mergeCells",
+        });
+    }
+    return [
+        constants_js_1.XML_DECLARATION,
+        (0, build_xml_js_1.buildXml)({
+            attrs: {
+                xmlns: constants_js_1.XML_NAMESPACES.SPREADSHEET_ML,
+                "xmlns:r": constants_js_1.XML_NAMESPACES.OFFICE_DOCUMENT,
+            },
+            children,
+            tag: "worksheet",
+        }),
+    ].join("\n");
+}

package/build/cjs/lib/workbook-builder/utils/build-xml.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildXml = buildXml;
+/**
+ * Builds XML string from an XmlNode structure.
+ *
+ * @param node - The XML node to convert to string
+ * @param level - The indentation level for formatting (default: 0)
+ *
+ * @returns The formatted XML string
+ */
+function buildXml(node, level = 0) {
+    const { attrs = {}, children = [], tag } = node;
+    const attrStr = Object.entries(attrs)
+        .filter(attr => ((attr[1] !== undefined) && (attr[1] !== null)))
+        .map(([k, v]) => ` ${k}="${v}"`)
+        .join("");
+    const gap = "  ".repeat(level);
+    // No children → self-closing tag
+    if (!children.length) {
+        return `${gap}<${tag}${attrStr}/>`;
+    }
+    // Single text child → inline formatting
+    if (children.length === 1 && typeof children[0] === "string" && !children[0].includes("<")) {
+        return `${gap}<${tag}${attrStr}>${children[0].trimEnd()}</${tag}>`;
+    }
+    // Has children → recursive rendering
+    const inner = children
+        .map(c => typeof c === "string" ? `${"  ".repeat(level + 1)}${c.trimEnd()}` : buildXml(c, level + 1))
+        .join("\n");
+    return `${gap}<${tag}${attrStr}>\n${inner}\n${gap}</${tag}>`;
+}
+/**
+ * Cell XML Structure Documentation
+ *
+ * Reference: https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.cell?view=openxml-3.0.1
+ *
+ * Parent Elements:
+ * - row
+ *
+ * Child Elements:
+ * - extLst (Future Feature Data Storage Area)
+ * - f (Formula)
+ * - is (Rich Text Inline)
+ * - v (Cell Value)
+ *
+ * Attributes:
+ * - cm (Cell Metadata Index): The zero-based index of the cell metadata record associated with this cell.
+ *   Metadata information is found in the Metadata Part. Cell metadata is extra information stored at the
+ *   cell level, and is attached to the cell (travels through moves, copy / paste, clear, etc).
+ *   Cell metadata is not accessible via formula reference.
+ *   The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype.
+ *
+ * - ph (Show Phonetic): A Boolean value indicating if the spreadsheet application should show phonetic
+ *   information. Phonetic information is displayed in the same cell across the top of the cell and serves
+ *   as a 'hint' which indicates how the text should be pronounced. This should only be used for East Asian languages.
+ *   The possible values for this attribute are defined by the W3C XML Schema boolean datatype.
+ *
+ * - r (Reference): An A1 style reference to the location of this cell
+ *   The possible values for this attribute are defined by the ST_CellRef simple type.
+ *
+ * - s (Style Index): The index of this cell's style. Style records are stored in the Styles Part.
+ *   The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype.
+ *
+ * - t (Cell Data Type): An enumeration representing the cell's data type.
+ *   The possible values for this attribute are defined by the ST_CellType simple type.
+ *
+ * - vm (Value Metadata Index): The zero-based index of the value metadata record associated with this cell's value.
+ *   Metadata records are stored in the Metadata Part. Value metadata is extra information stored at the cell level,
+ *   but associated with the value rather than the cell itself. Value metadata is accessible via formula reference.
+ *   The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype.
+ */

package/build/cjs/lib/workbook-builder/utils/constants.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XML_NAMESPACES = exports.XML_DECLARATION = exports.RELATIONSHIP_TYPES = exports.FILE_PATHS = exports.CONTENT_TYPES = void 0;
+// Content Types
+exports.CONTENT_TYPES = {
+    APP: "application/vnd.openxmlformats-officedocument.extended-properties+xml",
+    CORE: "application/vnd.openxmlformats-package.core-properties+xml",
+    RELATIONSHIPS: "application/vnd.openxmlformats-package.relationships+xml",
+    SHARED_STRINGS: "application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml",
+    STYLES: "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml",
+    THEME: "application/vnd.openxmlformats-officedocument.theme+xml",
+    WORKBOOK: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml",
+    WORKSHEET: "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml",
+    XML: "application/xml",
+};
+// Default file paths
+exports.FILE_PATHS = {
+    APP: "docProps/app.xml",
+    CONTENT_TYPES: "[Content_Types].xml",
+    CORE: "docProps/core.xml",
+    RELS: "_rels/.rels",
+    SHARED_STRINGS: "xl/sharedStrings.xml",
+    STYLES: "xl/styles.xml",
+    THEME: "xl/theme/theme1.xml",
+    WORKBOOK: "xl/workbook.xml",
+    WORKBOOK_RELS: "xl/_rels/workbook.xml.rels",
+    WORKSHEET: "xl/worksheets/sheet1.xml",
+};
+// Relationship Types
+exports.RELATIONSHIP_TYPES = {
+    APP: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties",
+    CORE: "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties",
+    OFFICE_DOCUMENT: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument",
+    SHARED_STRINGS: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings",
+    STYLES: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles",
+    THEME: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme",
+    WORKSHEET: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet",
+};
+// XML Declarations
+exports.XML_DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>";
+// XML Namespaces
+exports.XML_NAMESPACES = {
+    CONTENT_TYPES: "http://schemas.openxmlformats.org/package/2006/content-types",
+    CORE_PROPERTIES: "http://schemas.openxmlformats.org/package/2006/metadata/core-properties",
+    DC: "http://purl.org/dc/elements/1.1/",
+    DCMITYPE: "http://purl.org/dc/dcmitype/",
+    DCTERMS: "http://purl.org/dc/terms/",
+    DOC_PROPS_VTYPES: "http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes",
+    DRAWINGML: "http://schemas.openxmlformats.org/drawingml/2006/main",
+    EXTENDED_PROPERTIES: "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties",
+    OFFICE_DOCUMENT: "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+    PACKAGE_RELATIONSHIPS: "http://schemas.openxmlformats.org/package/2006/relationships",
+    SPREADSHEET_ML: "http://schemas.openxmlformats.org/spreadsheetml/2006/main",
+    XSI: "http://www.w3.org/2001/XMLSchema-instance",
+};

package/build/cjs/lib/workbook-builder/utils/date-to-excel-serial.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dateToExcelSerial = dateToExcelSerial;
+/**
+ * Converts a JavaScript Date object to Excel serial number format.
+ * Excel stores dates as serial numbers where 1 represents January 1, 1900.
+ *
+ * @param date - The JavaScript Date object to convert
+ *
+ * @returns The Excel serial number as a floating-point number
+ */
+function dateToExcelSerial(date) {
+    const msPerDay = 24 * 60 * 60 * 1000;
+    const excelEpoch = Date.UTC(1899, 11, 30); // Excel "day 0"
+    return (date.getTime() - excelEpoch) / msPerDay;
+}

package/build/cjs/lib/workbook-builder/utils/index.js

@@ -0,0 +1,34 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./build-app-xml.js"), exports);
+__exportStar(require("./build-cell-children.js"), exports);
+__exportStar(require("./build-content-types-xml.js"), exports);
+__exportStar(require("./build-shared-strings-xml.js"), exports);
+__exportStar(require("./build-styles-xml.js"), exports);
+__exportStar(require("./build-theme-xml.js"), exports);
+__exportStar(require("./build-workbook-rels-xml.js"), exports);
+__exportStar(require("./build-workbook-xml.js"), exports);
+__exportStar(require("./build-worksheet-xml.js"), exports);
+__exportStar(require("./build-xml.js"), exports);
+__exportStar(require("./constants.js"), exports);
+__exportStar(require("./date-to-excel-serial.js"), exports);
+__exportStar(require("./initialize-files.js"), exports);
+__exportStar(require("./sheet.js"), exports);
+__exportStar(require("./write-shared-strings-xml.js"), exports);
+__exportStar(require("./write-styles-xml.js"), exports);
+__exportStar(require("./write-worksheet-xml.js"), exports);
+__exportStar(require("./write-xml.js"), exports);

package/build/cjs/lib/workbook-builder/utils/initialize-files.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initializeFiles = void 0;
+const build_app_xml_js_1 = require("./build-app-xml.js");
+const build_content_types_xml_js_1 = require("./build-content-types-xml.js");
+const build_core_xml_js_1 = require("./build-core-xml.js");
+const build_rels_xml_js_1 = require("./build-rels-xml.js");
+const build_shared_strings_xml_js_1 = require("./build-shared-strings-xml.js");
+const build_styles_xml_js_1 = require("./build-styles-xml.js");
+const build_theme_xml_js_1 = require("./build-theme-xml.js");
+const build_workbook_rels_xml_js_1 = require("./build-workbook-rels-xml.js");
+const build_workbook_xml_js_1 = require("./build-workbook-xml.js");
+const build_worksheet_xml_js_1 = require("./build-worksheet-xml.js");
+const constants_js_1 = require("./constants.js");
+const initializeFiles = (sheetName) => {
+    const sheetsCount = 1;
+    const contentTypesXml = (0, build_content_types_xml_js_1.buildContentTypesXml)(sheetsCount);
+    const relsXml = (0, build_rels_xml_js_1.buildRelsXml)();
+    const appXml = (0, build_app_xml_js_1.buildAppXml)({ sheetNames: [sheetName] });
+    const coreXml = (0, build_core_xml_js_1.buildCoreXml)();
+    const workbookRelsXml = (0, build_workbook_rels_xml_js_1.buildWorkbookRels)(sheetsCount);
+    const stylesXml = (0, build_styles_xml_js_1.buildStylesXml)();
+    const sharedStringsXml = (0, build_shared_strings_xml_js_1.buildSharedStringsXml)();
+    const themeXml = (0, build_theme_xml_js_1.buildThemeXml)();
+    const workbookXml = (0, build_workbook_xml_js_1.buildWorkbookXml)([{ name: sheetName }]);
+    const worksheetXml = (0, build_worksheet_xml_js_1.buildWorksheetXml)();
+    return {
+        [constants_js_1.FILE_PATHS.CONTENT_TYPES]: contentTypesXml,
+        [constants_js_1.FILE_PATHS.RELS]: relsXml,
+        [constants_js_1.FILE_PATHS.APP]: appXml,
+        [constants_js_1.FILE_PATHS.CORE]: coreXml,
+        [constants_js_1.FILE_PATHS.WORKBOOK_RELS]: workbookRelsXml,
+        [constants_js_1.FILE_PATHS.STYLES]: stylesXml,
+        [constants_js_1.FILE_PATHS.SHARED_STRINGS]: sharedStringsXml,
+        [constants_js_1.FILE_PATHS.THEME]: themeXml,
+        [constants_js_1.FILE_PATHS.WORKBOOK]: workbookXml,
+        [constants_js_1.FILE_PATHS.WORKSHEET]: worksheetXml,
+    };
+};
+exports.initializeFiles = initializeFiles;

package/build/cjs/lib/workbook-builder/utils/sheet.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSheet = createSheet;
+const index_js_1 = require("../../template/utils/index.js");
+const date_to_excel_serial_js_1 = require("./date-to-excel-serial.js");
+/** Maximum number of columns supported by Excel (XFD). */
+const MAX_COLUMNS = 16384;
+/** Maximum number of rows supported by Excel (1,048,576). */
+const MAX_ROWS = 1_048_576;
+/**
+ * Factory for creating a new sheet with bound helpers.
+ *
+ * @param name - Sheet name
+ * @param fn.addMerge - Function to add a merge range (bound to workbook)
+ * @param fn.removeMerge - Function to remove a merge range (bound to workbook)
+ * @param fn.addOrGetStyle - Function to add or get a style index
+ * @param fn.addSharedString - Function to add a shared string and return its index
+ * @returns SheetData instance with helpers
+ */
+function createSheet(name, fn) {
+    const { addMerge, addOrGetStyle, addSharedString, removeMerge, } = fn;
+    const rows = new Map();
+    return {
+        name,
+        rows,
+        addMerge(mergeCell) {
+            return addMerge({ ...mergeCell, sheetName: name });
+        },
+        removeMerge(mergeCell) {
+            return removeMerge({ ...mergeCell, sheetName: name });
+        },
+        setCell(rowIndex, column, cell) {
+            if (rowIndex <= 0) {
+                throw new Error("Invalid rowIndex");
+            }
+            if (!Number.isInteger(rowIndex) || rowIndex <= 0) {
+                throw new Error("Invalid rowIndex: must be a positive integer");
+            }
+            if (rowIndex > MAX_ROWS) {
+                throw new Error(`Invalid rowIndex: exceeds Excel max rows (${MAX_ROWS})`);
+            }
+            if (!rows.has(rowIndex)) {
+                rows.set(rowIndex, { cells: new Map() });
+            }
+            const letterColumn = typeof column === "number"
+                ? (0, index_js_1.columnIndexToLetter)(column)
+                : column;
+            if (!isValidColumn(letterColumn)) {
+                throw new Error(`Invalid column string: "${letterColumn}"`);
+            }
+            // if is Date
+            if (cell.value instanceof Date) {
+                cell.value = (0, date_to_excel_serial_js_1.dateToExcelSerial)(cell.value);
+            }
+            if (cell.isFormula) {
+                cell.type = undefined;
+            }
+            else {
+                if (cell.type === "str") {
+                    throw new Error(`Cell type: "${cell.type}" valid only for formula cells`);
+                }
+                // If type is not provided — detect automatically
+                cell.type = detectCellType(cell.value, cell.type);
+            }
+            // Handle shared string
+            if (cell.type === "s") {
+                const idx = addSharedString(String(cell.value ?? ""), name);
+                cell = { ...cell, value: idx };
+            }
+            if (cell.style) {
+                const styleIndex = addOrGetStyle(cell.style, name);
+                cell.style.index = styleIndex;
+            }
+            rows.get(rowIndex)?.cells.set(letterColumn, cell);
+        },
+        getCell(rowIndex, column) {
+            if (typeof column === "number") {
+                if (column < 0 || column > MAX_COLUMNS) {
+                    throw new Error("Invalid column number");
+                }
+                return rows.get(rowIndex)?.cells.get((0, index_js_1.columnIndexToLetter)(column));
+            }
+            else {
+                if (!isValidColumn(column)) {
+                    throw new Error(`Invalid column string: "${column}"`);
+                }
+                return rows.get(rowIndex)?.cells.get(column);
+            }
+        },
+        removeCell(rowIndex, column) {
+            if (rowIndex <= 0) {
+                throw new Error("Invalid rowIndex");
+            }
+            if (!Number.isInteger(rowIndex) || rowIndex <= 0) {
+                throw new Error("Invalid rowIndex: must be a positive integer");
+            }
+            if (rowIndex > MAX_ROWS) {
+                throw new Error(`Invalid rowIndex: exceeds Excel max rows (${MAX_ROWS})`);
+            }
+            const letterColumn = typeof column === "number"
+                ? (0, index_js_1.columnIndexToLetter)(column)
+                : column;
+            if (!isValidColumn(letterColumn)) {
+                throw new Error(`Invalid column string: "${letterColumn}"`);
+            }
+            return rows.get(rowIndex)?.cells.delete(letterColumn) ?? false;
+        },
+    };
+}
+/** Validates an Excel column string (A-Z, AA, ..., XFD). */
+function isValidColumn(column) {
+    if (!/^[A-Z]+$/.test(column))
+        return false;
+    const idx = (0, index_js_1.columnLetterToIndex)(column);
+    return idx > 0 && idx <= MAX_COLUMNS;
+}
+/**
+ * Detects the appropriate cell type based on the value when not explicitly specified.
+ *
+ * @param value - Cell value
+ * @param explicitType - Explicitly provided type, if any
+ * @returns CellType inferred or the explicit type
+ */
+function detectCellType(value, explicitType) {
+    if (explicitType) {
+        return explicitType;
+    }
+    if (value === null || value === undefined) {
+        // For empty cells we default to numeric type with empty value
+        return "n";
+    }
+    if (typeof value === "number") {
+        return "n";
+    }
+    if (typeof value === "boolean") {
+        return "b";
+    }
+    if (typeof value === "string") {
+        // Default to inlineStr for plain strings
+        return "inlineStr";
+    }
+    // Fallback to inlineStr
+    return "inlineStr";
+}

package/build/cjs/lib/workbook-builder/utils/write-shared-strings-xml.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSharedStringsXml = writeSharedStringsXml;
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const index_js_1 = require("../../utils/index.js");
+const constants_js_1 = require("./constants.js");
+/**
+ * Writes the `sharedStrings.xml` content to a file at the given destination.
+ *
+ * Uses a file write stream with backpressure control to avoid buffering large
+ * content in memory.
+ *
+ * @param destination - Absolute or relative file path to write
+ * @param strings - Array of unique strings used in the workbook
+ * @returns Promise that resolves when the write stream finishes
+ */
+async function writeSharedStringsXml(destination, strings = []) {
+    // Ensure destination folder exists
+    await promises_1.default.mkdir(node_path_1.default.dirname(destination), { recursive: true });
+    const stream = node_fs_1.default.createWriteStream(destination, { encoding: "utf-8" });
+    try {
+        // Document header
+        stream.write(constants_js_1.XML_DECLARATION + "\n");
+        stream.write(`<sst xmlns="${constants_js_1.XML_NAMESPACES.SPREADSHEET_ML}" count="${strings.length}" uniqueCount="${strings.length}">\n`);
+        // Main string items
+        for (const s of strings) {
+            const preserve = /^\s|\s$/.test(s) ? " xml:space=\"preserve\"" : "";
+            const siXml = `<si><t${preserve}>${(0, index_js_1.escapeXml)(s)}</t></si>\n`;
+            // Write with backpressure control
+            if (!stream.write(siXml)) {
+                await new Promise(resolve => stream.once("drain", () => resolve()));
+            }
+        }
+        // Closing tag
+        stream.write("</sst>");
+    }
+    finally {
+        stream.end();
+    }
+    return new Promise((resolve, reject) => {
+        stream.on("error", reject);
+        stream.on("finish", resolve);
+    });
+}