@justybase/spreadsheet-tasks 2.1.1 → 3.0.0

package/docs/API.md

@@ -7,6 +7,7 @@
 - [XlsbReader](#xlsbreader)
 - [XlsxReader](#xlsxreader)
 - [XlsxUpdater](#xlsxupdater)
+- [XlsmUpdater](#xlsmupdater)
 - [XlsbUpdater](#xlsbupdater)
 - [Excel conversion](#excel-conversion)
 - [ReaderFactory](#readerfactory)
@@ -61,7 +62,10 @@ Writes data to the current sheet.
 - `string` - Written as shared string
 - `number` - Written as number (integer or double)
 - `boolean` - Written as boolean
-- `Date` - Written as Excel date serial number
+- `Date` - Written as Excel date serial number. The serial is taken from the UTC
+  time (`getTime()`), not local wall-clock time: `new Date(2024, 5, 30)` in UTC+2
+  is stored as 2024-06-29 22:00 and shows that way in Excel. Use `Date.UTC(...)`
+  for date-only values
 - `null` / `undefined` - Written as empty cell
 
 **Example:**
@@ -160,6 +164,12 @@ console.log(sheets); // ['Sheet1', 'Sheet2']
 Reads the next row. Returns `true` if a row was read, `false` if end of sheet reached.
 Always use `await` (both XLSB and XLSX are async in v2+).
 
+Empty rows: gaps in the sheet (missing `<row>` / `BrtRowHdr`, including leading
+gaps) are returned as empty rows (`[]`, `getValue()` → `null`). Like xlspy,
+gap positions are yielded; unlike xlspy's padded `[None] * cols`, this reader
+yields a zero-length row so callers must not assume `fieldCount` width.
+The 1904 date system (`workbookPr date1904` / `BrtWbProp`) is honoured.
+
 **Example:**
 ```typescript
 while (await reader.read()) {
@@ -167,6 +177,27 @@ while (await reader.read()) {
 }
 ```
 
+#### `selectSheet(nameOrIndex: string | number): Promise<void>`
+
+Selects a worksheet for subsequent `read()` calls. Resets row/EOF and `fieldCount`.
+Default is sheet 0.
+
+```typescript
+await reader.selectSheet('Second');
+await reader.selectSheet(0);
+```
+
+#### `nextResult(): Promise<boolean>`
+
+Advances to the next worksheet. Returns `true` if another sheet was selected,
+`false` at the end.
+
+```typescript
+do {
+  while (await reader.read()) { /* rows */ }
+} while (await reader.nextResult());
+```
+
 #### `getValue(columnIndex: number): CellValue`
 
 Gets value at the specified column index in the current row.
@@ -176,6 +207,9 @@ Gets value at the specified column index in the current row.
 
 **Returns:** `CellValue` (string, number, boolean, Date, bigint, or null/undefined)
 
+Date cells are returned as `Date` objects built from the serial in UTC, the same
+convention the writers use, so a write/read round trip keeps the same instant.
+
 **Example:**
 ```typescript
 while (await reader.read()) {
@@ -220,6 +254,16 @@ Returns array of worksheet names.
 #### `read(): Promise<boolean>`
 
 Reads the next row. Returns `true` if a row was read. Always use `await`.
+Empty gap rows (including leading) are returned as empty rows; see
+[XlsbReader](#xlsbreader) for `selectSheet`/`nextResult`, which behave identically.
+
+#### `selectSheet(nameOrIndex: string | number): Promise<void>`
+
+See [XlsbReader](#xlsbreader).
+
+#### `nextResult(): Promise<boolean>`
+
+See [XlsbReader](#xlsbreader).
 
 #### `getValue(columnIndex: number): CellValue`
 
@@ -244,8 +288,9 @@ new XlsxUpdater(filePath: string)
 **Parameters:**
 - `filePath` - Path to an existing `.xlsx` file
 
-Throws if the file does not exist, is not a valid XLSX, or is an XLSB
-(XLSB updates are not supported yet).
+Throws if the file does not exist, is not a valid XLSX package, or is an XLSB.
+Macro-enabled `.xlsm` packages can use the explicit [XlsmUpdater](#xlsmupdater)
+alias; unknown VBA members are preserved.
 
 **Example:**
 ```typescript
@@ -286,6 +331,12 @@ Clears the entire cell data of the target sheet and writes new rows in its place
 - Pivot tables whose `worksheetSource` references the updated sheet get their
   `ref` and `recordCount` adjusted, and `refreshOnLoad="1"` is added to the
   pivot table definitions so Excel refreshes them on open.
+- The stale calculation chain (`xl/calcChain.xml`) is removed with its
+  `Content_Types`/rels entries; Excel rebuilds it on open.
+- ListObject tables (`xl/tables/*.xml`) anchored at `A1` get their `<table>`
+  and `<autoFilter>` `ref` updated to the new dimension. Tables whose column
+  count changes are left untouched (their `tableColumns` would need rebuilding),
+  and ranges are capped so they never overlap another table.
 
 **Example:**
 ```typescript
@@ -299,10 +350,28 @@ updater.save('report_new.xlsx');
 Writes the updated workbook to disk. When `outputPath` is omitted, the source
 file is overwritten in place.
 
+#### `replaceSheetDataStream(sheetName: string, rows: RowSource, options?: ReplaceSheetDataOptions): Promise<void>`
+
+Replaces worksheet rows from a synchronous or asynchronous one-pass row source.
+The row source is processed incrementally and is not collected into a complete
+2D array. Use `saveStreaming()` to also avoid materialising the final ZIP buffer.
+
+#### `saveStreaming(outputPath?: string): Promise<void>`
+
+Writes the updated package through a temporary file and installs it atomically.
+Staged worksheet parts are streamed; `save()` remains the simpler synchronous
+buffering path.
+
 #### `toBuffer(): Buffer`
 
 Returns the updated workbook as an in-memory ZIP buffer.
 
+## XlsmUpdater
+
+`XlsmUpdater` is an explicit alias of `XlsxUpdater` for macro-enabled `.xlsm`
+packages. It has the same API as `XlsxUpdater` and preserves VBA parts without
+parsing or modifying them.
+
 ---
 
 ## XlsbUpdater
@@ -364,6 +433,10 @@ Clears the entire cell data of the target sheet and writes new rows in its place
 - Pivot caches whose `worksheetSource` references the updated sheet get their
   range and record count adjusted, and the `refreshOnLoad` flag is set so Excel
   refreshes them on open.
+- The stale calculation chain (`xl/calcChain.bin`) is removed with its
+  `Content_Types`/rels entries.
+- XLSB ListObject tables are **not** patched (documented limitation); only the
+  sheet dimension (`BrtWsDim`) and pivot caches are updated.
 
 **Example:**
 ```typescript
@@ -458,6 +531,18 @@ await reader.open('data.xlsb');
 
 ## Types
 
+### Excel limits (throw, xlspy parity)
+
+```typescript
+import { MAX_ROWS, MAX_COLS, MAX_CELL_CHARS } from '@justybase/spreadsheet-tasks';
+// MAX_ROWS = 1_048_576, MAX_COLS = 16_384, MAX_CELL_CHARS = 32_767 UTF-16 units
+```
+
+Writers throw when a limit is exceeded (no truncation, workbook not published).
+`writeSheet` also throws when a row/header is longer than `columnCount`, matching
+streaming `writeRow` behaviour. Astral characters count as 2 units
+(`'😀'.length === 2`).
+
 ### Supported Cell Types
 
 | TypeScript Type | Excel Cell Type |
@@ -469,6 +554,16 @@ await reader.open('data.xlsb');
 | `Date` | Date Serial Number |
 | `null` / `undefined` | Empty Cell |
 
+### `RowSource`
+
+```typescript
+type RowSource =
+  | Iterable<ReadonlyArray<CellValue>>
+  | AsyncIterable<ReadonlyArray<CellValue>>;
+```
+
+Used by `replaceSheetDataStream()` in both updater classes.
+
 ### Sheet Name Restrictions
 
 Sheet names have the following restrictions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justybase/spreadsheet-tasks",
-  "version": "2.1.1",
+  "version": "3.0.0",
   "description": "High-performance TypeScript library for reading and writing Excel files in XLSB and XLSX formats. XLSB is 3.3x faster to write and 2.3x faster to read than XLSX.",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -26,10 +26,10 @@
     "build": "tsup && node -e \"require('fs').copyFileSync('dist-esm-package.json','dist/esm/package.json')\"",
     "build:browser": "esbuild src/browser/download.ts --bundle --minify --format=iife --global-name=JustybaseSpreadsheet --outfile=browser/justybase-spreadsheet.min.js && esbuild src/browser/download.ts --bundle --format=esm --outfile=browser/browser-spreadsheet.js",
     "lint": "eslint src/",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.browser.json",
     "test": "npm run typecheck && npm run test:smoke && npm run test:unit && npm run test:integration && npm run test:dist",
     "test:smoke": "npx ts-node tests/smoke.test.ts",
-    "test:unit": "npx ts-node tests/unit/bigbuffer.test.ts && npx ts-node tests/unit/biff-reader-writer.test.ts && npx ts-node tests/unit/xlsb-writer.test.ts && npx ts-node tests/unit/excel-converter.test.ts",
+    "test:unit": "npx ts-node tests/unit/bigbuffer.test.ts && npx ts-node tests/unit/biff-reader-writer.test.ts && npx ts-node tests/unit/xlsb-writer.test.ts && npx ts-node tests/unit/excel-converter.test.ts && npx ts-node tests/unit/updater-streaming.test.ts && npx ts-node tests/unit/xlsx-reader-cell-refs.test.ts && npx ts-node tests/unit/writer-limits-columns.test.ts && npx ts-node tests/unit/reader-xml-fixes.test.ts && npx ts-node tests/unit/xlsb-sst-dim.test.ts && npx ts-node tests/unit/updater-cleanup.test.ts && npx ts-node tests/unit/oa-1900-leap.test.ts && npx ts-node tests/unit/reader-row-limit.test.ts",
     "test:integration": "npx ts-node tests/integration/xlsb-writer.test.ts && npx ts-node tests/integration/xlsx-writer.test.ts && npx ts-node tests/integration/xlsx-updater.test.ts && npx ts-node tests/integration/xlsb-updater.test.ts",
     "test:dist": "npm run build && npx ts-node tests/dist-surface.test.ts",
     "test:excel-conversion": "npm run build && npx ts-node tests/excel-compat/conversion.ts",
@@ -38,6 +38,7 @@
     "benchmark": "npm run build && npx ts-node benchmarks/performance.bench.ts",
     "benchmark:comparison": "npm run build && npx ts-node benchmarks/comparison.bench.ts",
     "test:excel-compat": "npm run build && npx tsx tests/excel-compat/run.ts",
+    "test:cross": "npx ts-node tests/cross/xlspy-cross.test.ts",
     "prepublishOnly": "npm run build && npm run build:browser && npm test"
   },
   "keywords": [