Streaming

Memory Tuning

tempStorage, memoryProfile, and strings options and when to use each.

createWorkbookStream() accepts three options that control where temporary data lives and how strings are stored in the output file. The right combination depends on your available memory and whether you prefer smaller output files or lower peak heap.

`tempStorage`

Controls where sheet data is spooled while rows are being committed.

Value	Description
`"file"` (default)	Each sheet's OOXML fragments are written to a temp file on disk. Disk I/O is the limiting factor, not RAM.
`"memory"`	Fragments are held in memory buffers. Faster I/O but heap grows with total serialized XML size.

Use "file" for large exports. Use "memory" only when you need maximum throughput and your dataset is small enough that the serialized XML stays well within available heap.

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

// Large export — keep intermediate XML off the heap
const large
 = createWorkbookStream
({ tempStorage
: "file" });

// Small export running in a constrained environment where disk is slow
const small
 = createWorkbookStream
({ tempStorage
: "memory" });

`memoryProfile`

A convenience preset that picks a string-table strategy for you.

Value	String mode	Trade-off
`"balanced"` (default)	`"shared"`	Smaller output file, shared string table kept in heap
`"low-memory"`	`"inline"`	No shared string table in heap, larger output file
`"compact-file"`	`"shared"`	Same as balanced — optimizes for file size

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

// Minimize heap — useful in memory-constrained environments (edge, Lambda)
const lowMem
 = createWorkbookStream
({ memoryProfile
: "low-memory" });

// Minimize output file size
const compact
 = createWorkbookStream
({ memoryProfile
: "compact-file" });

`strings`

Overrides memoryProfile and sets the string storage strategy directly.

Value	Behavior
`"shared"`	All string cells written to a shared string table (`sharedStrings.xml`). Excel deduplicates repeated strings — smaller file for data with many repeated values.
`"inline"`	String values written inline in each cell element. No shared string table is built in memory.
`"auto"`	Falls back to the `memoryProfile` preset.

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

// Explicit shared strings — repeated string values (status, region, category) compress well
const sharedStrings
 = createWorkbookStream
({ strings
: "shared" });

// Explicit inline — no heap overhead for string deduplication
const inlineStrings
 = createWorkbookStream
({ strings
: "inline" });

When both memoryProfile and strings are set, strings takes precedence.

Combining options

For a large export in a memory-constrained environment:

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

const workbook
 = createWorkbookStream
({
  tempStorage
: "file",
  memoryProfile
: "low-memory", // inline strings, no shared table in heap
});

For a medium export where file size matters more than memory:

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

const workbook
 = createWorkbookStream
({
  tempStorage
: "memory", // fast I/O
  strings
: "shared", // deduplicate strings, smaller output
});

What is actually held in heap during streaming

Regardless of tempStorage, the following always lives in heap during a stream export:

The style registry (deduplicated CellStyle objects — usually small)
One batch's worth of rows while a .commit() call is executing
Summary accumulators (one per column per summary definition)
The shared string table, if strings: "shared" is active

With tempStorage: "file" and strings: "inline", peak heap is proportional to your largest single committed batch plus a small constant for the style registry and accumulators.

Output Targets

All five finalization methods — file, Node writable, Web writable, Node readable, Web readable.

Examples

S3 upload, multipart upload, progress tracking, parallel tables, and HTTP back-pressure.