exceljs-stream-utils

Streaming Excel helpers built on top of @protobi/exceljs, a maintained ExcelJS-based streaming implementation.

• Read .xlsx as async objects
• Write iterable or async-iterable rows to .xlsx
• Process large files in bounded batches
• Built-in timezone-aware date handling for read/write flows

Requirements

• Node.js >= 18

Install

npm install exceljs-stream-utils

@protobi/exceljs is installed automatically as a dependency of this package.

This package builds on top of:

• @protobi/exceljs for Excel workbook streaming support
• luxon for time zone aware date conversion

API

The package now has two entrypoints:

• exceljs-stream-utils: existing behavior, kept stable for compatibility
• exceljs-stream-utils/v2: improved behavior for new code

Read

• readXlsxRows(input, options)

Write

• writeXlsxRows(output, rows, options)

Processing

• processXlsxRows(input, handler, options)

Compatibility aliases are still exported:

• xlsxStreamToObjects
• objectsToXlsxStream
• processXlsxLarge

V2

Import from exceljs-stream-utils/v2 to opt into the safer API without affecting existing users.

import {
  readXlsxRows,
  writeXlsxRows,
  processXlsxRows,
} from 'exceljs-stream-utils/v2';

v2 currently improves a few edge cases:

• writeXlsxRows(output, rows) now works without requiring an options object
• Formula result cells are normalized through the same date handling path as other cells
• Duplicate headers are detected by default instead of silently overwriting earlier columns
• processXlsxRows drains in-flight work before surfacing batch errors

Automated Bun tests currently cover:

• file path input and output
• Node readable and writable stream transport
• timezone date round-trips
• array parsing, trimming, and header normalization
• root API compatibility and legacy aliases
• a realistic 10,000-row write-and-process scenario

Parameters

Unless noted otherwise, the parameter tables below describe the /v2 entrypoint. The root entrypoint keeps the older compatibility behavior.

readXlsxRows(input, options?)

input types:

• string (file path)
• Node Readable
• Web ReadableStream<Uint8Array>

options (XlsxReadOptions, all optional):

| Name | Type | Default | Description | | ----------------------- | ------------------------------- | --------------------------------- | --------------------------------------------------------------- | | sheetName | string | first matching sheet | Read only this sheet name | | headerRowNumber | number | 1 | Row number used as header row | | trimHeaders | boolean | true | Trim header cell text | | trimTextValues | boolean | false | Trim all string cell values | | trimTextColumns | string[] | [] | Trim only these columns (used when trimTextValues is false) | | arrayColumns | string[] | [] | Convert these string columns to arrays | | arrayDelimiter | string | "," | Delimiter for arrayColumns | | trimArrayItems | boolean | true | Trim each array item after split | | removeEmptyArrayItems | boolean | true | Remove empty items from split arrays | | skipEmptyRows | boolean | true | Skip rows where all cells are empty | | normalizeHeader | (header, index) => string | identity | Custom header normalizer | | duplicateHeaders | 'error' \| 'suffix' | 'error' | /v2 only. Error on duplicate headers or suffix them as _2, _3, etc. | | parseDates | boolean | true | Convert date-like numeric cells to Date | | date1904 | boolean | false | Use Excel 1904 epoch mode | | timeZone | string | undefined | Reinterpret read date wall-clock in this IANA time zone |

writeXlsxRows(output, rows, options?)

output types:

• string (output file path)
• Node Writable

rows types:

• Iterable<Record<string, unknown>>
• AsyncIterable<Record<string, unknown>>

options (XlsxWriteOptions, all optional):

| Name | Type | Default | Description | | ------------------ | --------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------- | | sheetName | string | 'Sheet1' | Worksheet name | | columns | { header: string; key: string; width?: number }[] | inferred from first row | Explicit column order and labels | | useStyles | boolean | false | Enable ExcelJS style writing | | useSharedStrings | boolean | false | Enable ExcelJS shared strings writing | | timeZone | string | undefined | Convert Date values to target time zone wall-clock | | dateColumns | string[] | [] | Restrict timezone conversion to these date columns; empty means all Date fields |

processXlsxRows(input, handler, options?)

Parameters:

• input (required): same accepted types as readXlsxRows
• handler (required): (row) => Promise<void> | void
• options (optional): all XlsxReadOptions plus:

| Name | Type | Default | Description | | ------------- | -------- | ------- | -------------------------------------- | | batchSize | number | 2000 | Rows per processing batch | | concurrency | number | 8 | Max concurrent handlers within a batch |

Quick start

import { readXlsxRows, writeXlsxRows } from 'exceljs-stream-utils';

for await (const row of readXlsxRows('/tmp/input.xlsx')) {
  console.log(row);
}

await writeXlsxRows('/tmp/output.xlsx', [{ id: 1, name: 'John' }], {
  sheetName: 'Sheet1',
});

How to use

1) Read from file

import { readXlsxRows } from 'exceljs-stream-utils';

for await (const row of readXlsxRows('/tmp/input.xlsx', {
  headerRowNumber: 1,
  trimHeaders: true,
  trimTextValues: true,
  parseDates: true,
  timeZone: 'Asia/Manila',
  arrayColumns: ['tags'],
  arrayDelimiter: ',',
})) {
  console.log(row);
}

2) Write to file

import { writeXlsxRows } from 'exceljs-stream-utils';

await writeXlsxRows(
  '/tmp/out.xlsx',
  [
    { accountNumber: '1234', amount: 100, dueDate: new Date() },
    { accountNumber: '5678', amount: 200, dueDate: new Date() },
  ],
  {
    sheetName: 'Debtors',
    columns: [
      { header: 'Account #', key: 'accountNumber' },
      { header: 'Amount', key: 'amount' },
      { header: 'Due Date', key: 'dueDate' },
    ],
    timeZone: 'Asia/Manila',
    dateColumns: ['dueDate'],
  },
);

3) Write from async iterator

import { writeXlsxRows } from 'exceljs-stream-utils';

async function* debtorRows() {
  yield { accountNumber: '1234', amount: 100, dueDate: new Date() };
  yield { accountNumber: '5678', amount: 200, dueDate: new Date() };
}

await writeXlsxRows('/tmp/streamed.xlsx', debtorRows(), {
  sheetName: 'Debtors',
  columns: [
    { header: 'Account #', key: 'accountNumber' },
    { header: 'Amount', key: 'amount' },
    { header: 'Due Date', key: 'dueDate' },
  ],
});

4) Stream directly to S3

import { PassThrough } from 'node:stream';
import { Upload } from '@aws-sdk/lib-storage';
import { writeXlsxRows } from 'exceljs-stream-utils';

const pass = new PassThrough();

const upload = new Upload({
  client: s3Client,
  params: {
    Bucket: 'my-bucket',
    Key: 'exports/debtors.xlsx',
    Body: pass,
  },
});

const uploadPromise = upload.done();

await writeXlsxRows(pass, debtorRows(), {
  sheetName: 'Debtors',
  timeZone: 'Asia/Manila',
  dateColumns: ['dueDate'],
});

await uploadPromise;

5) Process very large files in batches

import { processXlsxRows } from 'exceljs-stream-utils';

await processXlsxRows(
  '/tmp/input.xlsx',
  async (row) => {
    // handle one row
  },
  {
    batchSize: 2000,
    concurrency: 8,
    trimTextValues: true,
    parseDates: true,
  },
);

6) Export a realistic large dataset

import { writeXlsxRows } from 'exceljs-stream-utils/v2';

async function* debtorExportRows() {
  for (let id = 1; id <= 10000; id += 1) {
    yield {
      debtorId: `D-${id.toString().padStart(5, '0')}`,
      email: `user${id}@example.com`,
      balanceCents: id * 125,
      dueDate: new Date('2024-01-01T00:00:00.000Z'),
      tags: id % 2 === 0 ? 'priority,renewal' : 'standard',
    };
  }
}

await writeXlsxRows('/tmp/debtors.xlsx', debtorExportRows(), {
  sheetName: 'Debtors',
  columns: [
    { header: 'Debtor ID', key: 'debtorId' },
    { header: 'Email', key: 'email' },
    { header: 'Balance', key: 'balanceCents' },
    { header: 'Due Date', key: 'dueDate' },
    { header: 'Tags', key: 'tags' },
  ],
  timeZone: 'Asia/Manila',
  dateColumns: ['dueDate'],
});

Notes

• writeXlsxRows supports both Iterable and AsyncIterable rows.
• columns is optional; if omitted, columns are inferred from the first row.
• Set timeZone in read/write options to enable built-in timezone date conversion.
• writeXlsxRows accepts either a file path or a Node Writable and handles writable backpressure.

Type Behavior

• String cells are returned as strings.
• Boolean cells are returned as booleans.
• Integer and decimal numeric cells are returned as numbers.
• Empty cells are returned as null.
• Date cells are returned as Date objects when date parsing is enabled.

Excel date values are commonly stored as numeric serials plus cell formatting metadata. Because of that, automatic date parsing depends on the workbook indicating that a numeric cell is date-like, usually through its Excel number format. This is a normal Excel parsing constraint, not a Node-specific quirk.

If you want raw numeric serials instead of parsed Date values, set:

{ parseDates: false }

Build and publish

bun run build

Release flow follows the local npm-publish skill process.