Reference

API Reference

Full reference for createExcelSchema, createWorkbook, createWorkbookStream, and summaries.

`createExcelSchema<T>()`

Returns a SchemaBuilder<T>. Schemas carry no mutable state after .build() and can be reused across any number of tables.

const schema
 = createExcelSchema
<Row
>().column
("name", { accessor
: "name" }).build
();

`SchemaBuilder.column(id, definition)`

Field	Type	Description
`id`	`string`	Stable column identifier. Must be unique within the schema.
`accessor`	`Path<T>` or `(row: T) => value`	Extracts the cell value from the row.
`header`	`string`	Column header text. Defaults to `id`.
`defaultValue`	`CellValue`	Fallback when accessor returns `null` or `undefined`.
`transform`	`(value, row, rowIndex) => CellValue`	Post-processes the extracted value.
`format`	`string` or `(row, rowIndex, subRowIndex) => string`	Excel number format string applied to the cell.
`style`	`CellStyle` or `(row, rowIndex, subRowIndex) => CellStyle`	Style for data cells.
`headerStyle`	`CellStyle`	Style for the header cell.
`width`	`number`	Column width in character units.
`autoWidth`	`boolean`	Compute width from content. Overridden by explicit `width`.
`minWidth`	`number`	Minimum width when `autoWidth` is active.
`maxWidth`	`number`	Maximum width when `autoWidth` is active.
`summary`	`SummaryInput<T>`	Reducer-based summary cells, defined directly or via the callback builder.

`SchemaBuilder.group(id, buildFn)`

Generates columns dynamically from an optional context value passed at table-build time. If the callback declares a second parameter, that parameter type becomes the required context shape for the group id.

Argument	Type	Description
`id`	`string`	Group identifier. Used as the key in the `context` object passed to `.table()`.
`buildFn`	`(builder: SchemaBuilder<T>, context?: TContext) => void`	Called with the current builder and, optionally, the resolved context value.

Selection stays strongly typed at the group level. Use the group id in select.include or select.exclude to include or exclude every generated column from that group:

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

type Row
 = { name
: string; orgs
: number[] };

const schema
 = createExcelSchema
<Row
>()
  .column
("name", { accessor
: "name" })
  .group
("memberships", (builder
, orgIds
: number[]) => {
    for (const id
 of orgIds
) {
      builder
.column
(`org-${id
}`, {
        accessor
: (row
) => row
.orgs
.includes
(id
),
      });
    }
  })
  .build
();

createWorkbook
()
  .sheet
("Users")
  .table
({
    rows
: [],
    schema
,
    select
: { exclude
: ["memberships"] },
  });

When the excluded group is the only contextful group in the schema, context is optional and can be omitted entirely.

`SchemaBuilder.build()`

Returns a frozen SchemaDefinition<T> object. Safe to share across multiple workbooks.

`createWorkbook(options?)`

Returns a Workbook builder for synchronous, in-memory XLSX generation.

`Workbook.sheet(name, options?)`

Option	Type	Description
`tablesPerRow`	`number`	Number of tables placed side-by-side before wrapping. Default: `1`.
`tableColumnGap`	`number`	Blank columns between tables in the same row. Default: `1`.
`tableRowGap`	`number`	Blank rows between table rows. Default: `1`.
`freezePane`	`{ rows?: number; columns?: number }`	Freeze the first N rows and/or columns.
`rightToLeft`	`boolean`	Enable right-to-left sheet direction.

Returns a WorkbookSheet with a .table(input) method.

`WorkbookSheet.table(input)`

Field	Type	Description
`schema`	`SchemaDefinition<T>`	Built schema from `createExcelSchema<T>().build()`.
`rows`	`T[]`	Data rows.
`id`	`string`	Optional table identifier.
`title`	`string`	Optional title row rendered above the header.
`select`	`{ include?: readonly (SchemaColumnId<TSchema> \| SchemaGroupId<TSchema>)[]; exclude?: readonly (SchemaColumnId<TSchema> \| SchemaGroupId<TSchema>)[] }`	Column or group selection by id.
`context`	`SchemaGroupContext<TSchema>`	Required only when selected groups declare a context parameter. Context values are keyed by group id.

Returns the WorkbookSheet for chaining.

Output methods

Method	Return type	Description
`toUint8Array()`	`Uint8Array`	XLSX bytes.
`toBuffer()`	`Buffer`	Node.js Buffer wrapping the XLSX bytes.
`writeToFile(path)`	`Promise<void>`	Write the XLSX file to disk.

`createWorkbookStream(options?)`

Returns a WorkbookStream builder for incremental, commit-based XLSX generation.

Option	Type	Default	Description
`tempStorage`	`"file"` or `"memory"`	`"file"`	Where serialized sheet fragments are spooled.
`tempDirectory`	`string`	OS temp dir	Directory for file-backed spool.
`strings`	`"auto"` · `"inline"` · `"shared"`	`"auto"`	String storage strategy. Overrides `memoryProfile`.
`memoryProfile`	`"balanced"` · `"low-memory"` · `"compact-file"`	`"balanced"`	Convenience preset for string strategy.

`WorkbookStream.sheet(name, options?)`

Accepts a subset of sheet options: freezePane and rightToLeft. Layout options (tablesPerRow, gaps) are also supported.

Returns a WorkbookSheetStream.

`WorkbookSheetStream.table(options)`

Async. Registers a table and returns a WorkbookTableStream<T>.

Field	Type	Description
`id`	`string`	Required table identifier.
`schema`	`SchemaDefinition<T>`	Built schema.
`select`	`{ include?: readonly (SchemaColumnId<TSchema> \| SchemaGroupId<TSchema>)[]; exclude?: readonly (SchemaColumnId<TSchema> \| SchemaGroupId<TSchema>)[] }`	Column or group selection.
`context`	`SchemaGroupContext<TSchema>`	Required only when selected groups declare a context parameter.

`WorkbookTableStream.commit(batch)`

Async. Serializes the batch and appends it to the sheet spool.

Field	Type	Description
`rows`	`T[]`	Batch of rows to serialize.

Output methods

Method	Description
`writeToFile(path)`	Write directly to a file path.
`pipeToNode(stream)`	Pipe to any `NodeJS.WritableStream`.
`pipeTo(stream)`	Pipe to a Web Streams `WritableStream<Uint8Array>`.
`toNodeReadable()`	Returns a `NodeJS.ReadableStream`.
`toReadableStream()`	Returns a Web `ReadableStream<Uint8Array>`.

Only one output method may be called per workbook instance.

`SummaryInput<T>`

The summary field accepts either:

a single SummaryDefinition<T, TAcc>
an array of SummaryDefinition<T, TAcc>
a callback of shape (summary) => SummaryDefinition[]

The callback form is the recommended API because it gives you access to helper methods like summary.cell(...), summary.label(...), and summary.empty().

`SummaryDefinition<T, TAcc>`

Field	Type	Description
`label`	`string`	Optional label cell rendered in non-summary columns on the same summary row.
`init`	`() => TAcc`	Returns the initial accumulator value. Called once.
`step`	`(acc: TAcc, row: T, rowIndex: number) => TAcc`	Updates the accumulator for each row.
`finalize`	`(acc: TAcc) => SummaryCellValue`	Converts the final accumulator to a cell value.
`format`	`string` or `(value) => string`	Number format applied to the summary cell.
`style`	`CellStyle` or `(value) => CellStyle`	Style applied to the summary cell.

Patterns

Practical guidance for large exports — builder choice, batch sizing, auto-width, sub-row expansion, and multi-sheet.

Types

CellStyle, SummaryDefinition, SchemaDefinition, WorkbookStreamOptions, SheetOptions, and TableInput shapes.