react-native-nitro-xlsx 0.1.2 → 0.2.5

package/scripts/run-cpp-tests.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT/cpp/tests"
+
+if [ -z "${OPENXLSX_PATH:-}" ]; then
+  OPENXLSX_PATH="$ROOT/OpenXLSX"
+fi
+
+cmake -B build -DOPENXLSX_PATH="$OPENXLSX_PATH"
+cmake --build build
+cd build
+ctest --output-on-failure

package/src/__mocks__/react-native-nitro-modules.ts

@@ -24,5 +24,6 @@ export const NitroModules = {
     createWorkbook: jest.fn(),
     openWorkbook: jest.fn(),
     openWorkbookFromBuffer: jest.fn(),
+    fromJSON: jest.fn(),
   }),
 };

package/src/__tests__/index.test.ts

@@ -10,7 +10,11 @@ import {
   Gridlines,
   Colors,
   NumFormat,
-  ImagePosition,
+  XlsxError,
+  XlsxErrorCode,
+  CfType,
+  CfOperator,
+  CfTimePeriod,
 } from '../index';
 
 describe('NitroXlsx', () => {
@@ -33,6 +37,14 @@ describe('NitroXlsx', () => {
     expect(NitroXlsx.openWorkbookFromBuffer).toBeDefined();
     expect(typeof NitroXlsx.openWorkbookFromBuffer).toBe('function');
   });
+
+  it('should have fromJSON method that accepts a Record of sheet rows', () => {
+    expect(NitroXlsx.fromJSON).toBeDefined();
+    expect(typeof NitroXlsx.fromJSON).toBe('function');
+    expect(() =>
+      NitroXlsx.fromJSON({ Sheet1: [{ Name: 'Alice', Age: 30 }] })
+    ).not.toThrow();
+  });
 });
 
 describe('Constants', () => {
@@ -130,12 +142,69 @@ describe('Constants', () => {
     });
   });
 
-  describe('ImagePosition', () => {
-    it('should export ImagePosition constants', () => {
-      expect(ImagePosition).toBeDefined();
-      expect(ImagePosition.MOVE_AND_SIZE).toBe(1);
-      expect(ImagePosition.MOVE_DONT_SIZE).toBe(2);
-      expect(ImagePosition.DONT_MOVE_DONT_SIZE).toBe(3);
+  describe('CfType', () => {
+    it('should export CfType constants', () => {
+      expect(CfType).toBeDefined();
+      expect(CfType.EXPRESSION).toBe(0);
+      expect(CfType.CELL_IS).toBe(1);
+      expect(CfType.TOP10).toBe(5);
+      expect(CfType.CONTAINS_TEXT).toBe(8);
+      expect(CfType.TIME_PERIOD).toBe(16);
+    });
+  });
+
+  describe('CfOperator', () => {
+    it('should export CfOperator constants', () => {
+      expect(CfOperator).toBeDefined();
+      expect(CfOperator.LESS_THAN).toBe(0);
+      expect(CfOperator.EQUAL).toBe(2);
+      expect(CfOperator.GREATER_THAN).toBe(5);
+      expect(CfOperator.BETWEEN).toBe(6);
     });
   });
+
+  describe('CfTimePeriod', () => {
+    it('should export CfTimePeriod constants', () => {
+      expect(CfTimePeriod).toBeDefined();
+      expect(CfTimePeriod.TODAY).toBe(0);
+      expect(CfTimePeriod.YESTERDAY).toBe(1);
+      expect(CfTimePeriod.THIS_WEEK).toBe(7);
+    });
+  });
+});
+
+describe('XlsxError', () => {
+  it('should export XlsxErrorCode constants', () => {
+    expect(XlsxErrorCode.INVALID_ARGUMENT).toBe('INVALID_ARGUMENT');
+    expect(XlsxErrorCode.SHEET_NOT_FOUND).toBe('SHEET_NOT_FOUND');
+    expect(XlsxErrorCode.INDEX_OUT_OF_RANGE).toBe('INDEX_OUT_OF_RANGE');
+    expect(XlsxErrorCode.UNSUPPORTED).toBe('UNSUPPORTED');
+    expect(XlsxErrorCode.XLSX_ERROR).toBe('XLSX_ERROR');
+  });
+
+  it('should create XlsxError with code and message', () => {
+    const err = new XlsxError(XlsxErrorCode.SHEET_NOT_FOUND, 'Sheet missing');
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe('XlsxError');
+    expect(err.code).toBe('SHEET_NOT_FOUND');
+    expect(err.message).toContain('SHEET_NOT_FOUND');
+    expect(err.message).toContain('Sheet missing');
+  });
+
+  it('should parse native error message into XlsxError', () => {
+    const native = new Error('deleteSheet: SHEET_NOT_FOUND: Worksheet not found: Foo');
+    const err = XlsxError.from(native);
+    expect(err.code).toBe('SHEET_NOT_FOUND');
+    expect(err.message).toContain('Worksheet not found: Foo');
+  });
+
+  it('should wrap unknown errors with INTERNAL_ERROR', () => {
+    const err = XlsxError.from(new Error('something odd'));
+    expect(err.code).toBe('INTERNAL_ERROR');
+  });
+
+  it('should return the same instance if already XlsxError', () => {
+    const original = new XlsxError(XlsxErrorCode.IO_ERROR, 'disk');
+    expect(XlsxError.from(original)).toBe(original);
+  });
 });

package/src/index.ts

@@ -1,9 +1,117 @@
 import { NitroModules } from 'react-native-nitro-modules'
-import type { NitroXlsx as NitroXlsxSpec } from './specs/NitroXlsx.nitro'
+import type {
+  NitroXlsx as NitroXlsxSpec
+} from './specs/NitroXlsx.nitro'
 
 export const NitroXlsx = NitroModules.createHybridObject<NitroXlsxSpec>('NitroXlsx')
 
-export type { XlsxWorkbook, XlsxWorksheet, XlsxCellFormat } from './specs/NitroXlsx.nitro'
+export type {
+  XlsxWorkbook,
+  XlsxWorksheet,
+  XlsxCellFormat,
+  XlsxConditionalFormat,
+  XlsxConditionalFormats,
+  CellType,
+} from './specs/NitroXlsx.nitro'
+
+/**
+ * Error codes emitted by the native layer.
+ * Native errors arrive as `Error` with message `methodName: CODE: detail`.
+ */
+export const XlsxErrorCode = {
+  INVALID_ARGUMENT: 'INVALID_ARGUMENT',
+  SHEET_NOT_FOUND: 'SHEET_NOT_FOUND',
+  SHEET_EXISTS: 'SHEET_EXISTS',
+  INDEX_OUT_OF_RANGE: 'INDEX_OUT_OF_RANGE',
+  CELL_NOT_FOUND: 'CELL_NOT_FOUND',
+  WORKBOOK_CLOSED: 'WORKBOOK_CLOSED',
+  IO_ERROR: 'IO_ERROR',
+  UNSUPPORTED: 'UNSUPPORTED',
+  XLSX_ERROR: 'XLSX_ERROR',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const
+
+export type XlsxErrorCode = (typeof XlsxErrorCode)[keyof typeof XlsxErrorCode]
+
+/**
+ * Structured XLSX error. Use `XlsxError.from(caught)` to convert a native throw.
+ */
+export class XlsxError extends Error {
+  readonly code: XlsxErrorCode | string
+
+  constructor(code: XlsxErrorCode | string, message: string) {
+    super(`[${code}] ${message}`)
+    this.name = 'XlsxError'
+    this.code = code
+  }
+
+  /**
+   * Convert an error thrown by the native module into an XlsxError.
+   * Non-XLSX errors are wrapped with code INTERNAL_ERROR.
+   */
+  static from(error: unknown): XlsxError {
+    if (error instanceof XlsxError) return error
+    const message = error instanceof Error ? error.message : String(error)
+    // Nitro prefixes "methodName: " then our "CODE: detail"
+    const match = message.match(/(?:^|:\s*)([A-Z_]+):\s*(.*)$/)
+    if (match && match[1] && (Object.values(XlsxErrorCode) as string[]).includes(match[1])) {
+      return new XlsxError(match[1], match[2] ?? '')
+    }
+    return new XlsxError(XlsxErrorCode.INTERNAL_ERROR, message)
+  }
+}
+
+// Conditional formatting rule types (OpenXLSX XLCfType)
+export const CfType = {
+  EXPRESSION: 0,
+  CELL_IS: 1,
+  COLOR_SCALE: 2,
+  DATA_BAR: 3,
+  ICON_SET: 4,
+  TOP10: 5,
+  UNIQUE_VALUES: 6,
+  DUPLICATE_VALUES: 7,
+  CONTAINS_TEXT: 8,
+  NOT_CONTAINS_TEXT: 9,
+  BEGINS_WITH: 10,
+  ENDS_WITH: 11,
+  CONTAINS_BLANKS: 12,
+  NOT_CONTAINS_BLANKS: 13,
+  CONTAINS_ERRORS: 14,
+  NOT_CONTAINS_ERRORS: 15,
+  TIME_PERIOD: 16,
+  ABOVE_AVERAGE: 17,
+} as const
+
+// Conditional formatting operators (OpenXLSX XLCfOperator)
+export const CfOperator = {
+  LESS_THAN: 0,
+  LESS_THAN_OR_EQUAL: 1,
+  EQUAL: 2,
+  NOT_EQUAL: 3,
+  GREATER_THAN_OR_EQUAL: 4,
+  GREATER_THAN: 5,
+  BETWEEN: 6,
+  NOT_BETWEEN: 7,
+  CONTAINS_TEXT: 8,
+  NOT_CONTAINS: 9,
+  BEGINS_WITH: 10,
+  ENDS_WITH: 11,
+} as const
+
+// Conditional formatting time periods (OpenXLSX XLCfTimePeriod)
+export const CfTimePeriod = {
+  TODAY: 0,
+  YESTERDAY: 1,
+  TOMORROW: 2,
+  LAST_7_DAYS: 3,
+  THIS_MONTH: 4,
+  LAST_MONTH: 5,
+  NEXT_MONTH: 6,
+  THIS_WEEK: 7,
+  LAST_WEEK: 8,
+  NEXT_WEEK: 9,
+} as const
 
 // Cell alignment (based on OpenXLSX XLAlignmentStyle)
 export const Align = {
@@ -185,11 +293,4 @@ export const NumFormat = {
   TIME_4: 23,
   DATETIME: 22,
   TEXT: 49,
-} as const
-
-// Image object position
-export const ImagePosition = {
-  MOVE_AND_SIZE: 1,
-  MOVE_DONT_SIZE: 2,
-  DONT_MOVE_DONT_SIZE: 3,
 } as const

package/src/specs/NitroXlsx.nitro.ts

@@ -1,4 +1,4 @@
-import { type HybridObject } from 'react-native-nitro-modules'
+import { type HybridObject, type AnyMap } from 'react-native-nitro-modules'
 
 export type CellType = 'empty' | 'string' | 'number' | 'boolean' | 'date' | 'error' | 'formula' | 'blank'
 
@@ -8,8 +8,12 @@ export interface XlsxWorkbook extends HybridObject<{ ios: 'c++'; android: 'c++'
   getWorksheetByName(name: string): XlsxWorksheet
   getOrAddWorksheet(name: string): XlsxWorksheet
   getWorksheetCount(): number
+  deleteSheet(name: string): void
+  updateSheetName(oldName: string, newName: string): void
+  clone(existingName: string, newName: string): XlsxWorksheet
   addCellFormat(): XlsxCellFormat
   getBuffer(): Promise<ArrayBuffer>
+  toJSON(): Record<string, Array<AnyMap>>
 }
 
 export interface XlsxWorksheet extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
@@ -18,73 +22,167 @@ export interface XlsxWorksheet extends HybridObject<{ ios: 'c++'; android: 'c++'
   writeNumber(row: number, col: number, value: number, format?: XlsxCellFormat): void
   writeBoolean(row: number, col: number, value: boolean, format?: XlsxCellFormat): void
   writeBlank(row: number, col: number, format?: XlsxCellFormat): void
-  
+
   // Formula support
   writeFormula(row: number, col: number, formula: string, format?: XlsxCellFormat): void
   writeFormulaNum(row: number, col: number, formula: string, number: number, format?: XlsxCellFormat): void
   writeFormulaString(row: number, col: number, formula: string, str: string, format?: XlsxCellFormat): void
   writeFormulaBoolean(row: number, col: number, formula: string, boolVal: boolean, format?: XlsxCellFormat): void
   writeArrayFormula(firstRow: number, firstCol: number, lastRow: number, lastCol: number, formula: string, format?: XlsxCellFormat): void
-  
+
   // Date/DateTime support
   writeDatetime(row: number, col: number, datetime: number, format?: XlsxCellFormat): void
   writeURL(row: number, col: number, url: string, format?: XlsxCellFormat): void
-  
+
   // Column/Row operations
   setColumn(firstCol: number, lastCol: number, width: number, format?: XlsxCellFormat): void
   setRow(row: number, height: number, format?: XlsxCellFormat): void
-  
+  deleteRow(row: number): boolean
+  deleteColumn(col: number): boolean
+
   // Merge cells
   mergeRange(firstRow: number, firstCol: number, lastRow: number, lastCol: number, value: string, format?: XlsxCellFormat): void
   mergeRangeNum(firstRow: number, firstCol: number, lastRow: number, lastCol: number, value: number, format?: XlsxCellFormat): void
-  
-  // Image (uses file path)
-  insertImage(row: number, col: number, path: string, xOffset?: number, yOffset?: number, xScale?: number, yScale?: number): void
-  insertImageBuffer(row: number, col: number, buffer: ArrayBuffer, extension: string, xOffset?: number, yOffset?: number, xScale?: number, yScale?: number): void
-  
-  // Autofilter
-  autofilter(firstRow: number, firstCol: number, lastRow: number, lastCol: number): void
-  
-  // Freeze/Split panes
-  freezePanes(row: number, col: number): void
-  splitPanes(row: number, col: number): void
-  
+  unmergeCells(firstRow: number, firstCol: number, lastRow: number, lastCol: number): void
+
   // Tab appearance
-  setTabColor(color: number): void
   hide(): void
   activate(): void
-  setFirstSheet(): void
+
+  // Sheet protection
   protect(password?: string): void
-  
-  // Page setup
-  setPortrait(): void
-  setLandscape(): void
-  setPaper(paperType: number): void
-  setHeader(header: string): void
-  setFooter(footer: string): void
-  setPrintArea(firstRow: number, firstCol: number, lastRow: number, lastCol: number): void
-  fitToPages(width: number, height: number): void
-  setZoom(scale: number): void
-  setGridlines(option: number): void
-  centerHorizontally(): void
-  centerVertically(): void
-  
+  protectSheet(set?: boolean): void
+  protectObjects(set?: boolean): void
+  protectScenarios(set?: boolean): void
+
+  // Password
+  setPassword(password: string): void
+  setPasswordHash(hash: string): void
+  clearPassword(): void
+  clearSheetProtection(): void
+
+  // Fine-grained permissions (allow*/deny* pairs)
+  allowInsertColumns(set?: boolean): void
+  allowInsertRows(set?: boolean): void
+  allowDeleteColumns(set?: boolean): void
+  allowDeleteRows(set?: boolean): void
+  allowSelectLockedCells(set?: boolean): void
+  allowSelectUnlockedCells(set?: boolean): void
+
+  denyInsertColumns(): void
+  denyInsertRows(): void
+  denyDeleteColumns(): void
+  denyDeleteRows(): void
+  denySelectLockedCells(): void
+  denySelectUnlockedCells(): void
+
+  // Protection state
+  sheetProtected(): boolean
+  objectsProtected(): boolean
+  scenariosProtected(): boolean
+  insertColumnsAllowed(): boolean
+  insertRowsAllowed(): boolean
+  deleteColumnsAllowed(): boolean
+  deleteRowsAllowed(): boolean
+  selectLockedCellsAllowed(): boolean
+  selectUnlockedCellsAllowed(): boolean
+  passwordIsSet(): boolean
+  passwordHash(): string
+  sheetProtectionSummary(): string
+
   // Outline/Grouping
-  setOutline(level: number): void
   setColumnHidden(firstCol: number, lastCol: number, hidden: boolean): void
   setRowHidden(row: number, hidden: boolean): void
 
+  // Comments (XLComments)
+  setComment(row: number, col: number, text: string, authorId?: number): void
+  getComment(row: number, col: number): string
+  hasComment(row: number, col: number): boolean
+  deleteComment(row: number, col: number): boolean
+  getCommentCount(): number
+  addCommentAuthor(author: string): number
+  getCommentAuthor(authorId: number): string
+
+  // Conditional formatting (XLConditionalFormats)
+  getConditionalFormats(): XlsxConditionalFormats
+
   // Read methods
   getCellValue(row: number, col: number): string | number | boolean | null
   getCellString(row: number, col: number): string
   getCellRawValue(row: number, col: number): string
   getCellType(row: number, col: number): CellType
   getCellFormat(row: number, col: number): XlsxCellFormat
+  hasFormula(row: number, col: number): boolean
+  formula(row: number, col: number): string
+  findCell(row: number, col: number): boolean
   getRowCount(): number
   getColumnCount(): number
   getLastRow(): number
   getLastColumn(): number
   getName(): string
+
+  // JSON import / export for this worksheet
+  toJSON(keys?: string[]): Array<AnyMap>
+  fromJSON(data: Array<AnyMap>): void
+}
+
+/**
+ * A single <conditionalFormatting> entry: a cell range (sqref) plus its cfRules.
+ */
+export interface XlsxConditionalFormat extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
+  getSqref(): string
+  setSqref(sqref: string): void
+
+  // Rule collection
+  getRuleCount(): number
+  createRule(): number
+  deleteRule(index: number): boolean
+
+  // Rule type / dxf
+  getRuleType(index: number): number
+  setRuleType(index: number, type: number): void
+  getRuleDxfId(index: number): number
+  setRuleDxfId(index: number, dxfId: number): void
+
+  // Rule formula (supports up to 3 formulas: formula/formula2/formula3)
+  getRuleFormula(index: number, formulaIndex: number): string
+  setRuleFormula(index: number, formulaIndex: number, formula: string): void
+
+  // Rule attributes
+  getRuleOperator(index: number): number
+  setRuleOperator(index: number, op: number): void
+  getRuleText(index: number): string
+  setRuleText(index: number, text: string): void
+  getRulePriority(index: number): number
+  setRulePriority(index: number, priority: number): void
+  getRuleStopIfTrue(index: number): boolean
+  setRuleStopIfTrue(index: number, stop: boolean): void
+  getRuleTimePeriod(index: number): number
+  setRuleTimePeriod(index: number, period: number): void
+  getRuleRank(index: number): number
+  setRuleRank(index: number, rank: number): void
+  getRuleStdDev(index: number): number
+  setRuleStdDev(index: number, stdDev: number): void
+  getRuleAboveAverage(index: number): boolean
+  setRuleAboveAverage(index: number, set: boolean): void
+  getRulePercent(index: number): boolean
+  setRulePercent(index: number, set: boolean): void
+  getRuleBottom(index: number): boolean
+  setRuleBottom(index: number, set: boolean): void
+  getRuleEqualAverage(index: number): boolean
+  setRuleEqualAverage(index: number, set: boolean): void
+
+  summary(): string
+}
+
+/**
+ * All <conditionalFormatting> entries of a worksheet.
+ */
+export interface XlsxConditionalFormats extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
+  getCount(): number
+  create(sqref: string): XlsxConditionalFormat
+  getByIndex(index: number): XlsxConditionalFormat
+  summary(): string
 }
 
 export interface XlsxCellFormat extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
@@ -97,7 +195,7 @@ export interface XlsxCellFormat extends HybridObject<{ ios: 'c++'; android: 'c++
   setItalic(): void
   setUnderline(style?: number): void
   setStrikeout(): void
-  
+
   // Alignment
   setAlign(align: number): void
   setVerticalAlign(align: number): void
@@ -105,16 +203,16 @@ export interface XlsxCellFormat extends HybridObject<{ ios: 'c++'; android: 'c++
   setRotation(angle: number): void
   setIndent(level: number): void
   setShrink(): void
-  
+
   // Number format
   setNumFormat(format: string): void
   setNumFormatIndex(index: number): void
-  
+
   // Colors/Pattern
   setBgColor(color: number): void
   setFgColor(color: number): void
   setPattern(pattern: number): void
-  
+
   // Borders
   setBorder(style: number): void
   setBorderColor(color: number): void
@@ -128,11 +226,11 @@ export interface XlsxCellFormat extends HybridObject<{ ios: 'c++'; android: 'c++
   setRightColor(color: number): void
   setDiagonal(style: number): void
   setDiagonalColor(color: number): void
-  
+
   // Protection
   setLocked(): void
   setUnlocked(): void
-  
+
   // Other
   setHyperlink(): void
   setFontOnly(): void
@@ -148,7 +246,8 @@ export interface XlsxCellFormat extends HybridObject<{ ios: 'c++'; android: 'c++
 }
 
 export interface NitroXlsx extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
-  createWorkbook(tempDir?: string): XlsxWorkbook
+  createWorkbook(): XlsxWorkbook
   openWorkbook(path: string): XlsxWorkbook
   openWorkbookFromBuffer(buffer: ArrayBuffer): XlsxWorkbook
-}
+  fromJSON(data: Record<string, Array<AnyMap>>): XlsxWorkbook
+}