react-native-nitro-xlsx 0.2.6 → 0.2.7

package/README.md

@@ -197,7 +197,7 @@ const buffer = await workbook.getBuffer();
 - `createWorkbook(): XlsxWorkbook` - Create a new workbook. The native side supplies the platform cache directory automatically (`Context.getCacheDir()` on Android, `NSCachesDirectory` on iOS).
 - `openWorkbook(path: string): XlsxWorkbook` - Open workbook from file path
 - `openWorkbookFromBuffer(buffer: ArrayBuffer): XlsxWorkbook` - Open workbook from buffer
-- `fromJSON(data: Record<string, Array<Record<string, string | number | boolean | null>>>): XlsxWorkbook` - Create a workbook with one worksheet per key (native `AnyMap`s, no JSON round-trip)
+- `fromJSON(data: Record<string, Array<Record<string, string | number | boolean | null>>>): XlsxWorkbook` - Create a workbook with one worksheet per key (native `AnyMap`s, no JSON round-trip). The default sheet is removed unless one of the keys is named after it
 
 ### XlsxWorkbook
 
@@ -211,7 +211,7 @@ const buffer = await workbook.getBuffer();
 - `clone(existingName: string, newName: string): XlsxWorksheet` - Copy a worksheet
 - `addCellFormat(): XlsxCellFormat` - Add a new cell format
 - `getBuffer(): Promise<ArrayBuffer>` - Generate and return the XLSX file as a buffer
-- `toJSON(): Record<string, Array<Record<string, string | number | boolean | null>>>` - Export every worksheet as a `Record` keyed by sheet name
+- `toJSON(): Record<string, Array<Record<string, string | number | boolean | null>>>` - Export every worksheet as a `Record` keyed by sheet name. Worksheets without a single cell are skipped, so a fresh workbook exports as `{}`
 
 ### XlsxWorksheet
 
@@ -232,7 +232,7 @@ const buffer = await workbook.getBuffer();
 | `writeFormulaNum(row, col, formula, number, format?)` | Write a formula with number default |
 | `writeFormulaString(row, col, formula, string, format?)` | Write a formula with string default |
 | `writeFormulaBoolean(row, col, formula, boolean, format?)` | Write a formula with boolean default |
-| `writeArrayFormula(firstRow, firstCol, lastRow, lastCol, formula, format?)` | Write an array formula |
+| `writeArrayFormula(firstRow, firstCol, lastRow, lastCol, formula, format?)` | Not supported by the underlying engine — always throws `UNSUPPORTED` |
 
 #### Date/URL
 | Method | Description |
@@ -409,7 +409,7 @@ The `XlsxCellFormat` interface is based on OpenXLSX's `XLCellFormat` class and p
 - `setNumFormatIndex(index)` - Set built-in format (use `NumFormat` constants)
 
 #### Colors/Pattern
-- `setBgColor(color)`, `setFgColor(color)`
+- `setBgColor(color)`, `setFgColor(color)` - For solid fills Excel paints the foreground colour, so a colour set only via `setBgColor` is also written as the fill's foreground colour to make it visible
 - `setPattern(pattern)`
 
 #### Borders
@@ -436,9 +436,9 @@ The `XlsxCellFormat` interface is based on OpenXLSX's `XLCellFormat` class and p
 
 When reading cells, the following types are returned:
 
-- `empty` - Empty cell
 - `string` - Text string
-- `number` - Numeric value. Dates are stored as **Excel serial numbers in the 1900 date system** (days since `1900-01-01`, where `1900-01-01` = `1`, including the spurious `1900-02-29`), and are read back as `number`:
+- `number` - Numeric value with no date/time number format applied
+- `date` - Numeric value whose number format is a date/time code. This covers the built-in ids 14–22 and custom codes such as `yyyy-mm-dd`, `h:mm` or `yyyy-mm-dd h:mm:ss`. The stored value is still an **Excel serial number in the 1900 date system** (days since `1900-01-01`, where `1900-01-01` = `1`, including the spurious `1900-02-29`):
   ```ts
   // Excel serial (1900-based) → JS Date
   const date = new Date(Math.round((serial - 25569) * 86400000));
@@ -447,8 +447,11 @@ When reading cells, the following types are returned:
   ```
 - `boolean` - Boolean value
 - `error` - Error value
-- `formula` - Formula
-- `blank` - Blank cell
+- `formula` - Cell holds a formula (checked before the value type, so a formula cell never reads as `number`/`string`)
+- `blank` - Cell exists (e.g. it only carries a style) but has no value
+- `empty` - No cell at these coordinates at all
+
+`getCellType` returns `empty`/`blank` without creating the cell, so probing a cell never mutates the sheet.
 
 ## Constants
 
@@ -510,6 +513,15 @@ To regenerate the native specs after modifying the TypeScript spec files:
 npx nitrogen
 ```
 
+### Tests
+
+```sh
+yarn test        # JS/TS suite (Jest)
+yarn test:cpp    # configure + build cpp/tests into cpp/tests/build, then run gtest
+```
+
+`yarn test:cpp` needs a local GoogleTest installation (`brew install googletest` on macOS); the CMake project looks under `/opt/homebrew`, `/usr/local` and `/usr` first and only falls back to downloading googletest when nothing is found. OpenXLSX, pugixml and miniz are vendored under `thirdparty/`, so the C++ build works offline.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/cpp/HybridNitroXlsx.cpp

@@ -39,12 +39,36 @@ std::shared_ptr<HybridXlsxWorkbookSpec> HybridNitroXlsx::openWorkbookFromBuffer(
 std::shared_ptr<HybridXlsxWorkbookSpec> HybridNitroXlsx::fromJSON(const std::unordered_map<std::string, std::vector<std::shared_ptr<AnyMap>>>& data) {
   return withXlsxError(xlsx_error::INVALID_ARGUMENT, [&]() -> std::shared_ptr<HybridXlsxWorkbookSpec> {
     auto workbook = std::make_shared<HybridXlsxWorkbook>();
-    if (data.empty()) return workbook;
+    // Always leave the workbook usable: create the underlying XLDocument even
+    // when there is no data, so getBuffer()/toJSON()/getWorksheetCount() work.
+    workbook->ensureOpen();
+
+    // Snapshot the sheet(s) OpenXLSX created by default (e.g. "Sheet1") so they
+    // can be removed once the key sheets exist (deleteSheet refuses to delete
+    // the last sheet, so key sheets must be added first).
+    std::vector<std::string> defaultNames;
+    {
+      double count = workbook->getWorksheetCount();
+      for (double i = 0; i < count; ++i) {
+        defaultNames.push_back(workbook->getWorksheet(i)->getName());
+      }
+    }
 
     for (const auto& [sheetName, rows] : data) {
       auto sheet = workbook->addWorksheet(sheetName);
       sheet->fromJSON(rows);
     }
+
+    // README promises one worksheet per key: drop the default sheet(s) unless a
+    // key claimed them. Skip when there is no data - a workbook must keep at
+    // least one sheet.
+    if (!data.empty()) {
+      for (const auto& name : defaultNames) {
+        if (data.count(name) == 0) {
+          workbook->deleteSheet(name);
+        }
+      }
+    }
     return workbook;
   });
 }

package/cpp/HybridXlsxCellFormat.cpp

@@ -1,24 +1,7 @@
 #include "HybridXlsxCellFormat.hpp"
-#include <sstream>
-#include <iomanip>
-#include <cctype>
 
 namespace margelo::nitro::xlsx {
 
-static std::string doubleToHexColor(double color) {
-  uint32_t c = static_cast<uint32_t>(color);
-  // Excel uses ARGB format, prepend alpha channel (FF)
-  uint32_t argb = c | 0xFF000000;
-  std::stringstream ss;
-  ss << std::hex << std::setfill('0') << std::setw(8) << argb;
-  std::string result = ss.str();
-  // Convert to uppercase (OpenXLSX expects uppercase hex)
-  for (char& ch : result) {
-    ch = std::toupper(ch);
-  }
-  return result;
-}
-
 HybridXlsxCellFormat::HybridXlsxCellFormat()
     : HybridObject("XlsxCellFormat"), HybridXlsxCellFormatSpec() {
 }
@@ -26,263 +9,180 @@ HybridXlsxCellFormat::HybridXlsxCellFormat()
 HybridXlsxCellFormat::~HybridXlsxCellFormat() {
 }
 
-OpenXLSX::XLStyleIndex HybridXlsxCellFormat::applyToDocument(OpenXLSX::XLStyles& styles) {
-  if (_styleIndex.has_value()) {
-    return *_styleIndex;
-  }
-
-  // Create cell format in document first to get a valid XML node.
-  // OpenXLSX default-constructed style objects have empty XML nodes;
-  // setters on empty nodes silently fail. We must create the node in
-  // the document first, then modify the live node via operator[].
-  OpenXLSX::XLCellFormat emptyCellFormat;
-  OpenXLSX::XLStyleIndex cellFormatIndex = styles.cellFormats().create(emptyCellFormat);
-  OpenXLSX::XLCellFormat cellFormat = styles.cellFormats()[cellFormatIndex];
-
-  // Font
-  if (!_fontName.empty() || _fontSize > 0 || _fontColor > 0 || _bold || _italic || _underline > 0 || _strikeout || _fontScript > 0) {
-    OpenXLSX::XLFont emptyFont;
-    OpenXLSX::XLStyleIndex fontIndex = styles.fonts().create(emptyFont);
-    OpenXLSX::XLFont font = styles.fonts()[fontIndex];
-    if (!_fontName.empty()) font.setFontName(_fontName);
-    if (_fontSize > 0) font.setFontSize(static_cast<size_t>(_fontSize));
-    if (_fontColor > 0) font.setFontColor(OpenXLSX::XLColor(doubleToHexColor(_fontColor)));
-    if (_bold) font.setBold();
-    if (_italic) font.setItalic();
-    if (_underline > 0) font.setUnderline(static_cast<OpenXLSX::XLUnderlineStyle>(_underline));
-    if (_strikeout) font.setStrikethrough();
-    if (_fontScript > 0) font.setVertAlign(static_cast<OpenXLSX::XLVerticalAlignRunStyle>(_fontScript));
-    cellFormat.setFontIndex(fontIndex);
-    cellFormat.setApplyFont(true);
-  }
-
-  // Alignment
-  if (_textWrap || _rotation != 0 || _indent > 0 || _align > 0 || _verticalAlign > 0 || _shrink) {
-    if (_align > 0) cellFormat.alignment(true).setHorizontal(static_cast<OpenXLSX::XLAlignmentStyle>(_align));
-    if (_verticalAlign > 0) cellFormat.alignment(true).setVertical(static_cast<OpenXLSX::XLAlignmentStyle>(_verticalAlign));
-    if (_textWrap) cellFormat.alignment(true).setWrapText();
-    if (_rotation != 0) cellFormat.alignment(true).setTextRotation(static_cast<uint16_t>(_rotation));
-    if (_indent > 0) cellFormat.alignment(true).setIndent(static_cast<uint32_t>(_indent));
-    if (_shrink) cellFormat.alignment(true).setShrinkToFit();
-    cellFormat.setApplyAlignment(true);
-  }
-
-  // Number format
-  if (!_numFormat.empty()) {
-    OpenXLSX::XLNumberFormat emptyNumFormat;
-    OpenXLSX::XLStyleIndex numFmtIndex = styles.numberFormats().create(emptyNumFormat);
-    OpenXLSX::XLNumberFormat numFormat = styles.numberFormats()[numFmtIndex];
-    numFormat.setFormatCode(_numFormat);
-    // Assign a unique custom numFmtId (>= 164 for user-defined formats)
-    static uint32_t nextCustomNumFmtId = 164;
-    numFormat.setNumberFormatId(nextCustomNumFmtId++);
-    cellFormat.setNumberFormatId(numFormat.numberFormatId());
-    cellFormat.setApplyNumberFormat(true);
-  }
-
-  // Fill
-  if (_bgColor > 0 || _fgColor > 0 || _pattern > 0) {
-    OpenXLSX::XLFill emptyFill;
-    OpenXLSX::XLStyleIndex fillIndex = styles.fills().create(emptyFill);
-    OpenXLSX::XLFill fill = styles.fills()[fillIndex];
-    fill.setPatternType(_pattern > 0
-      ? static_cast<OpenXLSX::XLPatternType>(_pattern)
-      : OpenXLSX::XLPatternType::XLPatternSolid);
-    if (_bgColor > 0) fill.setBackgroundColor(OpenXLSX::XLColor(doubleToHexColor(_bgColor)));
-    if (_fgColor > 0) fill.setColor(OpenXLSX::XLColor(doubleToHexColor(_fgColor)));
-    cellFormat.setFillIndex(fillIndex);
-    cellFormat.setApplyFill(true);
-  }
-
-  // Border
-  if (_border > 0 || _bottom > 0 || _top > 0 || _left > 0 || _right > 0 || _diagonal > 0) {
-    OpenXLSX::XLBorder emptyBorder;
-    OpenXLSX::XLStyleIndex borderIndex = styles.borders().create(emptyBorder);
-    OpenXLSX::XLBorder border = styles.borders()[borderIndex];
-    // TODO: Implement border styling with OpenXLSX v0.5.1 API
-    cellFormat.setBorderIndex(borderIndex);
-    cellFormat.setApplyBorder(true);
-  }
-
-  // Protection
-  if (_locked) {
-    cellFormat.setLocked(true);
-    cellFormat.setApplyProtection(true);
-  }
-
-  _styleIndex = cellFormatIndex;
-  return cellFormatIndex;
+OpenXLSX::XLStyleIndex HybridXlsxCellFormat::applyToDocument(OpenXLSX::XLStyles& styles, uint64_t documentGeneration) {
+  return _fmt.applyToDocument(styles, documentGeneration);
 }
 
 void HybridXlsxCellFormat::applyToCell(OpenXLSX::XLCell& cell, OpenXLSX::XLStyleIndex styleIndex) {
-  cell.setCellFormat(styleIndex);
+  _fmt.applyToCell(cell, styleIndex);
 }
 
 void HybridXlsxCellFormat::setFontName(const std::string& name) {
-  _fontName = name;
+  _fmt.setFontName(name);
 }
 
 void HybridXlsxCellFormat::setFontSize(double size) {
-  _fontSize = size;
+  _fmt.setFontSize(size);
 }
 
 void HybridXlsxCellFormat::setFontColor(double color) {
-  _fontColor = color;
+  _fmt.setFontColor(color);
 }
 
 void HybridXlsxCellFormat::setFontScript(double style) {
-  _fontScript = style;
+  _fmt.setFontScript(style);
 }
 
 void HybridXlsxCellFormat::setBold() {
-  _bold = true;
+  _fmt.setBold();
 }
 
 void HybridXlsxCellFormat::setItalic() {
-  _italic = true;
+  _fmt.setItalic();
 }
 
 void HybridXlsxCellFormat::setUnderline(std::optional<double> style) {
-  _underline = style.has_value() ? *style : 1;
+  _fmt.setUnderline(style);
 }
 
 void HybridXlsxCellFormat::setStrikeout() {
-  _strikeout = true;
+  _fmt.setStrikeout();
 }
 
 void HybridXlsxCellFormat::setAlign(double align) {
-  _align = align;
+  _fmt.setAlign(align);
 }
 
 void HybridXlsxCellFormat::setVerticalAlign(double align) {
-  _verticalAlign = align;
+  _fmt.setVerticalAlign(align);
 }
 
 void HybridXlsxCellFormat::setTextWrap() {
-  _textWrap = true;
+  _fmt.setTextWrap();
 }
 
 void HybridXlsxCellFormat::setRotation(double angle) {
-  _rotation = angle;
+  _fmt.setRotation(angle);
 }
 
 void HybridXlsxCellFormat::setIndent(double level) {
-  _indent = level;
+  _fmt.setIndent(level);
 }
 
 void HybridXlsxCellFormat::setShrink() {
-  _shrink = true;
+  _fmt.setShrink();
 }
 
 void HybridXlsxCellFormat::setNumFormat(const std::string& format) {
-  _numFormat = format;
+  _fmt.setNumFormat(format);
 }
 
 void HybridXlsxCellFormat::setNumFormatIndex(double index) {
-  _numFormatIndex = index;
+  _fmt.setNumFormatIndex(index);
 }
 
 void HybridXlsxCellFormat::setBgColor(double color) {
-  _bgColor = color;
+  _fmt.setBgColor(color);
 }
 
 void HybridXlsxCellFormat::setFgColor(double color) {
-  _fgColor = color;
+  _fmt.setFgColor(color);
 }
 
 void HybridXlsxCellFormat::setPattern(double pattern) {
-  _pattern = pattern;
+  _fmt.setPattern(pattern);
 }
 
 void HybridXlsxCellFormat::setBorder(double style) {
-  _border = style;
+  _fmt.setBorder(style);
 }
 
 void HybridXlsxCellFormat::setBorderColor(double color) {
-  _borderColor = color;
+  _fmt.setBorderColor(color);
 }
 
 void HybridXlsxCellFormat::setBottom(double style) {
-  _bottom = style;
+  _fmt.setBottom(style);
 }
 
 void HybridXlsxCellFormat::setTop(double style) {
-  _top = style;
+  _fmt.setTop(style);
 }
 
 void HybridXlsxCellFormat::setLeft(double style) {
-  _left = style;
+  _fmt.setLeft(style);
 }
 
 void HybridXlsxCellFormat::setRight(double style) {
-  _right = style;
+  _fmt.setRight(style);
 }
 
 void HybridXlsxCellFormat::setBottomColor(double color) {
-  _bottomColor = color;
+  _fmt.setBottomColor(color);
 }
 
 void HybridXlsxCellFormat::setTopColor(double color) {
-  _topColor = color;
+  _fmt.setTopColor(color);
 }
 
 void HybridXlsxCellFormat::setLeftColor(double color) {
-  _leftColor = color;
+  _fmt.setLeftColor(color);
 }
 
 void HybridXlsxCellFormat::setRightColor(double color) {
-  _rightColor = color;
+  _fmt.setRightColor(color);
 }
 
 void HybridXlsxCellFormat::setDiagonal(double style) {
-  _diagonal = style;
+  _fmt.setDiagonal(style);
 }
 
 void HybridXlsxCellFormat::setDiagonalColor(double color) {
-  _diagonalColor = color;
+  _fmt.setDiagonalColor(color);
 }
 
 void HybridXlsxCellFormat::setLocked() {
-  _locked = true;
+  _fmt.setLocked();
 }
 
 void HybridXlsxCellFormat::setUnlocked() {
-  _locked = false;
+  _fmt.setUnlocked();
 }
 
 void HybridXlsxCellFormat::setHyperlink() {
-  _hyperlink = true;
+  _fmt.setHyperlink();
 }
 
 void HybridXlsxCellFormat::setFontOnly() {
+  _fmt.setFontOnly();
 }
 
 std::string HybridXlsxCellFormat::getFontName() {
-  return _fontName;
+  return _fmt.getFontName();
 }
 
 double HybridXlsxCellFormat::getFontSize() {
-  return _fontSize;
+  return _fmt.getFontSize();
 }
 
 double HybridXlsxCellFormat::getFontColor() {
-  return _fontColor;
+  return _fmt.getFontColor();
 }
 
 bool HybridXlsxCellFormat::getIsBold() {
-  return _bold;
+  return _fmt.getIsBold();
 }
 
 bool HybridXlsxCellFormat::getIsItalic() {
-  return _italic;
+  return _fmt.getIsItalic();
 }
 
 std::string HybridXlsxCellFormat::getNumFormat() {
-  return _numFormat;
+  return _fmt.getNumFormat();
 }
 
 double HybridXlsxCellFormat::getBgColor() {
-  return _bgColor;
+  return _fmt.getBgColor();
 }
 
-}
+}

package/cpp/HybridXlsxCellFormat.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "HybridXlsxCellFormatSpec.hpp"
+#include "XlsxCellStyle.hpp"
 #include <OpenXLSX/XLDocument.hpp>
 #include <OpenXLSX/XLSheet.hpp>
 #include <OpenXLSX/XLStyles.hpp>
@@ -14,7 +15,11 @@ public:
   HybridXlsxCellFormat();
   ~HybridXlsxCellFormat() override;
 
-  OpenXLSX::XLStyleIndex applyToDocument(OpenXLSX::XLStyles& styles);
+  // `documentGeneration` identifies the XLDocument that owns `styles` (see
+  // HybridXlsxWorkbook::documentGeneration()). It must be passed on every call
+  // so the style cache can never be reused by a different document that happens
+  // to reuse the same heap address.
+  OpenXLSX::XLStyleIndex applyToDocument(OpenXLSX::XLStyles& styles, uint64_t documentGeneration);
   void applyToCell(OpenXLSX::XLCell& cell, OpenXLSX::XLStyleIndex styleIndex);
 
   void setFontName(const std::string& name) override;
@@ -68,45 +73,8 @@ public:
   double getBgColor() override;
 
 private:
-  std::optional<OpenXLSX::XLStyleIndex> _styleIndex;
-  std::string _fontName;
-  double _fontSize = 0;
-  double _fontColor = 0;
-  double _fontScript = 0;
-  bool _bold = false;
-  bool _italic = false;
-  double _underline = 0;
-  bool _strikeout = false;
-  
-  double _align = 0;
-  double _verticalAlign = 0;
-  bool _textWrap = false;
-  double _rotation = 0;
-  double _indent = 0;
-  bool _shrink = false;
-  
-  std::string _numFormat;
-  double _numFormatIndex = 0;
-  
-  double _bgColor = 0;
-  double _fgColor = 0;
-  double _pattern = 0;
-  
-  double _border = 0;
-  double _borderColor = 0;
-  double _bottom = 0;
-  double _top = 0;
-  double _left = 0;
-  double _right = 0;
-  double _bottomColor = 0;
-  double _topColor = 0;
-  double _leftColor = 0;
-  double _rightColor = 0;
-  double _diagonal = 0;
-  double _diagonalColor = 0;
-  
-  bool _locked = false;
-  bool _hyperlink = false;
+  // Style state and styles.xml materialization, shared with the unit tests.
+  XlsxCellStyle _fmt;
 };
 
-}
+}

package/cpp/HybridXlsxConditionalFormat.cpp

@@ -84,9 +84,12 @@ void HybridXlsxConditionalFormat::setRuleDxfId(double index, double dxfId) {
 
 std::string HybridXlsxConditionalFormat::getRuleFormula(double index, double formulaIndex) {
   return withXlsxError(xlsx_error::XLSX_ERROR, [&] {
+    // Validate the rule index first so out-of-range throws INDEX_OUT_OF_RANGE
+    // like every other getter (and like setRuleFormula).
+    auto rule = ruleAt(index);
     // OpenXLSX only supports the primary <formula> node
     if (formulaIndex != 0) return std::string();
-    return ruleAt(index).formula();
+    return rule.formula();
   });
 }
 

package/cpp/HybridXlsxConditionalFormats.cpp

@@ -19,7 +19,11 @@ std::shared_ptr<HybridXlsxConditionalFormatSpec> HybridXlsxConditionalFormats::c
   return withXlsxError(xlsx_error::XLSX_ERROR, [&] {
     size_t index = _formats.create();
     OpenXLSX::XLConditionalFormat format = _formats.conditionalFormatByIndex(index);
-    format.setSqref(sqref);
+    // setSqref() returns false when it cannot apply the value (and treats an empty
+    // attribute value as a no-op), so a blank sqref is rejected explicitly too.
+    if (sqref.empty() || !format.setSqref(sqref)) {
+      throw XlsxError(xlsx_error::INVALID_ARGUMENT, "Invalid sqref: " + sqref);
+    }
     auto hybrid = std::make_shared<HybridXlsxConditionalFormat>(format);
     _created.push_back(hybrid);
     return std::static_pointer_cast<HybridXlsxConditionalFormatSpec>(hybrid);

package/cpp/HybridXlsxWorkbook.cpp

@@ -33,17 +33,34 @@ HybridXlsxWorkbook::~HybridXlsxWorkbook() {
 
 void HybridXlsxWorkbook::openFromFile(const std::string& path) {
   _workbook->open(path);
+  ++_generation;
   loadWorksheets();
 }
 
 void HybridXlsxWorkbook::openFromBuffer(const uint8_t* data, size_t size) {
   std::string tempPath = tempFilePath("xlsx_open");
-  std::ofstream file(tempPath, std::ios::binary);
-  file.write(reinterpret_cast<const char*>(data), size);
-  file.close();
+  {
+    std::ofstream file(tempPath, std::ios::binary);
+    if (!file.is_open()) {
+      throw XlsxError(xlsx_error::IO_ERROR, "Failed to open temp file for writing: " + tempPath);
+    }
+    file.write(reinterpret_cast<const char*>(data), static_cast<std::streamsize>(size));
+    file.close();
+    if (file.fail()) {
+      std::remove(tempPath.c_str());
+      throw XlsxError(xlsx_error::IO_ERROR, "Failed to write buffer to temp file: " + tempPath);
+    }
+  }
 
-  _workbook->open(tempPath);
+  try {
+    _workbook->open(tempPath);
+  } catch (...) {
+    // Never leak the temp file when opening fails.
+    std::remove(tempPath.c_str());
+    throw;
+  }
   std::remove(tempPath.c_str());
+  ++_generation;
   loadWorksheets();
 }
 
@@ -56,7 +73,7 @@ void HybridXlsxWorkbook::loadWorksheets() {
   for (uint16_t i = 1; i <= count; ++i) {
     auto worksheet = wb.worksheet(i);
     std::string sheetName = worksheet.name();
-    auto hybridWorksheet = std::make_shared<HybridXlsxWorksheet>(*_workbook, worksheet);
+    auto hybridWorksheet = std::make_shared<HybridXlsxWorksheet>(*_workbook, worksheet, _generation);
     _worksheets.push_back(hybridWorksheet);
     _worksheetNames[sheetName] = hybridWorksheet;
   }
@@ -67,6 +84,7 @@ void HybridXlsxWorkbook::ensureOpen() {
   std::string tempPath = tempFilePath("xlsx_create");
   _workbook->create(tempPath, OpenXLSX::XLForceOverwrite);
   std::remove(tempPath.c_str());
+  ++_generation;
   loadWorksheets();
 }
 
@@ -91,7 +109,7 @@ std::shared_ptr<HybridXlsxWorksheetSpec> HybridXlsxWorkbook::addWorksheet(const
 
     _workbook->workbook().addWorksheet(sheetName);
     auto worksheet = _workbook->workbook().worksheet(sheetName);
-    auto hybridWorksheet = std::make_shared<HybridXlsxWorksheet>(*_workbook, worksheet);
+    auto hybridWorksheet = std::make_shared<HybridXlsxWorksheet>(*_workbook, worksheet, _generation);
     _worksheets.push_back(hybridWorksheet);
     _worksheetNames[sheetName] = hybridWorksheet;
     return hybridWorksheet;
@@ -133,6 +151,7 @@ std::shared_ptr<HybridXlsxWorksheetSpec> HybridXlsxWorkbook::getOrAddWorksheet(c
 
 double HybridXlsxWorkbook::getWorksheetCount() {
   return withXlsxError(xlsx_error::XLSX_ERROR, [&] {
+    ensureOpen();
     return static_cast<double>(_workbook->workbook().worksheetCount());
   });
 }
@@ -200,7 +219,7 @@ std::shared_ptr<HybridXlsxWorksheetSpec> HybridXlsxWorkbook::clone(const std::st
 
     _workbook->workbook().cloneSheet(existingName, newName);
     auto worksheet = _workbook->workbook().worksheet(newName);
-    auto hybridWorksheet = std::make_shared<HybridXlsxWorksheet>(*_workbook, worksheet);
+    auto hybridWorksheet = std::make_shared<HybridXlsxWorksheet>(*_workbook, worksheet, _generation);
     _worksheets.push_back(hybridWorksheet);
     _worksheetNames[newName] = hybridWorksheet;
     return hybridWorksheet;
@@ -222,6 +241,7 @@ std::shared_ptr<Promise<std::shared_ptr<ArrayBuffer>>> HybridXlsxWorkbook::getBu
   }
 
   try {
+    ensureOpen();
     std::string tempPath = tempFilePath("xlsx_temp");
     _workbook->saveAs(tempPath, OpenXLSX::XLForceOverwrite);
 
@@ -256,8 +276,18 @@ std::shared_ptr<Promise<std::shared_ptr<ArrayBuffer>>> HybridXlsxWorkbook::getBu
 
 std::unordered_map<std::string, std::vector<std::shared_ptr<AnyMap>>> HybridXlsxWorkbook::toJSON() {
   return withXlsxError(xlsx_error::XLSX_ERROR, [&] {
+    ensureOpen();
     auto wb = _workbook->workbook();
-    return workbookToRecords(wb);
+    auto records = workbookToRecords(wb);
+    // Sheets without any records (e.g. the default sheet of a fresh workbook)
+    // are omitted so an empty workbook round-trips to an empty map.
+    std::unordered_map<std::string, std::vector<std::shared_ptr<AnyMap>>> result;
+    for (auto& [name, rows] : records) {
+      if (!rows.empty()) {
+        result.emplace(name, std::move(rows));
+      }
+    }
+    return result;
   });
 }
 

package/cpp/HybridXlsxWorkbook.hpp

@@ -19,6 +19,10 @@ public:
   void openFromFile(const std::string& path);
   void openFromBuffer(const uint8_t* data, size_t size);
 
+  // Ensure the underlying XLDocument has been created/opened so the workbook is
+  // usable even if it was never explicitly opened (fromJSON, createWorkbook).
+  void ensureOpen();
+
   std::shared_ptr<HybridXlsxWorksheetSpec> addWorksheet(const std::optional<std::string>& name) override;
   std::shared_ptr<HybridXlsxWorksheetSpec> getWorksheet(double index) override;
   std::shared_ptr<HybridXlsxWorksheetSpec> getWorksheetByName(const std::string& name) override;
@@ -37,10 +41,15 @@ private:
   std::unordered_map<std::string, std::shared_ptr<HybridXlsxWorksheet>> _worksheetNames;
   std::vector<std::shared_ptr<HybridXlsxCellFormat>> _cellFormats;
   bool _finalized;
+  // Identifies the current underlying XLDocument. Bumped every time the
+  // document is (re)created or opened so per-document caches (cell styles) can
+  // tell a recycled heap address apart from the document it was built for.
+  uint64_t documentGeneration() const { return _generation; }
+
   std::string _tempDir;
+  uint64_t _generation = 0;
 
   void loadWorksheets();
-  void ensureOpen();
   std::string tempFilePath(const char* prefix);
 };