@cj-tech-master/excelts 1.6.3 → 2.0.0-canary.20251228024848.8822305

package/README.md

@@ -8,13 +8,14 @@ Modern TypeScript Excel Workbook Manager - Read, manipulate and write spreadshee
 
 ExcelTS is a modernized fork of [ExcelJS](https://github.com/exceljs/exceljs) with:
 
+- 🚀 **Zero Runtime Dependencies** - Pure TypeScript implementation with no external packages
 - ✅ **Full TypeScript Support** - Complete type definitions and modern TypeScript patterns
-- ✅ **Updated Dependencies** - All dependencies upgraded to latest stable versions
 - ✅ **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
 - ✅ **Node 20+** - Optimized for modern Node.js versions
 - ✅ **Named Exports** - All exports are named for better tree-shaking
+- ✅ **Broad Browser Support** - Works in Chrome 85+, Firefox 79+, Safari 14+ with built-in polyfills
 
 ## Translations
 
@@ -104,53 +105,167 @@ cell.fill = {
   - Data protection
   - Comments and notes
 
-## Browser Support
+## Streaming API (Node.js)
+
+For processing large Excel files without loading them entirely into memory, ExcelTS provides streaming reader and writer APIs.
+
+### Streaming Reader
+
+Read large XLSX files with minimal memory usage:
+
+```javascript
+import { WorkbookReader } from "@cj-tech-master/excelts";
+
+// Read from file path
+const reader = new WorkbookReader("large-file.xlsx", {
+  worksheets: "emit", // emit worksheet events
+  sharedStrings: "cache", // cache shared strings for cell values
+  hyperlinks: "ignore", // ignore hyperlinks
+  styles: "ignore" // ignore styles for faster parsing
+});
+
+for await (const worksheet of reader) {
+  console.log(`Reading: ${worksheet.name}`);
+  for await (const row of worksheet) {
+    console.log(row.values);
+  }
+}
+```
+
+### Streaming Writer
+
+Write large XLSX files row by row:
+
+```javascript
+import { WorkbookWriter } from "@cj-tech-master/excelts";
+
+const workbook = new WorkbookWriter({
+  filename: "output.xlsx",
+  useSharedStrings: true,
+  useStyles: true
+});
+
+const sheet = workbook.addWorksheet("Data");
+
+// Write rows one at a time
+for (let i = 0; i < 1000000; i++) {
+  sheet.addRow([`Row ${i}`, i, new Date()]).commit();
+}
+
+// Commit worksheet and finalize
+sheet.commit();
+await workbook.commit();
+```
+
+## CSV Support
 
-ExcelTS supports both Node.js and browser environments:
+### Node.js (Full Streaming Support)
 
 ```javascript
-// Browser usage
-import { Workbook } from "@cj-tech-master/excelts/browser";
+import { Workbook } from "@cj-tech-master/excelts";
 
 const workbook = new Workbook();
-// ... use workbook API
+
+// Read CSV from file (streaming)
+await workbook.csv.readFile("data.csv");
+
+// Read CSV from stream
+import fs from "fs";
+const stream = fs.createReadStream("data.csv");
+await workbook.csv.read(stream, { sheetName: "Imported" });
+
+// Write CSV to file (streaming)
+await workbook.csv.writeFile("output.csv");
+
+// Write CSV to stream
+const writeStream = fs.createWriteStream("output.csv");
+await workbook.csv.write(writeStream);
+
+// Write CSV to buffer
+const buffer = await workbook.csv.writeBuffer();
 ```
 
-### Vite Configuration
+### Browser (In-Memory)
+
+```javascript
+import { Workbook } from "@cj-tech-master/excelts";
+
+const workbook = new Workbook();
+
+// Load CSV from string
+workbook.csv.load(csvString);
+
+// Load CSV from ArrayBuffer (e.g., from fetch or file input)
+const response = await fetch("data.csv");
+const arrayBuffer = await response.arrayBuffer();
+workbook.csv.load(arrayBuffer);
 
-When using ExcelTS with Vite, you need to install Node.js polyfills:
+// Write CSV to string
+const csvOutput = workbook.csv.writeString();
 
-```bash
-npm install -D vite-plugin-node-polyfills
+// Write CSV to Uint8Array buffer
+const buffer = workbook.csv.writeBuffer();
 ```
 
-Configure your `vite.config.ts`:
+## Browser Support
+
+ExcelTS has native browser support with **zero configuration** required for modern bundlers.
+
+### Using with Bundlers (Vite, Webpack, Rollup, esbuild)
 
-```typescript
-import { defineConfig } from 'vite'
-import { nodePolyfills } from 'vite-plugin-node-polyfills'
+Simply import ExcelTS - no polyfills or configuration needed:
 
-export default defineConfig({
-  plugins: [nodePolyfills()]
-})
+```javascript
+import { Workbook } from "@cj-tech-master/excelts";
+
+const workbook = new Workbook();
+const sheet = workbook.addWorksheet("Sheet1");
+sheet.getCell("A1").value = "Hello, Browser!";
+
+// Write to buffer and download
+const buffer = await workbook.xlsx.writeBuffer();
+const blob = new Blob([buffer], {
+  type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+});
+const url = URL.createObjectURL(blob);
+// ... trigger download
 ```
 
+### Using with Script Tags (No Bundler)
+
+```html
+<script src="https://unpkg.com/@cj-tech-master/excelts/dist/browser/excelts.iife.min.js"></script>
+<script>
+  const { Workbook } = ExcelTS;
+  const wb = new Workbook();
+  // ... use workbook API
+</script>
+```
+
+### Browser-Specific Notes
+
+- **CSV operations are supported** using native RFC 4180 implementation
+  - Use `csv.load(stringOrArrayBuffer)` to read CSV
+  - Use `csv.writeString()` or `csv.writeBuffer()` to write CSV
+- Use `xlsx.load(arrayBuffer)` instead of `xlsx.readFile()`
+- Use `xlsx.writeBuffer()` instead of `xlsx.writeFile()`
+- Worksheet protection with passwords is fully supported (pure JS SHA-512)
+
 ## Requirements
 
 ### Node.js
 
-- **Node.js >= 18.0.0** (ES2020 native support)
-- Recommended: Node.js >= 20.0.0 for best performance
+- **Node.js >= 20.0.0** (ES2020 native support)
 
 ### Browsers (No Polyfills Required)
 
 - **Chrome >= 85** (August 2020)
 - **Edge >= 85** (August 2020)
-- **Firefox >= 113** (May 2023)
-- **Safari >= 16.4** (March 2023)
+- **Firefox >= 79** (July 2020)
+- **Safari >= 14** (September 2020)
 - **Opera >= 71** (September 2020)
 
-All modern JavaScript features are natively supported in these versions.
+For older browsers without native `CompressionStream` API (Firefox < 113, Safari < 16.4), ExcelTS automatically uses a built-in pure JavaScript DEFLATE implementation - no configuration or polyfills needed.
 
 ## Maintainer
 
@@ -230,9 +345,9 @@ This project is a fork of ExcelJS with modernization improvements. All credit fo
 
 ## Links
 
-- [GitHub Repository](https://github.com/cjnoname/exceljs)
+- [GitHub Repository](https://github.com/cjnoname/excelts)
 - [Original ExcelJS](https://github.com/exceljs/exceljs)
-- [Issue Tracker](https://github.com/cjnoname/exceljs/issues)
+- [Issue Tracker](https://github.com/cjnoname/excelts/issues)
 
 ## Changelog
 

package/README_zh.md

@@ -8,13 +8,14 @@
 
 ExcelTS 是 [ExcelJS](https://github.com/exceljs/exceljs) 的现代化版本，具有以下特性:
 
+- 🚀 **零运行时依赖** - 纯 TypeScript 实现，无任何外部包依赖
 - ✅ **完整的 TypeScript 支持** - 完整的类型定义和现代 TypeScript 模式
-- ✅ **升级的依赖** - 所有依赖项升级到最新稳定版本
 - ✅ **现代构建系统** - 使用 Rolldown 进行更快的构建
 - ✅ **增强的测试** - 迁移到 Vitest 并支持浏览器测试
 - ✅ **ESM 优先** - 原生 ES Module 支持，兼容 CommonJS
 - ✅ **Node 20+** - 针对现代 Node.js 版本优化
 - ✅ **命名导出** - 所有导出都是命名导出，更好的 tree-shaking
+- ✅ **广泛浏览器支持** - 支持 Chrome 85+、Firefox 79+、Safari 14+，内置兼容方案
 
 ## 翻译
 
@@ -104,54 +105,167 @@ cell.fill = {
   - 数据保护
   - 注释和批注
 
-## 浏览器支持
+## 流式 API（Node.js）
+
+处理大型 Excel 文件时无需将整个文件加载到内存中，ExcelTS 提供了流式读写 API。
 
-ExcelTS 同时支持 Node.js 和浏览器环境：
+### 流式读取器
+
+以最小内存占用读取大型 XLSX 文件：
 
-````javascript
 ```javascript
-// 浏览器使用
-import { Workbook } from "@cj-tech-master/excelts/browser";
+import { WorkbookReader } from "@cj-tech-master/excelts";
+
+// 从文件路径读取
+const reader = new WorkbookReader("large-file.xlsx", {
+  worksheets: "emit", // 触发工作表事件
+  sharedStrings: "cache", // 缓存共享字符串以获取单元格值
+  hyperlinks: "ignore", // 忽略超链接
+  styles: "ignore" // 忽略样式以加快解析
+});
+
+for await (const worksheet of reader) {
+  console.log(`正在读取: ${worksheet.name}`);
+  for await (const row of worksheet) {
+    console.log(row.values);
+  }
+}
+```
+
+### 流式写入器
+
+逐行写入大型 XLSX 文件：
+
+```javascript
+import { WorkbookWriter } from "@cj-tech-master/excelts";
+
+const workbook = new WorkbookWriter({
+  filename: "output.xlsx",
+  useSharedStrings: true,
+  useStyles: true
+});
+
+const sheet = workbook.addWorksheet("Data");
+
+// 逐行写入
+for (let i = 0; i < 1000000; i++) {
+  sheet.addRow([`第 ${i} 行`, i, new Date()]).commit();
+}
+
+// 提交工作表并完成
+sheet.commit();
+await workbook.commit();
+```
+
+## CSV 支持
+
+### Node.js（完整流式支持）
+
+```javascript
+import { Workbook } from "@cj-tech-master/excelts";
 
 const workbook = new Workbook();
-// ... 使用 workbook API
-````
 
-### Vite 配置
+// 从文件读取 CSV（流式）
+await workbook.csv.readFile("data.csv");
 
-在 Vite 项目中使用 ExcelTS 时，需要安装 Node.js polyfills：
+// 从流读取 CSV
+import fs from "fs";
+const stream = fs.createReadStream("data.csv");
+await workbook.csv.read(stream, { sheetName: "Imported" });
 
-```bash
-npm install -D vite-plugin-node-polyfills
+// 写入 CSV 到文件（流式）
+await workbook.csv.writeFile("output.csv");
+
+// 写入 CSV 到流
+const writeStream = fs.createWriteStream("output.csv");
+await workbook.csv.write(writeStream);
+
+// 写入 CSV 到 buffer
+const buffer = await workbook.csv.writeBuffer();
 ```
 
-配置 `vite.config.ts`：
+### 浏览器（内存中）
 
-```typescript
-import { defineConfig } from 'vite'
-import { nodePolyfills } from 'vite-plugin-node-polyfills'
+```javascript
+import { Workbook } from "@cj-tech-master/excelts";
+
+const workbook = new Workbook();
+
+// 从字符串加载 CSV
+workbook.csv.load(csvString);
+
+// 从 ArrayBuffer 加载 CSV（例如从 fetch 或文件输入）
+const response = await fetch("data.csv");
+const arrayBuffer = await response.arrayBuffer();
+workbook.csv.load(arrayBuffer);
+
+// 写入 CSV 为字符串
+const csvOutput = workbook.csv.writeString();
+
+// 写入 CSV 为 Uint8Array buffer
+const buffer = workbook.csv.writeBuffer();
+```
+
+## 浏览器支持
+
+ExcelTS 原生支持浏览器环境，现代打包工具**无需任何配置**。
+
+### 在打包工具中使用（Vite, Webpack, Rollup, esbuild）
 
-export default defineConfig({
-  plugins: [nodePolyfills()]
-})
+直接导入 ExcelTS - 无需 polyfills 或额外配置：
+
+```javascript
+import { Workbook } from "@cj-tech-master/excelts";
+
+const workbook = new Workbook();
+const sheet = workbook.addWorksheet("Sheet1");
+sheet.getCell("A1").value = "你好，浏览器！";
+
+// 写入 buffer 并下载
+const buffer = await workbook.xlsx.writeBuffer();
+const blob = new Blob([buffer], {
+  type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+});
+const url = URL.createObjectURL(blob);
+// ... 触发下载
+```
+
+### 使用 Script 标签（无打包工具）
+
+```html
+<script src="https://unpkg.com/@cj-tech-master/excelts/dist/browser/excelts.iife.min.js"></script>
+<script>
+  const { Workbook } = ExcelTS;
+  const wb = new Workbook();
+  // ... 使用 workbook API
+</script>
 ```
 
+### 浏览器版本注意事项
+
+- **支持 CSV 操作**（使用原生 RFC 4180 标准实现）
+  - 使用 `csv.load(stringOrArrayBuffer)` 读取 CSV
+  - 使用 `csv.writeString()` 或 `csv.writeBuffer()` 写入 CSV
+- 使用 `xlsx.load(arrayBuffer)` 代替 `xlsx.readFile()`
+- 使用 `xlsx.writeBuffer()` 代替 `xlsx.writeFile()`
+- 完全支持带密码的工作表保护（纯 JS SHA-512 实现）
+
 ## 系统要求
 
 ### Node.js
 
-- **Node.js >= 18.0.0**（原生支持 ES2020）
-- 推荐：Node.js >= 20.0.0 以获得最佳性能
+- **Node.js >= 20.0.0**（原生支持 ES2020）
 
 ### 浏览器（无需 Polyfills）
 
 - **Chrome >= 85**（2020年8月）
 - **Edge >= 85**（2020年8月）
-- **Firefox >= 113**（2023年5月）
-- **Safari >= 16.4**（2023年3月）
+- **Firefox >= 79**（2020年7月）
+- **Safari >= 14**（2020年9月）
 - **Opera >= 71**（2020年9月）
 
-所有现代 JavaScript 特性在这些版本中都原生支持。
+对于不支持原生 `CompressionStream` API 的旧浏览器（Firefox < 113, Safari < 16.4），ExcelTS 会自动使用内置的纯 JavaScript DEFLATE 实现 - 无需任何配置或 polyfills。
 
 ## 维护者
 
@@ -231,9 +345,9 @@ MIT License
 
 ## 链接
 
-- [GitHub 仓库](https://github.com/cjnoname/exceljs)
+- [GitHub 仓库](https://github.com/cjnoname/excelts)
 - [原始 ExcelJS](https://github.com/exceljs/exceljs)
-- [问题跟踪](https://github.com/cjnoname/exceljs/issues)
+- [问题跟踪](https://github.com/cjnoname/excelts/issues)
 
 ## 更新日志