@cj-tech-master/excelts 4.0.0 → 4.0.1

package/README.md

@@ -303,7 +303,7 @@ const url = URL.createObjectURL(blob);
 ### Using with Script Tags (No Bundler)
 
 ```html
-<script src="https://unpkg.com/@cj-tech-master/excelts/dist/browser/excelts.iife.min.js"></script>
+<script src="https://unpkg.com/@cj-tech-master/excelts/dist/iife/excelts.iife.min.js"></script>
 <script>
   const { Workbook } = ExcelTS;
   const wb = new Workbook();
@@ -320,7 +320,7 @@ For a quick manual smoke test in a real browser (create/download/read XLSX, work
 Steps:
 
 ```bash
-npm run build:browser
+npm run build:browser:bundle
 npx serve .
 ```
 

package/README_zh.md

@@ -303,7 +303,7 @@ const url = URL.createObjectURL(blob);
 ### 使用 Script 标签（无打包工具）
 
 ```html
-<script src="https://unpkg.com/@cj-tech-master/excelts/dist/browser/excelts.iife.min.js"></script>
+<script src="https://unpkg.com/@cj-tech-master/excelts/dist/iife/excelts.iife.min.js"></script>
 <script>
   const { Workbook } = ExcelTS;
   const wb = new Workbook();
@@ -320,7 +320,7 @@ const url = URL.createObjectURL(blob);
 使用方式：
 
 ```bash
-npm run build:browser
+npm run build:browser:bundle
 npx serve .
 ```
 

package/dist/browser/index.browser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Browser entry point - No Node.js dependencies
+ * This version is optimized for browser environments with minimal bundle size
+ */
+export { Workbook } from "@excel/workbook";
+export { Worksheet } from "@excel/worksheet";
+export { Row } from "@excel/row";
+export { Column } from "@excel/column";
+export { Cell } from "@excel/cell";
+export { Range } from "@excel/range";
+export { Image } from "@excel/image";
+export * from "@excel/anchor";
+export { Table } from "@excel/table";
+export { DataValidations } from "@excel/data-validations";
+export * from "@excel/enums";
+export * from "@excel/types";
+export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "@excel/pivot-table";
+import { WorkbookWriter } from "@excel/stream/workbook-writer.browser";
+import { WorkbookReader } from "@excel/stream/workbook-reader.browser";
+import { WorksheetWriter } from "@excel/stream/worksheet-writer";
+import { WorksheetReader } from "@excel/stream/worksheet-reader";
+export { WorkbookWriter, WorkbookReader, WorksheetWriter, WorksheetReader };
+export type { CsvReadOptions, CsvWriteOptions, CsvStreamReadOptions, CsvStreamWriteOptions } from "@csv/csv.browser";
+export { CsvParserStream, CsvFormatterStream } from "@csv/csv.browser";
+export * from "@excel/utils/sheet-utils";

package/dist/browser/index.browser.js

@@ -0,0 +1,40 @@
+/**
+ * Browser entry point - No Node.js dependencies
+ * This version is optimized for browser environments with minimal bundle size
+ */
+// =============================================================================
+// Main Classes (Browser-compatible)
+// =============================================================================
+export { Workbook } from "./modules/excel/workbook.js";
+export { Worksheet } from "./modules/excel/worksheet.js";
+export { Row } from "./modules/excel/row.js";
+export { Column } from "./modules/excel/column.js";
+export { Cell } from "./modules/excel/cell.js";
+export { Range } from "./modules/excel/range.js";
+export { Image } from "./modules/excel/image.js";
+export * from "./modules/excel/anchor.js";
+export { Table } from "./modules/excel/table.js";
+export { DataValidations } from "./modules/excel/data-validations.js";
+// =============================================================================
+// Enums
+// =============================================================================
+export * from "./modules/excel/enums.js";
+// =============================================================================
+// Types
+// =============================================================================
+// Export all type definitions from types.ts
+export * from "./modules/excel/types.js";
+// =============================================================================
+// Streaming Writer (Browser-compatible)
+// Uses cross-platform base implementation without Node.js fs
+// =============================================================================
+import { WorkbookWriter } from "./modules/excel/stream/workbook-writer.browser.js";
+import { WorkbookReader } from "./modules/excel/stream/workbook-reader.browser.js";
+import { WorksheetWriter } from "./modules/excel/stream/worksheet-writer.js";
+import { WorksheetReader } from "./modules/excel/stream/worksheet-reader.js";
+export { WorkbookWriter, WorkbookReader, WorksheetWriter, WorksheetReader };
+export { CsvParserStream, CsvFormatterStream } from "./modules/csv/csv.browser.js";
+// =============================================================================
+// Utilities
+// =============================================================================
+export * from "./modules/excel/utils/sheet-utils.js";

package/dist/browser/index.d.ts

@@ -0,0 +1,23 @@
+export { Workbook } from "@excel/workbook";
+export { Worksheet } from "@excel/worksheet";
+export { Row } from "@excel/row";
+export { Column } from "@excel/column";
+export { Cell } from "@excel/cell";
+export { Range } from "@excel/range";
+export { Image } from "@excel/image";
+export * from "@excel/anchor";
+export { Table } from "@excel/table";
+export { DataValidations } from "@excel/data-validations";
+export { WorkbookWriter } from "@excel/stream/workbook-writer";
+export { WorkbookReader } from "@excel/stream/workbook-reader";
+export { WorksheetWriter } from "@excel/stream/worksheet-writer";
+export { WorksheetReader } from "@excel/stream/worksheet-reader";
+export * from "@excel/enums";
+export * from "@excel/types";
+export type { PivotTable, PivotTableModel, PivotTableSource, CacheField, DataField, PivotTableSubtotal, ParsedCacheDefinition, ParsedCacheRecords } from "@excel/pivot-table";
+export type { WorkbookReaderOptions, ParseEvent, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent } from "@excel/stream/workbook-reader";
+export type { WorksheetReaderOptions, WorksheetEvent, RowEvent, HyperlinkEvent, WorksheetHyperlink } from "@excel/stream/worksheet-reader";
+export type { WorkbookWriterOptions, ZipOptions, ZlibOptions } from "@excel/stream/workbook-writer";
+export type { CsvReadOptions, CsvWriteOptions, CsvStreamReadOptions, CsvStreamWriteOptions } from "@csv/csv";
+export { CsvParserStream, CsvFormatterStream } from "@csv/csv";
+export * from "@excel/utils/sheet-utils";

package/dist/browser/index.js

@@ -0,0 +1,35 @@
+// =============================================================================
+// Main Classes
+// =============================================================================
+export { Workbook } from "./modules/excel/workbook.js";
+export { Worksheet } from "./modules/excel/worksheet.js";
+export { Row } from "./modules/excel/row.js";
+export { Column } from "./modules/excel/column.js";
+export { Cell } from "./modules/excel/cell.js";
+export { Range } from "./modules/excel/range.js";
+export { Image } from "./modules/excel/image.js";
+export * from "./modules/excel/anchor.js";
+export { Table } from "./modules/excel/table.js";
+export { DataValidations } from "./modules/excel/data-validations.js";
+// =============================================================================
+// Node.js Only: Streaming Classes
+// These can also be accessed via Workbook.createStreamWriter/createStreamReader
+// =============================================================================
+export { WorkbookWriter } from "./modules/excel/stream/workbook-writer.browser.js";
+export { WorkbookReader } from "./modules/excel/stream/workbook-reader.browser.js";
+export { WorksheetWriter } from "./modules/excel/stream/worksheet-writer.js";
+export { WorksheetReader } from "./modules/excel/stream/worksheet-reader.js";
+// =============================================================================
+// Enums
+// =============================================================================
+export * from "./modules/excel/enums.js";
+// =============================================================================
+// Types
+// =============================================================================
+// Export all type definitions from types.ts
+export * from "./modules/excel/types.js";
+export { CsvParserStream, CsvFormatterStream } from "./modules/csv/csv.browser.js";
+// =============================================================================
+// Utilities
+// =============================================================================
+export * from "./modules/excel/utils/sheet-utils.js";

package/dist/browser/modules/archive/byte-queue.d.ts

@@ -0,0 +1,18 @@
+export declare class ByteQueue {
+    private static readonly EMPTY;
+    private _buf;
+    private _start;
+    private _end;
+    private _cachedView;
+    private _cachedBuf;
+    private _cachedStart;
+    private _cachedEnd;
+    constructor(initial?: Uint8Array);
+    get length(): number;
+    isEmpty(): boolean;
+    view(): Uint8Array;
+    reset(data?: Uint8Array): void;
+    append(chunk: Uint8Array): void;
+    read(length: number): Uint8Array;
+    discard(length: number): void;
+}

package/dist/browser/modules/archive/byte-queue.js

@@ -0,0 +1,125 @@
+export class ByteQueue {
+    constructor(initial) {
+        this._start = 0;
+        this._end = 0;
+        this._cachedView = null;
+        this._cachedBuf = null;
+        this._cachedStart = 0;
+        this._cachedEnd = 0;
+        this._buf = new Uint8Array(0);
+        if (initial && initial.length > 0) {
+            this.reset(initial);
+        }
+    }
+    get length() {
+        return this._end - this._start;
+    }
+    isEmpty() {
+        return this.length === 0;
+    }
+    view() {
+        if (this._start === this._end) {
+            return ByteQueue.EMPTY;
+        }
+        if (this._cachedView &&
+            this._cachedBuf === this._buf &&
+            this._cachedStart === this._start &&
+            this._cachedEnd === this._end) {
+            return this._cachedView;
+        }
+        const view = this._buf.subarray(this._start, this._end);
+        this._cachedView = view;
+        this._cachedBuf = this._buf;
+        this._cachedStart = this._start;
+        this._cachedEnd = this._end;
+        return view;
+    }
+    reset(data) {
+        this._cachedView = null;
+        this._cachedBuf = null;
+        if (!data || data.length === 0) {
+            this._buf = ByteQueue.EMPTY;
+            this._start = 0;
+            this._end = 0;
+            return;
+        }
+        // Keep a private copy to ensure future writes cannot mutate the source.
+        const copy = new Uint8Array(data.length);
+        copy.set(data);
+        this._buf = copy;
+        this._start = 0;
+        this._end = copy.length;
+    }
+    append(chunk) {
+        if (chunk.length === 0) {
+            return;
+        }
+        this._cachedView = null;
+        this._cachedBuf = null;
+        const unread = this.length;
+        // Fast path: enough tail room.
+        if (this._end + chunk.length <= this._buf.length) {
+            this._buf.set(chunk, this._end);
+            this._end += chunk.length;
+            return;
+        }
+        // Allocate a new buffer and copy unread bytes (never compacts in-place).
+        const required = unread + chunk.length;
+        const nextSize = this._buf.length === 0 ? required : Math.max(this._buf.length * 2, required);
+        const next = new Uint8Array(nextSize);
+        if (unread > 0) {
+            next.set(this._buf.subarray(this._start, this._end), 0);
+        }
+        next.set(chunk, unread);
+        this._buf = next;
+        this._start = 0;
+        this._end = required;
+    }
+    read(length) {
+        if (length <= 0) {
+            return new Uint8Array(0);
+        }
+        if (length > this.length) {
+            throw new RangeError("ByteQueue: read beyond available data");
+        }
+        // Return a view for performance.
+        // To keep this safe for async consumers, we must ensure we never write into
+        // the same backing buffer again after it becomes fully consumed.
+        const out = this._buf.subarray(this._start, this._start + length);
+        this._start += length;
+        this._cachedView = null;
+        this._cachedBuf = null;
+        if (this._start === this._end) {
+            // Release backing storage to avoid reusing memory that might still be
+            // referenced by previously returned views.
+            this._buf = ByteQueue.EMPTY;
+            this._start = 0;
+            this._end = 0;
+        }
+        return out;
+    }
+    discard(length) {
+        if (length <= 0) {
+            return;
+        }
+        if (length >= this.length) {
+            // Release backing storage for the same reason as read(): previously
+            // returned views may still be referenced by consumers.
+            this._buf = ByteQueue.EMPTY;
+            this._start = 0;
+            this._end = 0;
+            this._cachedView = null;
+            this._cachedBuf = null;
+            return;
+        }
+        this._start += length;
+        this._cachedView = null;
+        this._cachedBuf = null;
+        if (this._start === this._end) {
+            this._buf = ByteQueue.EMPTY;
+            this._start = 0;
+            this._end = 0;
+        }
+    }
+}
+ByteQueue.EMPTY = new Uint8Array(0);

package/dist/browser/modules/archive/compress.base.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Base compression utilities using Web Streams API
+ * Shared between Node.js and Browser implementations
+ *
+ * Uses CompressionStream/DecompressionStream API with "deflate-raw" format
+ * (raw DEFLATE without zlib header/trailer, required for ZIP files)
+ *
+ * Browser fallback: For browsers without deflate-raw support (Firefox < 113, Safari < 16.4),
+ * see deflate-fallback.ts for pure JS implementation
+ */
+/**
+ * Compression options
+ */
+export interface CompressOptions {
+    /**
+     * Compression level (0-9)
+     * - 0: No compression (STORE)
+     * - 1: Fastest compression
+     * - 6: Default compression (good balance)
+     * - 9: Best compression (slowest)
+     *
+     * Note: CompressionStream does not support level configuration,
+     * it uses a fixed level (~6)
+     */
+    level?: number;
+    /**
+     * Threshold (in bytes) to choose the lower-overhead path.
+     *
+     * - Node.js: inputs <= threshold use sync zlib fast-path (avoid threadpool overhead)
+     * - Browser: inputs <= threshold use the pure-JS fallback (avoid stream scheduling overhead)
+     */
+    thresholdBytes?: number;
+}
+/**
+ * Default threshold (in bytes) to choose the lower-overhead path.
+ *
+ * This is a performance knob, not a correctness requirement.
+ */
+export declare const DEFAULT_COMPRESS_THRESHOLD_BYTES: number;
+/**
+ * Resolve the effective threshold bytes.
+ */
+export declare function resolveCompressThresholdBytes(options: CompressOptions): number;
+/**
+ * Check if CompressionStream is available
+ */
+export declare function hasCompressionStream(): boolean;
+/**
+ * Non-cached probe for CompressionStream("deflate-raw") support.
+ *
+ * Prefer this in code paths that want up-to-date environment checks
+ * (e.g. tests that stub globals).
+ */
+export declare function probeDeflateRawCompressionStream(): boolean;
+/**
+ * Non-cached probe for DecompressionStream("deflate-raw") support.
+ */
+export declare function probeDeflateRawDecompressionStream(): boolean;
+/**
+ * Non-cached probe for full deflate-raw Web Streams support.
+ *
+ * Returns true only if BOTH CompressionStream("deflate-raw") and
+ * DecompressionStream("deflate-raw") are supported.
+ */
+export declare function probeDeflateRawWebStreams(): boolean;
+/**
+ * Check if CompressionStream supports the "deflate-raw" format.
+ *
+ * This is a stricter check than {@link hasCompressionStream} because some
+ * environments expose CompressionStream but do not support "deflate-raw".
+ */
+export declare function hasDeflateRawCompressionStream(): boolean;
+/**
+ * Check if DecompressionStream supports the "deflate-raw" format.
+ */
+export declare function hasDeflateRawDecompressionStream(): boolean;
+/**
+ * Cached check for full deflate-raw Web Streams support.
+ *
+ * Returns true only if BOTH CompressionStream("deflate-raw") and
+ * DecompressionStream("deflate-raw") are supported.
+ */
+export declare function hasDeflateRawWebStreams(): boolean;
+/**
+ * Compress using CompressionStream API
+ * Uses "deflate-raw" format (required for ZIP files)
+ *
+ * @param data - Data to compress
+ * @returns Compressed data
+ */
+export declare function compressWithStream(data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decompress using DecompressionStream API
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export declare function decompressWithStream(data: Uint8Array): Promise<Uint8Array>;

package/dist/browser/modules/archive/compress.base.js

@@ -0,0 +1,173 @@
+/**
+ * Base compression utilities using Web Streams API
+ * Shared between Node.js and Browser implementations
+ *
+ * Uses CompressionStream/DecompressionStream API with "deflate-raw" format
+ * (raw DEFLATE without zlib header/trailer, required for ZIP files)
+ *
+ * Browser fallback: For browsers without deflate-raw support (Firefox < 113, Safari < 16.4),
+ * see deflate-fallback.ts for pure JS implementation
+ */
+import { ByteQueue } from "./byte-queue.js";
+/**
+ * Default threshold (in bytes) to choose the lower-overhead path.
+ *
+ * This is a performance knob, not a correctness requirement.
+ */
+export const DEFAULT_COMPRESS_THRESHOLD_BYTES = 8 * 1024 * 1024;
+/**
+ * Resolve the effective threshold bytes.
+ */
+export function resolveCompressThresholdBytes(options) {
+    const value = options.thresholdBytes;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return DEFAULT_COMPRESS_THRESHOLD_BYTES;
+    }
+    return value;
+}
+/**
+ * Check if CompressionStream is available
+ */
+export function hasCompressionStream() {
+    return typeof CompressionStream !== "undefined";
+}
+/**
+ * Non-cached probe for CompressionStream("deflate-raw") support.
+ *
+ * Prefer this in code paths that want up-to-date environment checks
+ * (e.g. tests that stub globals).
+ */
+export function probeDeflateRawCompressionStream() {
+    try {
+        if (typeof CompressionStream === "undefined") {
+            return false;
+        }
+        new CompressionStream("deflate-raw");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Non-cached probe for DecompressionStream("deflate-raw") support.
+ */
+export function probeDeflateRawDecompressionStream() {
+    try {
+        if (typeof DecompressionStream === "undefined") {
+            return false;
+        }
+        new DecompressionStream("deflate-raw");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Non-cached probe for full deflate-raw Web Streams support.
+ *
+ * Returns true only if BOTH CompressionStream("deflate-raw") and
+ * DecompressionStream("deflate-raw") are supported.
+ */
+export function probeDeflateRawWebStreams() {
+    return probeDeflateRawCompressionStream() && probeDeflateRawDecompressionStream();
+}
+let _hasDeflateRawCompressionStream = null;
+let _hasDeflateRawDecompressionStream = null;
+/**
+ * Check if CompressionStream supports the "deflate-raw" format.
+ *
+ * This is a stricter check than {@link hasCompressionStream} because some
+ * environments expose CompressionStream but do not support "deflate-raw".
+ */
+export function hasDeflateRawCompressionStream() {
+    if (typeof CompressionStream === "undefined") {
+        return false;
+    }
+    if (_hasDeflateRawCompressionStream !== null) {
+        return _hasDeflateRawCompressionStream;
+    }
+    _hasDeflateRawCompressionStream = probeDeflateRawCompressionStream();
+    return _hasDeflateRawCompressionStream;
+}
+/**
+ * Check if DecompressionStream supports the "deflate-raw" format.
+ */
+export function hasDeflateRawDecompressionStream() {
+    if (typeof DecompressionStream === "undefined") {
+        return false;
+    }
+    if (_hasDeflateRawDecompressionStream !== null) {
+        return _hasDeflateRawDecompressionStream;
+    }
+    _hasDeflateRawDecompressionStream = probeDeflateRawDecompressionStream();
+    return _hasDeflateRawDecompressionStream;
+}
+/**
+ * Cached check for full deflate-raw Web Streams support.
+ *
+ * Returns true only if BOTH CompressionStream("deflate-raw") and
+ * DecompressionStream("deflate-raw") are supported.
+ */
+export function hasDeflateRawWebStreams() {
+    return hasDeflateRawCompressionStream() && hasDeflateRawDecompressionStream();
+}
+async function streamToUint8Array(reader) {
+    const out = new ByteQueue();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        out.append(value);
+    }
+    return out.read(out.length);
+}
+async function transformWithStream(data, stream) {
+    const writer = stream.writable.getWriter();
+    const reader = stream.readable.getReader();
+    try {
+        // Start reading immediately to avoid potential backpressure deadlocks
+        // (writer.write/close may wait for the readable side to be consumed).
+        const readPromise = streamToUint8Array(reader);
+        await writer.write(data);
+        await writer.close();
+        return await readPromise;
+    }
+    finally {
+        try {
+            writer.releaseLock();
+        }
+        catch {
+            // ignore
+        }
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+/**
+ * Compress using CompressionStream API
+ * Uses "deflate-raw" format (required for ZIP files)
+ *
+ * @param data - Data to compress
+ * @returns Compressed data
+ */
+export async function compressWithStream(data) {
+    const cs = new CompressionStream("deflate-raw");
+    return transformWithStream(data, cs);
+}
+/**
+ * Decompress using DecompressionStream API
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export async function decompressWithStream(data) {
+    const ds = new DecompressionStream("deflate-raw");
+    return transformWithStream(data, ds);
+}

package/dist/browser/modules/archive/compress.browser.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Browser compression utilities
+ *
+ * Primary: CompressionStream API (Chrome 103+, Firefox 113+, Safari 16.4+)
+ * Fallback: Pure JS DEFLATE implementation for older browsers
+ *
+ * Supported browsers with fallback:
+ * - Chrome >= 89
+ * - Firefox >= 102
+ * - Safari >= 14.1
+ * - Edge >= 89
+ */
+import { type CompressOptions } from "@archive/compress.base";
+export { type CompressOptions };
+/**
+ * Check if CompressionStream is available in this environment.
+ *
+ * Note: Some environments may expose CompressionStream but not support
+ * the "deflate-raw" format that ZIP requires.
+ */
+export declare function hasCompressionStream(): boolean;
+/**
+ * Compress data using browser's native CompressionStream or JS fallback
+ *
+ * @param data - Data to compress
+ * @param options - Compression options
+ * @returns Compressed data
+ *
+ * @example
+ * ```ts
+ * const data = new TextEncoder().encode("Hello, World!");
+ * const compressed = await compress(data, { level: 6 });
+ * ```
+ */
+export declare function compress(data: Uint8Array, options?: CompressOptions): Promise<Uint8Array>;
+/**
+ * Compress data synchronously using pure JS implementation
+ *
+ * @param data - Data to compress
+ * @param options - Compression options
+ * @returns Compressed data
+ */
+export declare function compressSync(data: Uint8Array, options?: CompressOptions): Uint8Array;
+/**
+ * Decompress data using browser's native DecompressionStream or JS fallback
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export declare function decompress(data: Uint8Array, options?: CompressOptions): Promise<Uint8Array>;
+/**
+ * Decompress data synchronously using pure JS implementation
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export declare function decompressSync(data: Uint8Array): Uint8Array;