@cj-tech-master/excelts 6.2.0 → 7.0.0

package/README.md

@@ -6,15 +6,12 @@ Modern TypeScript Excel Workbook Manager - Read, manipulate and write spreadshee
 
 ## About This Project
 
-ExcelTS is a modern TypeScript Excel workbook manager with:
+ExcelTS is a zero-dependency TypeScript toolkit for spreadsheets and documents:
 
-- 🚀 **Zero Runtime Dependencies** - Pure TypeScript implementation with no external packages
-- ✅ **Broad Runtime Support** - LTS Node.js, Bun, and modern browsers (Chrome, Firefox, Safari, Edge)
-- ✅ **Full TypeScript Support** - Complete type definitions and modern TypeScript patterns
-- ✅ **Modern Build System** - Using Rolldown for faster builds
-- ✅ **Enhanced Testing** - Migrated to Vitest with browser testing support
-- ✅ **ESM First** - Native ES Module support with CommonJS compatibility
-- ✅ **Named Exports** - All exports are named for better tree-shaking
+- 🚀 **Zero Runtime Dependencies** — Pure TypeScript, no external packages
+- 📦 **Five Modules** — Excel (XLSX/JSON), PDF (standalone engine + Excel bridge), CSV (RFC 4180), Archive (ZIP/TAR), Stream (cross-platform)
+- ✅ **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
 
 ## Translations
 
@@ -104,7 +101,7 @@ cell.fill = {
   - Pivot tables
 
 - **PDF Export**
-  - Zero-dependency Excel-to-PDF conversion
+  - Full-featured, zero-dependency PDF engine (standalone or with Excel)
   - Full cell styling (fonts, colors, borders, fills, alignment)
   - Automatic pagination with repeat header rows
   - TrueType font embedding for Unicode/CJK text
@@ -141,7 +138,7 @@ import { Readable, pipeline, createTransform } from "@cj-tech-master/excelts/str
 
 Each subpath supports `browser`, `import` (ESM), and `require` (CJS) conditions. See the module READMEs for details:
 
-- [PDF Module](src/modules/pdf/README.md) - Zero-dependency Excel-to-PDF export with encryption and font embedding
+- [PDF Module](src/modules/pdf/README.md) - Full-featured zero-dependency PDF engine with encryption and font embedding
 - [CSV Module](src/modules/csv/README.md) - RFC 4180 parser/formatter, streaming, data generation
 - [Archive Module](src/modules/archive/README.md) - ZIP/TAR create/read/edit, compression, encryption
 - [Stream Module](src/modules/stream/README.md) - Cross-platform Readable/Writable/Transform/Duplex
@@ -151,7 +148,7 @@ Each subpath supports `browser`, `import` (ESM), and `require` (CJS) conditions.
 Export any workbook to PDF with zero external dependencies:
 
 ```javascript
-import { Workbook, exportPdf } from "@cj-tech-master/excelts";
+import { Workbook, excelToPdf } from "@cj-tech-master/excelts";
 
 const workbook = new Workbook();
 const sheet = workbook.addWorksheet("Report");
@@ -163,7 +160,7 @@ sheet.addRow({ product: "Widget", revenue: 1000 });
 sheet.getColumn("revenue").numFmt = "$#,##0.00";
 
 // One-line export
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   showGridLines: true,
   showPageNumbers: true,
   title: "Sales Report"
@@ -184,13 +181,13 @@ window.open(url);
 ```javascript
 const workbook = new Workbook();
 await workbook.xlsx.readFile("input.xlsx");
-const pdf = exportPdf(workbook);
+const pdf = excelToPdf(workbook);
 ```
 
 ### Encryption
 
 ```javascript
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   encryption: {
     ownerPassword: "admin",
     userPassword: "reader",
@@ -204,11 +201,42 @@ const pdf = exportPdf(workbook, {
 ```javascript
 import { readFileSync } from "fs";
 
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   font: readFileSync("NotoSansSC-Regular.ttf") // TrueType font for CJK text
 });
 ```
 
+### Standalone PDF (No Excel)
+
+Generate PDFs from plain data — no workbook, no Map objects, no boilerplate:
+
+```javascript
+import { pdf } from "@cj-tech-master/excelts/pdf";
+
+// Simplest — pass a 2D array
+const bytes = pdf([
+  ["Product", "Revenue"],
+  ["Widget", 1000],
+  ["Gadget", 2500]
+]);
+
+// With column widths and styled cells
+const bytes = pdf(
+  {
+    name: "Report",
+    columns: [
+      { width: 25, header: "Product" },
+      { width: 15, header: "Revenue" }
+    ],
+    data: [
+      ["Widget", 1000],
+      ["Gadget", 2500]
+    ]
+  },
+  { showGridLines: true }
+);
+```
+
 For the full API reference and all options, see the [PDF Module documentation](src/modules/pdf/README.md).
 
 ## Archive Utilities (ZIP/TAR)
@@ -506,8 +534,8 @@ import {
   xmlDecode,
 
   // PDF export
-  exportPdf, // Workbook -> Uint8Array (PDF)
-  PdfExporter, // Class-based PDF export
+  pdf, // Simplest: pdf([["A", 1], ["B", 2]]) → Uint8Array
+  excelToPdf, // Workbook -> Uint8Array (Excel-to-PDF)
   PageSizes, // Built-in page size definitions
   PdfError, // Base PDF error
   PdfRenderError, // Layout/rendering failures

package/README_zh.md

@@ -6,15 +6,12 @@
 
 ## 关于本项目
 
-ExcelTS 是现代化的 TypeScript Excel 工作簿管理器，具有以下特性:
+ExcelTS 是零依赖的 TypeScript 电子表格与文档工具包：
 
-- 🚀 **零运行时依赖** - 纯 TypeScript 实现，无任何外部包依赖
-- ✅ **广泛运行时支持** - 支持 LTS Node.js、Bun 及主流最新浏览器（Chrome、Firefox、Safari、Edge）
-- ✅ **完整的 TypeScript 支持** - 完整的类型定义和现代 TypeScript 模式
-- ✅ **现代构建系统** - 使用 Rolldown 进行更快的构建
-- ✅ **增强的测试** - 迁移到 Vitest 并支持浏览器测试
-- ✅ **ESM 优先** - 原生 ES Module 支持，兼容 CommonJS
-- ✅ **命名导出** - 所有导出都是命名导出，更好的 tree-shaking
+- 🚀 **零运行时依赖** — 纯 TypeScript 实现，无任何外部包依赖
+- 📦 **五大模块** — Excel（XLSX/JSON）、PDF（独立引擎 + Excel 桥接）、CSV（RFC 4180）、Archive（ZIP/TAR）、Stream（跨平台）
+- ✅ **跨平台** — Node.js 22+、Bun、Chrome 89+、Firefox 102+、Safari 14.1+
+- ✅ **ESM 优先** — 原生 ES Modules，兼容 CommonJS，完整 tree-shaking 支持
 
 ## 翻译
 
@@ -151,7 +148,7 @@ import { Readable, pipeline, createTransform } from "@cj-tech-master/excelts/str
 零依赖将任意工作簿导出为 PDF：
 
 ```javascript
-import { Workbook, exportPdf } from "@cj-tech-master/excelts";
+import { Workbook, excelToPdf } from "@cj-tech-master/excelts";
 
 const workbook = new Workbook();
 const sheet = workbook.addWorksheet("报告");
@@ -163,7 +160,7 @@ sheet.addRow({ product: "组件A", revenue: 1000 });
 sheet.getColumn("revenue").numFmt = "¥#,##0.00";
 
 // 一行导出
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   showGridLines: true,
   showPageNumbers: true,
   title: "销售报告"
@@ -184,13 +181,13 @@ window.open(url);
 ```javascript
 const workbook = new Workbook();
 await workbook.xlsx.readFile("input.xlsx");
-const pdf = exportPdf(workbook);
+const pdf = excelToPdf(workbook);
 ```
 
 ### 加密
 
 ```javascript
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   encryption: {
     ownerPassword: "admin",
     userPassword: "reader",
@@ -204,11 +201,42 @@ const pdf = exportPdf(workbook, {
 ```javascript
 import { readFileSync } from "fs";
 
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   font: readFileSync("NotoSansSC-Regular.ttf") // 嵌入 TrueType 字体以支持中文
 });
 ```
 
+### 独立 PDF 生成（无需 Excel）
+
+无需工作簿，直接从数组数据生成 PDF：
+
+```javascript
+import { pdf } from "@cj-tech-master/excelts/pdf";
+
+// 最简方式 — 传入二维数组
+const bytes = pdf([
+  ["产品", "收入"],
+  ["组件A", 1000],
+  ["组件B", 2500]
+]);
+
+// 带列宽和样式
+const bytes = pdf(
+  {
+    name: "报告",
+    columns: [
+      { width: 25, header: "产品" },
+      { width: 15, header: "收入" }
+    ],
+    data: [
+      ["组件A", 1000],
+      ["组件B", 2500]
+    ]
+  },
+  { showGridLines: true }
+);
+```
+
 完整 API 参考和所有选项请查看 [PDF 模块文档](src/modules/pdf/README.md)。
 
 ## 归档工具（ZIP/TAR）
@@ -504,8 +532,8 @@ import {
   xmlDecode,
 
   // PDF 导出
-  exportPdf, // Workbook -> Uint8Array (PDF)
-  PdfExporter, // 基于类的 PDF 导出
+  pdf, // 最简单：pdf([["A", 1], ["B", 2]]) → Uint8Array
+  excelToPdf, // Workbook -> Uint8Array（Excel 转 PDF）
   PageSizes, // 内置页面尺寸定义
   PdfError, // PDF 基础错误
   PdfRenderError, // 布局/渲染错误

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

@@ -37,6 +37,6 @@ export { xmlEncode, xmlDecode } from "./utils/utils.base.js";
 export { DateParser, DateFormatter, getSupportedFormats, type DateFormat } from "./utils/datetime.js";
 export { BaseError, type BaseErrorOptions, toError, errorToJSON, getErrorChain, getRootCause } from "./utils/errors.js";
 export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString } from "./utils/binary.js";
-export { PdfExporter, exportPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
+export { pdf, excelToPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
 export type { PdfExportOptions, PdfPageSize, PdfOrientation, PdfMargins, PageSizeName, PdfColor } from "./modules/pdf/index.js";
 export { ExcelError, isExcelError, ExcelFileError, ExcelDownloadError, ExcelNotSupportedError, ExcelStreamStateError, InvalidAddressError, ColumnOutOfBoundsError, RowOutOfBoundsError, MergeConflictError, InvalidValueTypeError, XmlParseError, WorksheetNameError, PivotTableError, TableError, ImageError, MaxItemsExceededError } from "./modules/excel/errors.js";

package/dist/browser/index.browser.js

@@ -58,7 +58,7 @@ export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString
 // =============================================================================
 // PDF Export (Browser-compatible, zero external dependencies)
 // =============================================================================
-export { PdfExporter, exportPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
+export { pdf, excelToPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
 // =============================================================================
 // Errors
 // =============================================================================

package/dist/browser/index.d.ts

@@ -19,7 +19,7 @@ export type { PivotTable, PivotTableModel, PivotTableValue, PivotTableSource, Ca
 export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "./modules/excel/form-control.js";
 export type { WorkbookReaderOptions, ParseEvent, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent } from "./modules/excel/stream/workbook-reader.js";
 export type { WorksheetReaderOptions, WorksheetEvent, RowEvent, HyperlinkEvent, WorksheetHyperlink } from "./modules/excel/stream/worksheet-reader.js";
-export type { WorkbookWriterOptions, WorkbookZipOptions, ZipOptions, ZlibOptions } from "./modules/excel/stream/workbook-writer.js";
+export type { WorkbookWriterOptions, WorkbookZipOptions, ZlibOptions } from "./modules/excel/stream/workbook-writer.js";
 export type { CsvOptions, CsvInput } from "./modules/excel/workbook.js";
 export { CsvParserStream, CsvFormatterStream, createCsvParserStream, createCsvFormatterStream } from "./modules/csv/stream/index.js";
 export { DefinedNames, type DefinedNameModel } from "./modules/excel/defined-names.js";
@@ -37,6 +37,6 @@ export { xmlEncode, xmlDecode } from "./utils/utils.base.js";
 export { DateParser, DateFormatter, getSupportedFormats, type DateFormat } from "./utils/datetime.js";
 export { BaseError, type BaseErrorOptions, toError, errorToJSON, getErrorChain, getRootCause } from "./utils/errors.js";
 export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString } from "./utils/binary.js";
-export { PdfExporter, exportPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
+export { pdf, excelToPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
 export type { PdfExportOptions, PdfPageSize, PdfOrientation, PdfMargins, PageSizeName, PdfColor } from "./modules/pdf/index.js";
 export { ExcelError, isExcelError, ExcelFileError, ExcelDownloadError, ExcelNotSupportedError, ExcelStreamStateError, InvalidAddressError, ColumnOutOfBoundsError, RowOutOfBoundsError, MergeConflictError, InvalidValueTypeError, XmlParseError, WorksheetNameError, PivotTableError, TableError, ImageError, MaxItemsExceededError } from "./modules/excel/errors.js";

package/dist/browser/index.js

@@ -54,7 +54,7 @@ export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString
 // =============================================================================
 // PDF Export
 // =============================================================================
-export { PdfExporter, exportPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
+export { pdf, excelToPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
 // =============================================================================
 // Errors
 // =============================================================================

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

@@ -42,8 +42,6 @@ export interface WorkbookZipOptions {
         level?: number;
     };
 }
-/** @deprecated Use {@link WorkbookZipOptions} instead */
-export type ZipOptions = WorkbookZipOptions;
 export interface WorkbookWriterOptions {
     created?: Date;
     modified?: Date;

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

@@ -4,8 +4,8 @@
  * Extends base with file path support and file system image loading.
  */
 import { WorksheetWriter } from "./worksheet-writer.js";
-import { WorkbookWriterBase, type WorkbookWriterOptions as BaseOptions, type WorkbookZipOptions, type ZipOptions, type ZlibOptions } from "./workbook-writer.browser.js";
-export type { WorkbookZipOptions, ZipOptions, ZlibOptions };
+import { WorkbookWriterBase, type WorkbookWriterOptions as BaseOptions, type WorkbookZipOptions, type ZlibOptions } from "./workbook-writer.browser.js";
+export type { WorkbookZipOptions, ZlibOptions };
 export interface WorkbookWriterOptions extends BaseOptions {
     /** If stream not specified, this field specifies the path to a file to write the XLSX workbook to */
     filename?: string;

package/dist/browser/modules/excel/types.d.ts

@@ -326,8 +326,6 @@ export interface ImageData {
     filename?: string;
     buffer?: Buffer;
 }
-/** @deprecated Use {@link ImageData} instead */
-export type Image = ImageData;
 export interface ImagePosition {
     tl: {
         col: number;

package/dist/browser/modules/pdf/excel-bridge.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Excel-to-PDF Bridge
+ *
+ * Converts Excel Workbook data into the PDF module's independent data model.
+ * This is the ONLY file in the PDF module that imports from @excel.
+ *
+ * @example
+ * ```typescript
+ * import { Workbook } from "excelts";
+ * import { excelToPdf } from "excelts/pdf";
+ *
+ * const workbook = new Workbook();
+ * // ... build workbook ...
+ * const pdf = excelToPdf(workbook);
+ * ```
+ */
+import type { Workbook } from "../excel/workbook.js";
+import { type PdfExportOptions } from "./types.js";
+/**
+ * Export an Excel Workbook directly to PDF.
+ *
+ * This is a convenience function that converts the Workbook to the PDF module's
+ * data model and then generates the PDF.
+ *
+ * @param workbook - An Excel Workbook instance
+ * @param options  - PDF export options
+ * @returns PDF file as a Uint8Array
+ */
+export declare function excelToPdf(workbook: Workbook, options?: PdfExportOptions): Uint8Array;