Workbook Builder

Tables

Connecting a schema and row data to a sheet in buffered and stream mode.

Tables connect rows to a built schema.

Buffered tables

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

const schema
 = createExcelSchema
<{ firstName
: string; lastName
: string }>()
  .column
("firstName", { accessor
: "firstName" })
  .column
("lastName", { accessor
: "lastName" })
  .build
();

const workbook
 = createWorkbook
();

workbook
.sheet
("Users").table
({
  id
: "users",
  rows
: [{ firstName
: "Ada", lastName
: "Lovelace" }],
  schema
,
});

Stream tables

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

const schema
 = createExcelSchema
<{ firstName
: string; lastName
: string }>()
  .column
("firstName", { accessor
: "firstName" })
  .column
("lastName", { accessor
: "lastName" })
  .build
();

const workbook
 = createWorkbookStream
();
const table
 = await workbook
.sheet
("Users").table
({
  id
: "users",
  schema
,
});

await table
.commit
({
  rows
: [{ firstName
: "Ada", lastName
: "Lovelace" }],
});

Selection

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

const schema
 = createExcelSchema
<{ email
: string; firstName
: string; lastName
: string }>()
  .column
("firstName", { accessor
: "firstName" })
  .column
("lastName", { accessor
: "lastName" })
  .column
("email", { accessor
: "email" })
  .build
();

createWorkbook
()
  .sheet
("Users")
  .table
({
    rows
: [],
    schema
,
    select
: {
      include
: ["firstName", "email"],
    },
  });

Row type safety

The rows array is typed to match the row type the schema was created with. Passing an object with extra or missing required fields is a compile error:

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

const schema
 = createExcelSchema
<{ email
: string; firstName
: string }>()
  .column
("firstName", { accessor
: "firstName" })
  .column
("email", { accessor
: "email" })
  .build
();

createWorkbook
()
  .sheet
("Users")
  .table
({
    rows
: [{ email
: "ada@example.com", firstName
: "Ada", unknownField: true }],
Object literal may only specify known properties, and 'unknownField' does not exist in type '{ email: string; firstName: string; }'.
    schema
,
  });

The same constraint is enforced in stream mode — commit() infers its row type directly from the schema, so there is no separate type annotation to keep in sync:

import { createExcelSchema
, createWorkbookStream
 } from "@chronicstone/typed-xlsx";
import type { WorkbookTableStream
 } from "@chronicstone/typed-xlsx";

type Order
 = { id
: string; total
: number };

const schema
 = createExcelSchema
<Order
>()
  .column
("id", { accessor
: "id" })
  .column
("total", { accessor
: "total" })
  .build
();

declare const table
: WorkbookTableStream
<Order
>;

await table
.commit
({
  rows
: [{ id
: "ord-1", total
: 150 }],
});

Sheets

Creating sheets with layout options, freeze panes, and right-to-left direction.

Output

Finalizing a workbook to a buffer, Uint8Array, or file.