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

package/dist/esm/index.browser.js

@@ -5,32 +5,41 @@
 // =============================================================================
 // Main Classes (Browser-compatible)
 // =============================================================================
-export { Workbook } from "./doc/workbook.browser.js";
-export { Worksheet } from "./doc/worksheet.js";
-export { Row } from "./doc/row.js";
-export { Column } from "./doc/column.js";
-export { Cell } from "./doc/cell.js";
-export { Range } from "./doc/range.js";
-export { Image } from "./doc/image.js";
-export * from "./doc/anchor.js";
-export { Table } from "./doc/table.js";
-export { DataValidations } from "./doc/data-validations.js";
+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 "./doc/enums.js";
+export * from "./modules/excel/enums.js";
 // =============================================================================
 // Types
 // =============================================================================
 // Export all type definitions from types.ts
-export * from "./types.js";
+export * from "./modules/excel/types.js";
 // =============================================================================
 // Utilities
 // =============================================================================
-export * from "./utils/sheet-utils.js";
+export * from "./modules/excel/utils/sheet-utils.js";
+export { CsvParserStream, CsvFormatterStream } from "./modules/csv/csv.browser.js";
 // =============================================================================
-// NOTE: The following are NOT exported in browser build (Node.js only):
-// - WorkbookWriter, WorkbookReader (streaming classes for file I/O)
-// - WorksheetWriter, WorksheetReader (streaming classes)
-// - ModelContainer
+// 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 };
+// =============================================================================
+// NOTE: Node.js-only features not available in browser:
+// - Reading from a file path is not supported (use Uint8Array/ArrayBuffer/Blob instead)
+// - Writing to a file path is not supported (use writeBuffer() / stream output, then save as Blob/download)
 // =============================================================================

package/dist/esm/index.js

@@ -1,36 +1,35 @@
 // =============================================================================
 // Main Classes
 // =============================================================================
-export { Workbook } from "./doc/workbook.js";
-export { Worksheet } from "./doc/worksheet.js";
-export { Row } from "./doc/row.js";
-export { Column } from "./doc/column.js";
-export { Cell } from "./doc/cell.js";
-export { Range } from "./doc/range.js";
-export { Image } from "./doc/image.js";
-export * from "./doc/anchor.js";
-export { Table } from "./doc/table.js";
-export { DataValidations } from "./doc/data-validations.js";
+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 "./stream/xlsx/workbook-writer.js";
-export { WorkbookReader } from "./stream/xlsx/workbook-reader.js";
-export { WorksheetWriter } from "./stream/xlsx/worksheet-writer.js";
-export { WorksheetReader } from "./stream/xlsx/worksheet-reader.js";
-export { ModelContainer } from "./doc/modelcontainer.js";
+export { WorkbookWriter } from "./modules/excel/stream/workbook-writer.js";
+export { WorkbookReader } from "./modules/excel/stream/workbook-reader.js";
+export { WorksheetWriter } from "./modules/excel/stream/worksheet-writer.js";
+export { WorksheetReader } from "./modules/excel/stream/worksheet-reader.js";
 // =============================================================================
 // Enums
 // =============================================================================
-export * from "./doc/enums.js";
+export * from "./modules/excel/enums.js";
 // =============================================================================
 // Types
 // =============================================================================
 // Export all type definitions from types.ts
-export * from "./types.js";
-export { CsvParserStream, CsvFormatterStream } from "./csv/csv.js";
+export * from "./modules/excel/types.js";
+export { CsvParserStream, CsvFormatterStream } from "./modules/csv/csv.js";
 // =============================================================================
 // Utilities
 // =============================================================================
-export * from "./utils/sheet-utils.js";
+export * from "./modules/excel/utils/sheet-utils.js";

package/dist/esm/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/esm/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/esm/modules/archive/compress.browser.js

@@ -0,0 +1,93 @@
+/**
+ * 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 { compressWithStream, decompressWithStream, hasDeflateRawCompressionStream, hasDeflateRawDecompressionStream, resolveCompressThresholdBytes } from "./compress.base.js";
+import { inflateRaw, deflateRawCompressed } from "./deflate-fallback.js";
+import { DEFAULT_COMPRESS_LEVEL } from "./defaults.js";
+// Re-export shared types
+export {};
+/**
+ * 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 function hasCompressionStream() {
+    return typeof CompressionStream !== "undefined";
+}
+/**
+ * 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 async function compress(data, options = {}) {
+    const level = options.level ?? DEFAULT_COMPRESS_LEVEL;
+    const thresholdBytes = resolveCompressThresholdBytes(options);
+    // Level 0 means no compression
+    if (level === 0) {
+        return data;
+    }
+    // Use native CompressionStream only for larger inputs.
+    if (hasDeflateRawCompressionStream() && data.byteLength > thresholdBytes) {
+        return compressWithStream(data);
+    }
+    // Fallback to pure JS implementation
+    return deflateRawCompressed(data);
+}
+/**
+ * Compress data synchronously using pure JS implementation
+ *
+ * @param data - Data to compress
+ * @param options - Compression options
+ * @returns Compressed data
+ */
+export function compressSync(data, options = {}) {
+    const level = options.level ?? DEFAULT_COMPRESS_LEVEL;
+    // Level 0 means no compression
+    if (level === 0) {
+        return data;
+    }
+    // Pure JS implementation
+    return deflateRawCompressed(data);
+}
+/**
+ * Decompress data using browser's native DecompressionStream or JS fallback
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export async function decompress(data, options = {}) {
+    const thresholdBytes = resolveCompressThresholdBytes(options);
+    // Use native DecompressionStream only for larger inputs.
+    if (hasDeflateRawDecompressionStream() && data.byteLength > thresholdBytes) {
+        return decompressWithStream(data);
+    }
+    // Fallback to pure JS implementation
+    return inflateRaw(data);
+}
+/**
+ * Decompress data synchronously using pure JS implementation
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export function decompressSync(data) {
+    return inflateRaw(data);
+}

package/dist/esm/modules/archive/compress.js

@@ -0,0 +1,86 @@
+/**
+ * Node.js compression utilities using native zlib
+ *
+ * Uses zlib module (C++ implementation, fastest) with "deflate-raw" format
+ * (raw DEFLATE without zlib header/trailer, required for ZIP files)
+ */
+import { promisify } from "util";
+import * as zlib from "zlib";
+import { DEFAULT_COMPRESS_LEVEL } from "./defaults.js";
+// Re-export shared types and utilities
+export { hasCompressionStream } from "./compress.base.js";
+function uint8ArrayToBufferView(data) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+}
+const deflateRawAsync = promisify(zlib.deflateRaw);
+const inflateRawAsync = promisify(zlib.inflateRaw);
+import { resolveCompressThresholdBytes } from "./compress.base.js";
+/**
+ * Compress data using Node.js native zlib
+ *
+ * @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 async function compress(data, options = {}) {
+    const level = options.level ?? DEFAULT_COMPRESS_LEVEL;
+    const thresholdBytes = resolveCompressThresholdBytes(options);
+    // Level 0 means no compression
+    if (level === 0) {
+        return data;
+    }
+    // Small-input fast path: avoid threadpool overhead.
+    if (data.byteLength <= thresholdBytes) {
+        const result = zlib.deflateRawSync(uint8ArrayToBufferView(data), { level });
+        return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+    }
+    const result = await deflateRawAsync(uint8ArrayToBufferView(data), { level });
+    return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+}
+/**
+ * Compress data synchronously using Node.js zlib
+ *
+ * @param data - Data to compress
+ * @param options - Compression options
+ * @returns Compressed data
+ */
+export function compressSync(data, options = {}) {
+    const level = options.level ?? DEFAULT_COMPRESS_LEVEL;
+    if (level === 0) {
+        return data;
+    }
+    const result = zlib.deflateRawSync(uint8ArrayToBufferView(data), { level });
+    return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+}
+/**
+ * Decompress data using Node.js native zlib
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export async function decompress(data, options = {}) {
+    const thresholdBytes = resolveCompressThresholdBytes(options);
+    // Small-input fast path: avoid threadpool overhead.
+    if (data.byteLength <= thresholdBytes) {
+        const result = zlib.inflateRawSync(uint8ArrayToBufferView(data));
+        return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+    }
+    const result = await inflateRawAsync(uint8ArrayToBufferView(data));
+    return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+}
+/**
+ * Decompress data synchronously using Node.js zlib
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export function decompressSync(data) {
+    const result = zlib.inflateRawSync(uint8ArrayToBufferView(data));
+    return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+}

package/dist/esm/modules/archive/crc32.base.js

@@ -0,0 +1,51 @@
+/**
+ * CRC32 calculation core (shared between Node.js and browser).
+ *
+ * Implements CRC-32 IEEE 802.3 using the reversed polynomial 0xEDB88320.
+ *
+ * Notes:
+ * - Uses a lazily-initialized 256-entry lookup table.
+ * - Exposes an incremental update API for streaming use cases.
+ */
+let _crc32Table = null;
+function getCrc32Table() {
+    if (_crc32Table) {
+        return _crc32Table;
+    }
+    const table = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let crc = i;
+        for (let j = 0; j < 8; j++) {
+            crc = crc & 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
+        }
+        table[i] = crc;
+    }
+    _crc32Table = table;
+    return table;
+}
+/**
+ * Update a CRC32 value with a new data chunk.
+ *
+ * The CRC state here is the non-finalized (inverted) form:
+ * - initial state: 0xffffffff
+ * - finalize: xor with 0xffffffff
+ */
+export function crc32UpdateJS(crc, data) {
+    const table = getCrc32Table();
+    for (let i = 0; i < data.length; i++) {
+        crc = table[(crc ^ data[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return crc;
+}
+/**
+ * Finalize CRC32 calculation.
+ */
+export function crc32Finalize(crc) {
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/**
+ * Compute CRC32 for the full input using the JS table implementation.
+ */
+export function crc32JS(data) {
+    return crc32Finalize(crc32UpdateJS(0xffffffff, data));
+}

package/dist/esm/modules/archive/crc32.browser.js

@@ -0,0 +1,32 @@
+/**
+ * CRC32 calculation utility for ZIP files (Browser version)
+ *
+ * Uses lookup table optimization - no Node.js dependencies
+ *
+ * The polynomial used is the standard CRC-32 IEEE 802.3:
+ * x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
+ * Represented as 0xEDB88320 in reversed (LSB-first) form
+ */
+export { crc32JS as crc32, crc32UpdateJS as crc32Update, crc32Finalize } from "./crc32.base.js";
+/**
+ * Ensure CRC32 is ready (no-op in browser, for API compatibility)
+ */
+export async function ensureCrc32() {
+    // No-op in browser
+}
+/**
+ * Calculate CRC32 incrementally (useful for streaming)
+ * Call with initial crc of 0xffffffff, then finalize with crc32Finalize
+ *
+ * @param crc - Current CRC value (start with 0xffffffff)
+ * @param data - Input data chunk
+ * @returns Updated CRC value (not finalized)
+ *
+ * @example
+ * ```ts
+ * let crc = 0xffffffff;
+ * crc = crc32Update(crc, chunk1);
+ * crc = crc32Update(crc, chunk2);
+ * const checksum = crc32Finalize(crc);
+ * ```
+ */