@cj-tech-master/excelts 3.0.1 → 3.1.0-canary.20260102043356.6791d4e

package/dist/esm/modules/excel/utils/xml-stream.js

@@ -0,0 +1,179 @@
+import { xmlEncode } from "../../../utils/utils.js";
+// constants
+const OPEN_ANGLE = "<";
+const CLOSE_ANGLE = ">";
+const OPEN_ANGLE_SLASH = "</";
+const CLOSE_SLASH_ANGLE = "/>";
+// Chunk size for periodic consolidation (reduces final join overhead)
+const CHUNK_SIZE = 10000;
+function pushAttribute(xml, name, value) {
+    xml.push(` ${name}="${xmlEncode(value.toString())}"`);
+}
+function pushAttributes(xml, attributes) {
+    if (attributes) {
+        const tmp = [];
+        for (const name in attributes) {
+            if (!Object.prototype.hasOwnProperty.call(attributes, name)) {
+                continue;
+            }
+            const value = attributes[name];
+            if (value !== undefined) {
+                pushAttribute(tmp, name, value);
+            }
+        }
+        xml.push(tmp.join(""));
+    }
+}
+class XmlStream {
+    constructor() {
+        this._xml = [];
+        this._chunks = [];
+        this._stack = [];
+        this._rollbacks = [];
+        this.leaf = false;
+        this.open = false;
+    }
+    _consolidate() {
+        // Consolidation is not rollback-safe: joining and moving fragments into `_chunks`
+        // cannot be undone. Avoid consolidating while a rollback marker is active.
+        if (this._rollbacks.length > 0) {
+            return;
+        }
+        // Periodically join small strings into larger chunks to reduce final join overhead
+        if (this._xml.length >= CHUNK_SIZE) {
+            this._chunks.push(this._xml.join(""));
+            this._xml.length = 0;
+        }
+    }
+    get tos() {
+        return this._stack.length ? this._stack[this._stack.length - 1] : undefined;
+    }
+    get cursor() {
+        // handy way to track whether anything has been added
+        return this._chunks.length * CHUNK_SIZE + this._xml.length;
+    }
+    openXml(docAttributes) {
+        const xml = this._xml;
+        // <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+        xml.push("<?xml");
+        pushAttributes(xml, docAttributes);
+        xml.push("?>\n");
+    }
+    openNode(name, attributes) {
+        const parent = this.tos;
+        const xml = this._xml;
+        if (parent && this.open) {
+            xml.push(CLOSE_ANGLE);
+        }
+        this._stack.push(name);
+        // start streaming node
+        xml.push(OPEN_ANGLE);
+        xml.push(name);
+        pushAttributes(xml, attributes);
+        this.leaf = true;
+        this.open = true;
+    }
+    addAttribute(name, value) {
+        if (!this.open) {
+            throw new Error("Cannot write attributes to node if it is not open");
+        }
+        if (value !== undefined) {
+            pushAttribute(this._xml, name, value);
+        }
+    }
+    addAttributes(attrs) {
+        if (!this.open) {
+            throw new Error("Cannot write attributes to node if it is not open");
+        }
+        pushAttributes(this._xml, attrs);
+    }
+    writeText(text) {
+        const xml = this._xml;
+        if (this.open) {
+            xml.push(CLOSE_ANGLE);
+            this.open = false;
+        }
+        this.leaf = false;
+        xml.push(xmlEncode(text.toString()));
+    }
+    writeXml(xml) {
+        if (this.open) {
+            this._xml.push(CLOSE_ANGLE);
+            this.open = false;
+        }
+        this.leaf = false;
+        this._xml.push(xml);
+    }
+    closeNode() {
+        const node = this._stack.pop();
+        const xml = this._xml;
+        if (this.leaf) {
+            xml.push(CLOSE_SLASH_ANGLE);
+        }
+        else {
+            xml.push(OPEN_ANGLE_SLASH);
+            xml.push(node);
+            xml.push(CLOSE_ANGLE);
+        }
+        this.open = false;
+        this.leaf = false;
+        this._consolidate();
+    }
+    leafNode(name, attributes, text) {
+        this.openNode(name, attributes);
+        if (text !== undefined) {
+            // zeros need to be written
+            this.writeText(text);
+        }
+        this.closeNode();
+    }
+    closeAll() {
+        while (this._stack.length) {
+            this.closeNode();
+        }
+    }
+    addRollback() {
+        this._rollbacks.push({
+            xml: this._xml.length,
+            stack: this._stack.length,
+            leaf: this.leaf ?? false,
+            open: this.open ?? false,
+            chunksLength: this._chunks.length
+        });
+        return this.cursor;
+    }
+    commit() {
+        this._rollbacks.pop();
+    }
+    rollback() {
+        const r = this._rollbacks.pop();
+        if (this._xml.length > r.xml) {
+            this._xml.length = r.xml;
+        }
+        if (this._stack.length > r.stack) {
+            this._stack.length = r.stack;
+        }
+        if (this._chunks.length > r.chunksLength) {
+            this._chunks.length = r.chunksLength;
+        }
+        this.leaf = r.leaf;
+        this.open = r.open;
+    }
+    get xml() {
+        this.closeAll();
+        // Join chunks first, then remaining xml array
+        if (this._chunks.length === 0) {
+            return this._xml.join("");
+        }
+        if (this._xml.length > 0) {
+            this._chunks.push(this._xml.join(""));
+        }
+        return this._chunks.join("");
+    }
+}
+XmlStream.StdDocAttributes = {
+    version: "1.0",
+    encoding: "UTF-8",
+    standalone: "yes"
+};
+export { XmlStream };

package/dist/esm/modules/excel/workbook.js

@@ -0,0 +1,314 @@
+/**
+ * Workbook - Cross-platform Excel Workbook
+ *
+ * Full functionality:
+ * - xlsx: File/stream/buffer support (file operations Node.js only)
+ * - csv: CSV read/write support (file operations Node.js only)
+ * - streaming: createStreamWriter/createStreamReader for large files
+ *
+ * Note: Browser build uses rolldown aliases to swap in browser-specific
+ * implementations for xlsx, csv, and stream modules.
+ */
+import { Worksheet } from "./worksheet.js";
+import { DefinedNames } from "./defined-names.js";
+import { XLSX } from "./xlsx/xlsx.js";
+import { CSV } from "../csv/csv.js";
+import { WorkbookWriter } from "./stream/workbook-writer.js";
+import { WorkbookReader } from "./stream/workbook-reader.js";
+// =============================================================================
+// Workbook Class
+// =============================================================================
+class Workbook {
+    // ===========================================================================
+    // Constructor
+    // ===========================================================================
+    constructor() {
+        this.category = "";
+        this.company = "";
+        this.created = new Date();
+        this.description = "";
+        this.keywords = "";
+        this.manager = "";
+        this.modified = this.created;
+        this.properties = {};
+        this.calcProperties = {};
+        this._worksheets = [];
+        this.subject = "";
+        this.title = "";
+        this.views = [];
+        this.media = [];
+        this.pivotTables = [];
+        this._definedNames = new DefinedNames();
+    }
+    // ===========================================================================
+    // Format Operations (xlsx, csv)
+    // ===========================================================================
+    /**
+     * xlsx file format operations
+     * Node.js: readFile, writeFile, read (stream), write (stream), load (buffer), writeBuffer
+     * Browser: load (buffer), writeBuffer
+     */
+    get xlsx() {
+        if (!this._xlsx) {
+            this._xlsx = new XLSX(this);
+        }
+        return this._xlsx;
+    }
+    /**
+     * csv file format operations
+     * Node.js: readFile, writeFile, read (stream), write (stream)
+     * Browser: load (string/buffer), writeString, writeBuffer
+     */
+    get csv() {
+        if (!this._csv) {
+            this._csv = new CSV(this);
+        }
+        return this._csv;
+    }
+    // ===========================================================================
+    // Static Factory Methods for Streaming
+    // ===========================================================================
+    /**
+     * Create a streaming workbook writer for large files.
+     * This is more memory-efficient than using Workbook for large datasets.
+     *
+     * @param options - Options for the workbook writer
+     *   - Node.js: can use { filename } or { stream }
+     *   - Browser: must use { stream }
+     * @returns A new WorkbookWriter instance
+     *
+     * @example
+     * ```ts
+     * // Node.js with filename
+     * const writer = Workbook.createStreamWriter({ filename: "large-file.xlsx" });
+     *
+     * // Browser or Node.js with stream
+     * const writer = Workbook.createStreamWriter({ stream: writableStream });
+     *
+     * const sheet = writer.addWorksheet("Sheet1");
+     * for (let i = 0; i < 1000000; i++) {
+     *   sheet.addRow([i, `Row ${i}`]).commit();
+     * }
+     * await writer.commit();
+     * ```
+     */
+    static createStreamWriter(options) {
+        return new WorkbookWriter(options);
+    }
+    /**
+     * Create a streaming workbook reader for large files.
+     * This is more memory-efficient than using Workbook.xlsx.readFile for large datasets.
+     *
+     * @param input - File path (Node.js only) or readable stream
+     * @param options - Options for the workbook reader
+     * @returns A new WorkbookReader instance
+     *
+     * @example
+     * ```ts
+     * // Node.js with file path
+     * const reader = Workbook.createStreamReader("large-file.xlsx");
+     *
+     * // Browser or Node.js with stream
+     * const reader = Workbook.createStreamReader(readableStream);
+     *
+     * for await (const event of reader) {
+     *   if (event.eventType === "worksheet") {
+     *     const worksheet = event.value;
+     *     for await (const row of worksheet) {
+     *       console.log(row.values);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    static createStreamReader(input, options) {
+        return new WorkbookReader(input, options);
+    }
+    // ===========================================================================
+    // Worksheet Management
+    // ===========================================================================
+    get nextId() {
+        // Find the next unique spot to add worksheet
+        for (let i = 1; i < this._worksheets.length; i++) {
+            if (!this._worksheets[i]) {
+                return i;
+            }
+        }
+        return this._worksheets.length || 1;
+    }
+    /**
+     * Add a new worksheet and return a reference to it
+     */
+    addWorksheet(name, options) {
+        const id = this.nextId;
+        const lastOrderNo = this._worksheets.reduce((acc, ws) => ((ws && ws.orderNo) > acc ? ws.orderNo : acc), 0);
+        const worksheetOptions = {
+            ...options,
+            id,
+            name,
+            orderNo: lastOrderNo + 1,
+            workbook: this
+        };
+        const worksheet = new Worksheet(worksheetOptions);
+        this._worksheets[id] = worksheet;
+        return worksheet;
+    }
+    removeWorksheetEx(worksheet) {
+        delete this._worksheets[worksheet.id];
+    }
+    removeWorksheet(id) {
+        const worksheet = this.getWorksheet(id);
+        if (worksheet) {
+            worksheet.destroy();
+        }
+    }
+    /**
+     * Fetch sheet by name or id
+     */
+    getWorksheet(id) {
+        if (id === undefined) {
+            return this._worksheets.find(Boolean);
+        }
+        if (typeof id === "number") {
+            return this._worksheets[id];
+        }
+        if (typeof id === "string") {
+            return this._worksheets.find(worksheet => worksheet && worksheet.name === id);
+        }
+        return undefined;
+    }
+    /**
+     * Return a clone of worksheets in order
+     */
+    get worksheets() {
+        return this._worksheets
+            .slice(1)
+            .sort((a, b) => a.orderNo - b.orderNo)
+            .filter(Boolean);
+    }
+    /**
+     * Iterate over all sheets.
+     *
+     * Note: `workbook.worksheets.forEach` will still work but this is better.
+     */
+    eachSheet(callback) {
+        this.worksheets.forEach(sheet => {
+            callback(sheet, sheet.id);
+        });
+    }
+    // ===========================================================================
+    // Defined Names
+    // ===========================================================================
+    get definedNames() {
+        return this._definedNames;
+    }
+    // ===========================================================================
+    // Themes
+    // ===========================================================================
+    clearThemes() {
+        // Note: themes are not an exposed feature, meddle at your peril!
+        this._themes = undefined;
+    }
+    // ===========================================================================
+    // Images
+    // ===========================================================================
+    /**
+     * Add Image to Workbook and return the id
+     */
+    addImage(image) {
+        const id = this.media.length;
+        this.media.push({ ...image, type: "image" });
+        return id;
+    }
+    getImage(id) {
+        return this.media[Number(id)];
+    }
+    // ===========================================================================
+    // Model (Serialization)
+    // ===========================================================================
+    get model() {
+        return {
+            creator: this.creator || "Unknown",
+            lastModifiedBy: this.lastModifiedBy || "Unknown",
+            lastPrinted: this.lastPrinted,
+            created: this.created,
+            modified: this.modified,
+            properties: this.properties,
+            worksheets: this.worksheets.map(worksheet => worksheet.model),
+            sheets: this.worksheets.map(ws => ws.model).filter(Boolean),
+            definedNames: this._definedNames.model,
+            views: this.views,
+            company: this.company,
+            manager: this.manager,
+            title: this.title,
+            subject: this.subject,
+            keywords: this.keywords,
+            category: this.category,
+            description: this.description,
+            language: this.language,
+            revision: this.revision,
+            contentStatus: this.contentStatus,
+            themes: this._themes,
+            media: this.media,
+            pivotTables: this.pivotTables,
+            calcProperties: this.calcProperties
+        };
+    }
+    set model(value) {
+        this.creator = value.creator;
+        this.lastModifiedBy = value.lastModifiedBy;
+        this.lastPrinted = value.lastPrinted;
+        this.created = value.created;
+        this.modified = value.modified;
+        this.company = value.company;
+        this.manager = value.manager;
+        this.title = value.title;
+        this.subject = value.subject;
+        this.keywords = value.keywords;
+        this.category = value.category;
+        this.description = value.description;
+        this.language = value.language;
+        this.revision = value.revision;
+        this.contentStatus = value.contentStatus;
+        this.properties = value.properties;
+        this.calcProperties = value.calcProperties;
+        this._worksheets = [];
+        value.worksheets.forEach(worksheetModel => {
+            const { id, name, state } = worksheetModel;
+            const orderNo = value.sheets && value.sheets.findIndex(ws => ws.id === id);
+            const worksheet = (this._worksheets[id] = new Worksheet({
+                id,
+                name,
+                orderNo: orderNo !== -1 ? orderNo : undefined,
+                state,
+                workbook: this
+            }));
+            worksheet.model = worksheetModel;
+        });
+        this._definedNames.model = value.definedNames;
+        this.views = value.views;
+        this._themes = value.themes;
+        this.media = value.media || [];
+        // Handle pivot tables - either newly created or loaded from file
+        // Loaded pivot tables come from loadedPivotTables after reconciliation
+        this.pivotTables = value.pivotTables || value.loadedPivotTables || [];
+    }
+}
+// ===========================================================================
+// Static Properties
+// ===========================================================================
+/**
+ * Streaming workbook writer class for large files.
+ * @example
+ * // Node.js: new Workbook.Writer({ filename: "large.xlsx" })
+ * // Browser: new Workbook.Writer({ stream: writableStream })
+ */
+Workbook.Writer = WorkbookWriter;
+/**
+ * Streaming workbook reader class for large files.
+ * @example
+ * // Node.js: new Workbook.Reader("large.xlsx")
+ * // Browser: new Workbook.Reader(readableStream)
+ */
+Workbook.Reader = WorkbookReader;
+export { Workbook };