@nazarkalytiuk/rusc-xlsx 2.0.0 → 2.2.0

package/README.md

@@ -68,7 +68,7 @@ npm install @nazarkalytiuk/rusc-xlsx
 ### Requirements
 
 - Node.js >= 22.13
-- Rust >= 1.88 (only when building from source)
+- Rust >= 1.95 (only when building from source)
 
 ## Quick Start
 
@@ -171,6 +171,9 @@ workbook.save('output.xlsx');
 - `setTempdir(path)` - Set temp directory for memory modes
 - `setDefaultFormat(format, rowHeight, columnWidth)` - Set workbook-wide default formatting before adding worksheets
 - `useExcel2023Theme()` / `useCustomTheme(path)` - Select the workbook theme before adding worksheets
+- `setCalculationMode(mode)` - Formula recalculation: `'automatic'`, `'manual'` or `'partial'`
+- `setZipCompressionLevel(level)` - Trade file size for speed (1-9, default 6)
+- `setTabRatio(ratio)` - Width of the sheet tab bar vs. the horizontal scroll bar (0-100)
 - `save(filename)` - Save to file
 - `saveToBuffer()` - Save to Buffer
 - `saveToStream(writable)` - Save through a temp file and await stream completion
@@ -187,7 +190,7 @@ workbook.save('output.xlsx');
 - **Features**: `insertNote()`, `addDataValidation()`, `insertChart()`, `insertImage()`, `insertImageFitToCellCentered()`, `addTable()`, `insertButton()`, `insertShape()`
 - **Conditional Formatting**: 14 methods for all rule types
 - **Page Setup**: 26 methods for printing, margins, headers, etc.
-- **View**: `autofilter()`, `setFreezePanes()`, `setZoom()`, `setTabColor()`, `hideSheet()`
+- **View**: `autofilter()`, `setFreezePanes()`, `setZoom()`, `setTabColor()`, `setHiddenZeroes()`, `setHidden()`
 - **Hyperlinks**: `writeUrl()`
 - **Protection**: `protect()`, `protectWithPassword()`
 - **Rich Text**: `writeRichString()`
@@ -247,14 +250,31 @@ See the `examples/` directory for complete examples:
 git clone https://github.com/NazarKalytiuk/napi_rust_xlsxwrighter.git
 cd napi_rust_xlsxwrighter
 
-# Install dependencies
+# Install dependencies (also builds wrapper.js + wrapper.d.ts from wrapper.ts via tsdown)
 npm install
 
 # Build native module
 npm run build
 
-# Run tests (577 tests)
+# Rebuild the JavaScript wrapper after editing wrapper.ts
+npm run build:wrapper
+
+# Run tests (Vitest)
 npm test
+npm run test:watch      # re-run on change
+npm run test:coverage   # V8 coverage report for wrapper.ts
+npm run test:coverage:rust  # line coverage of src/*.rs via an instrumented addon;
+                            # needs cargo-llvm-cov and `rustup component add llvm-tools`
+
+# Format, lint (oxfmt, oxlint, rustfmt, clippy) and typecheck — same as CI
+npm run check
+npm run fmt             # apply oxfmt + rustfmt
+
+# rust_xlsxwriter coverage checklist (rust-xlsxwriter-coverage-checklist.md)
+npm run coverage:check  # verify test call sites, counts and the pinned version
+npm run coverage:sync   # refresh them after editing tests or row statuses; after a
+                        # rust_xlsxwriter upgrade it documents the new release with
+                        # rustdoc JSON (`rustup toolchain install nightly-2026-11-13`)
 
 # Run examples
 node examples/basic.js
@@ -267,7 +287,7 @@ node examples/basic.js
 Built with Rust and NAPI-RS for native-level performance:
 - **Fast execution**: Native Rust performance via NAPI bindings
 - **Low memory usage**: Optimized memory footprint across all modes
-- **Test performance**: All 577 tests complete in < 1 second
+- **Test performance**: All 601 tests complete in < 1 second
 
 ### Memory Modes
 
@@ -337,6 +357,49 @@ for await (const item of cursor) {
 This keeps memory bounded to the current cursor item while retaining
 constant-memory worksheet generation.
 
+### Node.js vs Bun Benchmarks
+
+The runtime benchmark executes the same package workload through the same
+release N-API binary on Node.js and Bun:
+
+```bash
+npm run benchmark:runtimes
+```
+
+Bun must be installed and available in `PATH`. The default workload generates
+200,000 rows × 20 columns through `writeRow()` in constant-memory mode. The
+runner alternates runtime order across three runs, reports both in-process
+generation time and end-to-end process wall time, and verifies identical
+worksheet XML size and CRC for every Node.js/Bun pair.
+
+Override the workload or package API, or reuse the existing release build:
+
+```bash
+npm run benchmark:runtimes -- --rows 100000 --columns 20 --runs 5
+npm run benchmark:runtimes -- --write-mode cell
+npm run benchmark:runtimes -- --write-mode batch --batch-rows 1000
+npm run benchmark:runtimes -- --skip-build
+```
+
+#### ExcelJS runtime comparison
+
+To isolate the runtime difference for a JavaScript XLSX implementation, run the
+same dataset through the ExcelJS streaming writer:
+
+```bash
+npm run benchmark:runtimes:exceljs
+```
+
+This profile uses ExcelJS `stream.xlsx.WorkbookWriter`, disables styles and
+shared strings, fixes ZIP DEFLATE compression at level 6, and commits every
+row. It uses the same alternating order, timing and memory metrics, and
+worksheet-equivalence checks as the native-package profile. Override the
+default workload when needed:
+
+```bash
+npm run benchmark:runtimes:exceljs -- --rows 100000 --columns 20 --runs 5
+```
+
 ### Node.js vs Go, C#, and Python Benchmark
 
 The cross-language benchmark compares concrete streaming XLSX libraries, not

package/index.d.ts

@@ -1,5 +1,14 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
 export declare class RuscButton {
   /** Create a new Button */
   static new(): RuscButton
@@ -178,6 +187,13 @@ export declare class RuscFormat {
   setQuotePrefix(): void
 }
 
+/**
+ * A formula for the native formula writers.
+ *
+ * @deprecated Pass a `RuscFormulaData` object instead. An instance keeps its Rust
+ * memory until its finalizer runs after the event loop turns, so instances
+ * created in a synchronous loop accumulate.
+ */
 export declare class RuscFormula {
   /** Create a new formula */
   constructor(formula: string)
@@ -272,15 +288,21 @@ export declare class RuscProtectionOptions {
   setContents(allow: boolean): this
 }
 
-/** Wrapper for rich text strings (multi-format text in a single cell) */
+/**
+ * Wrapper for rich text strings (multi-format text in a single cell)
+ *
+ * @deprecated Pass `[text, format]` segments to `RuscWorksheet.writeRichString`
+ * instead. An instance keeps its Rust memory until its finalizer runs after the
+ * event loop turns, so instances created in a synchronous loop accumulate.
+ */
 export declare class RuscRichText {
   /** Create a new empty rich text string */
   constructor()
   /**
-   * Add a text segment with formatting
-   * The format is cloned internally for storage
+   * Add a text segment, optionally formatted; without a format the segment uses
+   * the default cell font. The format is cloned internally for storage.
    */
-  addSegment(text: string, format: RuscFormat): this
+  addSegment(text: string, format?: RuscFormat | undefined | null): this
 }
 
 export declare class RuscShape {
@@ -301,7 +323,10 @@ export declare class RuscShape {
 export declare class RuscSparkline {
   /** Create a new Sparkline */
   static new(): RuscSparkline
-  /** Set the data range for the sparkline (e.g., "Sheet1!A1:E1") */
+  /**
+   * Set the data range for the sparkline, e.g. "Sheet1!A1:E1", or "A1:E1"
+   * for a range on the worksheet the sparkline is added to
+   */
   setRange(range: string): this
   /** Set the type of sparkline: 'line', 'column', or 'winLose' */
   setType(sparklineType: string): this
@@ -374,7 +399,10 @@ export declare class RuscTable {
   setAltText(altText: string): this
   /** Set the alternative text title for screen readers. */
   setAltTextTitle(title: string): this
-  /** Set the style of the table (1-21 for light styles, 22-49 for medium styles, 50-61 for dark styles) */
+  /**
+   * Set the style of the table: 0 for no style, 1-21 for light styles,
+   * 22-49 for medium styles and 50-60 for dark styles
+   */
   setStyle(styleId: number): this
   /** Add columns to the table */
   setColumns(columns: Array<RuscTableColumn>): this
@@ -410,6 +438,21 @@ export declare class RuscWorkbook {
    * Must be called before adding worksheets.
    */
   setDefaultFormat(format: RuscFormat, rowHeight: number, columnWidth: number): void
+  /**
+   * Set the zip compression level of the xlsx container (1-9, default 6).
+   * Lower levels are faster, higher levels produce smaller files.
+   */
+  setZipCompressionLevel(level: number): void
+  /**
+   * Set when Excel recalculates formulas: "automatic" (default), "manual",
+   * or "partial" (automatic except for data tables).
+   */
+  setCalculationMode(mode: string): void
+  /**
+   * Set the width of the worksheet tab bar as a percentage (0-100, default
+   * 60) of the space it shares with the horizontal scroll bar.
+   */
+  setTabRatio(ratio: number): void
   /**
    * Use the Excel 2023 Office theme with the Aptos default font.
    * Must be called before adding worksheets.
@@ -452,20 +495,25 @@ export declare class RuscWorkbook {
 
 /** Worksheet wrapper for Excel sheet manipulation */
 export declare class RuscWorksheet {
-  /** Write a value to a cell (auto-detects type) */
-  write(row: number, col: number, value: string | number | boolean, format?: RuscFormat | undefined | null): void
+  /**
+   * Write a value to a cell (auto-detects type). `null` or `undefined`
+   * writes nothing, or a blank cell with the format when one is given.
+   */
+  write(row: number, col: number, value: string | number | boolean | null | undefined, format?: RuscFormat | undefined | null): void
   /**
    * Write an array of values as a row starting at the given column.
    * Uses lazy Array iteration — reads one cell at a time from the JS array
    * instead of deserializing the entire row into Rust memory.
-   * Null/undefined values are skipped (preserving column positions).
+   * Values are written as `write` writes them: `null`, `undefined` and
+   * holes leave the cell empty, or write a blank cell with the format.
    */
   writeRow(row: number, startCol: number, values: unknown[], format?: RuscFormat | undefined | null): void
   /**
    * Write a 2D array of values starting at the given position.
    * Uses lazy Array iteration — reads one row/cell at a time from JS,
    * never materializing the entire grid in Rust memory.
-   * Null/undefined values are skipped (preserving column positions).
+   * Values are written as `write` writes them: `null`, `undefined` and
+   * holes leave the cell empty, or write a blank cell with the format.
    */
   writeRows(startRow: number, startCol: number, rows: unknown[], format?: RuscFormat | undefined | null): void
   /** Write a string to a cell */
@@ -476,10 +524,22 @@ export declare class RuscWorksheet {
   writeBoolean(row: number, col: number, value: boolean): void
   /** Write a blank cell with formatting */
   writeBlank(row: number, col: number, format: RuscFormat): void
-  /** Write a rich text string (multi-format text) to a cell */
-  writeRichString(row: number, col: number, richText: RuscRichText): void
-  /** Write a rich text string with an additional cell format */
-  writeRichStringWithFormat(row: number, col: number, richText: RuscRichText, cellFormat: RuscFormat): void
+  /**
+   * Write a rich text string (multi-format text) to a cell.
+   *
+   * `richText` is `[text, format]` segments, or a deprecated `RuscRichText`; a
+   * segment without a format uses the default cell font. Segments are plain data,
+   * so nothing outlives the call. Empty segments are skipped, and a rich string
+   * whose segments are all empty leaves the cell untouched.
+   */
+  writeRichString(row: number, col: number, richText: RuscRichText | Array<[string, RuscFormat | undefined | null]>): void
+  /**
+   * Write a rich text string with an additional cell format.
+   *
+   * `richText` is as for `writeRichString`. A rich string whose segments are all
+   * empty writes a blank cell with the cell format.
+   */
+  writeRichStringWithFormat(row: number, col: number, richText: RuscRichText | Array<[string, RuscFormat | undefined | null]>, cellFormat: RuscFormat): void
   /** Write a datetime from a Unix timestamp (seconds since 1970-01-01 UTC) */
   writeDatetimeFromTimestamp(row: number, col: number, timestamp: number, format?: RuscFormat | undefined | null): void
   /** Write a datetime from year, month, day components */
@@ -488,8 +548,11 @@ export declare class RuscWorksheet {
   writeDatetimeFromYmdHms(row: number, col: number, year: number, month: number, day: number, hour: number, min: number, sec: number, format?: RuscFormat | undefined | null): void
   /** Write a datetime from an ISO 8601 string (e.g., "2023-01-25T12:30:00") */
   writeDatetimeFromString(row: number, col: number, datetimeStr: string, format?: RuscFormat | undefined | null): void
-  /** Write a value with formatting to a cell */
-  writeWithFormat(row: number, col: number, value: string | number | boolean, format: RuscFormat): void
+  /**
+   * Write a value with formatting to a cell; `null` or `undefined` writes
+   * a blank cell with the format
+   */
+  writeWithFormat(row: number, col: number, value: string | number | boolean | null | undefined, format: RuscFormat): void
   /** Set the width of a column */
   setColumnWidth(col: number, width: number): void
   /** Set the height of a row */
@@ -513,11 +576,11 @@ export declare class RuscWorksheet {
   /** Set the default author name for all notes in the worksheet */
   setDefaultNoteAuthor(name: string): void
   /** Write a formula to a cell */
-  writeFormula(row: number, col: number, formula: RuscFormula, format?: RuscFormat | undefined | null): void
+  writeFormula(row: number, col: number, formula: RuscFormula | RuscFormulaData, format?: RuscFormat | undefined | null): void
   /** Write a dynamic array formula to a cell (Excel 365) */
-  writeDynamicFormula(row: number, col: number, formula: RuscFormula, format?: RuscFormat | undefined | null): void
+  writeDynamicFormula(row: number, col: number, formula: RuscFormula | RuscFormulaData, format?: RuscFormat | undefined | null): void
   /** Write an array formula to a range of cells */
-  writeArrayFormula(firstRow: number, firstCol: number, lastRow: number, lastCol: number, formula: RuscFormula, format?: RuscFormat | undefined | null): void
+  writeArrayFormula(firstRow: number, firstCol: number, lastRow: number, lastCol: number, formula: RuscFormula | RuscFormulaData, format?: RuscFormat | undefined | null): void
   /** Add data validation to a cell or range */
   addDataValidation(firstRow: number, firstCol: number, lastRow: number, lastCol: number, validation: RuscDataValidation): void
   /** Write a URL to a cell */
@@ -600,6 +663,11 @@ export declare class RuscWorksheet {
   setHidden(enable: boolean): void
   /** Set the worksheet zoom level (10-400) */
   setZoom(zoom: number): void
+  /**
+   * Hide zero values in worksheet cells, the equivalent of turning off the
+   * Excel option "Show a zero in cells that have zero value"
+   */
+  setHiddenZeroes(enable: boolean): void
   /** Set the default cell selection when opening the worksheet */
   setSelection(firstRow: number, firstCol: number, lastRow: number, lastCol: number): void
   /** Set which cell appears in the top-left corner when opening the worksheet */
@@ -640,8 +708,35 @@ export declare class RuscWorksheet {
   insertShapeWithOffset(row: number, col: number, shape: RuscShape, xOffset: number, yOffset: number): void
 }
 
-/** Resets peak memory tracking to current usage */
+/**
+ * The data of a JavaScript `Formula`: the formula text and, for applications
+ * that don't recalculate, its cached result.
+ *
+ * It is plain data rather than a class so that a formula written per row owns no
+ * Rust memory between writes.
+ */
+export interface RuscFormulaData {
+  formula: string
+  result?: string
+}
+
+/**
+ * Resets peak memory tracking to the current allocation level.
+ * Call before a section you want to measure.
+ *
+ * @example
+ * rustMemoryResetPeak();
+ * // ... do work ...
+ * const [current, peak] = rustMemoryStats();
+ */
 export declare function rustMemoryResetPeak(): void
 
-/** Returns [currentBytes, peakBytes] of Rust allocator usage */
-export declare function rustMemoryStats(): Array<number>
+/**
+ * Returns [currentBytes, peakBytes] of Rust allocator usage.
+ * Useful for profiling memory consumption of the native layer.
+ *
+ * @example
+ * const [current, peak] = rustMemoryStats();
+ * console.log(`Rust heap: ${(current / 1024 / 1024).toFixed(2)} MB (peak: ${(peak / 1024 / 1024).toFixed(2)} MB)`);
+ */
+export declare function rustMemoryStats(): [number, number]