@nazarkalytiuk/rusc-xlsx 1.0.10 → 2.1.0

package/README.md

@@ -67,8 +67,8 @@ npm install @nazarkalytiuk/rusc-xlsx
 
 ### Requirements
 
-- Node.js >= 16
-- Rust toolchain (for building from source)
+- Node.js >= 22.13
+- Rust >= 1.95 (only when building from source)
 
 ## Quick Start
 
@@ -169,6 +169,11 @@ workbook.save('output.xlsx');
 - `addWorksheetWithConstantMemory([name])` - Constant memory mode
 - `addWorksheetWithLowMemory([name])` - Low memory mode
 - `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
@@ -181,17 +186,17 @@ workbook.save('output.xlsx');
 - **Writing**: `write()`, `writeString()`, `writeNumber()`, `writeBoolean()`, `writeBlank()`
 - **DateTime**: `writeDatetime()`, `writeDatetimeFromTimestamp()`, `writeDatetimeFromYmd()`, etc.
 - **Formulas**: `writeFormula()`, `writeArrayFormula()`, `writeDynamicFormula()`
-- **Layout**: `setColumnWidth()`, `setRowHeight()`, `setDefaultRowHeight()`, `mergeRange()`, `setName()`
-- **Features**: `insertNote()`, `addDataValidation()`, `insertChart()`, `insertImage()`, `addTable()`, `insertButton()`, `insertShape()`
+- **Layout**: `setColumnWidth()`, `setRowHeight()`, `setDefaultRowHeight()`, `mergeRange()`, `setName()`, `autofit()`, `setAutofitMaxRow()`, `setAutofitMaxWidth()`
+- **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()`
 
-### Format (39 methods)
-- **Font**: `setBold()`, `setItalic()`, `setFontSize()`, `setFontColor()`, `setFontName()`, `setUnderline()`, `setStrikethrough()`, `setFontScript()`
+### Format (40 methods)
+- **Font**: `setBold()`, `setItalic()`, `setFontSize()`, `setFontColor()`, `setFontName()`, `setFontScheme()`, `setUnderline()`, `setStrikethrough()`, `setFontScript()`
 - **Alignment**: `setAlign()`, `setVerticalAlign()`, `setRotation()`, `setIndent()`, `setTextWrap()`, `setShrink()`
 - **Borders**: `setBorder()`, `setBorderTop/Bottom/Left/Right()`, `setBorderColor()`, `setBorderDiagonal()`
 - **Fill**: `setBackgroundColor()`, `setForegroundColor()`, `setPattern()`
@@ -202,7 +207,7 @@ workbook.save('output.xlsx');
 ### Supporting Classes
 - **Chart**: 25 chart types with series, titles, legends, 48 styles
 - **Image**: Insert with scaling, positioning, alt text, URLs
-- **Table**: Custom columns, total rows, 60 styles
+- **Table**: Custom columns, total rows, alternative text, 60 styles
 - **Sparkline**: 3 types, markers, colors, 36 styles
 - **DataValidation**: All validation types with custom messages
 - **Note**: Comments with author, size, color, visibility
@@ -245,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
@@ -265,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
 
@@ -335,6 +357,88 @@ 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
+language runtimes in isolation:
+
+| Runtime | XLSX implementation | Bounded-memory API |
+|---------|---------------------|--------------------|
+| Node.js | `@nazarkalytiuk/rusc-xlsx` | Constant-memory `writeRow()` |
+| Go | Excelize 2.11.0 | `StreamWriter.SetRow()` |
+| C# | Open XML SDK 3.5.1 | Forward-only worksheet XML writer |
+| Python | XlsxWriter 3.2.9 | `constant_memory` + `write_row()` |
+
+Install Rust, Go 1.25+, the .NET 8 SDK, and Python 3.10+, then run:
+
+```bash
+npm run benchmark:languages
+```
+
+The runner builds release artifacts and creates an isolated Python virtual
+environment under `benchmarks/python-xlsxwriter/.venv`. The default workload is
+the same 200,000 rows × 20 columns, 50/50 string-and-number dataset used by the
+Rust comparison. Before measurement, each implementation generates a small
+workbook that is checked for its worksheet name, complete row/cell shape, and
+representative values. Measured execution order is balanced across runs, and
+the report includes median generation time, end-to-end process wall time,
+throughput, peak RSS, and XLSX size.
+
+Override the workload, select available runtimes, or reuse existing artifacts:
+
+```bash
+npm run benchmark:languages -- --rows 100000 --columns 20 --runs 5
+npm run benchmark:languages -- --implementations node,go,python
+npm run benchmark:languages -- --skip-build
+```
+
+Use `--node-write-mode cell|row|batch` to measure a different Node.js API;
+`row` is the cross-language default because all four implementations consume
+the workload sequentially by row.
+
 ## Limitations
 
 - ❌ **Read-only**: Cannot read existing Excel files (rust_xlsxwriter is write-only)

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
@@ -122,6 +131,8 @@ export declare class RuscFormat {
   setNumFormat(numFormat: string): void
   /** Set font name (e.g., 'Arial', 'Calibri', 'Times New Roman') */
   setFontName(fontName: string): void
+  /** Set whether the font uses a body, headings, or custom font scheme. */
+  setFontScheme(scheme: string): void
   /** Set text underline style */
   setUnderline(underline: string): void
   /** Set strikethrough text */
@@ -275,10 +286,10 @@ 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 {
@@ -299,7 +310,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
@@ -368,7 +382,14 @@ export declare class RuscTable {
   setLastColumn(show: boolean): this
   /** Set the name of the table */
   setName(name: string): this
-  /** Set the style of the table (1-21 for light styles, 22-49 for medium styles, 50-61 for dark styles) */
+  /** Set alternative text for screen readers. */
+  setAltText(altText: string): this
+  /** Set the alternative text title for screen readers. */
+  setAltTextTitle(title: string): this
+  /**
+   * 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
@@ -399,6 +420,33 @@ export declare class RuscWorkbook {
   addWorksheetWithLowMemory(name?: string | undefined | null): RuscWorksheet
   /** Set a custom temporary directory for constant memory mode */
   setTempdir(dir: string): void
+  /**
+   * Set the default workbook format and row/column dimensions in pixels.
+   * 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.
+   */
+  useExcel2023Theme(): void
+  /** Load a custom theme from a .thmx, .xlsx, or theme XML file. */
+  useCustomTheme(path: string): void
   /** Save the workbook to a file */
   save(filename: string): void
   /** Save the workbook to a buffer */
@@ -434,20 +482,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 */
@@ -470,14 +523,23 @@ 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 */
   setRowHeight(row: number, height: number): void
   /** Set the default height for all worksheet rows efficiently */
   setDefaultRowHeight(height: number): void
+  /** Set the exclusive upper row bound inspected by autofit. */
+  setAutofitMaxRow(maxRow: number): void
+  /** Limit the autofitted column width in pixels. */
+  setAutofitMaxWidth(maxWidth: number): void
+  /** Autofit worksheet columns based on their cell contents. */
+  autofit(): void
   /** Set the name of the worksheet */
   setName(name: string): void
   /** Merge a range of cells */
@@ -576,6 +638,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 */
@@ -598,6 +665,8 @@ export declare class RuscWorksheet {
   insertImageWithOffset(row: number, col: number, image: RuscImage, xOffset: number, yOffset: number): void
   /** Insert an image that fits to a cell */
   insertImageFitToCell(row: number, col: number, image: RuscImage, keepAspectRatio: boolean): void
+  /** Insert an image scaled proportionally and centered within a cell. */
+  insertImageFitToCellCentered(row: number, col: number, image: RuscImage): void
   /** Add a table to the worksheet */
   addTable(firstRow: number, firstCol: number, lastRow: number, lastCol: number, table: RuscTable): void
   /** Add a sparkline to a single cell */
@@ -614,8 +683,23 @@ export declare class RuscWorksheet {
   insertShapeWithOffset(row: number, col: number, shape: RuscShape, xOffset: number, yOffset: number): void
 }
 
-/** Resets peak memory tracking to current usage */
+/**
+ * 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]