@cj-tech-master/excelts 3.1.0-canary.20260102071304.d80b29d → 4.0.0-canary.20260103013222.0e5d37f

package/dist/browser/modules/excel/stream/workbook-reader.browser.js

@@ -0,0 +1,443 @@
+/**
+ * WorkbookReader - Browser Streaming Workbook Reader
+ *
+ * This module contains the full shared implementation for the streaming
+ * workbook reader and a browser-compatible `WorkbookReader` that buffers
+ * waiting worksheets in memory.
+ *
+ * Node.js uses `workbook-reader.ts`, which extends the same base implementation
+ * with filesystem-specific features (filename input + temp-file buffering).
+ */
+import { EventEmitter, Readable } from "../../stream/index.browser.js";
+import { createParse } from "../../archive/parse.browser.js";
+import { iterateStream } from "../utils/iterate-stream.js";
+import { getWorksheetNoFromWorksheetPath, getWorksheetNoFromWorksheetRelsPath, normalizeZipPath, OOXML_PATHS, worksheetRelTarget } from "../utils/ooxml-paths.js";
+import { parseSax } from "../utils/parse-sax.js";
+import { StylesXform } from "../xlsx/xform/style/styles-xform.js";
+import { WorkbookXform } from "../xlsx/xform/book/workbook-xform.js";
+import { RelationshipsXform } from "../xlsx/xform/core/relationships-xform.js";
+import { WorksheetReader } from "./worksheet-reader.js";
+import { HyperlinkReader } from "./hyperlink-reader.js";
+// ============================================================================
+// Base Class
+// ============================================================================
+export class WorkbookReaderBase extends EventEmitter {
+    getHyperlinkReader(sheetNo) {
+        return this._hyperlinkReadersBySheetNo?.[String(sheetNo)];
+    }
+    getHyperlink(sheetNo, rId) {
+        return this.getHyperlinkReader(sheetNo)?.hyperlinks?.[rId];
+    }
+    getHyperlinkTarget(sheetNo, rId) {
+        return this.getHyperlink(sheetNo, rId)?.target;
+    }
+    constructor(input, options, WorksheetReaderClass, HyperlinkReaderClass) {
+        super();
+        this.input = input;
+        this.WorksheetReaderClass = WorksheetReaderClass;
+        this.HyperlinkReaderClass = HyperlinkReaderClass;
+        this.options = {
+            worksheets: "emit",
+            sharedStrings: "cache",
+            hyperlinks: "ignore",
+            styles: "ignore",
+            entries: "ignore",
+            ...options
+        };
+        this.styles = new StylesXform();
+        this.styles.init();
+    }
+    // Default implementation for CommonInput types
+    _getStream(input) {
+        if (input instanceof Readable) {
+            return input;
+        }
+        // Accept Web ReadableStream (browser fetch() body, Node 18+ fetch(), etc.)
+        if (input &&
+            typeof input === "object" &&
+            typeof input.getReader === "function") {
+            const fromWeb = Readable.fromWeb;
+            if (typeof fromWeb === "function") {
+                return fromWeb(input);
+            }
+            // Browser wrapper supports `{ stream }` constructor option.
+            // Node's Readable does not, so this is best-effort.
+            try {
+                return new Readable({
+                    stream: input
+                });
+            }
+            catch {
+                throw new Error("Could not recognise input: ReadableStream");
+            }
+        }
+        let data = input;
+        if (data instanceof ArrayBuffer) {
+            data = new Uint8Array(data);
+        }
+        if (data instanceof Uint8Array) {
+            // Cross-platform: both Node's Readable and our browser Readable implement `.from()`.
+            return Readable.from([data]);
+        }
+        throw new Error(`Could not recognise input: ${input}`);
+    }
+    _cleanupWaitingWorksheets(_waitingWorksheets) {
+        // Default: attempt best-effort cleanup if the stored object provides it.
+        for (const ws of _waitingWorksheets) {
+            if (ws && typeof ws.cleanup === "function") {
+                ws.cleanup();
+            }
+        }
+    }
+    // Unified implementations using passed-in classes
+    _createWorksheetReader(params) {
+        return new this.WorksheetReaderClass({
+            workbook: this,
+            id: params.id,
+            iterator: params.iterator,
+            options: params.options
+        });
+    }
+    _createHyperlinkReader(params) {
+        return new this.HyperlinkReaderClass({
+            workbook: this,
+            id: params.id,
+            iterator: params.iterator,
+            options: params.options
+        });
+    }
+    async read(input, options) {
+        try {
+            for await (const { eventType, value } of this.parse(input, options)) {
+                switch (eventType) {
+                    case "shared-strings":
+                        this.emit(eventType, value);
+                        break;
+                    case "worksheet":
+                        this.emit(eventType, value);
+                        await value.read();
+                        break;
+                    case "hyperlinks":
+                        this.emit(eventType, value);
+                        break;
+                }
+            }
+            this.emit("end");
+            this.emit("finished");
+        }
+        catch (error) {
+            this.emit("error", error);
+        }
+    }
+    async *[Symbol.asyncIterator]() {
+        for await (const { eventType, value } of this.parse()) {
+            if (eventType === "worksheet") {
+                yield value;
+            }
+        }
+    }
+    async *parse(input, options) {
+        if (options) {
+            this.options = options;
+        }
+        const stream = (this.stream = this._getStream(input || this.input));
+        const waitingWorksheets = [];
+        try {
+            for await (const event of this._parseEntries(stream)) {
+                if (event.eventType === "waiting-worksheet") {
+                    const stored = await this._storeWaitingWorksheet(event.sheetNo, event.entry);
+                    waitingWorksheets.push(stored);
+                }
+                else {
+                    yield event;
+                }
+            }
+            yield* this._processWaitingWorksheets(waitingWorksheets);
+        }
+        catch (error) {
+            this._cleanupWaitingWorksheets(waitingWorksheets);
+            throw error;
+        }
+    }
+    _emitEntry(payload) {
+        if (this.options.entries === "emit") {
+            this.emit("entry", payload);
+        }
+    }
+    async _parseRels(entry) {
+        const xform = new RelationshipsXform();
+        this.workbookRels = await xform.parseStream(iterateStream(entry));
+        // Build fast lookup for worksheet relationship ids.
+        this._workbookRelIdByTarget = Object.create(null);
+        for (const rel of this.workbookRels || []) {
+            if (rel?.Target && rel?.Id) {
+                this._workbookRelIdByTarget[rel.Target] = rel.Id;
+            }
+        }
+    }
+    async _parseWorkbook(entry) {
+        this._emitEntry({ type: "workbook" });
+        const workbook = new WorkbookXform();
+        this.model = await workbook.parseStream(iterateStream(entry));
+        this.properties = workbook.map?.workbookPr;
+        // Build fast lookup for sheet metadata by relationship id.
+        this._sheetByRelId = Object.create(null);
+        for (const sheet of this.model?.sheets || []) {
+            this._sheetByRelId[sheet.rId] = sheet;
+        }
+    }
+    async *_parseSharedStrings(entry) {
+        this._emitEntry({ type: "shared-strings" });
+        switch (this.options.sharedStrings) {
+            case "cache":
+                this.sharedStrings = [];
+                break;
+            case "emit":
+                break;
+            default:
+                return;
+        }
+        let text = null;
+        let richText = [];
+        let index = 0;
+        let font = null;
+        let inRichText = false;
+        for await (const events of parseSax(iterateStream(entry))) {
+            for (const { eventType, value } of events) {
+                if (eventType === "opentag") {
+                    const node = value;
+                    switch (node.name) {
+                        case "b":
+                            font = font || {};
+                            font.bold = true;
+                            break;
+                        case "charset":
+                            font = font || {};
+                            font.charset = parseInt(node.attributes.charset, 10);
+                            break;
+                        case "color":
+                            font = font || {};
+                            font.color = {};
+                            if (node.attributes.rgb) {
+                                font.color.argb = node.attributes.rgb;
+                            }
+                            if (node.attributes.val) {
+                                font.color.argb = node.attributes.val;
+                            }
+                            if (node.attributes.theme) {
+                                font.color.theme = node.attributes.theme;
+                            }
+                            break;
+                        case "family":
+                            font = font || {};
+                            font.family = parseInt(node.attributes.val, 10);
+                            break;
+                        case "i":
+                            font = font || {};
+                            font.italic = true;
+                            break;
+                        case "outline":
+                            font = font || {};
+                            font.outline = true;
+                            break;
+                        case "rFont":
+                            font = font || {};
+                            font.name = node.attributes.val;
+                            break;
+                        case "r":
+                            inRichText = true;
+                            break;
+                        case "si":
+                            font = null;
+                            richText = [];
+                            text = null;
+                            inRichText = false;
+                            break;
+                        case "sz":
+                            font = font || {};
+                            font.size = parseInt(node.attributes.val, 10);
+                            break;
+                        case "strike":
+                            font = font || {};
+                            font.strike = true;
+                            break;
+                        case "t":
+                            text = null;
+                            break;
+                        case "u":
+                            font = font || {};
+                            font.underline = true;
+                            break;
+                        case "vertAlign":
+                            font = font || {};
+                            font.vertAlign = node.attributes.val;
+                            break;
+                    }
+                }
+                else if (eventType === "text") {
+                    text = text ? text + value : value;
+                }
+                else if (eventType === "closetag") {
+                    const node = value;
+                    switch (node.name) {
+                        case "r":
+                            if (inRichText) {
+                                richText.push({ font, text });
+                                font = null;
+                                text = null;
+                            }
+                            break;
+                        case "si":
+                            if (this.options.sharedStrings === "cache") {
+                                this.sharedStrings.push(richText.length ? { richText } : text || "");
+                            }
+                            else if (this.options.sharedStrings === "emit") {
+                                yield { index: index++, text: richText.length ? { richText } : text || "" };
+                            }
+                            richText = [];
+                            font = null;
+                            text = null;
+                            inRichText = false;
+                            break;
+                    }
+                }
+            }
+        }
+    }
+    async _parseStyles(entry) {
+        this._emitEntry({ type: "styles" });
+        if (this.options.styles === "cache") {
+            this.styles = new StylesXform();
+            await this.styles.parseStream(iterateStream(entry));
+        }
+    }
+    *_parseWorksheet(iterator, sheetNo) {
+        this._emitEntry({ type: "worksheet", id: sheetNo });
+        const sheetNoNumber = parseInt(sheetNo, 10);
+        const worksheetReader = this._createWorksheetReader({
+            id: sheetNoNumber,
+            iterator,
+            options: this.options
+        });
+        // Preserve original sheet index from the zip path. `worksheetReader.id` may be remapped
+        // later using workbook metadata.
+        worksheetReader.sheetNo = sheetNoNumber;
+        const relId = this._workbookRelIdByTarget?.[worksheetRelTarget(sheetNo)];
+        const matchingSheet = relId ? this._sheetByRelId?.[relId] : undefined;
+        if (matchingSheet) {
+            worksheetReader.id = matchingSheet.id;
+            worksheetReader.name = matchingSheet.name;
+            worksheetReader.state = matchingSheet.state;
+        }
+        if (this.options.worksheets === "emit") {
+            yield { eventType: "worksheet", value: worksheetReader };
+        }
+    }
+    async *_parseHyperlinks(iterator, sheetNo) {
+        this._emitEntry({ type: "hyperlinks", id: sheetNo });
+        const hyperlinksReader = this._createHyperlinkReader({
+            id: parseInt(sheetNo, 10),
+            iterator,
+            options: this.options
+        });
+        if (this.options.hyperlinks === "cache") {
+            if (!this._hyperlinkReadersBySheetNo) {
+                this._hyperlinkReadersBySheetNo = Object.create(null);
+            }
+            this._hyperlinkReadersBySheetNo[sheetNo] = hyperlinksReader;
+            const readFn = hyperlinksReader.read;
+            if (typeof readFn === "function") {
+                await readFn.call(hyperlinksReader);
+            }
+            return;
+        }
+        if (this.options.hyperlinks === "emit") {
+            yield { eventType: "hyperlinks", value: hyperlinksReader };
+        }
+    }
+    async *_parseEntries(stream) {
+        const zip = createParse({ forceStream: true });
+        stream.on("error", (err) => zip.emit("error", err));
+        stream.pipe(zip);
+        for await (const entry of iterateStream(zip)) {
+            let sheetNo;
+            const normalizedPath = normalizeZipPath(entry.path);
+            switch (normalizedPath) {
+                case OOXML_PATHS.rootRels:
+                    break;
+                case OOXML_PATHS.xlWorkbookRels:
+                    await this._parseRels(entry);
+                    break;
+                case OOXML_PATHS.xlWorkbook:
+                    await this._parseWorkbook(entry);
+                    break;
+                case OOXML_PATHS.xlSharedStrings:
+                    for await (const item of this._parseSharedStrings(entry)) {
+                        yield { eventType: "shared-strings", value: item };
+                    }
+                    break;
+                case OOXML_PATHS.xlStyles:
+                    await this._parseStyles(entry);
+                    break;
+                default:
+                    sheetNo = getWorksheetNoFromWorksheetPath(normalizedPath)?.toString();
+                    if (sheetNo) {
+                        // Performance: only wait for sharedStrings when they are actually needed.
+                        const hasPrerequisites = !!this.workbookRels &&
+                            (this.options.sharedStrings !== "cache" || !!this.sharedStrings);
+                        if (hasPrerequisites) {
+                            yield* this._parseWorksheet(iterateStream(entry), sheetNo);
+                            continue;
+                        }
+                        else {
+                            yield { eventType: "waiting-worksheet", sheetNo, entry };
+                            continue;
+                        }
+                    }
+                    sheetNo = getWorksheetNoFromWorksheetRelsPath(normalizedPath)?.toString();
+                    if (sheetNo) {
+                        yield* this._parseHyperlinks(iterateStream(entry), sheetNo);
+                        continue;
+                    }
+                    break;
+            }
+            entry.autodrain();
+        }
+    }
+}
+export const WorkbookReaderOptionsSchema = {
+    worksheets: ["emit", "ignore"],
+    sharedStrings: ["cache", "emit", "ignore"],
+    hyperlinks: ["cache", "emit", "ignore"],
+    styles: ["cache", "ignore"],
+    entries: ["emit", "ignore"]
+};
+class WorkbookReader extends WorkbookReaderBase {
+    constructor(input, options = {}) {
+        super(input, options, WorksheetReader, HyperlinkReader);
+    }
+    async _storeWaitingWorksheet(sheetNo, entry) {
+        const chunks = [];
+        const encoder = new TextEncoder();
+        for await (const chunk of iterateStream(entry)) {
+            if (chunk instanceof Uint8Array) {
+                chunks.push(chunk);
+            }
+            else if (typeof chunk === "string") {
+                chunks.push(encoder.encode(chunk));
+            }
+        }
+        return { sheetNo, data: chunks };
+    }
+    async *_processWaitingWorksheets(waitingWorksheets) {
+        for (const ws of waitingWorksheets) {
+            const iterator = (async function* () {
+                for (const chunk of ws.data) {
+                    yield chunk;
+                }
+            })();
+            yield* this._parseWorksheet(iterator, ws.sheetNo);
+        }
+    }
+}
+export { WorkbookReader };

package/dist/browser/modules/excel/stream/workbook-reader.d.ts

@@ -0,0 +1,24 @@
+/**
+ * WorkbookReader - Node.js Streaming Workbook Reader
+ *
+ * Extends base with file path support and temp file storage for large files.
+ */
+import type { Readable } from "@stream";
+import { WorksheetReader } from "@excel/stream/worksheet-reader";
+import { HyperlinkReader } from "@excel/stream/hyperlink-reader";
+import { WorkbookReaderBase, type CommonInput, type WorkbookReaderOptions, type WorksheetReadyEvent, WorkbookReaderOptionsSchema } from "@excel/stream/workbook-reader.browser";
+export type { WorkbookReaderOptions, InternalWorksheetOptions, SharedStringRichText, SharedStringValue, WorkbookRelationship, SheetMetadata, WorkbookModel, WorkbookPropertiesXform, ParseEventType, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent, ParseEvent } from "@excel/stream/workbook-reader.browser";
+export type NodeInput = string | CommonInput;
+interface WaitingWorksheet {
+    sheetNo: string;
+    path: string;
+    cleanup: () => void;
+    writePromise: Promise<void>;
+}
+declare class WorkbookReader extends WorkbookReaderBase<NodeInput, WorksheetReader, HyperlinkReader, WaitingWorksheet> {
+    constructor(input: NodeInput, options?: WorkbookReaderOptions);
+    _getStream(input: NodeInput): Readable;
+    _storeWaitingWorksheet(sheetNo: string, entry: any): Promise<WaitingWorksheet>;
+    _processWaitingWorksheets(waitingWorksheets: WaitingWorksheet[]): AsyncIterableIterator<WorksheetReadyEvent<WorksheetReader>>;
+}
+export { WorkbookReader, WorkbookReaderOptionsSchema };

package/dist/browser/modules/excel/stream/workbook-reader.js

@@ -0,0 +1,50 @@
+/**
+ * WorkbookReader - Node.js Streaming Workbook Reader
+ *
+ * Extends base with file path support and temp file storage for large files.
+ */
+import fs from "fs";
+import os from "os";
+import { join } from "path";
+import { iterateStream } from "../utils/iterate-stream.js";
+import { WorksheetReader } from "./worksheet-reader.js";
+import { HyperlinkReader } from "./hyperlink-reader.js";
+import { WorkbookReaderBase, WorkbookReaderOptionsSchema } from "./workbook-reader.browser.js";
+class WorkbookReader extends WorkbookReaderBase {
+    constructor(input, options = {}) {
+        super(input, options, WorksheetReader, HyperlinkReader);
+        this.input = input;
+    }
+    _getStream(input) {
+        if (typeof input === "string") {
+            return fs.createReadStream(input);
+        }
+        return super._getStream(input);
+    }
+    async _storeWaitingWorksheet(sheetNo, entry) {
+        const tmpDir = fs.mkdtempSync(join(os.tmpdir(), "excelts-"));
+        const path = join(tmpDir, `sheet${sheetNo}.xml`);
+        const cleanup = () => fs.rm(tmpDir, { recursive: true, force: true }, () => { });
+        const writePromise = new Promise((resolve, reject) => {
+            const tempStream = fs.createWriteStream(path);
+            tempStream.on("error", reject);
+            tempStream.on("finish", resolve);
+            entry.pipe(tempStream);
+        });
+        return { sheetNo, path, cleanup, writePromise };
+    }
+    async *_processWaitingWorksheets(waitingWorksheets) {
+        for (const ws of waitingWorksheets) {
+            await ws.writePromise;
+            const fileStream = fs.createReadStream(ws.path);
+            try {
+                yield* this._parseWorksheet(iterateStream(fileStream), ws.sheetNo);
+            }
+            finally {
+                fileStream.close();
+                ws.cleanup();
+            }
+        }
+    }
+}
+export { WorkbookReader, WorkbookReaderOptionsSchema };

package/dist/browser/modules/excel/stream/workbook-writer.browser.d.ts

@@ -0,0 +1,147 @@
+/**
+ * WorkbookWriter - Browser Streaming Excel Writer
+ *
+ * This module contains the full cross-platform implementation for the streaming
+ * workbook writer and a browser-compatible `WorkbookWriter` class.
+ *
+ * Node.js uses `workbook-writer.ts`, which extends the same base implementation
+ * with filesystem-specific features (filename output + image loading).
+ */
+import { Zip } from "@archive/streaming-zip";
+import { StreamBuf } from "@excel/utils/stream-buf";
+import { StylesXform } from "@excel/xlsx/xform/style/styles-xform";
+import { SharedStrings } from "@excel/utils/shared-strings";
+import { DefinedNames } from "@excel/defined-names";
+import type { Writable } from "@stream";
+import type { Image, WorkbookView, AddWorksheetOptions } from "@excel/types";
+import { WorksheetWriter } from "@excel/stream/worksheet-writer";
+interface Medium extends Image {
+    type: "image";
+    name: string;
+}
+interface CommentRef {
+    commentName: string;
+    vmlDrawing: string;
+}
+export interface ZlibOptions {
+    flush?: number;
+    finishFlush?: number;
+    chunkSize?: number;
+    windowBits?: number;
+    level?: number;
+    memLevel?: number;
+    strategy?: number;
+    dictionary?: Uint8Array | ArrayBuffer;
+}
+export interface ZipOptions {
+    comment?: string;
+    forceLocalTime?: boolean;
+    forceZip64?: boolean;
+    store?: boolean;
+    zlib?: Partial<ZlibOptions>;
+    compressionOptions?: {
+        level?: number;
+    };
+}
+export interface WorkbookWriterOptions {
+    created?: Date;
+    modified?: Date;
+    creator?: string;
+    lastModifiedBy?: string;
+    lastPrinted?: Date;
+    useSharedStrings?: boolean;
+    useStyles?: boolean;
+    zip?: Partial<ZipOptions>;
+    stream?: Writable | WritableStream<Uint8Array>;
+    filename?: string;
+    trueStreaming?: boolean;
+}
+interface OutputStreamLike {
+    emit(eventName: string | symbol, ...args: any[]): boolean;
+    write(chunk: any): boolean | Promise<boolean>;
+    end(): void;
+    once(eventName: string | symbol, listener: (...args: any[]) => void): this;
+    removeListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
+}
+export interface WorksheetWriterLike {
+    id: number;
+    name: string;
+    rId?: string;
+    committed?: boolean;
+    stream: any;
+    commit(): void;
+}
+export interface WorksheetWriterConstructor<T extends WorksheetWriterLike> {
+    new (options: {
+        id: number;
+        name: string;
+        workbook: any;
+        useSharedStrings: boolean;
+        properties?: any;
+        state?: any;
+        pageSetup?: any;
+        views?: any;
+        autoFilter?: any;
+        headerFooter?: any;
+    }): T;
+}
+export declare abstract class WorkbookWriterBase<TWorksheetWriter extends WorksheetWriterLike> {
+    created: Date;
+    modified: Date;
+    creator: string;
+    lastModifiedBy: string;
+    lastPrinted?: Date;
+    useSharedStrings: boolean;
+    sharedStrings: SharedStrings;
+    styles: StylesXform;
+    _definedNames: DefinedNames;
+    _worksheets: TWorksheetWriter[];
+    views: WorkbookView[];
+    zipOptions?: Partial<ZipOptions>;
+    compressionLevel: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+    media: Medium[];
+    commentRefs: CommentRef[];
+    zip: Zip;
+    stream: OutputStreamLike;
+    promise: Promise<void[]>;
+    protected _trueStreaming: boolean;
+    protected WorksheetWriterClass: WorksheetWriterConstructor<TWorksheetWriter>;
+    constructor(options: WorkbookWriterOptions, WorksheetWriterClass: WorksheetWriterConstructor<TWorksheetWriter>);
+    /**
+     * Create output stream - can be overridden by Node.js to support filename
+     */
+    protected _createOutputStream(options: WorkbookWriterOptions): OutputStreamLike;
+    get definedNames(): DefinedNames;
+    _openStream(path: string): InstanceType<typeof StreamBuf>;
+    _addFile(data: string | Uint8Array, name: string, base64?: boolean): void;
+    _commitWorksheets(): Promise<void>;
+    commit(): Promise<void>;
+    get nextId(): number;
+    addImage(image: Image): number;
+    getImage(id: number): Image | undefined;
+    addWorksheet(name?: string, options?: Partial<AddWorksheetOptions>): TWorksheetWriter;
+    getWorksheet(id?: string | number): TWorksheetWriter | undefined;
+    addStyles(): Promise<void>;
+    addThemes(): Promise<void>;
+    addOfficeRels(): Promise<void>;
+    addContentTypes(): Promise<void>;
+    /**
+     * Add media files - can be overridden by Node.js for file system support
+     */
+    addMedia(): Promise<void[]>;
+    addApp(): Promise<void>;
+    addCore(): Promise<void>;
+    addSharedStrings(): Promise<void>;
+    addWorkbookRels(): Promise<void>;
+    addWorkbook(): Promise<void>;
+    _finalize(): Promise<this>;
+}
+export declare const WorkbookWriterOptionsSchema: {
+    readonly useSharedStrings: readonly ["boolean"];
+    readonly useStyles: readonly ["boolean"];
+    readonly trueStreaming: readonly ["boolean"];
+};
+declare class WorkbookWriter extends WorkbookWriterBase<WorksheetWriter> {
+    constructor(options?: WorkbookWriterOptions);
+}
+export { WorkbookWriter };