@aspect/nup-xlsx-core

Lightweight, Edge-compatible Excel (.xlsx) and CSV parser with full style resolution including theme colors.

Features

• Edge-Compatible: Zero Node.js dependencies, works in Cloudflare Workers, Vercel Edge, and browsers
• Small Bundle: ~6KB gzipped (uses only fflate for ZIP handling)
• Full Style Resolution: Theme colors, indexed colors, and tint calculations
• TypeScript: 100% TypeScript with full type definitions
• Tree-shakeable: Named exports with no side effects

Installation

npm install @aspect/nup-xlsx-core

Usage

Parse XLSX

import { parseXlsx } from '@aspect/nup-xlsx-core';

const response = await fetch('spreadsheet.xlsx');
const buffer = await response.arrayBuffer();
const workbook = await parseXlsx(buffer);

for (const sheet of workbook.sheets) {
  console.log(`Sheet: ${sheet.name}`);
  for (const row of sheet.cells) {
    for (const cell of row) {
      console.log(cell.value, cell.style);
    }
  }
}

Parse CSV

import { parseCsv } from '@aspect/nup-xlsx-core';

const csvText = 'Name,Age\nAlice,30\nBob,25';
const sheet = parseCsv(csvText);

console.log(sheet.cells[0][0].value); // "Name"
console.log(sheet.cells[1][1].value); // 30

Color Resolution

import { resolveColor, getDefaultTheme } from '@aspect/nup-xlsx-core';

const theme = getDefaultTheme();

// Resolve theme color
const color = resolveColor({ theme: 4, tint: 0.5 }, theme);
console.log(color); // "#A7BFDD" (lightened accent1)

Cell Reference Utilities

import { cellRefToCoords, coordsToCellRef } from '@aspect/nup-xlsx-core';

cellRefToCoords('B4'); // { row: 3, col: 1 }
coordsToCellRef({ row: 3, col: 1 }); // "B4"

API

Main Functions

• parseXlsx(data: ArrayBuffer | Uint8Array): Promise<NupWorkbook> - Parse XLSX file
• parseCsv(text: string, options?: CsvOptions): NupWorksheet - Parse CSV text

Color Functions

• resolveColor(color: ColorSpec, theme: NupTheme): string - Resolve any color to #RRGGBB
• getDefaultTheme(): NupTheme - Get default Office theme
• applyTint(hexColor: string, tint: number): string - Apply tint to a color
• getIndexedColor(index: number): string - Get indexed palette color

Utility Functions

• cellRefToCoords(ref: string): CellRef - Convert "B4" to {row: 3, col: 1}
• coordsToCellRef(coords: CellRef): string - Convert {row: 3, col: 1} to "B4"

Types

interface NupWorkbook {
  name: string;
  sheets: NupWorksheet[];
  theme: NupTheme;
  metadata?: { creator?: string; created?: Date; modified?: Date };
}

interface NupWorksheet {
  name: string;
  cells: NupCell[][];
  columns: ColumnInfo[];
  rows: RowInfo[];
  merges: MergeRange[];
  frozen?: FreezePane;
}

interface NupCell {
  value: string | number | boolean | Date | null;
  formula?: string;
  style: NupCellStyle;
  type: 'string' | 'number' | 'boolean' | 'date' | 'formula' | 'empty';
}

interface NupCellStyle {
  font?: FontStyle;
  fill?: FillStyle;
  border?: BorderStyle;
  alignment?: AlignmentStyle;
  numberFormat?: string;
}

License

MIT