Overview

Understanding how typed-xlsx processes rows helps you make the right decisions for large-scale exports.

Buffered mode memory model

In buffered mode, createWorkbook() holds everything in memory simultaneously:

1. Your full rows: T[] array as passed into .table()
2. The planned row output (expanded sub-rows, merged cells resolved)
3. The OOXML XML strings for the entire sheet
4. The in-memory ZIP archive

Peak heap is roughly proportional to rows × avg-columns × avg-cell-size × 3–4× for the multiple representation layers. A report with 10,000 rows and 30 columns of mostly string data sits comfortably in memory for most environments. A report with 300,000 rows of the same shape likely does not.

Stream mode memory model

In stream mode, createWorkbookStream() holds only one batch in memory at a time:

1. The current .commit({ rows }) batch while it's being serialized
2. The style registry (small — just deduplicated CellStyle objects)
3. Summary accumulators (one value per column per summary definition)
4. The shared string table, if strings: "shared" is active

Serialized XML fragments are appended to a spool (file or memory buffer) as each commit finishes. The final ZIP is assembled by streaming the spool contents — the compressor never loads the full workbook.

With tempStorage: "file" and strings: "inline", peak heap is:

max(batch_size × columns × cell_overhead) + style_registry + accumulators

For a 5000-row batch with 20 columns, this is typically 10–50 MB depending on cell content, well within any production Node.js environment.

Where time is spent

Buffered

All stages complete before any output is produced. The total time scales linearly with row count.

Stream

Commit calls scale linearly with batch size. Finalization time is dominated by ZIP compression of the already-serialized OOXML.

Throughput characteristics

These are rough estimates. Actual time depends on cell content complexity, style count, auto-width computation, and system I/O.

Summary accumulation and why it enables streaming

The pre-v1 summary API passed the full rows: T[] array to a value function. This meant summaries could not be computed until all rows were available, making stream mode impossible.

The reducer model (init / step / finalize) processes rows incrementally:

import { 
createExcelSchema
 } from "@chronicstone/typed-xlsx";

createExcelSchema
<{ 
amount
: number }>()
  .
column
("amount", {
    
accessor
: "amount",
    
summary
: (
summary
) => [
      
summary
.
cell
({
        
init
: () => 0, // called once at the start
        
step
: (
acc
, 
row
) => 
acc
 + 
row
.
amount
, // called per row, per batch
        
finalize
: (
acc
) => 
acc
, // called once at finalization
        
style
: { 
numFmt
: "#,##0.00", 
font
: { 
bold
: true } },
      }),
    ],
  })
  .
build
();

The accumulator is updated during each .commit() call as rows are processed. At finalization, finalize() is called once and the summary row is appended to the spool. No rows are held.