Streaming

Streaming Intro

Open a stream table, commit batches as they arrive, and finalize the workbook, with the same schemas as the buffered builder.

createWorkbookStream() writes a workbook from batches of rows. You open a table, commit pages as your data source returns them, and finalize once. Nothing about the schema changes.

01Opensheet.table(id, { schema })returns a table handle
02Commitcommit({ rows })plans, serializes and spools one batch
03Repeatfor await (…)as many batches as you have
04FinalizewriteToFile() · pipeTo()summary rows, then the ZIP is streamed out

A complete stream

import { createExcelSchema
, createWorkbookStream
 } from "typed-xlsx";

type Sale
 = { date
: string; region
: string; revenue
: number };
declare function salesPages
(): AsyncIterable
<Sale
[]>;

const schema
 = createExcelSchema
<Sale
>()
  .column
("date", { header
: "Date", accessor
: "date" })
  .column
("region", { header
: "Region", accessor
: "region" })
  .column
("revenue", {
    header
: "Revenue",
    accessor
: "revenue",
    style
: { numFmt
: '"$"#,##0.00' },
    summary
: (s
) => [s
.formula
("sum")],
  })
  .build
();

const workbook
 = createWorkbookStream
();
const table
 = await workbook
  .sheet
("Sales", { freezePane
: { rows
: 1 } })
  .table
("sales", { schema
 });

for await (const page
 of salesPages
()) {
  await table
.commit
({ rows
: page
 });
}

await workbook
.writeToFile
("./sales.xlsx");

Two differences from the buffered builder: .table() is awaited and returns a handle instead of the sheet, and rows go through commit() instead of a rows option.

Each commit() runs the batch through the same planner as the buffered builder: sub-row expansion, merges, widths, styles and formulas. It then serializes the rows to sheet XML, appends them to the sheet's temporary spool, and advances every summary reducer. When the promise resolves, the batch has been written and can be garbage collected.

Await each commit before starting the next one on the same table; that is how backpressure reaches your data source.

What finalizing does

The output method (writeToFile(), pipeTo(), pipeToNode(), toReadableStream() or toNodeReadable()) finishes the summary rows and totals, then streams every part of the workbook into the ZIP. Call exactly one output method per workbook. See Output Targets.

What the stream builder supports

Everything the buffered builder does: report and excel-table modes, formula columns, summary rows and totals rows, sub-row expansion, groups and dynamic columns, column selection, themes and styles, conditional formats, validation, hyperlinks, images, sparklines, protection, freeze panes and several tables per sheet.

Output Targets: files, HTTP responses, S3, Web streams
Memory Tuning: temp storage and string modes
Large Exports and Benchmarks

Protection

Lock a workbook's structure, protect sheets, and choose which cells stay editable or hide their formulas.

Output Targets

[object Object]

Streaming Intro

A complete stream

What a commit does

What finalizing does

What the stream builder supports

Next