Migration Guide: Async-First Lazy-Open

This guide covers the breaking changes and new APIs introduced by the async-first lazy-open refactor. All changes apply to the Node.js (@sheetkit/node) package. The Rust crate API is not affected.

This guide is intended for migrations from versions before 0.5.0 to 0.5.0 or later.

Summary of Changes

Breaking Changes

1. ParseMode replaced by ReadMode: The full/readfast mode names are replaced by eager/lazy/stream.
2. AuxParts policy: New option controlling when auxiliary parts (comments, charts, images) are parsed.
3. OpenOptions restructured: New typed options interface with readMode, auxParts, sheets, sheetRows.
4. getRowsIterator replaced by openSheetReader: Stream-based reader with async iterator protocol.
5. Default read mode changed: open() now defaults to readMode: 'lazy' instead of eagerly parsing all sheets.

New APIs

1. Workbook.openSheetReader(sheet, opts?) -- returns a SheetStreamReader
2. SheetStreamReader class with for await...of support
3. getRowsBufferV2(sheet) -- v2 raw buffer with inline strings
4. ReadMode type: 'eager' | 'lazy' | 'stream'
5. AuxParts type: 'eager' | 'deferred'

ReadMode Mapping

Old (parseMode)	New (readMode)	Behavior
'full'	'eager'	Parse all sheets and auxiliary parts during open. Same behavior as before.
'readfast'	'lazy'	Parse ZIP index and metadata only. Sheet XML is parsed on first access (e.g., getRows()).
(no equivalent)	'stream'	Minimal parse intent. In current Rust core implementation, open-path behavior is the same as 'lazy' (deferred sheet hydration and skipped eager auxiliary parsing), while openSheetReader() provides forward-only bounded-memory iteration.

Before (v0.4)

const wb = await Workbook.open('large.xlsx', {
  parseMode: 'readfast',
  sheetRows: 1000,
});

After (v0.5)

const wb = await Workbook.open('large.xlsx', {
  readMode: 'lazy',
  sheetRows: 1000,
});

If you were using parseMode: 'full' or no parseMode, the equivalent is readMode: 'eager'. However, consider switching to readMode: 'lazy' for improved open latency and lower memory usage. Lazy mode transparently hydrates sheets on first access, so most existing code works without further changes.

OpenOptions Changes

The new OpenOptions interface:

interface OpenOptions {
  readMode?: 'lazy' | 'stream' | 'eager';  // default: 'lazy'
  auxParts?: 'deferred' | 'eager';          // default: 'deferred'
  sheets?: string[];
  sheetRows?: number;
  maxUnzipSize?: number;
  maxZipEntries?: number;
}

Key differences from the previous JsOpenOptions:

• parseMode is removed. Use readMode instead.
• auxParts is new. It controls whether comments, charts, images, and other auxiliary parts are parsed during open ('eager') or deferred until first access ('deferred').
• The old JsOpenOptions type is still accepted for backward compatibility, but parseMode values are not recognized by the new code path.

AuxParts Policy

When auxParts is 'deferred' (the default), auxiliary parts like comments, charts, images, and pivot tables are not parsed during open(). They are loaded on-demand the first time you call a method that needs them (e.g., getComments(), getPivotTables()).

This reduces open latency and memory usage for workloads that only need cell data.

// Deferred (default): comments are not parsed during open
const wb = await Workbook.open('report.xlsx');
// Comments are loaded on first access:
const comments = wb.getComments('Sheet1');

// Eager: all parts parsed during open (old behavior)
const wb2 = await Workbook.open('report.xlsx', { auxParts: 'eager' });

Streaming Reader Migration

Before: getRowsIterator()

The old getRowsIterator() was a synchronous generator that materialized the entire sheet buffer first, then yielded rows one at a time. It reduced peak JS object count but not peak Rust memory.

const wb = Workbook.openSync('large.xlsx');
for (const row of wb.getRowsIterator('Sheet1')) {
  process(row);
}

After: openSheetReader()

The new openSheetReader() returns a SheetStreamReader that reads rows in batches directly from the ZIP entry without materializing the entire sheet. Memory usage is bounded by the batch size.

const wb = await Workbook.open('large.xlsx', { readMode: 'stream' });
const reader = await wb.openSheetReader('Sheet1', { batchSize: 500 });

for await (const batch of reader) {
  for (const row of batch) {
    process(row);
  }
}

Key differences:

• openSheetReader() is async and returns a SheetStreamReader.
• The reader implements the async iterator protocol (for await...of).
• Each iteration yields an array of rows (a batch), not a single row.
• Memory usage is bounded: only one batch of rows is in memory at a time.
• Call reader.close() to release resources early, or let the for await loop handle it automatically.

Manual Batch Control

const reader = await wb.openSheetReader('Sheet1');

while (true) {
  const batch = await reader.next(1000); // custom batch size per call
  if (batch === null) break;
  for (const row of batch) {
    process(row);
  }
}

await reader.close();

Raw Buffer V2

getRowsBufferV2() produces a v2 binary buffer that inlines string data instead of using a separate global string table. This enables incremental row-by-row decoding without eagerly materializing all strings.

The v1 format (getRowsBuffer()) is still available and fully supported.

// V1 (unchanged)
const bufV1 = wb.getRowsBuffer('Sheet1');

// V2 (new): inline strings, better for streaming decoders
const bufV2 = wb.getRowsBufferV2('Sheet1');

Use v2 when building custom streaming decoders or when you need to decode rows incrementally. For most use cases, the higher-level APIs (getRows(), getRowsRaw(), SheetData) handle format selection automatically.

Copy-on-Write Save

Workbooks opened in lazy mode use a copy-on-write save pipeline. When you save a lazy-opened workbook without modifying any sheets, unchanged sheet XML is written directly from the original ZIP entry without being parsed and re-serialized. This reduces save latency for workflows that modify only a subset of sheets.

// Open large file, modify one sheet, save
const wb = await Workbook.open('100-sheets.xlsx');
wb.setCellValue('Sheet1', 'A1', 'Updated');
await wb.save('output.xlsx');
// Only Sheet1 is re-serialized. The other 99 sheets are copied as-is.

This is transparent and requires no code changes. Modified sheets are tracked automatically via per-sheet dirty flags.

Full Migration Checklist

1. Replace parseMode: 'full' with readMode: 'eager' (or remove it to use the default 'lazy').
2. Replace parseMode: 'readfast' with readMode: 'lazy'.
3. Replace getRowsIterator() with openSheetReader() and update to async iteration.
4. If you rely on all auxiliary parts being available immediately after open, add auxParts: 'eager' to your open options.
5. Test that cell-access methods still work -- lazy mode hydrates sheets transparently.
6. Consider using readMode: 'stream' with openSheetReader() for very large files where you do not need random cell access.

Compatibility Notes

• The old JsOpenOptions type with sheetRows, sheets, maxUnzipSize, and maxZipEntries fields is still accepted by all open methods. Only parseMode is not recognized.
• getRowsIterator() still exists and works. It is not removed, but openSheetReader() is preferred for new code because it provides true bounded-memory streaming.
• getRowsBuffer() (v1) is not deprecated. V1 and V2 formats coexist.
• All sync methods (openSync, saveSync, openBufferSync, writeBufferSync) continue to work unchanged.