Rust XLSX Compatibility Notes

简体中文

Goal

The Rust MVP implements the smallest useful MiniExcel-style XLSX read/write surface behind one MiniExcel facade. It uses a focused OOXML pull parser for bounded-memory path queries, calamine data and Serde conversion internally, and rust_xlsxwriter for workbook generation.

Dependency Baseline

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 query/Insert 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
rust_xlsxwriter	0.96	New XLSX workbook generation and Serde serialization	MIT OR Apache-2.0	0.96 declares Rust 1.83
serde	1.x	Typed mapping	MIT OR Apache-2.0	Resolved by the workspace lockfile
chrono	0.4	Timezone-free Excel date/time values	MIT OR Apache-2.0	Resolved by the workspace lockfile
indexmap	2.x	Stable dynamic column ordering	MIT OR Apache-2.0	Resolved by the workspace lockfile
quick-xml	0.39	Incremental OOXML parsing	MIT	Locked and checked with Rust 1.85
serde_json	1.x	Query plans, analytics/RAG output, parity contracts, and CLI JSON	MIT OR Apache-2.0	Checked with Rust 1.85
sha2	0.10	Streaming SHA-256 source identity for RAG manifests	MIT OR Apache-2.0	Checked with Rust 1.85
thiserror	2.x	Public error composition	MIT OR Apache-2.0	Resolved by the workspace lockfile
uuid	1.x	Typed threaded-comment, reply, person, and legacy-note identifiers	MIT OR Apache-2.0	Resolved by the workspace lockfile
zip	7.2	Incremental worksheet entry decompression	MIT	Locked and checked with Rust 1.85

The latest calamine 0.36 and rust_xlsxwriter 0.97 require Rust 1.88. The MVP pins the preceding API lines so the declared Rust 1.85 MSRV is executable rather than aspirational.

API Mapping

MiniExcel V2 concept	Rust MVP	Notes
OpenXML importer	MiniExcel	Concrete reader/parser types are internal
Dynamic Query	MiniExcel::query()	Streams owned IndexMap<String, CellValue> rows with bounded buffering
Typed Query<T>	MiniExcel::query_as<T>()	Streams rows and applies Serde mapping one row at a time
Structure-preserving query	MiniExcel::query_structured()	Streams sparse rows with one-based coordinates, formulas, style IDs, and number formats
Group/filter analytics	MiniExcel::analyze_with_options()	Versioned Rust extension; streams rows and retains only bounded group/evidence state
RAG evidence export	MiniExcel::export_rag()	Versioned Rust extension; streams addressed JSONL-ready chunks, enriched GFM Markdown, and a source manifest
QueryRange	ReadOptions::with_start_cell() / with_end_cell()	Inclusive A1 range for dynamic and typed reads
GetSheetNames	MiniExcel::get_sheet_names()	Workbook order is preserved
GetSheetInformations	MiniExcel::get_sheet_info()	Includes OOXML ID, order, name, type, visibility, and active state
GetSheetDimensions	MiniExcel::get_sheet_dimensions()	Returns used ranges in workbook order with 1-based indices
GetColumns	MiniExcel::get_columns()	Returns selected dynamic keys or an empty vector
QueryTable	query_table() / query_table_as() / byte and borrowed-reader variants	Case-insensitive table-name lookup, metadata headers, and inclusive table bounds
Exact-cell object mapping	CellMap / read_mapped_as*()	Ordered Serde field-to-A1 bindings; path, bytes, and borrowed readers
Retrieve comments and notes	get_comments() / bytes / borrowed-reader variants	Thread roots, replies, people, resolution/timestamps, and legacy notes
startCell	ReadOptions::with_start_cell()	A1 start coordinate
IgnoreEmptyRows	ReadOptions::with_ignore_empty_rows()	Defaults to false for MiniExcel compatibility
FillMergedCells	ReadOptions::with_fill_merged_cells()	Defaults to false; applies to dynamic, typed, and byte queries
OpenXML exporter	MiniExcel::save_as*()	Concrete writer type is internal; creates new workbooks only
Dynamic export	save_as() / save_as_with_schema()	Map serialization is implemented internally
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
Async path query	query_async*() / query_as_async*()	Optional async feature; bounded dynamic/Serde streams, cooperative cancellation, blocking XLSX workers
Async dynamic/Serde export	save_as_with_schema_async*() / save_as_serialized_async*()	Optional async feature; explicit or first-row-inferred schema, bounded producer, atomic destination, cooperative cancellation, data-cell progress
Async basic template path output	save_as_template_async*()	Optional async feature; scalar/list renderer, atomic destination, cooperative cancellation
MergeSameCells	merge_same_cells() / merge_same_cells_bytes()	@merge/@endmerge regions, optional @mergelimit, all worksheets, atomic source-to-destination path output
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
AutoFilter	WriteOptions::with_auto_filter()	Defaults to true; covers the complete written range
RightToLeft	WriteOptions::with_right_to_left()	Defaults to false; changes worksheet view only
EnableAutoWidth / MinWidth / MaxWidth	WriteOptions::with_auto_width() / with_min_width() / with_max_width()	Fixed v1-style widths; defaults to disabled, 8.42857143, and 200
Per-column width/hidden	WriteOptions::with_column_width() / with_column_hidden()	Final header-name mapping; explicit width seeds AutoWidth
WrapCellContents	WriteOptions::with_wrap_cell_contents()	Defaults to false; wraps ordinary body values only
Body horizontal/vertical alignment	WriteOptions::with_horizontal_alignment() / with_vertical_alignment()	Defaults to left/general and bottom; headers are separate
Header style	HeaderStyle / WriteOptions::with_header_style()	Blue/white/thin-border v1 visual default with configurable wrap, RGB, and alignment
TableStyles.Default / None	TableStyle::Default / None	Cell styling modes; None retains number formats and AutoFilter
Basic template fill	save_as_template() / save_as_template_bytes()	Scalar placeholders and single-row array expansion; preserves package parts
Caller-owned XLSX input	visit_*_from_reader() / metadata *_from_reader()	Borrowed Read + Seek; synchronous visitor model
Caller-owned XLSX output	save_as*_to_writer()	Borrowed Write + Send; dynamic, schema, typed, and multi-sheet

MiniExcel is the only public behavior entry point. Reader, writer, parser, and concrete iterator types are crate-internal. Public supporting types are limited to row/cell values, structured provenance rows, options, errors/results, and Serde date/time helpers.

Compatibility Defaults

• MiniExcel::query() with HeaderMode::Auto uses column letters and treats the first row as data.
• MiniExcel::query_as() with HeaderMode::Auto consumes the first selected row as headers.
• MiniExcel::query_structured() never consumes a header row and emits only cells explicitly represented in worksheet XML.
• The first worksheet in workbook order is selected when no name is supplied.
• Empty rows between the selected start and last used cell are retained by default.
• Merged ranges expose only their physical top-left value unless fill_merged_cells is enabled. Structured queries never synthesize merged cells.
• Typed header strings are trimmed by default. Dynamic headers follow the .NET behavior and retain non-blank text as stored.
• Blank dynamic headers are omitted. Duplicate dynamic headers retain their first key position while later columns overwrite the value.
• A missing dynamic cell is represented by CellValue::Empty, not by omission from a known schema.
• Writer row counts exclude the header row.

Type Mapping

XLSX value	Dynamic Rust value
Empty	CellValue::Empty
Boolean	CellValue::Bool
Exact integral number in i64 range	CellValue::Int
Other number	CellValue::Float
Shared/inline string	CellValue::String
Excel serial date/time	CellValue::DateTime
Excel duration	CellValue::Duration
ISO date/time	Date, Time, or DateTime when parseable
Cell error	CellValue::Error
Formula through dynamic/typed query	Cached result value only
Formula through structured query	Raw formula text and cached result value; no calculation

Typed conversions are delegated to calamine's Serde deserializer. The public serde_helpers module adds strict chrono helpers that convert an invalid value into the library's contextual Error::Deserialize path.

For typed writing, chrono values must use the matching MiniExcel helper (serialize_date_to_excel, serialize_datetime_to_excel, or serialize_time_to_excel) and a corresponding WriteOptions::with_column_format() entry. Otherwise standard chrono Serde behavior writes text rather than an Excel serial value.

Memory And I/O Model

MiniExcel::query() and query_as() use a dedicated path-streaming backend. A worker owns the ZIP archive, reads workbook relationships, styles, and shared strings, then processes worksheet XML with quick-xml. A bounded channel holds at most eight parsed rows. Dropping the public iterator disconnects the channel and joins the worker, so an early take or find stops further work.

Borrowed readers use the same two-pass parser synchronously through callbacks. They are never closed or consumed by the library; ZIP discovery may seek independently on every call, and the final reader position is unspecified. Callback false stops row delivery, while callback errors propagate unchanged. Borrowed writers are left usable, begin at their current position, and are not truncated by the library.

Path queries automatically store xl/sharedStrings.xml in indexed temporary files when its uncompressed size is at least 5 MiB. ReadOptions can disable the cache, change the threshold, or select an existing cache directory. The index uses fixed-width offset/length records, so lookup metadata does not grow in memory with string count. Normal completion, parser failure, and early iterator drop remove the files through worker-owned RAII cleanup. Byte/WASM queries remain memory-only because they do not own a native temporary-filesystem contract.

MiniExcel::query_structured() uses the same bounded pipeline and additionally retains metadata for explicit cells in the current row and channel. Sheet names are shared per row, and number-format strings are shared by style. Missing cells are not expanded into structured cell objects. Formula expressions are preserved exactly as stored, but shared formulas are not expanded and cached values can be stale.

Grouped analytics consume the dynamic row stream without retaining source rows. Memory additionally contains one aggregate state and bounded source-row evidence list per distinct group. QueryPlan::max_groups rejects the group that would exceed the configured limit. Result limits do not reduce group-state memory. Version 1 does not implement disk spill, sorted-input aggregation, or constant-memory high-cardinality grouping.

Path RAG exports retain parser state, repeated header context, and one output chunk. Their manifest hashes the source file through a separate bounded read. Markdown includes stream-level source/sheet provenance and chunk-local formula/style/number-format metadata without retaining prior chunks. Byte/WASM workflows avoid collecting source rows, but browser uploads inherently retain compressed XLSX bytes in WebAssembly memory; generated JSONL, Markdown, and Blob downloads also consume output-sized memory. Browser Lab runs these operations in a Web Worker for responsiveness, not as a claim of path-equivalent memory.

The backend makes two sequential, bounded-memory passes over the selected worksheet entry. The first records the used extent and compact merged-cell rectangles. This is required for MiniExcel-compatible stable dynamic schemas when legal files omit <dimension>, to preserve style-only row elements like the .NET reader, and to support opt-in merged-cell filling without expanding ranges into an address map. The second pass emits rows and retains only anchor values for currently active merged ranges. Worksheet XML and prior rows are never retained; memory consists primarily of in-memory or disk-indexed shared strings, styles, merge metadata, parser buffers, the current row, and the bounded channel.

The internal writer assembles a new ZIP package with one or more worksheets. Path saves refuse existing files by default and can explicitly replace them. Path Insert APIs append or replace a worksheet through a validated package rewrite and atomic sibling-file replacement; unchanged ZIP entries and existing worksheet identities are preserved. Separate borrowed Insert APIs accept Read + Seek input and an empty Write + Seek output, leave both open, and preserve the same package behavior without atomic commit, rollback, or post-write validation. Fallible explicit-schema producers are consumed once through a disk spool and a constant-memory worksheet writer. Generated donor worksheet XML, shared-string conversion, style-ID rebasing, and ZIP insertion use temporary-file streams, so worksheet memory is independent of row count. Path Insert also uses advisory locking and a pre-commit source fingerprint to prevent lost concurrent updates. Template fills rewrite worksheet XML within a copied package; worksheet styles and unrelated ZIP parts are retained. Array expansion shifts row and cell addresses and updates the worksheet dimension. Formula expressions are preserved but not recalculated, and version 1 does not adjust formula references, merged ranges, tables, drawings, or defined names after inserted rows.

Test Sources

Rust integration tests reuse the repository's existing files under tests/data/xlsx, including:

• Dynamic header and no-header files.
• Center and self-closing empty rows.
• Typed value and trimmed-header mapping.
• Multiple worksheets.
• Cells without explicit r attributes.
• A typed conversion failure with a verified Excel row number.
• Strict streaming A1 starts, empty-row filtering, dates, trimmed headers, and early typed errors.
• Opt-in vertical and horizontal merged-cell filling across dynamic, typed, and byte queries.
• Forced shared-string disk spill, indexed lookup, invalid-directory handling, memory-only byte queries, and early-drop cleanup.
• Borrowed dynamic, typed, and structured readers; repeated metadata reads; callback stopping/errors; borrowed dynamic/schema/typed/multi-sheet writers.
• Structured formula text, cached values, A1 addresses, style IDs, built-in/custom number formats, ranges, and early iterator drop.

Writer tests generate temporary workbooks through MiniExcel::save_as*() and read them back through MiniExcel::query*(), covering dynamic and typed values, dates, multiple worksheets, visible/hidden/very-hidden states, active-sheet selection, row counts, empty schemas, default/custom/disabled freeze panes, header/headerless/typed AutoFilter ranges, right-to-left views, bounded fixed AutoWidth output, explicit/hidden column layout, ordinary body wrapping with formatted-value exclusions, body alignment composed with wrapping and number formats, default/custom header styles, default/minimal cell style modes, explicit path overwrite behavior, and worksheet-name validation. Template tests cover scalar and mixed text, native numbers and booleans, XML escaping, formula-injection protection, missing-variable policy, empty and populated arrays, multiple sheets, style retention, path overwrite, and byte workflows. The WASM adapter has native unit tests, while Browser Lab Playwright tests cover generated-workbook rendering, query controls, inclusive end ranges, the collapsible and resizable control rail with its validated persisted layout, and desktop/mobile viewports.

TableStyle controls ordinary cell formats and is not an OOXML table abstraction. Neither mode creates xl/tables entries or worksheet tableParts.

Header background colors are RGB-only. MiniExcel v1 serializes the default as ARGB 284472C4; Rust emits the visually equivalent opaque FF4472C4 because the backend does not preserve arbitrary alpha for spreadsheet fills.

.NET Parity Contract

Behavior shared by .NET and Rust is defined in tests/data/contracts/xlsx-parity-v1.json. This file is the single expected-data source for:

• MiniExcel.OpenXml.Tests/Compatibility/RustParityContractTests.cs
• miniexcel/tests/parity_contract.rs

Both adapters use their public APIs, query the same XLSX fixtures, normalize language-specific representations, and compare sheet order, row counts, column order, selected values, and common conversion-error context. Normalization maps null/empty cells, booleans, numbers, GUIDs, datetimes, durations, and strings to stable tagged text. In particular, integral .NET double and Rust CellValue::Int values compare as the same number, and ISO date strings compare with chrono date/time values.

Run both sides from the repository root:

cargo +1.85.0 test -p miniexcel --test parity_contract --locked
dotnet test ../MiniExcel/tests/MiniExcel.OpenXml.Tests/MiniExcel.OpenXml.Tests.csproj --framework net10.0 --filter "FullyQualifiedName~RustParityContractTests"

The Rust workflow runs the Rust contract on Linux and Windows. Its .NET parity job checks out the MiniExcel repository, copies this revision's contract into that checkout, and runs the .NET adapter on Linux. A compatibility change is complete only when the shared contract is updated deliberately and both adapters pass it.

The contract covers only the current common surface: dynamic/typed path queries, inclusive range queries, column-name discovery, header behavior, sheet selection/order, A1 starts, empty/style-only rows, inferred cell references, scalar/date/duration mapping, trimmed typed headers, and conversion-error row/value context. Structured provenance is a Rust research extension and is not a .NET parity claim. Async APIs are tested against the same fixtures but are not part of the shared contract; DataReader, templates, and writing parity also remain outside version 1.

.NET Coverage Boundary

.NET surface	Rust status	Shared contract
Dynamic and typed XLSX query	Implemented	Yes
Exact-cell Serde object mapping	Implemented	Rust path/bytes/borrowed parity tests; scoped .NET FluentMapping baseline
QueryRange with A1 coordinates	Implemented	Yes
GetSheetNames and GetColumns	Implemented	Yes
GetSheetInformations ID/index/name/type/visibility/active	Implemented	Rust tests against .NET fixtures
GetSheetDimensions	Implemented	Rust tests against .NET fixtures
Named OpenXML QueryTable	Implemented	Rust and .NET focused tests against TestQueryTable.xlsx
Threaded comments and legacy notes	Implemented	Rust and .NET focused tests against TestCommentsAndNotes.xlsx
CSV dynamic/typed query, save, append, and columns	Implemented	Rust tests plus pinned .NET CSV fixtures/baseline tests
New-workbook SaveAs, including multiple sheets	Implemented and roundtrip-tested	Not yet
Basic SaveAsTemplate scalar/list fill	Implemented and roundtrip-tested	Not yet
Enumerable-cell conditional template blocks	Implemented for string/number/bool comparisons	Rust sync/async tests; scoped .NET conditional test
Enumerable grouped template blocks	Implemented for JSON arrays with adjacent header suppression	Rust sync/async tests; scoped .NET sync/async group tests
$= formula templates	Implemented for ordinary and single-row enumerable expansion	Rust formula/address/calcChain tests; scoped .NET formula/calcChain tests
Byte-array query/write for WASM	Implemented	Rust/browser tests
Versioned grouped analytics	Rust research extension	No
Addressed JSONL/Markdown/manifest RAG export	Rust research extension	No
Async Insert producer	Implemented behind optional feature	Rust cancellation tests; not shared internals
Async dynamic/typed path query	Implemented behind optional feature	Rust parity, cancellation, error, and cleanup tests
Async dynamic/Serde path export	Implemented behind optional feature	Rust explicit/inferred schema, rollback, cancellation, progress, and cleanup tests; pinned .NET async-enumerable/progress baseline
Async basic template path output	Implemented behind optional feature	Rust success, rollback, cancellation, and cleanup tests; scoped pinned .NET async template baseline
DataReader and broader stream ownership	Deferred	No
Append worksheet to existing .xlsx workbook	Implemented and atomically committed	Rust tests; shared parity contract not yet extended
Strict worksheet replacement	Implemented for plain targets and supported target-owned closures	Rust tests; stale calcChain removed and full recalculation requested
Atomic worksheet rename	Implemented for existing .xlsx paths	Rust package-preservation tests; pinned .NET AlterSheet baseline
Atomic worksheet visibility mutation	Implemented for existing .xlsx paths	Rust invariant/rollback tests; pinned .NET AlterSheet baseline
Atomic worksheet reorder	Implemented for existing .xlsx paths	Rust positional-reference/rollback tests; pinned .NET AlterSheet baseline
Legacy .xls, .xlsb, and .ods formats	Deferred	No
Atomic workbook copy-and-add	Implemented for dynamic/schema/Serde path APIs	Rust source/destination rollback tests; pinned .NET CopyAndAddSheet baseline
Marker-driven MergeSameCells	Implemented	Exact Rust/.NET fixtures and scoped sync/async .NET baselines
Advanced templates and pictures	Deferred	No

This matrix is the coverage claim: Rust does not yet provide complete API parity with the current .NET packages.

Deferred Work

SQL text parsing, HAVING, ORDER BY, joins, windows, pivots, disk-spill aggregation, vector indexing, model calls, old Excel formats, nested/logical template conditions, grouped/conditional formulas and sheet cloning, image authoring, merged-cell APIs, formula calculation/dependency expansion, general formula authoring, general styling, async template streams, inferred/typed async export sources, async borrowed readers/writers, and borrowed XLSX lazy readers require separate design and acceptance milestones. CSV DataReader/DataTable adapters are intentionally replaced by Rust iterators, and a one-call CSV/XLSX converter is not exposed; callers compose query and save APIs. See the Insert migration guide for supported workflows and deliberate differences.