@dukelib/sheets 0.1.4

package/index.d.ts

@@ -0,0 +1,850 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/** Statistics from calculating a workbook. */
+export declare class CalculationStats {
+  /** Number of formulas found */
+  get formulaCount(): number
+  /** Number of cells calculated */
+  get cellsCalculated(): number
+  /** Number of errors encountered */
+  get errors(): number
+  /** Number of circular references detected */
+  get circularReferences(): number
+  /** Number of volatile cells (e.g., NOW(), RAND()) */
+  get volatileCells(): number
+  /** Whether iterative calculation converged */
+  get converged(): boolean
+  /** Number of iterations performed */
+  get iterations(): number
+}
+
+/**
+ * Represents a cell value in a spreadsheet.
+ *
+ * Cell values can be one of several types:
+ * - Empty (null/undefined)
+ * - Number
+ * - Text (string)
+ * - Boolean
+ * - Error (like "#DIV/0!")
+ * - Formula cached results are exposed as regular cell values; formula text lives on Worksheet accessors
+ */
+export declare class CellValue {
+  /** Check if the cell is empty */
+  get isEmpty(): boolean
+  /** Check if the cell contains a number */
+  get isNumber(): boolean
+  /** Check if the cell contains text */
+  get isText(): boolean
+  /** Check if the cell contains a boolean */
+  get isBoolean(): boolean
+  /** Check if the cell contains an error */
+  get isError(): boolean
+  /** Get the value as a number, or null if not a number */
+  asNumber(): number | null
+  /** Get the value as text, or null if not text */
+  asText(): string | null
+  /** Get the value as a boolean, or null if not a boolean */
+  asBoolean(): boolean | null
+  /** Get the error string, or null if not an error */
+  asError(): string | null
+  /** Convert to a JavaScript native value (number, string, boolean, or null) */
+  toJs(): number | string | boolean | null
+  /** Get string representation of the cell value */
+  toString(): string
+}
+
+/**
+ * A workbook containing one or more worksheets.
+ *
+ * This is the main entry point for working with spreadsheet files.
+ *
+ * @example
+ * ```typescript
+ * const wb = new Workbook();
+ * const sheet = wb.getSheet(0);
+ * sheet.setCell("A1", 10);
+ * sheet.setCell("A2", 20);
+ * sheet.setFormula("A3", "=A1+A2");
+ * wb.calculate();
+ * console.log(sheet.getCalculatedValue("A3").asNumber()); // 30
+ * ```
+ */
+export declare class Workbook {
+  /** Whether the workbook has no worksheets. */
+  get isEmpty(): boolean
+  /** The index of the active (selected) worksheet. */
+  get activeSheet(): number
+  /** Get the index of a worksheet by name, or null if not found. */
+  sheetIndex(name: string): number | null
+  /** Workbook-level settings (date system, protection, etc.). */
+  get settings(): JsWorkbookSettings
+  /** Get all named ranges defined in the workbook. */
+  get namedRanges(): Array<JsNamedRange>
+  /** Create a new empty workbook with one worksheet */
+  constructor()
+  /**
+   * Open a workbook from a file
+   *
+   * Supported formats:
+   * - `.xlsx` (Excel 2007+)
+   * - `.xls` (Legacy Excel)
+   * - `.csv` (Comma-separated values)
+   *
+   * @param path - Path to the file
+   */
+  static open(path: string): Workbook
+  /**
+   * Load a workbook from XLSX bytes (Buffer/Uint8Array)
+   *
+   * @param data - The XLSX file content as a Buffer
+   */
+  static fromXlsxBytes(data: Buffer): Workbook
+  /**
+   * Load a workbook from a CSV string
+   *
+   * @param csv - The CSV content as a string
+   */
+  static fromCsvString(csv: string): Workbook
+  /**
+   * Load a workbook from bytes (Buffer/Uint8Array), auto-detecting the format.
+   *
+   * Supports XLSX and XLS formats. The format is detected from magic bytes.
+   *
+   * @param data - The file content as a Buffer
+   */
+  static fromBytes(data: Buffer): Workbook
+  /**
+   * Save the workbook to a file
+   *
+   * The format is determined by the file extension:
+   * - `.xlsx` for Excel format
+   * - `.csv` for CSV format (first sheet only)
+   *
+   * @param path - Path to save to
+   */
+  save(path: string): void
+  /** Save the workbook as a CSV string (first sheet only) */
+  saveCsvString(): string
+  /** Get the number of worksheets */
+  get sheetCount(): number
+  /** Get a list of all worksheet names */
+  get sheetNames(): Array<string>
+  /**
+   * Get a worksheet by index (number) or name (string)
+   *
+   * @param indexOrName - Either a zero-based index or a sheet name
+   * @throws Error if index out of range or name not found
+   */
+  getSheet(indexOrName: number | string): Worksheet
+  /**
+   * Add a new worksheet with the given name
+   *
+   * @param name - Name for the new worksheet
+   * @returns Index of the new worksheet
+   */
+  addSheet(name: string): number
+  /**
+   * Remove a worksheet by index
+   *
+   * @param index - Zero-based index of the worksheet to remove
+   */
+  removeSheet(index: number): void
+  /**
+   * Calculate all formulas in the workbook
+   *
+   * @returns Statistics about the calculation
+   */
+  calculate(): CalculationStats
+  /**
+   * Calculate with custom options for iterative calculation
+   *
+   * @param iterative - Enable iterative calculation for circular references
+   * @param maxIterations - Maximum iterations (default 100)
+   * @param maxChange - Convergence threshold (default 0.001)
+   * @param mode - Calculation mode: "exact", "multipass", or "auto" (default "auto")
+   * @param autoThreshold - Formula count threshold for auto mode (default 50000)
+   */
+  calculateWithOptions(iterative?: boolean | undefined | null, maxIterations?: number | undefined | null, maxChange?: number | undefined | null, mode?: string | undefined | null, autoThreshold?: number | undefined | null): CalculationStats
+  /**
+   * Define a named range
+   *
+   * @param name - Name for the range (e.g., "TaxRate")
+   * @param refersTo - What the name refers to (e.g., "Sheet1!$A$1" or "0.05")
+   */
+  defineName(name: string, refersTo: string): void
+  /**
+   * Get a named range definition
+   *
+   * @param name - Name to look up
+   * @returns The refers_to string, or null if not found
+   */
+  getNamedRange(name: string): string | null
+  /**
+   * Save the workbook to a file asynchronously (non-blocking).
+   *
+   * @param path - Path to save to
+   * @returns Promise<void>
+   */
+  saveAsync(path: string): Promise<unknown>
+  /**
+   * Calculate all formulas asynchronously (non-blocking).
+   *
+   * @returns Promise<CalculationStats>
+   */
+  calculateAsync(): Promise<unknown>
+  /**
+   * Calculate with custom options asynchronously (non-blocking).
+   *
+   * @param iterative - Enable iterative calculation for circular references
+   * @param maxIterations - Maximum iterations (default 100)
+   * @param maxChange - Convergence threshold (default 0.001)
+   * @returns Promise<CalculationStats>
+   */
+  calculateWithOptionsAsync(iterative?: boolean | undefined | null, maxIterations?: number | undefined | null, maxChange?: number | undefined | null, mode?: string | undefined | null, autoThreshold?: number | undefined | null): Promise<unknown>
+}
+
+/**
+ * A worksheet within a workbook.
+ *
+ * Worksheets contain cells organized in rows and columns. Each cell can
+ * contain a value (number, text, boolean) or a formula.
+ */
+export declare class Worksheet {
+  /** Sheet visibility: "visible", "hidden", or "veryHidden". */
+  get visibility(): string
+  /** Whether the worksheet is selected. */
+  get isSelected(): boolean
+  /** Zoom scale percentage, or null if default. */
+  get zoomScale(): number | null
+  /** Sheet tab color, or null if default. */
+  get tabColor(): JsColor | null
+  /** Whether the worksheet has no cells. */
+  get isEmpty(): boolean
+  /** Total number of cells with data. */
+  get cellCount(): number
+  /** Sheet view selections. */
+  get selections(): Array<JsSelection>
+  /** Get the resolved style for a cell by address (e.g., "A1"). */
+  getCellStyle(address: string): JsStyle | null
+  /** Get the resolved style for a cell by row/col (0-based). */
+  getCellStyleAt(row: number, col: number): JsStyle | null
+  /** Get the display-formatted value of a cell (e.g., "$1,234.56"). */
+  getFormattedValue(address: string): string
+  /** Get the display-formatted value by row/col (0-based). */
+  getFormattedValueAt(row: number, col: number): string
+  /** Default row height in points. */
+  get defaultRowHeight(): number
+  /** Default column width in character units. */
+  get defaultColumnWidth(): number
+  /** Whether a row is hidden. */
+  isRowHidden(row: number): boolean
+  /** Whether a column is hidden. */
+  isColumnHidden(col: number): boolean
+  /** Get the outline (grouping) level of a row. */
+  getRowOutlineLevel(row: number): number
+  /** Get the outline (grouping) level of a column. */
+  getColumnOutlineLevel(col: number): number
+  /** Whether a row group is collapsed. */
+  isRowCollapsed(row: number): boolean
+  /** Whether a column group is collapsed. */
+  isColumnCollapsed(col: number): boolean
+  /** Freeze pane settings, or null if no freeze panes. */
+  get freezePanes(): JsFreezePanes | null
+  /** Split pane settings, or null if no split panes. */
+  get splitPanes(): JsSplitPanes | null
+  /** Get the hyperlink on a cell, or null if none. */
+  getHyperlink(address: string): JsHyperlink | null
+  /** Get the hyperlink on a cell by row/col (0-based), or null if none. */
+  getHyperlinkAt(row: number, col: number): JsHyperlink | null
+  /** Number of hyperlinks in the worksheet. */
+  get hyperlinkCount(): number
+  /** Get all hyperlinks as an array of `{ address, hyperlink }`. */
+  get hyperlinks(): Array<JsHyperlinkEntry>
+  /** Get the comment on a cell by address, or null if none. */
+  getComment(address: string): JsComment | null
+  /** Get the comment on a cell by row/col (0-based), or null if none. */
+  getCommentAt(row: number, col: number): JsComment | null
+  /** Whether a cell has a comment (by address). */
+  hasComment(address: string): boolean
+  /** Whether a cell has a comment (by row/col). */
+  hasCommentAt(row: number, col: number): boolean
+  /** Number of comments in the worksheet. */
+  get commentCount(): number
+  /** Get all comments as an array of `{ row, col, comment }`. */
+  get comments(): Array<JsCommentEntry>
+  /** List of distinct comment authors. */
+  get commentAuthors(): Array<string>
+  /** Get all tables in the worksheet. */
+  get tables(): Array<JsTable>
+  /** Get a table by name, or null if not found. */
+  getTableByName(name: string): JsTable | null
+  /** Number of tables in the worksheet. */
+  get tableCount(): number
+  /** Get all data validation rules. */
+  get dataValidations(): Array<JsDataValidation>
+  /** Number of data validation rules. */
+  get dataValidationCount(): number
+  /** Get all conditional formatting rules. */
+  get conditionalFormats(): Array<JsConditionalFormatRule>
+  /** Number of conditional formatting rules. */
+  get conditionalFormatCount(): number
+  /** The auto-filter on this worksheet, or null if none. */
+  get autoFilter(): JsAutoFilter | null
+  /** Sheet protection settings, or null if unprotected. */
+  get protection(): JsSheetProtection | null
+  /** Page setup / print settings. */
+  get pageSetup(): JsPageSetup
+  /** Print area range string, or null if not set. */
+  get printArea(): string | null
+  /** Repeat rows at top of each printed page as `[startRow, endRow]`, or null. */
+  get repeatRows(): Array<number> | null
+  /** Repeat columns at left of each printed page as `[startCol, endCol]`, or null. */
+  get repeatCols(): Array<number> | null
+  /** Manual row page breaks. */
+  get rowBreaks(): Array<JsPageBreak>
+  /** Manual column page breaks. */
+  get colBreaks(): Array<JsPageBreak>
+  /** Get the formula text of a cell by row/col (0-based), or null if not a formula cell. */
+  getFormulaAt(row: number, col: number): string | null
+  /** Get the number of formula cells in this worksheet. */
+  get formulaCount(): number
+  /** Get all formula cells as an array of `{ row, col, formula }`. */
+  get formulaCells(): Array<JsFormulaCell>
+  /** Whether a cell is a spill target (receives a spilled value from a dynamic array formula). */
+  isSpillTarget(row: number, col: number): boolean
+  /** Whether a cell is the source of a spill (has a dynamic array formula with results). */
+  isSpillSource(row: number, col: number): boolean
+  /** Get the source cell of a spill target, or null if not a spill target. */
+  getSpillSource(row: number, col: number): JsSpillSource | null
+  /** Whether the worksheet uses the 1904 date system. */
+  get date1904(): boolean
+  /** Get all merged regions as structured objects with start/end row/col. */
+  get mergedRegions(): Array<JsMergedRegion>
+  /**
+   * Get the merge span for a cell if it is the top-left origin of a merged region.
+   *
+   * Returns `{ rowSpan, colSpan }` if the cell is a merge origin, or null otherwise.
+   */
+  getMergeSpan(row: number, col: number): JsMergeSpan | null
+  /** Whether a cell is a non-origin member of a merged region (should be skipped when rendering). */
+  isMergedSecondary(row: number, col: number): boolean
+  /** Get the worksheet name */
+  get name(): string
+  /**
+   * Set a cell value by address (e.g., "A1", "B2")
+   *
+   * The value can be:
+   * - `null` or `undefined` (clears the cell)
+   * - `number` (numeric value)
+   * - `string` (text)
+   * - `boolean`
+   */
+  setCell(address: string, value?: number | string | boolean | undefined | null): void
+  /**
+   * Set a formula in a cell
+   *
+   * @param address - Cell address (e.g., "A1")
+   * @param formula - Formula string (e.g., "=SUM(A1:A10)")
+   */
+  setFormula(address: string, formula: string): void
+  /** Get the raw cell value (not calculated) */
+  getCell(address: string): CellValue
+  /** Get the raw cell value by row/col (0-based). */
+  getCellAt(row: number, col: number): CellValue
+  /**
+   * Get the calculated value of a cell
+   *
+   * For formulas, this returns the computed result.
+   * For regular values, returns the value itself.
+   */
+  getCalculatedValue(address: string): CellValue
+  /** Get the calculated value of a cell by row/col (0-based). */
+  getCalculatedValueAt(row: number, col: number): CellValue
+  /**
+   * Get the used range as `{ minRow, minCol, maxRow, maxCol }` or null
+   * if the worksheet is empty.
+   */
+  get usedRange(): UsedRange | null
+  /** Set the height of a row in points */
+  setRowHeight(row: number, height: number): void
+  /** Set the width of a column in character units */
+  setColumnWidth(col: number, width: number): void
+  /** Get the row height in points, or null if not explicitly set */
+  getRowHeight(row: number): number | null
+  /** Get the column width in character units, or null if not explicitly set */
+  getColumnWidth(col: number): number | null
+  /** Merge cells in a range (e.g., "A1:C3") */
+  mergeCells(rangeStr: string): void
+  /** Unmerge cells in a range */
+  unmergeCells(rangeStr: string): boolean
+}
+
+/**
+ * Load a workbook from XLSX bytes asynchronously (non-blocking).
+ *
+ * @param data - The XLSX file content as a Buffer
+ * @returns Promise<Workbook>
+ */
+export declare function fromXlsxBytesAsync(data: Buffer): Promise<unknown>
+
+/** Text alignment settings. */
+export interface JsAlignment {
+  horizontal: string
+  vertical: string
+  wrapText: boolean
+  shrinkToFit: boolean
+  indent: number
+  /** Rotation in degrees (-90 to 90, or 255 for vertical text). */
+  rotation: number
+  readingOrder: string
+}
+
+/** A standalone auto-filter on a worksheet. */
+export interface JsAutoFilter {
+  /** Range string the filter covers (e.g., `"A1:D10"`). */
+  range: string
+  filterColumns: Array<JsFilterColumn>
+}
+
+/** A single border edge (line style + color). */
+export interface JsBorderEdge {
+  /**
+   * One of: `"none"`, `"thin"`, `"medium"`, `"thick"`, `"dashed"`, `"dotted"`,
+   * `"double"`, `"hair"`, `"mediumDashed"`, `"dashDot"`, `"mediumDashDot"`,
+   * `"dashDotDot"`, `"mediumDashDotDot"`, `"slantDashDot"`.
+   */
+  style: string
+  color: JsColor
+}
+
+/** Cell border style. */
+export interface JsBorderStyle {
+  left?: JsBorderEdge
+  right?: JsBorderEdge
+  top?: JsBorderEdge
+  bottom?: JsBorderEdge
+  diagonal?: JsBorderEdge
+  /** One of: `"none"`, `"down"`, `"up"`, `"both"`. */
+  diagonalDirection: string
+}
+
+/** Cell protection settings. */
+export interface JsCellProtection {
+  locked: boolean
+  hidden: boolean
+}
+
+/**
+ * Color representation. The `colorType` field indicates the variant:
+ * `"auto"`, `"rgb"`, `"argb"`, `"theme"`, or `"indexed"`.
+ * The `hex` field always contains the resolved 6- or 8-char hex string.
+ */
+export interface JsColor {
+  colorType: string
+  /** Resolved hex string (6 or 8 chars, no `#` prefix). */
+  hex: string
+  r?: number
+  g?: number
+  b?: number
+  a?: number
+  /** Theme color index (0–9), present when `colorType === "theme"`. */
+  themeIndex?: number
+  /** Tint percentage (-100 to 100), present when `colorType === "theme"`. */
+  tint?: number
+  /** Palette index, present when `colorType === "indexed"`. */
+  paletteIndex?: number
+}
+
+/** A cell comment/note. */
+export interface JsComment {
+  author: string
+  text: string
+  visible: boolean
+}
+
+/** A comment with its cell address. */
+export interface JsCommentEntry {
+  row: number
+  col: number
+  comment: JsComment
+}
+
+/** A conditional formatting rule. */
+export interface JsConditionalFormatRule {
+  /**
+   * The type of rule: `"cellIs"`, `"expression"`, `"colorScale"`, `"dataBar"`,
+   * `"iconSet"`, `"top10"`, `"aboveAverage"`, `"containsText"`, `"beginsWith"`,
+   * `"endsWith"`, `"duplicateValues"`, `"uniqueValues"`, `"containsBlanks"`,
+   * `"notContainsBlanks"`, `"containsErrors"`, `"notContainsErrors"`, `"timePeriod"`.
+   */
+  ruleType: string
+  /** Ranges this rule applies to (as range strings). */
+  ranges: Array<string>
+  /** Lower number = higher priority. */
+  priority: number
+  stopIfTrue: boolean
+  /** Operator (present for `cellIs` rules). */
+  operator?: string
+  /** Formula/value (present for `cellIs`, `expression` rules). */
+  formula1?: string
+  formula2?: string
+  /** Text value (present for `containsText`, `beginsWith`, `endsWith`). */
+  text?: string
+  /** Rank for top/bottom N rules. */
+  rank?: number
+  /** Whether the top/bottom N rule uses percentages. */
+  percent?: boolean
+  /** Whether it's a "bottom N" rule (vs top N). */
+  bottom?: boolean
+}
+
+/** A data validation rule. */
+export interface JsDataValidation {
+  /**
+   * The type of validation: `"none"`, `"whole"`, `"decimal"`, `"list"`,
+   * `"date"`, `"time"`, `"textLength"`, `"custom"`.
+   */
+  validationType: string
+  /** Ranges this validation applies to (as range strings). */
+  ranges: Array<string>
+  allowBlank: boolean
+  showDropdown: boolean
+  showInputMessage: boolean
+  inputTitle?: string
+  inputMessage?: string
+  showErrorAlert: boolean
+  /** `"stop"`, `"warning"`, or `"information"`. */
+  errorStyle: string
+  errorTitle?: string
+  errorMessage?: string
+  /**
+   * Operator (present for numeric/date/time/textLength validations):
+   * `"between"`, `"notBetween"`, `"equal"`, `"notEqual"`, `"greaterThan"`,
+   * `"lessThan"`, `"greaterThanOrEqual"`, `"lessThanOrEqual"`.
+   */
+  operator?: string
+  /** First value/formula (present for most validation types). */
+  value1?: string
+  /** Second value/formula (present for `between`/`notBetween`). */
+  value2?: string
+  /** List source string (present when `validationType === "list"`). */
+  listSource?: string
+  /** Custom formula (present when `validationType === "custom"`). */
+  formula?: string
+}
+
+/**
+ * Fill/background style. The `fillType` field indicates the variant:
+ * `"none"`, `"solid"`, `"pattern"`, or `"gradient"`.
+ */
+export interface JsFillStyle {
+  fillType: string
+  /** Solid fill color (present when `fillType === "solid"`). */
+  color?: JsColor
+  /** Pattern type string (present when `fillType === "pattern"`). */
+  pattern?: string
+  /** Pattern foreground color. */
+  foreground?: JsColor
+  /** Pattern background color. */
+  background?: JsColor
+  /** Gradient type: `"linear"` or `"path"` (present when `fillType === "gradient"`). */
+  gradientType?: string
+  /** Gradient angle in degrees. */
+  angle?: number
+  /** Gradient color stops. */
+  stops?: Array<JsGradientStop>
+}
+
+/** A filter on a single column. */
+export interface JsFilterColumn {
+  colId: number
+  hiddenButton: boolean
+  showButton: boolean
+  /** The type of filter: `"values"`, `"custom"`, `"top10"`, `"dynamic"`, or `"color"`. */
+  filterType: string
+  /** Values for a discrete value filter (present when `filterType === "values"`). */
+  values?: Array<string>
+  /** Include blanks (present when `filterType === "values"`). */
+  blank?: boolean
+}
+
+/** Font style settings. */
+export interface JsFontStyle {
+  name: string
+  size: number
+  bold: boolean
+  italic: boolean
+  /** One of: `"none"`, `"single"`, `"double"`, `"singleAccounting"`, `"doubleAccounting"`. */
+  underline: string
+  strikethrough: boolean
+  color: JsColor
+  /** One of: `"baseline"`, `"superscript"`, `"subscript"`. */
+  verticalAlign: string
+  family?: number
+  charset?: number
+  scheme?: string
+}
+
+/** A formula cell with address. */
+export interface JsFormulaCell {
+  row: number
+  col: number
+  formula: string
+}
+
+/** Freeze pane settings. */
+export interface JsFreezePanes {
+  /** First unfrozen row. */
+  row: number
+  /** First unfrozen column. */
+  col: number
+}
+
+/** Gradient color stop. */
+export interface JsGradientStop {
+  position: number
+  color: JsColor
+}
+
+/** A hyperlink attached to a cell. */
+export interface JsHyperlink {
+  /** Target URL (external) or cell reference (internal). */
+  target: string
+  /** Display text (shown in cell; `null` means cell value is used). */
+  display?: string
+  /** Tooltip shown on hover. */
+  tooltip?: string
+  /** Location within target (e.g., sheet reference for internal links). */
+  location?: string
+}
+
+/** A hyperlink with its cell address. */
+export interface JsHyperlinkEntry {
+  address: string
+  hyperlink: JsHyperlink
+}
+
+/** A merged cell region with structured coordinates. */
+export interface JsMergedRegion {
+  startRow: number
+  startCol: number
+  endRow: number
+  endCol: number
+  /** The range as an A1-style string (e.g., "A1:C3"). */
+  range: string
+}
+
+/** The row/column span of a merged region's origin cell. */
+export interface JsMergeSpan {
+  rowSpan: number
+  colSpan: number
+}
+
+/** A named range definition. */
+export interface JsNamedRange {
+  name: string
+  /** `"workbook"` or `"sheet"`. */
+  scope: string
+  /** Sheet index when `scope === "sheet"`. */
+  sheetIndex?: number
+  /** The formula/reference the name refers to. */
+  refersTo: string
+  comment?: string
+  hidden: boolean
+}
+
+/**
+ * Number format. The `formatType` field indicates the variant:
+ * `"general"`, `"builtin"`, or `"custom"`.
+ */
+export interface JsNumberFormat {
+  formatType: string
+  /** Built-in format ID (present when `formatType === "builtin"`). */
+  id?: number
+  /** The resolved format string (always present). */
+  formatString: string
+  /** Whether this format represents a date/time. */
+  isDateFormat: boolean
+}
+
+/** A manual page break (row or column). */
+export interface JsPageBreak {
+  /** Row index (for row breaks) or column index (for col breaks), 0-based. */
+  id: number
+  min: number
+  max: number
+  /** Whether this is a manual break. */
+  manual: boolean
+}
+
+/** Page setup / print settings. */
+export interface JsPageSetup {
+  /** Paper size (1 = Letter, 9 = A4, etc.). */
+  paperSize: number
+  /** `"portrait"` or `"landscape"`. */
+  orientation: string
+  /** Scale percentage (10–400). */
+  scale: number
+  fitToWidth?: number
+  fitToHeight?: number
+  topMargin: number
+  bottomMargin: number
+  leftMargin: number
+  rightMargin: number
+  headerMargin: number
+  footerMargin: number
+  printGridlines: boolean
+  printHeadings: boolean
+  oddHeader?: string
+  oddFooter?: string
+  evenHeader?: string
+  evenFooter?: string
+  firstHeader?: string
+  firstFooter?: string
+  differentOddEven: boolean
+  differentFirst: boolean
+  scaleWithDoc: boolean
+  alignWithMargins: boolean
+}
+
+/** A single run of rich text. */
+export interface JsRichTextRun {
+  text: string
+  font?: JsRunFont
+}
+
+/** Font properties for a rich text run (all fields optional — unset inherits cell style). */
+export interface JsRunFont {
+  bold?: boolean
+  italic?: boolean
+  size?: number
+  color?: JsColor
+  name?: string
+  underline?: string
+  strikethrough?: boolean
+  verticalAlign?: string
+}
+
+/** A selection within a sheet view. */
+export interface JsSelection {
+  pane?: string
+  activeCell?: string
+  sqref?: string
+}
+
+/** Sheet protection settings. */
+export interface JsSheetProtection {
+  protected: boolean
+  selectLockedCells: boolean
+  selectUnlockedCells: boolean
+  formatCells: boolean
+  formatColumns: boolean
+  formatRows: boolean
+  insertColumns: boolean
+  insertRows: boolean
+  insertHyperlinks: boolean
+  deleteColumns: boolean
+  deleteRows: boolean
+  sort: boolean
+  autoFilter: boolean
+  pivotTables: boolean
+}
+
+/** A cell with address and value. */
+export interface JsSpillSource {
+  row: number
+  col: number
+}
+
+/** Split pane settings. */
+export interface JsSplitPanes {
+  xSplit: number
+  ySplit: number
+  topLeftRow?: number
+  topLeftCol?: number
+  activePane?: string
+}
+
+/**
+ * Complete cell style including font, fill, border, alignment, number format,
+ * and protection settings.
+ */
+export interface JsStyle {
+  font: JsFontStyle
+  fill: JsFillStyle
+  border: JsBorderStyle
+  alignment: JsAlignment
+  numberFormat: JsNumberFormat
+  protection: JsCellProtection
+}
+
+/** An Excel table (ListObject). */
+export interface JsTable {
+  id: number
+  name: string
+  displayName: string
+  /** Range string (e.g., `"A1:D10"`). */
+  reference: string
+  columns: Array<JsTableColumn>
+  styleInfo?: JsTableStyleInfo
+  headerRowCount: number
+  totalsRowCount: number
+  totalsRowShown: boolean
+}
+
+/** A column within a table. */
+export interface JsTableColumn {
+  id: number
+  name: string
+  /**
+   * One of: `"average"`, `"count"`, `"countNums"`, `"max"`, `"min"`,
+   * `"sum"`, `"stdDev"`, `"var"`, `"custom"`, `"none"`, or `null`.
+   */
+  totalsRowFunction?: string
+  totalsRowFormula?: string
+  totalsRowLabel?: string
+  calculatedColumnFormula?: string
+}
+
+/** Table style configuration. */
+export interface JsTableStyleInfo {
+  name?: string
+  showFirstColumn: boolean
+  showLastColumn: boolean
+  showRowStripes: boolean
+  showColumnStripes: boolean
+}
+
+/** Workbook-level settings. */
+export interface JsWorkbookSettings {
+  /** Whether the 1904 date system is used (macOS default). */
+  date1904: boolean
+  /** Whether the workbook structure is protected. */
+  protected: boolean
+  /** Calculate formulas on open. */
+  calcOnOpen: boolean
+  theme?: string
+}
+
+/**
+ * Open a workbook from a file asynchronously (non-blocking).
+ *
+ * Runs file I/O and parsing on the libuv thread pool so the
+ * Node.js event loop is not blocked.
+ *
+ * @param path - Path to the file
+ * @returns Promise<Workbook>
+ */
+export declare function openAsync(path: string): Promise<unknown>
+
+/**
+ * The used range of a worksheet, describing the bounding box of all cells
+ * that contain data.
+ */
+export interface UsedRange {
+  minRow: number
+  minCol: number
+  maxRow: number
+  maxCol: number
+}