v4 → v5

Version 5 changes the types only. A workbook built with 4.x is built the same way with 5.0: same cells, styles, formulas and files. What changes is what the compiler accepts. Mistakes that used to compile, and were silently ignored or broke the file, are now type errors on the key at fault, with a message that says what would fit.

Upgrade, run your type checker, and fix what it reports. Each case below shows the message and the fix.

Excel table options on a report schema

totalsRow, name and style on a table only work with excel-table schemas. A report schema used to accept them and ignore them.

// 'totalsRow' is not a table option. Options: autoFilter, context, defaults, …
workbook.sheet("Sales").table("sales", { schema: reportSchema, rows, totalsRow: true });

Remove the option, or build the schema with createExcelSchema<Row>({ mode: "excel-table" }) if you want a native table. Report schemas put totals in summary rows.

Unknown options

A misspelled option is an error everywhere: columns, tables, charts, marks and pivots. Chart and pivot specs returned from a callback used to skip this check entirely.

.chart("revenue", ({ refs }) => ({
  titel: "Revenue", // 'titel' is not a chart option. Options: at, axes, colors, legend, marks, size, title
  marks: [refs.table("sales").bar({ x: "month", y: "revenue" })],
}))

Use the option named in the message.

Options that don't fit the column kind

Each column kind accepts its own options. format on a checkbox, variants on a plain column or summary on an excel-table column are errors now.

// 'format' is not an option of checkbox columns. Options: accessor, autoWidth, condition, …
.column("paid", { type: "checkbox", accessor: "paid", format: "0" })

Remove the option, or change the column type.

Accessors must hold a cell value

An accessor path must point at a string, number, boolean, Date, null or undefined, or an array of those. A path to an object used to write [object Object]. Column kinds also check their field: a checkbox needs a boolean.

// 'customer' doesn't hold a cell value (…). Fields that do: customer.name, qty, …
.column("customer", { accessor: "customer" })
// 'qty' doesn't hold a boolean. Fields that do: paid
.column("paid", { type: "checkbox", accessor: "qty" })

Point at a field inside the object ("customer.name"), or use an accessor function.

Charts and pivots check their columns

• A chart y must be a numeric column, after its transform.
• A pivot can only "count" a text, date or boolean column; sum, average, min and max need numbers.
• Grouping a pivot field by year, quarter or month needs a date column that can't be blank. Give a nullable date column a defaultValue.
• Pivot rows must be a non-empty list.

Most of these used to produce a chart of zeros or a pivot Excel had to repair.

@ts-expect-error comments may move

Errors used to be reported on the whole .column() or .table() call as "No overload matches this call". They are now reported on the key. A @ts-expect-error above the call can become unused if the error now sits on a later line: move the comment to the line just above the key.

Annotated schema types

build() returns ReportSchemaDefinition or ExcelTableSchemaDefinition. If you annotate built schemas, use these types (or let TypeScript infer them).

WorkbookTableStream

The streamed table handle has had chart and pivot methods since 4.3. WorkbookTableStream<Row>, without the other type parameters, accepts any handle of that row type, so code that stores handles in a variable typed this way keeps compiling.

Type-check time

The new checks cost a little at compile time on large schemas: a 150-column schema takes about 0.3 s longer on TypeScript 7 (0.80 s instead of 0.46 s), and grows linearly with the number of columns. Schemas of a few dozen columns are within noise.

Also new in 5.0

• An agent skill for coding agents: npx skills add ChronicStone/typed-xlsx.
• Helpers generic over a schema's row and context type (an export runner that forwards context) compile, in both the buffered and streaming builders.