@cj-tech-master/excelts 5.1.18 → 6.0.0-beta.1

package/dist/browser/modules/archive/compression/streaming-compress.js

@@ -4,45 +4,32 @@
  * Uses zlib.createDeflateRaw() with explicit flush() calls for real chunk-by-chunk streaming.
  * Each write() immediately produces compressed output without waiting for end().
  */
-import { createDeflateRaw, createInflateRaw, constants } from "zlib";
+import { createDeflateRaw, createInflateRaw, createGzip, createGunzip, createDeflate, createInflate, deflateRawSync, constants } from "zlib";
 import { Transform } from "../../stream/index.browser.js";
-import { DEFAULT_COMPRESS_LEVEL } from "../defaults.js";
+import { DEFAULT_COMPRESS_LEVEL } from "../shared/defaults.js";
 /**
- * Wrapper around zlib DeflateRaw that flushes after every write
- * This ensures true streaming behavior - data is emitted immediately, not buffered
+ * Generic wrapper around zlib streams that flushes after every write.
+ * This ensures true streaming behavior - data is emitted immediately, not buffered.
  */
-class TrueStreamingDeflate extends Transform {
-    constructor(level) {
+class TrueStreamingZlib extends Transform {
+    constructor(zstream) {
         super();
-        this.deflate = createDeflateRaw({ level });
-        // Forward data from deflate to this transform
-        this.deflate.on("data", chunk => {
-            this.push(chunk);
-        });
-        this.deflate.on("error", err => {
-            this.destroy(err);
-        });
+        this.zstream = zstream;
+        zstream.on("data", chunk => this.push(chunk));
+        zstream.on("error", err => this.destroy(err));
     }
     _transform(chunk, _encoding, callback) {
-        // Write to deflate
-        this.deflate.write(chunk, writeErr => {
+        this.zstream.write(chunk, writeErr => {
             if (writeErr) {
                 callback(writeErr);
                 return;
             }
-            // Explicitly flush to ensure data is emitted NOW, not later
-            this.deflate.flush(constants.Z_SYNC_FLUSH, () => {
-                callback();
-            });
+            this.zstream.flush(constants.Z_SYNC_FLUSH, () => callback());
         });
     }
     _flush(callback) {
-        // End the deflate stream with Z_FINISH to write proper termination
-        // This is critical - Z_SYNC_FLUSH doesn't write the final block marker
-        this.deflate.flush(constants.Z_FINISH, () => {
-            this.deflate.end(() => {
-                callback();
-            });
+        this.zstream.flush(constants.Z_FINISH, () => {
+            this.zstream.end(() => callback());
         });
     }
 }
@@ -51,12 +38,17 @@ class TrueStreamingDeflate extends Transform {
  * Returns a Transform stream that emits compressed data immediately after each write
  */
 export function createDeflateStream(options = {}) {
-    return new TrueStreamingDeflate(options.level ?? DEFAULT_COMPRESS_LEVEL);
+    const level = options.level ?? DEFAULT_COMPRESS_LEVEL;
+    return new TrueStreamingZlib(createDeflateRaw({ level }));
 }
 /**
  * Create a true streaming INFLATE decompressor
+ *
+ * @param options - Decompression options (useWorker is ignored in Node.js)
  */
-export function createInflateStream() {
+export function createInflateStream(options = {}) {
+    // Note: options.useWorker is ignored in Node.js (zlib uses native thread pool)
+    void options;
     return createInflateRaw();
 }
 /**
@@ -66,3 +58,66 @@ export function createInflateStream() {
 export function hasDeflateRaw() {
     return true;
 }
+/**
+ * Create a streaming GZIP compressor
+ */
+export function createGzipStream(options = {}) {
+    const level = options.level ?? DEFAULT_COMPRESS_LEVEL;
+    return new TrueStreamingZlib(createGzip({ level }));
+}
+/**
+ * Create a streaming GZIP decompressor
+ */
+export function createGunzipStream(_options = {}) {
+    return createGunzip();
+}
+/**
+ * Create a streaming Zlib compressor
+ */
+export function createZlibStream(options = {}) {
+    const level = options.level ?? DEFAULT_COMPRESS_LEVEL;
+    return new TrueStreamingZlib(createDeflate({ level }));
+}
+/**
+ * Create a streaming Zlib decompressor
+ */
+export function createUnzlibStream(_options = {}) {
+    return createInflate();
+}
+// =============================================================================
+// Synchronous stateful deflater (Node.js — native zlib)
+// =============================================================================
+/**
+ * Node.js synchronous deflater using `deflateRawSync` with `Z_SYNC_FLUSH`.
+ *
+ * Each `write()` compresses the chunk independently (no cross-chunk dictionary)
+ * but uses `Z_SYNC_FLUSH` so the output is byte-aligned and can be concatenated
+ * into a single valid DEFLATE stream. The final `finish()` emits a proper
+ * BFINAL=1 block.
+ *
+ * This is fast (native C zlib) and produces valid output on all Node.js versions
+ * (20+). The trade-off is ~2% worse compression ratio vs a stateful context,
+ * which is acceptable for streaming where memory is the priority.
+ */
+export class SyncDeflater {
+    constructor(level = DEFAULT_COMPRESS_LEVEL) {
+        this._level = level;
+    }
+    write(data) {
+        if (data.length === 0) {
+            return new Uint8Array(0);
+        }
+        const result = deflateRawSync(Buffer.from(data), {
+            level: this._level,
+            finishFlush: constants.Z_SYNC_FLUSH
+        });
+        // deflateRawSync returns a Buffer sharing a 16 KB slab ArrayBuffer.
+        // Copy to a tight Uint8Array so the slab can be reclaimed.
+        return new Uint8Array(result);
+    }
+    finish() {
+        // Emit a final empty DEFLATE block (BFINAL=1, BTYPE=01, EOB).
+        // This terminates the concatenated DEFLATE stream.
+        return new Uint8Array(deflateRawSync(Buffer.alloc(0), { level: this._level }));
+    }
+}

package/dist/browser/modules/archive/compression/worker-pool/index.browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Worker Pool Module - Browser Entry
+ *
+ * Re-exports the browser implementation of the worker pool.
+ */
+export { WorkerPool, getDefaultWorkerPool, terminateDefaultWorkerPool, deflateWithPool, inflateWithPool, deflateBatchWithPool, inflateBatchWithPool, hasWorkerSupport, type WorkerPoolOptions, type WorkerPoolStats, type TaskOptions, type TaskResult, type WorkerTaskType } from "./pool.browser.js";

package/dist/browser/modules/archive/compression/worker-pool/index.browser.js

@@ -0,0 +1,6 @@
+/**
+ * Worker Pool Module - Browser Entry
+ *
+ * Re-exports the browser implementation of the worker pool.
+ */
+export { WorkerPool, getDefaultWorkerPool, terminateDefaultWorkerPool, deflateWithPool, inflateWithPool, deflateBatchWithPool, inflateBatchWithPool, hasWorkerSupport } from "./pool.browser.js";

package/dist/browser/modules/archive/compression/worker-pool/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Worker Pool Module - Node Entry (Stub)
+ *
+ * Node.js doesn't need a worker pool for compression since zlib
+ * already uses the libuv thread pool internally.
+ *
+ * This stub exports a no-op implementation for API parity.
+ */
+export type { WorkerPoolOptions, WorkerPoolStats, TaskOptions, TaskResult, WorkerTaskType } from "./types.js";
+export { hasWorkerSupport, createAbortError } from "./pool.base.js";
+/**
+ * Node.js stub - throws if called
+ */
+export declare class WorkerPool {
+    constructor();
+    execute(): never;
+    getStats(): never;
+    terminate(): void;
+    isTerminated(): boolean;
+}
+export declare function getDefaultWorkerPool(): never;
+export declare function terminateDefaultWorkerPool(): void;
+export declare function deflateWithPool(): Promise<never>;
+export declare function inflateWithPool(): Promise<never>;
+export declare function deflateBatchWithPool(): Promise<never>;
+export declare function inflateBatchWithPool(): Promise<never>;

package/dist/browser/modules/archive/compression/worker-pool/index.js

@@ -0,0 +1,53 @@
+/**
+ * Worker Pool Module - Node Entry (Stub)
+ *
+ * Node.js doesn't need a worker pool for compression since zlib
+ * already uses the libuv thread pool internally.
+ *
+ * This stub exports a no-op implementation for API parity.
+ */
+export { hasWorkerSupport, createAbortError } from "./pool.base.js";
+/** Shared error for Node.js stub methods */
+const NODEJS_STUB_ERROR = "WorkerPool is not available in Node.js";
+function throwStubError() {
+    throw new Error(NODEJS_STUB_ERROR);
+}
+/**
+ * Node.js stub - throws if called
+ */
+export class WorkerPool {
+    constructor() {
+        throw new Error("WorkerPool is only available in browser environments. " +
+            "Node.js uses the native zlib thread pool automatically.");
+    }
+    execute() {
+        throwStubError();
+    }
+    getStats() {
+        throwStubError();
+    }
+    terminate() {
+        // No-op
+    }
+    isTerminated() {
+        return true;
+    }
+}
+export function getDefaultWorkerPool() {
+    throwStubError();
+}
+export function terminateDefaultWorkerPool() {
+    // No-op
+}
+export async function deflateWithPool() {
+    throwStubError();
+}
+export async function inflateWithPool() {
+    throwStubError();
+}
+export async function deflateBatchWithPool() {
+    throwStubError();
+}
+export async function inflateBatchWithPool() {
+    throwStubError();
+}

package/dist/browser/modules/archive/compression/worker-pool/pool.base.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Worker Pool Base Module
+ *
+ * Environment-agnostic interfaces and utilities for worker pool management.
+ */
+import type { WorkerPoolOptions } from "./types.js";
+export type { WorkerPoolOptions };
+/**
+ * Resolved worker pool options with all values defined
+ */
+export interface ResolvedPoolOptions {
+    maxWorkers: number;
+    minWorkers: number;
+    idleTimeout: number;
+    useTransferables: boolean;
+    workerUrl: string | undefined;
+}
+/**
+ * Default worker pool options
+ */
+export declare const DEFAULT_POOL_OPTIONS: ResolvedPoolOptions;
+/**
+ * Resolve worker pool options with defaults
+ */
+export declare function resolvePoolOptions(options?: WorkerPoolOptions): ResolvedPoolOptions;
+/**
+ * Get priority value for sorting
+ */
+export declare function getPriorityValue(priority?: string): number;
+/**
+ * Check if Web Workers are available in the current environment
+ */
+export declare function hasWorkerSupport(): boolean;
+export { createAbortError } from "../../shared/errors.js";

package/dist/browser/modules/archive/compression/worker-pool/pool.base.js

@@ -0,0 +1,56 @@
+/**
+ * Worker Pool Base Module
+ *
+ * Environment-agnostic interfaces and utilities for worker pool management.
+ */
+/**
+ * Default worker pool options
+ */
+export const DEFAULT_POOL_OPTIONS = {
+    maxWorkers: typeof navigator !== "undefined" ? navigator.hardwareConcurrency || 4 : 4,
+    minWorkers: 0,
+    idleTimeout: 30000,
+    useTransferables: true,
+    workerUrl: undefined
+};
+/**
+ * Resolve worker pool options with defaults
+ */
+export function resolvePoolOptions(options) {
+    const maxWorkers = options?.maxWorkers ?? DEFAULT_POOL_OPTIONS.maxWorkers;
+    const minWorkers = options?.minWorkers ?? DEFAULT_POOL_OPTIONS.minWorkers;
+    // Validate: minWorkers should not exceed maxWorkers
+    const validatedMinWorkers = Math.min(minWorkers, maxWorkers);
+    return {
+        maxWorkers: Math.max(1, maxWorkers), // At least 1 worker
+        minWorkers: Math.max(0, validatedMinWorkers),
+        idleTimeout: Math.max(0, options?.idleTimeout ?? DEFAULT_POOL_OPTIONS.idleTimeout),
+        useTransferables: options?.useTransferables ?? DEFAULT_POOL_OPTIONS.useTransferables,
+        workerUrl: options?.workerUrl
+    };
+}
+/**
+ * Task priority values for sorting (internal)
+ */
+const PRIORITY_VALUES = {
+    high: 3,
+    normal: 2,
+    low: 1
+};
+/**
+ * Get priority value for sorting
+ */
+export function getPriorityValue(priority) {
+    if (!priority) {
+        return PRIORITY_VALUES.normal;
+    }
+    return PRIORITY_VALUES[priority] ?? PRIORITY_VALUES.normal;
+}
+/**
+ * Check if Web Workers are available in the current environment
+ */
+export function hasWorkerSupport() {
+    return typeof Worker !== "undefined" && typeof Blob !== "undefined";
+}
+// Re-export from shared errors module
+export { createAbortError } from "../../shared/errors.js";

package/dist/browser/modules/archive/compression/worker-pool/pool.browser.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Browser Worker Pool Implementation
+ *
+ * A worker pool for parallel compression/decompression in the browser.
+ * Automatically manages worker lifecycle, task scheduling, and load balancing.
+ *
+ * Features:
+ * - Automatic worker scaling based on workload
+ * - Task prioritization (high/normal/low)
+ * - Idle worker termination to save resources
+ * - Transferable objects for zero-copy data transfer
+ * - Task cancellation via AbortSignal
+ * - Graceful error handling and recovery
+ */
+import type { WorkerPoolOptions, WorkerPoolStats, TaskOptions, TaskResult, WorkerTaskType } from "./types.js";
+import { hasWorkerSupport } from "./pool.base.js";
+export type { WorkerPoolOptions, WorkerPoolStats, TaskOptions, TaskResult, WorkerTaskType };
+export { hasWorkerSupport };
+export interface WorkerPoolStream {
+    write(data: Uint8Array): Promise<void>;
+    end(): Promise<void>;
+    abort(reason?: string): void;
+}
+/**
+ * Browser Worker Pool
+ *
+ * Manages a pool of Web Workers for parallel compression/decompression.
+ */
+export declare class WorkerPool {
+    private readonly _options;
+    private readonly _workers;
+    private readonly _taskQueue;
+    private _taskQueueHead;
+    private readonly _pendingTasks;
+    private _nextTaskId;
+    private _nextWorkerId;
+    private _terminated;
+    private _completedTasks;
+    private _failedTasks;
+    private readonly _workerUrl;
+    private readonly _useCustomUrl;
+    private readonly _pendingStreamRequests;
+    private _pendingStreamRequestHead;
+    private _taskQueueSize;
+    private _compactTaskQueueIfNeeded;
+    private _dequeueTask;
+    private _compactPendingStreamRequestsIfNeeded;
+    private _dequeuePendingStreamRequest;
+    private _waitForStreamSlot;
+    private _waitForStreamDrain;
+    private _resolveSlotWaiter;
+    private _resolveDrainWaiter;
+    constructor(options?: WorkerPoolOptions);
+    /**
+     * Execute a task in the worker pool
+     */
+    execute(taskType: WorkerTaskType, data: Uint8Array, options?: TaskOptions & {
+        level?: number;
+    }): Promise<TaskResult>;
+    /**
+     * Get current pool statistics
+     */
+    getStats(): WorkerPoolStats;
+    /**
+     * Terminate all workers and clean up resources
+     */
+    terminate(): void;
+    /**
+     * Check if the pool has been terminated
+     */
+    isTerminated(): boolean;
+    /**
+     * Create a new worker
+     */
+    private _createWorker;
+    /**
+     * Terminate a single worker
+     */
+    private _terminateWorker;
+    /**
+     * Clear a worker's idle timer if set
+     */
+    private _clearIdleTimer;
+    /**
+     * Find an idle worker
+     */
+    private _findIdleWorker;
+    /**
+     * Enqueue a task with priority ordering using binary search (O(log n))
+     */
+    private _enqueueTask;
+    /**
+     * Process the task queue
+     */
+    private _processQueue;
+    /**
+     * Assign a task to a worker
+     */
+    private _assignTask;
+    /**
+     * Handle message from worker
+     */
+    private _handleWorkerMessage;
+    /**
+     * Handle worker error
+     */
+    private _handleWorkerError;
+    /**
+     * Called when a worker becomes idle
+     */
+    private _workerBecameIdle;
+    /**
+     * Open a streaming session bound to a worker.
+     *
+     * This enables true chunk-by-chunk compression/decompression in the worker without buffering
+     * the entire input on the main thread.
+     */
+    openStream(taskType: WorkerTaskType, options?: {
+        level?: number;
+        allowTransfer?: boolean;
+        onData: (chunk: Uint8Array) => void;
+        onEnd: () => void;
+        onError: (err: Error) => void;
+    }): WorkerPoolStream;
+    private _bindStreamSession;
+    private _startStreamSession;
+    /**
+     * Cancel a task
+     */
+    private _cancelTask;
+    /**
+     * Clean up task resources
+     */
+    private _cleanupTask;
+    /**
+     * Execute multiple tasks in parallel
+     *
+     * @param tasks - Array of task definitions
+     * @returns Array of results in the same order as input
+     */
+    executeBatch(tasks: Array<{
+        taskType: WorkerTaskType;
+        data: Uint8Array;
+        options?: TaskOptions & {
+            level?: number;
+        };
+    }>): Promise<TaskResult[]>;
+}
+/**
+ * Get or create the default worker pool
+ */
+export declare function getDefaultWorkerPool(options?: WorkerPoolOptions): WorkerPool;
+/**
+ * Terminate the default worker pool
+ */
+export declare function terminateDefaultWorkerPool(): void;
+/**
+ * Execute a compression task using the default pool
+ */
+export declare function deflateWithPool(data: Uint8Array, options?: TaskOptions & {
+    level?: number;
+}): Promise<Uint8Array>;
+/**
+ * Execute a decompression task using the default pool
+ */
+export declare function inflateWithPool(data: Uint8Array, options?: TaskOptions): Promise<Uint8Array>;
+/**
+ * Batch compress multiple data chunks in parallel using the default pool
+ */
+export declare function deflateBatchWithPool(items: Array<{
+    data: Uint8Array;
+    options?: TaskOptions & {
+        level?: number;
+    };
+}>): Promise<Uint8Array[]>;
+/**
+ * Batch decompress multiple data chunks in parallel using the default pool
+ */
+export declare function inflateBatchWithPool(items: Array<{
+    data: Uint8Array;
+    options?: TaskOptions;
+}>): Promise<Uint8Array[]>;