# Hypaxel for Rust

> A constant-memory Rust XLSX writer and streaming reader: stream Excel files to any io::Write or tokio AsyncWrite, read them row by row, and serve axum downloads.

Source: https://hypaxel.libs.vensas.de/docs/rust  
Last updated: 2026-11-20

Hypaxel is a Rust XLSX writer for services that export large tables. It writes `.xlsx` files as a forward-only stream: each cell is serialized to UTF-8 XML the moment you write it and compressed straight into a small buffer, which is flushed to any `io::Write` or tokio `AsyncWrite`. No `Seek` is needed, memory stays at about 200 KiB of buffers per workbook whether you export 10 rows or 10 million, and with `hypaxel-axum` the first bytes reach the HTTP client while your `sqlx` query is still running. The same crate reads `.xlsx` files back: `XlsxReader` streams any `Read + Seek` source one row at a time, about 2.8 times faster than calamine's cell reader, and fails with a clear error on damaged or hostile files. The crate uses `#![deny(unsafe_code)]`.

| | |
| --- | --- |
| Package | `hypaxel`, `hypaxel-axum` |
| Requires | Rust 1.85+ |
| Engine | Native Rust, #![deny(unsafe_code)]; writer and streaming reader |
| Web | axum: Xlsx::from_records(...), Xlsx::from_stream(...) |
| Registry | crates.io (not published yet) |
| License | Apache-2.0 |

## Install

```bash
cargo add hypaxel
cargo add hypaxel-axum
```

_Status: not published to crates.io yet._

The crates are not published yet. Until then, build them from source: see [Building from source](#building-from-source).

| Crate | Purpose |
| --- | --- |
| `hypaxel` | Core writer and reader. Features: `chrono` (default), `serde` (default), `tokio` |
| `hypaxel-axum` | `Xlsx` response type for axum 0.8 |

## Quick start

```rust
use hypaxel::{formats, Color, Formula, SheetOptions, Style, Styled, XlsxWriter};

fn main() -> hypaxel::Result<()> {
    let file = std::io::BufWriter::new(std::fs::File::create("report.xlsx")?);
    let mut writer = XlsxWriter::new(file);

    let header = writer.add_style(&Style::new().bold().font_color(Color::WHITE).fill(Color::hex("#305496").unwrap()));
    let money = writer.add_style(&Style::new().num_format(formats::THOUSANDS2));

    let options = SheetOptions::new().freeze_rows(1).column_widths(&[20.0, 14.0, 14.0]);
    let mut sheet = writer.add_worksheet_with("Sales", &options)?;

    sheet.add_row((Styled("Product", header), Styled("Date", header), Styled("Revenue", header)))?;
    sheet.add_row(("Widget", chrono::NaiveDate::from_ymd_opt(2024, 5, 1).unwrap(), Styled(1234.5, money)))?;
    sheet.add_row(("Gadget", chrono::NaiveDate::from_ymd_opt(2024, 5, 2).unwrap(), Styled(99.99, money)))?;
    sheet.write("Total").skip_cells(1).write_styled(Formula("SUM(C2:C3)"), money).end_row()?;

    writer.finish()?;
    Ok(())
}
```

Cell methods (`write`, `write_styled`, `skip_cells`) are infallible and chainable. Problems at the cell level are reported by the next `end_row` / `add_row` / `finish`, for example text over 32,767 characters or more than 16,384 columns. The offending cell is left empty, so the file stays valid.

Rows can be tuples (up to 16 elements), arrays, `Vec`s, slices, serde records or async streams.

## axum

`hypaxel-axum` turns iterators, closures and async `Stream`s into download responses:

```rust
use axum::{Router, routing::get};
use hypaxel_axum::Xlsx;

// Iterator → worksheet, generated on the blocking pool and streamed while it is produced.
async fn orders() -> Xlsx {
    Xlsx::from_records("Orders", load_orders()).filename("orders.xlsx")
}

// Async source (e.g. sqlx): rows go from the database to the client without being collected.
async fn export(State(pool): State<PgPool>) -> Xlsx {
    let rows = sqlx::query_as::<_, Order>("SELECT ...").fetch(&pool);
    Xlsx::from_stream("Orders", rows).filename("export.xlsx")
}

// Full control with synchronous code ...
async fn report() -> Xlsx {
    Xlsx::from_fn(|w| {
        let mut sheet = w.add_worksheet("Summary")?;
        sheet.add_row(("Generated", chrono::Utc::now()))?;
        w.write_sheet_records("Orders", load_orders())
    })
}

// ... or with async code.
async fn live() -> Xlsx {
    Xlsx::from_async_fn(|mut w| async move {
        let mut sheet = w.add_worksheet("Live")?;
        while let Some(tick) = next_tick().await {
            sheet.add_row_async((tick.at, tick.value)).await?;
        }
        Ok(w)
    })
}
```

`Xlsx` sets `Content-Type`, `Content-Disposition` (RFC 6266/5987 encoded) and `Cache-Control: no-store`.

- **Backpressure:** generation is limited by a bounded channel, so a slow client slows the producer down instead of filling memory.
- **Disconnects:** if the client hangs up, the producer's next write fails and generation stops.
- **Errors:** if the producer fails after streaming has started, the body ends with an error, so the client sees an aborted download instead of a silently truncated file.

The repository includes an example server: `cargo run -p hypaxel-axum --example server`, then open `http://localhost:3000/orders.xlsx?count=1000000`.

## Serde records

Any `T: Serialize` can be written as a record. Serde field names become headers.

```rust
#[derive(serde::Serialize)]
struct Order {
    #[serde(rename = "Order #")]
    id: u32,
    customer: String,
    #[serde(serialize_with = "hypaxel::records::excel_date")]   // native, sortable Excel date
    placed: chrono::NaiveDate,
    amount: f64,
    note: Option<String>,                                       // None → empty cell
}

// New worksheet: styled + frozen header, auto filter, estimated column widths.
writer.write_sheet_records("Orders", &orders)?;

// Or append to an existing sheet with per-column formats:
use hypaxel::records::RecordOptions;
sheet.write_records(&orders, &RecordOptions::new().header(false).column_style("amount", money))?;
```

Structs, maps, tuples and scalars all work. Unit enum variants are written by name. Without `excel_date`, chrono values serialize as ISO strings (text cells). With other serializers such as JSON, the `excel_date` fields still produce ordinary ISO strings.

## Tables, row grouping and auto-fit

```rust
use hypaxel::{AutoFit, RowOptions, SheetOptions, Table, TableStyle};

let options = SheetOptions::new()
    .autofit_columns()            // or .autofit(AutoFit::new().sample_rows(5_000).max_width(60.0))
    .row_outline_levels(1)        // deepest grouping level used on this sheet (1–7)
    .outline_summary_above();     // group buttons on the row above each group
let mut sheet = writer.add_worksheet_with("Regions", &options)?;

sheet.add_row(("Region", "Revenue"))?;
sheet.add_row(("North", 300))?;
sheet.begin_row_with(&RowOptions::new().outline_level(1))?.add_row(("Store A", 120))?;
sheet.begin_row_with(&RowOptions::new().outline_level(1).hidden())?.add_row(("Store B", 180))?;

let last = sheet.row();
sheet.add_table(&Table::new(1, 1, last, 2).name("Regions").columns(["Region", "Revenue"]).style(TableStyle::Medium(9)))?;
```

### Auto-fit

Column widths come before the cell data in the file, so the writer holds back the sheet's output until `sample_rows` rows (default 1,000, at most 8 MiB of XML) have been measured, then inserts the widths and streams as usual. Widths are estimated from the text, number format and font size; formulas and merged cells are not measured. Explicit widths win. The first bytes of a sheet are sent after the sample instead of immediately.

### Row grouping

Declare the deepest level in `SheetOptions`, because Excel reads it before the rows. `begin_row_with` / `begin_row` start a row that the next `add_row` (or cell writes) fills.

### Tables

With a header row, `columns` must equal the header texts as written. Table names are unique in the workbook. Tables cannot overlap each other, merged cells or the worksheet auto filter. The range may include rows written later.

## Async writing

With the `tokio` feature, every flushing method has an `_async` twin for `tokio::io::AsyncWrite` destinations: `add_row_async`, `end_row_async`, `write_records_async`, `write_records_stream`, `write_sheet_stream`, `finish_async`.

## Options

```rust
Options::new()
    .compression_level(1)                     // 0–9; 6 ≈ 40% smaller files at ~4x the CPU
    .string_storage(StringStorage::Inline)    // or Shared for repetitive text
    .flush_threshold(64 * 1024)               // bytes buffered before a write
    .cell_references(false)                   // true = r="A1" on every cell
    .date_1904(false);
```

Pass the options when you create the writer with `XlsxWriter::with_options(out, options)`.

## Reading

`XlsxReader` reads a workbook from a path, or from any `Read + Seek` source with `XlsxReader::new`, and hands out one worksheet at a time:

```rust
use hypaxel::{Value, XlsxReader};

fn main() -> hypaxel::Result<()> {
    let mut reader = XlsxReader::open("orders.xlsx")?;
    println!("{:?}", reader.sheet_names().collect::<Vec<_>>());

    let mut rows = reader.worksheet("Orders")?;          // or worksheet_at(0)
    while let Some(row) = rows.next_row()? {
        // row.number() is the 1-based Excel row; rows without values are skipped.
        for cell in row.cells() {
            match cell.value() {
                Value::String(s) => println!("{}: {s}", hypaxel::cell_ref(row.number(), cell.column())),
                Value::Number(n) => println!("{n}"),
                Value::DateTime(d) => println!("{:?}", d.to_naive_datetime()),
                Value::Bool(b) => println!("{b}"),
                Value::Error(e) => println!("error {e}"),
                _ => {}
            }
        }
        let amount = row.get(3).as_f64();                   // by 1-based column
        let dense: Vec<Value> = row.values().collect();     // columns 1..=last, Empty for gaps
    }
    Ok(())
}
```

`reader.sheets()` lists every sheet in workbook order with its name, visibility and kind, including hidden sheets and chart sheets.

### Values

A cell is a `String`, `Number`, `Bool`, `Error` (`#N/A`, ...) or `Empty`, or a `DateTime` when its built-in or custom number format shows a date, time or duration. `ExcelDateTime` keeps the serial and its `kind()`, and converts with `to_naive_datetime()`, `to_naive_date()`, `to_naive_time()` and `to_duration()`, in both the 1900 and the 1904 system. Times are rounded to the millisecond. Formulas yield their cached result; a formula that was never calculated has no value.

### Memory

Rows are decompressed and parsed as a stream. What stays in memory is the shared string table (text that Excel stores once per workbook) plus the current row. Reading 1M rows peaks at 7 MB RSS for a file with inline strings, and at 57 MB for one whose 1M unique strings are in the shared table.

### Compatibility

The reader accepts files from Excel, LibreOffice, openpyxl, rust_xlsxwriter and other producers. It follows the package relationships instead of fixed paths, and handles Strict Open XML, prefixed namespaces, cells without references, rich text, inline strings and ISO 8601 dates.

### Untrusted input

- **No entity expansion:** DTDs are rejected.
- **Bounded parsing:** every XML token and every row is bounded, and ZIP entries must match their declared size and CRC.
- **Shared strings cap:** `ReadOptions::max_shared_strings_bytes` (default 1 GiB) caps the shared string table. Pass the options with `XlsxReader::with_options(source, &options)`.
- **Clear errors:** legacy `.xls` files, encrypted workbooks, CSV and Word files are reported as `Error::InvalidFile`, and damaged parts as `Error::Malformed`.

### Several sheets at once

`reader.with_source(File::open(path)?)` creates a second reader that shares the parsed workbook and string table, for example for another thread. `into_worksheet` gives rows that own their source.

### Not read yet

Formula text, styles beyond date detection, merged ranges, comments and hyperlinks.

## Notes and limits

These limits apply to writing.

- **Write order:** rows are written top to bottom, and cells left to right. Use `skip_cells`, `skip_rows` and `begin_row_at` to leave gaps.
- **One worksheet at a time:** adding the next worksheet completes the previous one.
- **Options up front:** column definitions, frozen panes and the row outline depth go in `SheetOptions` when you create the sheet. Merges, filters and tables can be added at any time before the sheet completes.
- **Formulas** are stored without cached results. Excel recalculates them when the file opens.
- **Dates:** chrono `NaiveDate`, `NaiveDateTime`, `DateTime<Tz>`, `NaiveTime` and `TimeDelta`, in the 1900 or 1904 system. Unstyled dates get the viewer's locale format. Dates before 1900 are written as ISO text.
- **Values:** NaN and infinity become `#NUM!`.
- **Large files:** the writer has its own streaming ZIP implementation with automatic ZIP64 for worksheets over 4 GB.

## Performance

On a Linux Xeon (2.1 GHz, 4 vCPUs), Hypaxel writes 1 million rows × 10 mixed columns in about 0.75 s, roughly 11 to 14 times faster than rust_xlsxwriter. About half of the time is deflate (zlib-rs, level 1); the other half is generating about 330 MB of XML. The example axum server peaked at 5.4 MB RSS for the whole process after three 3M-row downloads, and at 11 MB with 8 concurrent downloads.

**Rust: 100,000 and 1,000,000 rows**

| Case | 100k rows | 1M rows | File (1M) |
| --- | ---: | ---: | ---: |
| **Hypaxel (tuples)** | 74 ms | 0.75 s | 50 MB |
| **Hypaxel (serde records)** | 75 ms | 0.75 s | 50 MB |
| **Hypaxel (shared strings)** | 100 ms | 1.4 s | 53 MB |
| **Hypaxel (deflate level 6)** | 316 ms | 3.1 s | 31 MB |
| rust\_xlsxwriter (constant memory) | 796 ms | 8.7 s | 57 MB |
| rust\_xlsxwriter | 1,019 ms | 11 s | 59 MB |

_Xeon 2.1 GHz, 4 vCPUs, Linux; Rust 1.97, --release. Compared with rust_xlsxwriter 0.102. Criterion for 100k rows; a stopwatch run for 1M rows. Source: https://github.com/vensas/hypaxel/tree/main/rust/hypaxel/benches_

### Reading

On an Apple M1 Max (macOS, Rust 1.100), `XlsxReader` reads the same dataset, 1M rows × 10 columns written by Hypaxel, in 0.78 s with inline strings and 0.73 s with shared strings, against 2.05 to 2.43 s for calamine 0.38. Peak RSS is 7 MB and 57 MB; calamine's `worksheet_range` needs 793 MB and 849 MB. About a quarter of the time is inflate, and row buffers are reused, so reading allocates nothing per cell.

**Rust reading: 1,000,000 rows, inline strings**

| Case | Time | Peak RSS |
| --- | ---: | ---: |
| **Hypaxel XlsxReader** | 0.78 s | 7 MB |
| calamine worksheet\_cells\_reader | 2.18 s | 7 MB |
| calamine worksheet\_range | 2.43 s | 793 MB |

_Apple M1 Max, macOS; Rust 1.100, --release. Compared with calamine 0.38. examples/read_bench.rs. The file is written by Hypaxel and read cell by cell, with a checksum over all values that every reader must match. Each run is in its own process; best of three. Source: https://github.com/vensas/hypaxel/tree/main/rust/hypaxel/examples_

**Rust reading: 1,000,000 rows, shared strings**

| Case | Time | Peak RSS |
| --- | ---: | ---: |
| **Hypaxel XlsxReader** | 0.73 s | 57 MB |
| calamine worksheet\_cells\_reader | 2.05 s | 64 MB |
| calamine worksheet\_range | 2.33 s | 849 MB |

_Apple M1 Max, macOS; Rust 1.100, --release. Compared with calamine 0.38. examples/read_bench.rs. The file is written by Hypaxel and read cell by cell, with a checksum over all values that every reader must match. Each run is in its own process; best of three. Source: https://github.com/vensas/hypaxel/tree/main/rust/hypaxel/examples_

See [Performance](https://hypaxel.libs.vensas.de/docs/performance) for methodology and reproduction, and [Benchmarks](https://hypaxel.libs.vensas.de/benchmarks) for the full tables.

## Building from source

The source is at [github.com/vensas/hypaxel](https://github.com/vensas/hypaxel), in the `rust/` directory. Report bugs at [github.com/vensas/hypaxel/issues](https://github.com/vensas/hypaxel/issues).

```bash
cargo test --workspace --all-features
```

The writer tests read files back with calamine and inspect the raw parts with the `zip` crate. The reader tests round-trip every value type, read files from rust_xlsxwriter and handcrafted packages (Strict Open XML, unusual XML), check error messages, and feed thousands of randomly damaged files to make sure they fail cleanly. The axum tests drive real routers, including error propagation and client disconnects.
