@cj-tech-master/excelts 1.6.2 → 1.6.3-canary.20251224125850.7da664f

package/README.md

@@ -104,24 +104,157 @@ cell.fill = {
   - Data protection
   - Comments and notes
 
+## 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
+
+### Node.js (Full Streaming Support)
+
+```javascript
+import { Workbook } from "@cj-tech-master/excelts";
+
+const workbook = new Workbook();
+
+// 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();
+```
+
+### 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);
+
+// Write CSV to string
+const csvOutput = workbook.csv.writeString();
+
+// Write CSV to Uint8Array buffer
+const buffer = workbook.csv.writeBuffer();
+```
+
 ## Browser Support
 
-ExcelTS supports both Node.js and browser environments:
+ExcelTS has native browser support with **zero configuration** required for modern bundlers.
+
+### Using with Bundlers (Vite, Webpack, Rollup, esbuild)
+
+Simply import ExcelTS - no polyfills or configuration needed:
 
 ```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
+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)
 
@@ -211,9 +344,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

@@ -104,25 +104,157 @@ cell.fill = {
   - 数据保护
   - 注释和批注
 
+## 流式 API（Node.js）
+
+处理大型 Excel 文件时无需将整个文件加载到内存中，ExcelTS 提供了流式读写 API。
+
+### 流式读取器
+
+以最小内存占用读取大型 XLSX 文件：
+
+```javascript
+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();
+
+// 从文件读取 CSV（流式）
+await workbook.csv.readFile("data.csv");
+
+// 从流读取 CSV
+import fs from "fs";
+const stream = fs.createReadStream("data.csv");
+await workbook.csv.read(stream, { sheetName: "Imported" });
+
+// 写入 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();
+```
+
+### 浏览器（内存中）
+
+```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 同时支持 Node.js 和浏览器环境：
+ExcelTS 原生支持浏览器环境，现代打包工具**无需任何配置**。
+
+### 在打包工具中使用（Vite, Webpack, Rollup, esbuild）
+
+直接导入 ExcelTS - 无需 polyfills 或额外配置：
 
-````javascript
 ```javascript
-// 浏览器使用
-import { Workbook } from "@cj-tech-master/excelts/browser";
+import { Workbook } from "@cj-tech-master/excelts";
 
 const workbook = new Workbook();
-// ... 使用 workbook API
-````
+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）
 
@@ -212,9 +344,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)
 
 ## 更新日志