Skip to content
Docs: Hypaxel for RustMenu

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.

v0.3.0 unreleasedLast updated View as Markdown

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)].

Compatibilityv0.3.0 unreleased
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#

Install · crates.io
cargo add hypaxel
cargo add hypaxel-axum

Not published yethypaxel, hypaxel-axum are not on crates.io yet. The command above is what installation will look like once it is.

The crates are not published yet. Until then, build them from source: see Building from source.

CratePurpose
hypaxelCore writer and reader. Features: chrono (default), serde (default), tokio
hypaxel-axumXlsx response type for axum 0.8

Quick start#

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, Vecs, slices, serde records or async streams.

axum#

hypaxel-axum turns iterators, closures and async Streams into download responses:

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.

#[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#

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#

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:

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 rowsXeon 2.1 GHz, 4 vCPUs, Linux; Rust 1.97, --release. Compared with rust_xlsxwriter 0.102.
100k rowslower is better
  1. Hypaxel (tuples)74 ms, best
  2. Hypaxel (serde records)75 ms, best
  3. Hypaxel (shared strings)100 ms, 1.4×
  4. Hypaxel (deflate level 6)316 ms, 4.3×
  5. rust_xlsxwriter (constant memory)796 ms, 11×
  6. rust_xlsxwriter1,019 ms, 14×
Rust: 100,000 and 1,000,000 rows
Case100k rows1M rowsFile (1M)
Hypaxel (tuples)74 ms0.75 s50 MB
Hypaxel (serde records)75 ms0.75 s50 MB
Hypaxel (shared strings)100 ms1.4 s53 MB
Hypaxel (deflate level 6)316 ms3.1 s31 MB
rust_xlsxwriter (constant memory)796 ms8.7 s57 MB
rust_xlsxwriter1,019 ms11 s59 MB

Methodology and notes · Benchmark source

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 stringsApple M1 Max, macOS; Rust 1.100, --release. Compared with calamine 0.38.
Timelower is better
  1. Hypaxel XlsxReader0.78 s, best
  2. calamine worksheet_cells_reader2.18 s, 2.8×
  3. calamine worksheet_range2.43 s, 3.1×
Rust reading: 1,000,000 rows, inline strings
CaseTimePeak RSS
Hypaxel XlsxReader0.78 s7 MB
calamine worksheet_cells_reader2.18 s7 MB
calamine worksheet_range2.43 s793 MB

Methodology and notes · Benchmark source

Rust reading: 1,000,000 rows, shared stringsApple M1 Max, macOS; Rust 1.100, --release. Compared with calamine 0.38.
Timelower is better
  1. Hypaxel XlsxReader0.73 s, best
  2. calamine worksheet_cells_reader2.05 s, 2.8×
  3. calamine worksheet_range2.33 s, 3.2×
Rust reading: 1,000,000 rows, shared strings
CaseTimePeak RSS
Hypaxel XlsxReader0.73 s57 MB
calamine worksheet_cells_reader2.05 s64 MB
calamine worksheet_range2.33 s849 MB

Methodology and notes · Benchmark source

See Performance for methodology and reproduction, and Benchmarks for the full tables.

Building from source#

The source is at github.com/vensas/hypaxel, in the rust/ directory. Report bugs at github.com/vensas/hypaxel/issues.

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.