@chronicstone/typed-xlsx

Excel Reporting
Re-Engineered.

Schema-driven XLSX generation for TypeScript. If the export definition is wrong, the compiler tells you — not the spreadsheet.

Get started Why typed-xlsx?

npm install @chronicstone/typed-xlsx MIT license Zero dependencies

schema + formula + export

Invoice report — full example

const const schema: SchemaDefinition<Invoice, "id" | "qty" | "status" | "price" | "subtotal", never, {}, "report">schema = createExcelSchema<Invoice>(): SchemaBuilder<Invoice, never, never, {}> (+2 overloads)createExcelSchema<type Invoice = {
    id: string;
    customer: string;
    qty: number;
    unitPrice: number;
    taxRate: number;
    status: "paid" | "pending" | "overdue";
}Invoice>()
  .SchemaBuilder<Invoice, never, never, {}>.column<"id", "id">(id: "id", definition: AccessorColumnInput<Invoice, "id", "id", never, never>): SchemaBuilder<Invoice, "id", never, {}> (+2 overloads)column("id", {
    header?: LazyText | undefinedheader: "Invoice #",
    accessor: "id"accessor: "id",
  })
  .SchemaBuilder<Invoice, "id", never, {}>.column<"qty", "qty">(id: "qty", definition: AccessorColumnInput<Invoice, "qty", FormulaLikeReference<"qty", "id">, "id", never>): SchemaBuilder<Invoice, "id" | "qty", never, {}> (+2 overloads)column("qty", {
    header?: LazyText | undefinedheader: "Qty",
    accessor: "qty"accessor: "qty",
  })
  .SchemaBuilder<Invoice, "id" | "qty", never, {}>.column<"price", "unitPrice">(id: "price", definition: AccessorColumnInput<Invoice, "unitPrice", FormulaLikeReference<"price", "id" | "qty">, "id" | "qty", never>): SchemaBuilder<Invoice, "id" | "qty" | "price", never, {}> (+2 overloads)column("price", {
    header?: LazyText | undefinedheader: "Unit Price",
    accessor: "unitPrice"accessor: "unitPrice",
    style?: CellStyle | StyleFn<Invoice> | undefinedstyle: { CellStyle.numFmt?: string | undefinednumFmt: "$#,##0.00" },
  })
  // Type-checked formula refs — row.ref("qty") must be declared before this column
  .SchemaBuilder<Invoice, "id" | "qty" | "price", never, {}>.column<"subtotal">(id: "subtotal", definition: FormulaColumnInput<Invoice, FormulaLikeReference<"subtotal", "id" | "qty" | "price">, "id" | "qty" | "price", never>): SchemaBuilder<Invoice, "id" | "qty" | "price" | "subtotal", never, {}> (+2 overloads)column("subtotal", {
    formula: FormulaFn<"id" | "qty" | "price", never>formula: ({ row: FormulaRowContext<"id" | "qty" | "price", never>row, fx: FormulaFunctions<"id" | "qty" | "price", never>fx }) =>
      fx: FormulaFunctions<"id" | "qty" | "price", never>fx.FormulaFunctions<"id" | "qty" | "price", never>.round(value: FormulaValue<"id" | "qty" | "price", never>, decimals?: number): FormulaOperand<"id" | "qty" | "price", never>round(row: FormulaRowContext<"id" | "qty" | "price", never>row.FormulaRowContext<"id" | "qty" | "price", never>.ref(columnId: "id" | "qty" | "price"): FormulaOperand<"id" | "qty" | "price", never>ref("qty").FormulaOperand<"id" | "qty" | "price", never>.mul(right: FormulaValue<"id" | "qty" | "price", never>): FormulaOperand<"id" | "qty" | "price", never>mul(row: FormulaRowContext<"id" | "qty" | "price", never>row.FormulaRowContext<"id" | "qty" | "price", never>.ref(columnId: "id" | "qty" | "price"): FormulaOperand<"id" | "qty" | "price", never>ref("price")), 2),
    style?: CellStyle | StyleFn<Invoice> | undefinedstyle: { CellStyle.numFmt?: string | undefinednumFmt: "$#,##0.00" },
    summary?: SummaryInput<Invoice> | undefinedsummary: (s: SummaryBuilder<Invoice>s) => [s: SummaryBuilder<Invoice>s.SummaryBuilder<Invoice>.formula(formula: SummaryFormulaFunction | ((context: SummaryFormulaBuilderContext) => FormulaValue<string, never> | SummaryRowAggregateExpr), options?: Pick<SummaryDefinition<Invoice, unknown>, "format" | "style" | "conditionalStyle"> | undefined): SummaryDefinition<Invoice, undefined>formula("sum")],
  })
  // TypeScript fails if you reference a later column
  .SchemaBuilder<Invoice, "id" | "qty" | "price" | "subtotal", never, {}>.column<"status", "status">(id: "status", definition: AccessorColumnInput<Invoice, "status", FormulaLikeReference<"status", "id" | "qty" | "price" | "subtotal">, "id" | "qty" | "price" | "subtotal", never>): SchemaBuilder<Invoice, "id" | "qty" | "status" | "price" | "subtotal", never, {}> (+2 overloads)column("status", {
    accessor: "status"accessor: "status",
    style?: CellStyle | StyleFn<Invoice> | undefinedstyle: (row: Invoicerow) => ({
      CellStyle.font?: FontStyle | undefinedfont: {
        FontStyle.bold?: boolean | undefinedbold: row: Invoicerow.status: "paid" | "pending" | "overdue"status === "overdue",
        FontStyle.color?: ColorStyle | undefinedcolor: {
          ColorStyle.rgb: stringrgb: row: Invoicerow.status: "paid" | "pending" | "overdue"status === "paid" ? "166534" : "B42318",
        },
      },
    }),
  })
  .SchemaBuilder<Invoice, "id" | "qty" | "status" | "price" | "subtotal", never, {}>.build(): SchemaDefinition<Invoice, "id" | "qty" | "status" | "price" | "subtotal", never, {}, "report">build();

function createWorkbook(_options?: WorkbookOptions): PublicWorkbookcreateWorkbook()
  .PublicWorkbook.sheet(name: string, options?: WorkbookSheetOptions): PublicWorkbookSheetsheet("Invoices", { SheetViewOptions.freezePane?: FreezePane | undefinedfreezePane: { FreezePane.rows?: number | undefinedrows: 1 } })
  .PublicWorkbookSheet.table<SchemaDefinition<Invoice, "id" | "qty" | "status" | "price" | "subtotal", never, {}, "report">, undefined>(id: string, input: WorkbookReportTableOptions<SchemaDefinition<Invoice, "id" | "qty" | "status" | "price" | "subtotal", never, {}, "report">, undefined>): PublicWorkbookSheettable("invoices", { rows: Invoice[]rows, WorkbookReportTableInput<SchemaDefinition<Invoice, "id" | "qty" | "status" | "price" | "subtotal", never, {}, "report">, undefined>.schema: SchemaDefinition<Invoice, "id" | "qty" | "status" | "price" | "subtotal", never, {}, "report">schema });

Runtime dependencies

Custom OOXML + ZIP engine — nothing to audit

Schema modes

Report layout or native Excel tables

Table style presets

Light, Medium & Dark tiers built in

Output targets

File, Buffer, Node stream & Web stream

Why typed-xlsx

The right primitives for
serious TypeScript reporting.

Type-safe schema

Declare columns against your row type. Accessors, path validation, sub-row expansion, and per-cell styling are all checked at compile time — shape drift is caught before export.

Formula DSL

Reference columns by ID, never by cell address. Forward references won't compile, so broken formula wiring is a TypeScript error — not a silent Excel bug.

Two schema modes

Emit classic report layouts or real Excel table objects complete with SUBTOTAL() totals, structured refs, and 60 built-in style presets.

Dynamic column groups

Generate columns from runtime data with fully inferred context. Missing or mistyped group context is a compile-time error, not a runtime surprise.

Streaming pipeline

Commit rows in batches through a spool-backed pipeline. Heap stays flat no matter the dataset size — with full schema parity to buffered mode.

Zero dependencies

Ships a custom OOXML serializer and incremental ZIP engine. No SheetJS, no ExcelJS — zero transitive risk in your dependency graph.

API surface

Three functions.
The whole library.

Schema

Typed columns, formulas & styles

createExcelSchema<T>(options?)
  .column(id, {
    accessor, formula,
    style, summary,
    validation,
  })
  .group(id, (group, ctx) => { ... })
  // Array accessors expand rows automatically
  .build()

Workbook

Sheets, tables & output in one chain

createWorkbook()
  .sheet(name, {
    freezePane, rightToLeft,
    tablesPerRow,
  })
  .table(name, {
    schema, rows,
    context, mode,
  })
  .writeToFile(path)

Streaming

Same schema, unbounded datasets

const wb = createWorkbookStream();

const tbl = await wb
  .sheet(name)
  .table(name, { schema });

for await (const batch of cursor) {
  await tbl.commit({ rows: batch });
}

await wb.writeToFile(path);

Feature Surface

Depth where reports
actually get hard.

Formula DSL

Column IDs replace fragile cell addresses

Write formulas against column IDs and let the engine resolve final Excel coordinates. Rearranging columns is a layout decision, not a formula maintenance event.

Read docs

Without typed-xlsx

// SheetJS: every formula is a string tied to a cell address
const r = dataStartRow + i;
ws[
  `D${r}`
] = {
  t: "n",
  f: `=ROUND(B${r}*C${r},2)`,
  z: "$#,##0.00",
};

// Insert a column before B?
// Re-audit every formula string by hand.
// Row type changed? No error. Wrong value at runtime.

// SheetJS: totals row is manual range math
const last = dataStartRow + rows.length - 1;
ws[
  `E${last + 2}`
] = {
  f: `SUM(E${dataStartRow}:E${last})`,
  z: "$#,##0.00",
};

// Range is a hardcoded string template.
// Move a column and update the formula manually.

// SheetJS: runtime columns mean manual header + cell loops
let col = 1;
for (const region of regions) {
  ws[XLSX.utils.encode_cell({ r: 0, c: col })] = {
    v: region,
    t: "s",
  };

  for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
    ws[XLSX.utils.encode_cell({ r: rowIndex + 1, c: col })] = {
      v: rows[rowIndex]?.revenueByRegion?.[region] ?? 0,
      t: "n",
    };
  }

  col += 1;
}

// Dynamic layout logic leaks into worksheet mutation.

// SheetJS: flatten parent/child rows yourself
const rows = [];
for (const order of orders) {
  rows.push([order.id, order.customer, "", ""]);
  for (const line of order.lines) {
    rows.push(["", "", line.product, line.qty]);
  }
}

// Row offsets tracked manually.
// Parent/child intent is split across loops.

// Style cells to look table-like
worksheet["A1"] = "Revenue";
worksheet["E22"] = { f: "SUM(E2:E21)" };

// No native table object in the workbook.
// Totals ignore active filters.
// Structured refs are unavailable.

// SheetJS: style decisions happen against raw worksheet state
const cellRef = XLSX.utils.encode_cell({ r, c });
const status = rawRows[r - 1]?.status;
ws[cellRef].s = {
  font: {
    bold: status === "overdue",
    color: { rgb: "B42318" },
  },
};

// Row type is lost at the point of styling.

// SheetJS: maintain separate export column lists
const cols = baseColumns.filter((col) => {
  if (col.key === "internalCode" && !isAdmin) return false;
  if (col.key === "euVat" && region !== "EU") return false;
  return true;
});

// Type inference breaks after filter().
// Schema logic is split across two places.

// Ship an editable workbook
worksheet["F2"].v = proposedValue;

// No validation guardrails.
// Hidden logic columns easy to expose.
// Users can overwrite formulas accidentally.

// SheetJS: every worksheet is a separate construction path
const wb  = XLSX.utils.book_new();
const ws1 = buildSheet(summaryRows);
const ws2 = buildSheet(detailRows);

XLSX.utils.book_append_sheet(wb, ws1, "Summary");
XLSX.utils.book_append_sheet(wb, ws2, "Details");

// Each sheet is a separate construction path.

// SheetJS: stream-like export still means manual worksheet writes
const ws = XLSX.utils.aoa_to_sheet([headers]);
let rowIndex = 1;

for await (const batch of fetchRows()) {
  for (const row of batch) {
    XLSX.utils.sheet_add_aoa(ws, [[
      row.orderId,
      row.customer,
      row.total,
    ]], { origin: { r: rowIndex, c: 0 } });

    rowIndex += 1;
  }
}

// Full worksheet state stays in memory.
// No schema reuse, formulas, summaries, or autoWidth layer.

With typed-xlsx

// Reference columns by ID — addresses resolved at build time
.column("subtotal", {
  formula: ({ row, fx }) =>
    fx.round(row.ref("qty").mul(row.ref("price")), 2),
  // TypeScript error if "qty" or "price"
  // aren't declared before this column
  style: { numFmt: "$#,##0.00" },
  summary: (s) => [s.formula("sum")],
});

// Move columns freely — formulas shift automatically.
// Row type changes fail before export.

.column("revenue", {
  accessor: "revenue",
  style: { numFmt: "$#,##0.00" },
  summary: (s) => [s.formula("sum")],
})
.column("margin", {
  formula: ({ row, fx }) =>
    fx.round(row.ref("revenue").sub(row.ref("cost")), 2),
  summary: (s) => [s.formula("average")],
});

// Footer ranges resolve from the schema engine.
// No string arithmetic required.

const schema = createExcelSchema<Row>()
  .column("account", { accessor: "account" })
  .group("regions", (group, regions: string[]) => {
  for (const region of regions) {
    group.column(region, {
      header: region,
      accessor: (row) => row.revenueByRegion[region] ?? 0,
    });
  }
})
.column("regionalTotal", {
  formula: ({ row }) => row.group("regions").sum(),
});

workbook.sheet("Regional revenue").table("revenue", {
  rows,
  schema,
  context: { regions },
});

// Runtime columns stay inside the schema surface.

createExcelSchema<Order>()
  .column("id", { accessor: "id" })
  .column("customer", { accessor: "customer" })
  .column("product", {
    accessor: (row) => row.lines.map((line) => line.product),
  })
  .column("qty", {
    accessor: (row) => row.lines.map((line) => line.qty),
  });

// Array accessors expand the logical row automatically.
// Single-value columns are merged for you.

createExcelSchema<OrderRow>({ mode: "excel-table" })
  .column("units", {
    accessor: "units",
  })
  .column("revenue", {
    accessor: "revenue",
    totalsRow: { function: "sum" },
  })
  .column("avgPrice", {
    formula: ({ row, fx }) =>
      fx.round(row.ref("revenue").div(row.ref("units")), 2),
  })
  .build();

// Totals become SUBTOTAL(). Structured refs stay readable.

.column("status", {
  accessor: "status",
  conditionalStyle: (conditional) =>
    conditional
      .when(({ row }) => row.ref("status").eq("paid"), {
        fill: { color: { rgb: "DCFCE7" } },
        font: { color: { rgb: "166534" }, bold: true },
      })
      .when(({ row }) => row.ref("status").eq("overdue"), {
        fill: { color: { rgb: "FEE2E2" } },
        font: { color: { rgb: "991B1B" }, bold: true },
      }),
});

// Rules stay live in Excel after the file opens.

const schema = createExcelSchema<Row>()
  .column("company", { accessor: "company" })
  .column("revenue", { accessor: "revenue" })
  .column("internalCode", { accessor: "internalCode" })
  .column("euVat", { accessor: "euVat" })
  .build();

workbook.sheet("External").table("accounts", {
  rows,
  schema,
  select: { exclude: ["internalCode", "euVat"] },
});

// One schema, multiple export shapes, typed column IDs.

.column("targetArr", {
  accessor: "targetArr",
  style: { protection: { locked: false } },
  validation: (v) => v.integer().between(10000, 3000000),
})
.column("uplift", {
  formula: ({ row }) =>
    row.ref("targetArr").div(row.ref("currentArr")),
  style: { protection: { hidden: true } },
});

// Pair with sheet protection and editable inputs stay unlocked.

createWorkbook()
  .sheet("Summary", { freezePane: { rows: 1 } })
  .table("summary", { schema: summarySchema, rows })
  .sheet("Details", { freezePane: { rows: 1 } })
  .table("details", { schema: detailSchema, rows })
  .writeToFile("./report.xlsx");

// One builder. Two sheets. Same ergonomics.

const schema = createExcelSchema<Order>()
  .column("orderId", { accessor: "orderId", autoWidth: true })
  .column("customer", { accessor: "customer", autoWidth: true })
  .column("total", {
    accessor: "total",
    style: { numFmt: "$#,##0.00" },
    summary: (s) => [s.formula("sum")],
  })
  .build();

// Buffered: same schema for smaller exports
createWorkbook().sheet("Orders").table("orders", { rows, schema });

// Streaming: same schema for large exports
const table = await createWorkbookStream().sheet("Orders").table("orders", { schema });
for await (const batch of fetchRows()) await table.commit({ rows: batch });

10 SheetJS-to-schema examples

Technical Blueprint

The Architectural
Monolith

Four layers, one coherent system. Each builds on the last — stop at any layer or use the full stack.

The Schema Layer

Model your worksheet directly from TypeScript row types. Accessors, selection, sub-rows, defaults, and styling live in a single declarative surface.

typed accessorsselectionsub-rowsstylesdefaults

The Formula Engine

Compose Excel formulas from column IDs, not coordinates. Predecessor ordering is enforced at compile time — broken references never reach the spreadsheet.

row.ref()fx.*group sumssummary formulascompile-time safety

The Workbook Builder

Assemble multi-sheet workbooks with report mode or native Excel tables, freeze panes, and deterministic table placement — all from a single fluent chain.

report modeexcel tablesmulti-sheetlayoutfreeze panes

The Stream Pipeline

Flush large exports in batches through a spool-backed pipeline. The ZIP is assembled incrementally while the schema surface stays identical to buffered mode.

batch commitspoolincremental ZIPNode streamsWeb streams

Showcase

Real outputs from
real schemas.

Explore all artifacts

Typed pricing workflow

Deal Desk Quote Review

A quote approval workbook that models multi-line pricing, margin math, and approval flags without fragile cell-address code.

sub-row expansionformula DSLtyped predecessor refs

2 sheets Open playground

Multi-sheet composition

Executive Board Pack

A polished leadership workbook that turns typed customer portfolio data into board-ready views and watchlists.

buffered workbookmulti-sheet compositionmulti-table layout

2 sheets Open playground

Logical vs physical rows

Logical vs Physical Summary

A compact workbook that makes logical rows, physical rows, and row-aware summary formulas visible in one place.

sub-row expansionrow.series aggregateslogical row summaries

1 sheet Open playground

Scale Layer

One schema.
Two output paths.

Switch from buffered to streaming without touching your schema. Column definitions, formulas, summaries, validation, and table modes all carry over unchanged.

Bufferedup to ~50k rows

const wb = createWorkbook()
  .sheet("Orders", { freezePane: { rows: 1 } })
  .table("orders", { schema, rows });

await wb.writeToFile("./orders.xlsx");
// or: const bytes = wb.toBuffer()

Streamingunbounded — heap stays flat

const wb = createWorkbookStream();

const tbl = await wb
  .sheet("Orders")
  .table("orders", { schema });

for await (const batch of db.cursor()) {
  await tbl.commit({ rows: batch });
}

await wb.writeToFile("./orders.xlsx");

Schema

Unchanged

Identical definition in both modes

Heap

Flat

Released after every batch commit

Dataset

Unbounded

Spool-backed incremental ZIP

Outputs

File · Buffer · Node · Web

Buffered: file/buffer. Streaming: file/Node/Web.

Entry Points

Pick your
starting point.

Build your first report

Typed accessors, formula refs, a summary row, and a freeze pane — in under 30 lines of code.

Quick start

Explore the schema API

Columns, formulas, groups, sub-rows, styling, and validation — the full schema surface explained.

Schema builder

Compare to SheetJS / ExcelJS

Type safety, formula DSL, native tables, and schema reuse — side by side with the two most popular alternatives.

Library comparison

Engineered for TypeScript

Ready to
compile?

Define a schema, pass your rows, export a workbook. Your first report ships in under 30 lines — no configuration, no boilerplate.

Build your first report GitHub

Excel ReportingRe-Engineered.

The right primitives forserious TypeScript reporting.

Type-safe schema

Formula DSL

Two schema modes

Dynamic column groups

Streaming pipeline

Zero dependencies

Three functions.The whole library.

Depth where reportsactually get hard.

Column IDs replace fragile cell addresses

The ArchitecturalMonolith

The Schema Layer

The Formula Engine

The Workbook Builder

The Stream Pipeline

Real outputs fromreal schemas.

Deal Desk Quote Review

Executive Board Pack

Logical vs Physical Summary

One schema.Two output paths.

Pick yourstarting point.

Build your first report

Explore the schema API

Compare to SheetJS / ExcelJS

Ready tocompile?

Excel Reporting
Re-Engineered.

The right primitives for
serious TypeScript reporting.

Three functions.
The whole library.

Depth where reports
actually get hard.

The Architectural
Monolith

Real outputs from
real schemas.

One schema.
Two output paths.

Pick your
starting point.

Ready to
compile?