Add cancellable runtime-neutral async XLSX inserts

Author: shps951023

Cargo.lock

@@ -12,11 +12,16 @@ homepage = "https://github.com/mini-software/MiniExcel-Rust"
 
 [workspace.dependencies]
 atomicwrites = "0.4.4"
+async-channel = "2.5.0"
 calamine = { version = "0.35.0", features = ["chrono"] }
 chrono = { version = "0.4.42", features = ["serde"] }
 clap = { version = "4.6.6", features = ["derive"] }
 console_error_panic_hook = "0.1.7"
+event-listener = "5.4.1"
 fs2 = "0.4.3"
+futures-core = "0.3.31"
+futures-executor = "0.3.31"
+futures-util = { version = "0.3.31", default-features = false, features = ["async-await", "async-await-macro", "std"] }
 indexmap = { version = "2.12.1", features = ["serde"] }
 quick-xml = "0.39.4"
 rust_xlsxwriter = { version = "0.96.0", features = ["chrono", "serde"] }

Cargo.toml

@@ -314,6 +314,29 @@ Insert holds a cross-process advisory lock and verifies a source SHA-256 fingerp
 concurrent writers or external source changes return a deterministic conflict instead of silently
 overwriting newer content.
 
+Enable the optional `async` feature to feed an existing-workbook Insert from a runtime-neutral
+`Stream<Item = miniexcel::Result<DynamicRow>>`:
+
+```rust
+use miniexcel::{CancellationToken, InsertOptions, MiniExcel};
+
+let cancellation = CancellationToken::new();
+let count = MiniExcel::insert_with_schema_async_with_cancellation(
+    "book.xlsx",
+    &["Name".to_owned(), "Version".to_owned()],
+    rows,
+    &InsertOptions::new().with_sheet_name("Async"),
+    cancellation,
+).await?;
+```
+
+The async API uses a bounded channel for row backpressure and isolates blocking XLSX work on a
+dedicated thread; ZIP, XML, and filesystem I/O are not async. Explicit cancellation waits for
+worker cleanup before returning. Dropping the future requests cooperative cancellation and cleanup
+finishes in the background. Cancellation that wins before commit preserves the original workbook;
+once atomic replacement begins, cancellation cannot revoke it. No async runtime is enabled by
+default, and Tokio is not a dependency.
+
 Appending a formula-free worksheet preserves an existing calculation chain and workbook calculation properties. Replacement removes the complete stale `calcChain` part, relationship, and content-type override, then sets `fullCalcOnLoad` and `forceFullCalc` so Excel recalculates on the next open. MiniExcel does not evaluate or rewrite formulas; formulas and cached values in untouched worksheets remain byte-identical.
 
 ## Typed Writing

README.md

@@ -312,6 +312,28 @@ XML depth 与 relationship count；同时拒绝不安全或别名 part path、
 lock，并在 commit 前校验 source SHA-256 fingerprint；并发 writer 或外部 source 变化会返回
 确定性 conflict，不会静默覆盖更新后的内容。
 
+启用可选 `async` feature 后，可通过 runtime-neutral
+`Stream<Item = miniexcel::Result<DynamicRow>>` 为现有 workbook 的 Insert 提供 row：
+
+```rust
+use miniexcel::{CancellationToken, InsertOptions, MiniExcel};
+
+let cancellation = CancellationToken::new();
+let count = MiniExcel::insert_with_schema_async_with_cancellation(
+    "book.xlsx",
+    &["Name".to_owned(), "Version".to_owned()],
+    rows,
+    &InsertOptions::new().with_sheet_name("Async"),
+    cancellation,
+).await?;
+```
+
+Async API 使用 bounded channel 提供 row backpressure，并把 blocking XLSX 工作隔离到专用
+thread；ZIP、XML 和 filesystem I/O 并不是 async。显式 cancellation 会等待 worker cleanup
+后返回；drop future 会请求 cooperative cancellation，cleanup 在后台完成。Commit 前由
+cancellation 获胜时原 workbook 保持不变；atomic replacement 开始后不能撤销。默认不启用
+任何 async runtime，也不依赖 Tokio。
+
 追加 formula-free worksheet 时会保留已有 calculation chain 与 workbook calculation property。Replacement 会完整删除 stale `calcChain` part、relationship 和 content-type override，并设置 `fullCalcOnLoad` 与 `forceFullCalc`，让 Excel 下次打开时重算。MiniExcel 不执行或改写公式；未修改 worksheet 中的 formula 与 cached value 保持原始字节。
 
 ## 类型化写入

README.zh-CN.md

@@ -11,6 +11,7 @@ The Rust MVP implements the smallest useful MiniExcel-style XLSX read/write surf
 | Dependency | Locked API line | Role | License | MSRV note |
 | --- | --- | --- | --- | --- |
 | `atomicwrites` | 0.4 | Safe cross-platform atomic replacement for Windows path inserts | MIT | Windows-only dependency; checked with Rust 1.85 |
+| `async-channel` / `event-listener` / `futures-*` | 2.5 / 5.4 / 0.3 | Optional runtime-neutral async Insert producer and cancellation | MIT OR Apache-2.0 | Enabled only by the `async` feature; checked with Rust 1.85 |
 | `fs2` | 0.4 | Cross-platform advisory locking for path inserts | MIT OR Apache-2.0 | Checked with Rust 1.85 |
 | `calamine` | 0.35 | XLSX parsing and Serde row deserialization | MIT | 0.35 declares Rust 1.83 |
 | `clap` | 4.6 | Local CLI argument parsing | MIT OR Apache-2.0 | 4.6 declares Rust 1.85 |
@@ -49,6 +50,7 @@ The latest `calamine 0.36` and `rust_xlsxwriter 0.97` require Rust 1.88. The MVP
 | Typed export | `save_as_serialized<T>()` | Uses Serde mapping internally |
 | Multi-sheet export | `save_as_sheets()` / `save_as_serialized_sheets()` | Preserves input sheet order and returns data-row counts |
 | `InsertSheet` append/replace | `insert()` / `insert_with_schema()` / `insert_serialized()` / borrowed reader-to-writer variants | Path APIs are atomic; separate borrowed streams require an empty sink and preserve package behavior without atomic commit |
+| Async Insert producer | `insert_with_schema_async*()` | Optional `async` feature; bounded producer channel with blocking XLSX work on a dedicated thread |
 | Per-sheet visibility | `WriteOptions::with_sheet_visibility()` | Visible, hidden, and very hidden; first visible sheet is active |
 | `overwriteFile` | `WriteOptions::with_overwrite_file()` | Defaults to `false`; existing paths require explicit opt-in |
 | `FreezeRowCount` / `FreezeColumnCount` | `WriteOptions::with_freeze_row_count()` / `with_freeze_column_count()` | Defaults to one frozen row and zero frozen columns |

docs/compatibility.md

@@ -11,6 +11,7 @@ Rust MVP 在统一的 `MiniExcel` facade 后实现最小但实用的 MiniExcel 
 | 依赖 | 锁定 API 版本线 | 用途 | 许可证 | MSRV 说明 |
 | --- | --- | --- | --- | --- |
 | `atomicwrites` | 0.4 | Windows path insert 的安全跨平台原子替换 | MIT | 仅 Windows 依赖；已使用 Rust 1.85 检查 |
+| `async-channel` / `event-listener` / `futures-*` | 2.5 / 5.4 / 0.3 | 可选 runtime-neutral async Insert producer 与 cancellation | MIT OR Apache-2.0 | 仅由 `async` feature 启用；已使用 Rust 1.85 检查 |
 | `fs2` | 0.4 | Path insert 的跨平台 advisory lock | MIT OR Apache-2.0 | 已使用 Rust 1.85 检查 |
 | `calamine` | 0.35 | XLSX 解析和 Serde row 反序列化 | MIT | 0.35 声明 Rust 1.83 |
 | `clap` | 4.6 | 本地 CLI 参数解析 | MIT OR Apache-2.0 | 4.6 声明 Rust 1.85 |
@@ -49,6 +50,7 @@ Rust MVP 在统一的 `MiniExcel` facade 后实现最小但实用的 MiniExcel 
 | 类型化导出 | `save_as_serialized<T>()` | 内部使用 Serde 映射 |
 | 多工作表导出 | `save_as_sheets()` / `save_as_serialized_sheets()` | 保留输入工作表顺序并返回数据行数 |
 | `InsertSheet` append/replace | `insert()` / `insert_with_schema()` / `insert_serialized()` / borrowed reader-to-writer variants | Path API 为原子操作；独立 borrowed stream 要求空 sink，并在无原子 commit 的情况下保持相同 package 行为 |
+| Async Insert producer | `insert_with_schema_async*()` | 可选 `async` feature；bounded producer channel，XLSX 工作在专用 blocking thread |
 | 每表 visibility | `WriteOptions::with_sheet_visibility()` | visible、hidden、very hidden；第一个 visible sheet 为 active |
 | `overwriteFile` | `WriteOptions::with_overwrite_file()` | 默认 `false`；已有路径需要显式允许覆盖 |
 | `FreezeRowCount` / `FreezeColumnCount` | `WriteOptions::with_freeze_row_count()` / `with_freeze_column_count()` | 默认冻结一行、零列 |

docs/compatibility.zh-CN.md

@@ -30,7 +30,7 @@ Rust already implements dynamic and Serde-typed XLSX path queries, inclusive A1
 | Named tables | Missing | Query an OpenXML table by table name (`QueryTable`), including table-specific headers and bounds. |
 | DataReader and DataTable | Missing | `IDataReader`/async reader access, schema tables, typed getters, `NextResult` sheet traversal, and `DataTable` materialization. |
 | Caller-owned streams | Partial | Borrowed synchronous dynamic/typed/structured visitors, metadata reads, dynamic/schema/typed/multi-sheet writers, and separate reader-to-writer Insert are implemented with leave-open semantics. Borrowed lazy iterators, async streams, and template streams remain unsupported. |
-| Async and cancellation | Missing | Async query/export/template operations, async row sources, cancellation tokens, and progress callbacks. Rust iterators are synchronous even though path reads use a worker thread. |
+| Async and cancellation | Partial | Optional runtime-neutral async row production and cancellation are implemented for explicit-schema path Insert. Async query/export/template operations, typed async sources, and progress callbacks remain unsupported. ZIP and filesystem work remains blocking on a dedicated worker. |
 | General save inputs | Partial | Export from general objects/enumerables, dictionaries, `DataTable`, `IDataReader`, and async enumerables, with progress. Rust accepts dynamic or same-type Serde slices and reports per-sheet row counts. |
 | Multi-sheet export | Partial | Rust creates ordered visible, hidden, and very-hidden worksheets, but does not yet accept heterogeneous Serde row types in one call. |
 | Existing-workbook operations | Partial | Rust appends or strictly replaces worksheets through atomic path APIs or separate borrowed streams, preserving unrelated package parts and worksheet identity. Copy-and-add, rename, reorder, and standalone visibility mutation remain unsupported. |

docs/dotnet-feature-gaps.md

@@ -30,7 +30,7 @@ Rust 已支持动态及 Serde 强类型 XLSX 路径查询、闭区间 A1 范围
 | 命名表格 | 未实现 | 按表格名称查询 OpenXML Table（`QueryTable`），并遵循表格自身的表头与范围。 |
 | DataReader 与 DataTable | 未实现 | `IDataReader`/异步 reader、架构表、强类型 getter、通过 `NextResult` 遍历工作表，以及物化为 `DataTable`。 |
 | 调用方提供的流 | 部分实现 | 已实现借用的同步动态/类型化/structured visitor、metadata 读取、动态/schema/类型化/多表 writer，以及独立 reader-to-writer Insert，并保持 leave-open。借用 lazy iterator、async stream 和 template stream 仍不支持。 |
-| 异步与取消 | 未实现 | 异步查询/导出/模板操作、异步行源、取消令牌和进度回调。Rust 路径读取虽使用工作线程，对外迭代器仍是同步的。 |
+| 异步与取消 | 部分实现 | 显式 schema path Insert 已支持可选、runtime-neutral 的 async row producer 与 cancellation。Async query/export/template、类型化 async source 和 progress callback 仍不支持；ZIP 与 filesystem 工作仍在专用 blocking worker 上执行。 |
 | 通用保存输入 | 部分实现 | 从普通对象/可枚举对象、字典、`DataTable`、`IDataReader` 和异步枚举导出，并报告进度。Rust 接受动态行或同类型 Serde 切片，并返回每张工作表的行数。 |
 | 多工作表导出 | 部分实现 | Rust 可按输入顺序创建 visible、hidden 和 very-hidden 工作表，但尚不能在一次调用中接受异构 Serde 行类型。 |
 | 修改现有工作簿 | 部分实现 | Rust 可通过原子 path API 或独立 borrowed stream append 或严格 replace worksheet，并保留无关 package part 与 worksheet identity。复制新增、重命名、重排和独立 visibility 修改仍不支持。 |

docs/dotnet-feature-gaps.zh-CN.md

@@ -406,17 +406,23 @@ successfully round-tripped the streamed style-rebase output.
 
 Depends on Task 11. This task is optional and should use a feature flag.
 
-- [ ] Define an async producer API without making Tokio a mandatory core dependency.
-- [ ] Feed a blocking package worker through a bounded channel.
-- [ ] Support cancellation before preflight, during row generation, during ZIP copy, and before commit.
-- [ ] Guarantee cleanup and original-file preservation for every cancellation point.
-- [ ] Do not present async scheduling as async ZIP I/O if the ZIP backend remains blocking.
+- [x] Define an async producer API without making Tokio a mandatory core dependency.
+- [x] Feed a blocking package worker through a bounded channel.
+- [x] Support cancellation before preflight, during row generation, during ZIP copy, and before commit.
+- [x] Guarantee cleanup and original-file preservation for every cancellation point.
+- [x] Do not present async scheduling as async ZIP I/O if the ZIP backend remains blocking.
 
 Acceptance:
 
 - Cancellation tests cover all lifecycle phases.
 - Default feature builds remain runtime-neutral.
 
+Completed on 2026-08-25 behind the optional `async` feature. The public explicit-schema async
+producer uses a capacity-16 channel, a runtime-neutral `CancellationToken`, and one blocking XLSX
+worker thread. Deterministic phase-hook tests cover cancellation before preflight, before row
+polling, during row generation, ZIP copy, validation, and before commit, plus future-drop cleanup
+and producer-error over-poll protection. Default and wasm32 builds remain runtime-neutral.
+
 ### Task 13: Documentation, Compatibility, And Release
 
 Depends on all required tasks above.

docs/insert-existing-workbook-plan.md

@@ -405,17 +405,23 @@ roundtrip 流式 style-rebase output。
 
 依赖 Task 11；此 task 可选，并应使用 feature flag。
 
-- [ ] 定义 async producer API，不让 Tokio 成为 core mandatory dependency。
-- [ ] 通过 bounded channel 将数据交给 blocking package worker。
-- [ ] 支持 preflight 前、row generation、ZIP copy 与 commit 前 cancellation。
-- [ ] 每个 cancellation point 都保证 cleanup 和原文件保留。
-- [ ] 如果 ZIP backend 仍是 blocking，不得把 async scheduling 描述为 async ZIP I/O。
+- [x] 定义 async producer API，不让 Tokio 成为 core mandatory dependency。
+- [x] 通过 bounded channel 将数据交给 blocking package worker。
+- [x] 支持 preflight 前、row generation、ZIP copy 与 commit 前 cancellation。
+- [x] 每个 cancellation point 都保证 cleanup 和原文件保留。
+- [x] 如果 ZIP backend 仍是 blocking，不得把 async scheduling 描述为 async ZIP I/O。
 
 验收：
 
 - Cancellation test 覆盖全部生命周期阶段。
 - 默认 feature build 保持 runtime-neutral。
 
+已于 2026-08-25 在可选 `async` feature 后完成。Public 显式 schema async producer 使用
+capacity-16 channel、runtime-neutral `CancellationToken` 和一个 blocking XLSX worker
+thread。确定性 phase-hook test 覆盖 preflight 前、row polling 前、row generation、ZIP
+copy、validation、commit 前 cancellation，以及 future-drop cleanup 与 producer-error
+over-poll 防护。默认与 wasm32 build 仍保持 runtime-neutral。
+
 ### Task 13：文档、兼容契约与 Release
 
 依赖以上全部必需 task。