@cj-tech-master/excelts 8.0.0 → 8.1.0

package/README.md

@@ -14,6 +14,12 @@ ExcelTS is a zero-dependency TypeScript toolkit for spreadsheets and documents:
 - **Cross-Platform** — Node.js 22+, Bun, Chrome 89+, Firefox 102+, Safari 14.1+
 - **ESM First** — Native ES Modules with CommonJS compatibility and full tree-shaking
 
+## Motivation
+
+The TypeScript ecosystem is heavily fragmented when it comes to document and data processing. To handle Excel, PDF, CSV, XML, ZIP, and streaming, developers often need to pull in a different package for each task — and then yet another set of packages to make them work in the browser, plus separate streaming wrappers on top. These libraries vary in API style, quality, and maintenance status, creating a tax on every project that needs more than one of them.
+
+ExcelTS was built to fix this. One package, one consistent API, one codebase — working identically across Node.js, Bun, and browsers. Streaming is a first-class citizen in every module, not an afterthought bolted on through a third-party adapter. The goal is simple: install once, import what you need, and get the same reliable behavior everywhere — with maximum streaming performance out of the box.
+
 ## Modules
 
 ExcelTS is organized into seven standalone modules. Each module has its own documentation and runnable examples.
@@ -27,7 +33,7 @@ Create, read, and modify Excel spreadsheets with full styling, formulas, images,
 
 ### PDF — Zero-Dependency PDF Engine
 
-Full-featured PDF generation with font embedding, encryption, images, and Excel-to-PDF conversion.
+Full-featured PDF generation and reading. Write PDFs with font embedding, AES-256 encryption, images, and Excel-to-PDF conversion. Read any PDF with text, image, annotation, form field, and metadata extraction.
 
 - [Documentation](src/modules/pdf/README.md) | [中文](src/modules/pdf/README_zh.md)
 - [Examples](src/modules/pdf/examples/)
@@ -99,6 +105,12 @@ const pdfBytes = pdf([
   ["Widget", 1000]
 ]);
 
+// PDF — read text, images, and metadata from any PDF
+import { readPdf } from "@cj-tech-master/excelts/pdf";
+const result = readPdf(pdfBytes);
+console.log(result.text); // extracted text
+console.log(result.metadata); // title, author, etc.
+
 // CSV — parse and format
 import { parseCsv, formatCsv } from "@cj-tech-master/excelts/csv";
 const rows = parseCsv("name,age\nAlice,30", { headers: true });
@@ -123,6 +135,7 @@ Each module is available as a standalone subpath export:
 
 ```typescript
 import { Workbook, WorkbookWriter } from "@cj-tech-master/excelts";
+import { pdf, readPdf, excelToPdf } from "@cj-tech-master/excelts/pdf";
 import { SaxParser, parseXml, XmlWriter, query } from "@cj-tech-master/excelts/xml";
 import { zip, unzip, ZipArchive, compress } from "@cj-tech-master/excelts/zip";
 import { parseCsv, formatCsv, CsvParserStream } from "@cj-tech-master/excelts/csv";

package/README_zh.md

@@ -14,6 +14,12 @@ ExcelTS 是一个零依赖的 TypeScript 电子表格和文档工具包：
 - **跨平台** — Node.js 22+、Bun、Chrome 89+、Firefox 102+、Safari 14.1+
 - **ESM 优先** — 原生 ES Modules，兼容 CommonJS，完整的 tree-shaking 支持
 
+## 项目初衷
+
+TypeScript 生态在文档和数据处理领域长期存在碎片化问题。处理 Excel、PDF、CSV、XML、ZIP 和流式操作，往往需要分别引入不同的包；到了浏览器端又要换一套方案；流式处理还得再额外接入一个适配库。这些库的 API 风格、质量和维护状态参差不齐，给每个需要组合使用它们的项目都带来了额外的负担。
+
+ExcelTS 正是为了解决这个问题而生。一个包、一套 API、一份代码 — 在 Node.js、Bun 和浏览器中行为完全一致。流式处理是每个模块的一等公民，而非通过第三方适配器后期拼装的附属品。目标很简单：安装一次，按需导入，在任何环境下都获得相同的可靠体验 — 同时将流式处理的性能发挥到极致。
+
 ## 模块
 
 ExcelTS 由七个独立模块组成，每个模块都有自己的文档和可运行示例。

package/dist/browser/modules/archive/zip/stream.d.ts

@@ -60,6 +60,8 @@ export declare class ZipDeflateFile {
     private _dataQueue;
     private _finalQueued;
     private _pushChain;
+    private _inputBuf;
+    private _inputPos;
     private _syncDeflater;
     private _syncZlibReady;
     readonly name: string;
@@ -159,6 +161,8 @@ export declare class ZipDeflateFile {
      * memory growth when callers push data in a tight synchronous loop.
      */
     push(data: Uint8Array, final?: boolean, callback?: (err?: Error | null) => void): Promise<void>;
+    /** Enqueue an async push through the _pushChain serialization. */
+    private _pushAsync;
     /**
      * Synchronous push path — compresses and emits data without any Promises.
      *

package/dist/browser/modules/archive/zip/stream.js

@@ -19,6 +19,12 @@ import { createAbortError, toError } from "../shared/errors.js";
 import { measureCentralDirectoryAndEocd, writeCentralDirectoryAndEocdInto } from "./writer-core.js";
 import { buildDataDescriptor, buildDataDescriptorZip64, concatExtraFields, UINT16_MAX, UINT32_MAX, buildLocalFileHeader, VERSION_ZIP64, VERSION_NEEDED, FLAG_ENCRYPTED, FLAG_DATA_DESCRIPTOR, FLAG_UTF8, COMPRESSION_AES, getUnixModeFromExternalAttributes, isSymlinkMode } from "../zip-spec/zip-records.js";
 const SMART_STORE_DECIDE_BYTES = 16 * 1024;
+/** Input batching threshold for push().  Small chunks are accumulated in an
+ *  internal buffer and flushed to the compression pipeline once this size is
+ *  reached.  64 KB matches the standard deflate window and keeps the number
+ *  of async push() calls — each of which creates a full Promise chain in the
+ *  browser CompressionStream path — down to a manageable level. */
+const INPUT_BATCH_BYTES = 65536;
 /**
  * True Streaming ZIP File - compresses chunk by chunk
  */
@@ -62,6 +68,12 @@ export class ZipDeflateFile {
         this._finalQueued = false;
         // Serialize push() calls so callers don't need to await to preserve ordering.
         this._pushChain = Promise.resolve();
+        // Input batching: accumulate small chunks before feeding the compression
+        // pipeline.  This collapses thousands of tiny push() calls (each creating a
+        // full async Promise chain on browsers) into a handful of large pushes.
+        // Threshold matches the common deflate window size (64 KB).
+        this._inputBuf = null;
+        this._inputPos = 0;
         // Synchronous compression state for pushSync() path.
         this._syncDeflater = null;
         this._syncZlibReady = false;
@@ -639,6 +651,47 @@ export class ZipDeflateFile {
             }
             return Promise.resolve();
         }
+        // --- Async path: batch small chunks to reduce Promise-chain overhead ---
+        // Each real push through the async pipeline creates a full Promise chain
+        // (push → _pushChain → _pushUnchained → AsyncStreamCodec.writeChain →
+        // CompressionStream.writer.write).  By accumulating small chunks into a
+        // 64 KB buffer we reduce the number of async round-trips by ~100x for
+        // typical XML workloads without sacrificing streaming semantics.
+        if (!final && data.length > 0 && data.length < INPUT_BATCH_BYTES) {
+            // Lazy-allocate the batch buffer.
+            if (!this._inputBuf) {
+                this._inputBuf = new Uint8Array(INPUT_BATCH_BYTES);
+                this._inputPos = 0;
+            }
+            // If the chunk fits in the remaining space, just copy it in.
+            if (this._inputPos + data.length <= INPUT_BATCH_BYTES) {
+                this._inputBuf.set(data, this._inputPos);
+                this._inputPos += data.length;
+                // Not full yet — return resolved promise, no async work.
+                callback?.();
+                return Promise.resolve();
+            }
+            // Buffer would overflow — flush everything (buffered + new data) together.
+            const combined = new Uint8Array(this._inputPos + data.length);
+            combined.set(this._inputBuf.subarray(0, this._inputPos));
+            combined.set(data, this._inputPos);
+            this._inputPos = 0;
+            return this._pushAsync(combined, false, callback);
+        }
+        // Large chunk or final — flush any buffered data first, then push.
+        if (this._inputPos > 0) {
+            const flushData = this._inputBuf.slice(0, this._inputPos);
+            this._inputPos = 0;
+            // Chain: flush buffered → push current
+            const flushPromise = this._pushAsync(flushData, false);
+            const promise = (this._pushChain = flushPromise.then(() => this._pushUnchained(data, final, callback), () => this._pushUnchained(data, final, callback)));
+            promise.catch(() => { });
+            return promise;
+        }
+        return this._pushAsync(data, final, callback);
+    }
+    /** Enqueue an async push through the _pushChain serialization. */
+    _pushAsync(data, final, callback) {
         // Chain the async push so calls are serialized. Use a recovery wrapper
         // so that a single failed push does not break the chain for subsequent
         // pushes — errors are surfaced via onerror/rejectComplete instead.

package/dist/browser/modules/pdf/core/crypto.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Shared cryptographic primitives for PDF encryption/decryption.
+ *
+ * Zero-dependency, pure JavaScript implementations of:
+ * - AES (128/256-bit) CBC encrypt and decrypt
+ * - SHA-256
+ * - MD5
+ * - RC4 (for reading legacy PDFs only)
+ *
+ * @see FIPS 197 — AES
+ * @see FIPS 180-4 — SHA-256
+ * @see RFC 1321 — MD5
+ */
+/**
+ * AES-CBC encryption with PKCS#7 padding.
+ * Supports AES-128 (16-byte key) and AES-256 (32-byte key).
+ */
+export declare function aesCbcEncrypt(plaintext: Uint8Array, key: Uint8Array, iv: Uint8Array): Uint8Array;
+/**
+ * AES-CBC decryption with PKCS#7 padding removal.
+ * Supports AES-128 (16-byte key) and AES-256 (32-byte key).
+ */
+export declare function aesCbcDecrypt(ciphertext: Uint8Array, key: Uint8Array, iv: Uint8Array): Uint8Array;
+/**
+ * AES-CBC decryption WITHOUT PKCS#7 padding removal.
+ * Used for key derivation in V=5 where the output length is known.
+ */
+export declare function aesCbcDecryptRaw(ciphertext: Uint8Array, key: Uint8Array, iv: Uint8Array): Uint8Array;
+/**
+ * AES-CBC encryption WITHOUT PKCS#7 padding.
+ * Used when the plaintext is already block-aligned (e.g., encrypting
+ * the 32-byte file encryption key in V=5).
+ *
+ * @throws if plaintext length is not a multiple of 16.
+ */
+export declare function aesCbcEncryptRaw(plaintext: Uint8Array, key: Uint8Array, iv: Uint8Array): Uint8Array;
+/**
+ * AES-ECB encryption of a single 16-byte block (no padding, no IV).
+ * Used for the /Perms value in V=5 encryption.
+ */
+export declare function aesEcbEncrypt(block: Uint8Array, key: Uint8Array): Uint8Array;
+/**
+ * SHA-256 hash function.
+ * @returns 32-byte digest
+ */
+export declare function sha256(input: Uint8Array): Uint8Array;
+/**
+ * MD5 hash function (RFC 1321).
+ * @returns 16-byte digest
+ */
+export declare function md5(input: Uint8Array): Uint8Array;
+/**
+ * RC4 stream cipher.
+ * @deprecated Only used for reading legacy encrypted PDFs. Writer uses AES-256.
+ */
+export declare function rc4(key: Uint8Array, data: Uint8Array): Uint8Array;
+/**
+ * Generate pseudo-random bytes.
+ * Uses Math.random — adequate for PDF IVs but not cryptographically secure.
+ */
+export declare function randomBytes(length: number): Uint8Array;
+/**
+ * Concatenate multiple Uint8Arrays.
+ */
+export declare function concatArrays(...arrays: Uint8Array[]): Uint8Array;