@eredzik/calaminejs

A high-performance JavaScript/TypeScript library for reading Excel files (XLS/XLSX) and converting them to Parquet format. Built on the Rust calamine library using WebAssembly for optimal performance.

Features

• 📊 Read Excel files (XLS and XLSX formats)
• 🚀 High performance through WebAssembly
• 🔄 Convert sheets to Parquet format
• 🎯 Smart header row detection
• 📈 Progress tracking for large files
• 🌐 Works in Node.js and browsers
• 📝 Full TypeScript support
• 🔢 Preserves data types (strings, numbers, booleans, dates, etc.)

Installation

npm install @eredzik/calaminejs

Quick Start

Node.js

import { Workbook } from '@eredzik/calaminejs';
import { readFileSync } from 'fs';

// Read an Excel file
const buffer = readFileSync('data.xlsx');
const workbook = Workbook.from_bytes(new Uint8Array(buffer));

// Get sheet names
const sheetNames = workbook.sheet_names();
console.log('Sheets:', sheetNames);

// Access a sheet
const sheet = workbook.get_sheet(sheetNames[0]);
console.log(`Rows: ${sheet.row_count()}, Columns: ${sheet.col_count()}`);

// Access cell data
const rows = sheet.rows;
console.log('First row:', rows[0]);

Browser

import { Workbook } from '@eredzik/calaminejs/web';

// From file input
const file = document.querySelector('input[type="file"]').files[0];
const arrayBuffer = await file.arrayBuffer();
const workbook = Workbook.from_bytes(new Uint8Array(arrayBuffer));

// Process the workbook
const sheet = workbook.get_sheet_by_index(0);
console.log('Sheet name:', sheet.name);

API Reference

Workbook

The main class for working with Excel files.

Static Methods

Workbook.from_bytes(data: Uint8Array): Workbook

Load an Excel file from bytes. Automatically detects XLS or XLSX format.

const workbook = Workbook.from_bytes(new Uint8Array(buffer));

Workbook.from_bytes_with_progress(data: Uint8Array, callback?: Function, interval?: number): Workbook

Load an Excel file with progress tracking.

const workbook = Workbook.from_bytes_with_progress(
  new Uint8Array(buffer),
  (progress) => {
    console.log(`Processing sheet ${progress.sheetIndex + 1}/${progress.totalSheets}`);
    console.log(`Sheet: ${progress.sheetName}, Row: ${progress.currentRow}`);
  },
  100 // Report progress every 100 rows
);

Progress object properties:

• sheetIndex: number - Current sheet index (0-based)
• totalSheets: number - Total number of sheets
• sheetName: string - Name of current sheet
• currentRow: number - Current row being processed
• totalRows: number | null - Total rows (available when sheet is complete)

Instance Methods

sheet_names(): string[]

Get an array of all sheet names in the workbook.

const names = workbook.sheet_names();

get_sheet(name: string): Sheet | undefined

Get a sheet by name.

const sheet = workbook.get_sheet('Sheet1');

get_sheet_by_index(index: number): Sheet | undefined

Get a sheet by index (0-based).

const firstSheet = workbook.get_sheet_by_index(0);

sheet_count(): number

Get the total number of sheets.

const count = workbook.sheet_count();

Sheet

Represents a single worksheet in an Excel file.

Properties

name: string

The name of the sheet.

console.log(sheet.name); // "Sheet1"

rows: Array<Array<any>>

A 2D array of cell values. Values are converted to native JavaScript types:

• Strings → string
• Numbers → number
• Booleans → boolean
• Empty cells → null
• Dates → number (Excel date format)
• Errors → string

const rows = sheet.rows;
rows.forEach((row, rowIndex) => {
  row.forEach((cell, colIndex) => {
    console.log(`Cell [${rowIndex}, ${colIndex}]:`, cell);
  });
});

Methods

get_cell(row: number, col: number): CellValue | undefined

Get a specific cell with type information.

const cell = sheet.get_cell(0, 0);
if (cell.is_string) {
  console.log('String value:', cell.to_string_value());
}

row_count(): number

Get the number of rows in the sheet.

const rowCount = sheet.row_count();

col_count(): number

Get the maximum number of columns in the sheet.

const colCount = sheet.col_count();

infer_header_row(): HeaderInfo | undefined

Automatically detect which row contains the table header using heuristics:

• Headers typically contain string values in most columns
• Headers are followed by rows with data
• Headers have multiple non-empty cells
• Prioritizes rows in the first 20 rows

const headerInfo = sheet.infer_header_row();
if (headerInfo) {
  console.log('Header found at row:', headerInfo.row_index);
  console.log('Column names:', headerInfo.column_names);
}

to_parquet(): Uint8Array

Convert the sheet to Parquet format. Column types are automatically inferred:

• All booleans → Boolean column
• All integers → Int64 column
• All floats/numbers → Float64 column
• All dates → Datetime column (millisecond precision)
• Mixed or strings → String column

const parquetBytes = sheet.to_parquet();
// Save to file or process further

to_parquet_with_names(columnNames: string[]): Uint8Array

Convert the sheet to Parquet format with custom column names.

const columnNames = ['ID', 'Name', 'Age', 'Email'];
const parquetBytes = sheet.to_parquet_with_names(columnNames);

CellValue

Detailed cell information with type checking and conversion methods.

Type Checking Properties

• is_empty: boolean - Check if cell is empty
• is_string: boolean - Check if cell contains a string
• is_float: boolean - Check if cell contains a float
• is_int: boolean - Check if cell contains an integer
• is_bool: boolean - Check if cell contains a boolean
• is_error: boolean - Check if cell contains an error
• is_datetime: boolean - Check if cell contains a date/time
• is_duration: boolean - Check if cell contains a duration

Conversion Methods

to_string_value(): string | undefined

Convert cell to string representation.

const cell = sheet.get_cell(0, 0);
const str = cell.to_string_value();

to_float_value(): number | undefined

Convert cell to float (works for numbers, booleans, dates).

const num = cell.to_float_value();

to_int_value(): number | undefined

Convert cell to integer (works for integers, floats, booleans).

const int = cell.to_int_value();

to_bool_value(): boolean | undefined

Get boolean value (only works for boolean cells).

const bool = cell.to_bool_value();

HeaderInfo

Information about detected header row.

Properties

• row_index: number - The index of the header row (0-based)
• column_names: string[] - Array of column names extracted from the header

Examples

Reading and Processing Data

import { Workbook } from '@eredzik/calaminejs';
import { readFileSync } from 'fs';

const buffer = readFileSync('sales.xlsx');
const workbook = Workbook.from_bytes(new Uint8Array(buffer));
const sheet = workbook.get_sheet('Sales Data');

// Detect header
const headerInfo = sheet.infer_header_row();
if (headerInfo) {
  console.log('Columns:', headerInfo.column_names);
  
  // Process data rows (skip header)
  const dataRows = sheet.rows.slice(headerInfo.row_index + 1);
  dataRows.forEach(row => {
    console.log('Row data:', row);
  });
}

Converting to Parquet

import { Workbook } from '@eredzik/calaminejs';
import { writeFileSync, readFileSync } from 'fs';

const buffer = readFileSync('data.xlsx');
const workbook = Workbook.from_bytes(new Uint8Array(buffer));
const sheet = workbook.get_sheet_by_index(0);

// Option 1: Auto-generated column names
const parquet1 = sheet.to_parquet();
writeFileSync('output1.parquet', parquet1);

// Option 2: Custom column names
const headerInfo = sheet.infer_header_row();
if (headerInfo) {
  // Skip header row and convert data
  const dataSheet = {
    ...sheet,
    rows: sheet.rows.slice(headerInfo.row_index + 1)
  };
  const parquet2 = dataSheet.to_parquet_with_names(headerInfo.column_names);
  writeFileSync('output2.parquet', parquet2);
}

Working with Cell Types

const sheet = workbook.get_sheet_by_index(0);

for (let row = 0; row < sheet.row_count(); row++) {
  for (let col = 0; col < sheet.col_count(); col++) {
    const cell = sheet.get_cell(row, col);
    
    if (cell.is_string) {
      console.log(`String: ${cell.to_string_value()}`);
    } else if (cell.is_int) {
      console.log(`Integer: ${cell.to_int_value()}`);
    } else if (cell.is_float) {
      console.log(`Float: ${cell.to_float_value()}`);
    } else if (cell.is_bool) {
      console.log(`Boolean: ${cell.to_bool_value()}`);
    } else if (cell.is_datetime) {
      const excelDate = cell.to_float_value();
      // Convert Excel date to JavaScript Date
      const jsDate = new Date((excelDate - 25569) * 86400 * 1000);
      console.log(`Date: ${jsDate.toISOString()}`);
    }
  }
}

Progress Tracking for Large Files

import { Workbook } from '@eredzik/calaminejs';
import { readFileSync } from 'fs';

const buffer = readFileSync('large-file.xlsx');

console.log('Loading workbook...');
const workbook = Workbook.from_bytes_with_progress(
  new Uint8Array(buffer),
  (progress) => {
    const percent = ((progress.currentRow / (progress.totalRows || progress.currentRow)) * 100).toFixed(1);
    console.log(`[${progress.sheetName}] Processing: ${percent}%`);
  },
  500 // Report every 500 rows
);

console.log('Workbook loaded successfully!');

Browser vs Node.js

The package provides separate builds optimized for each environment:

// Node.js (default)
import { Workbook } from '@eredzik/calaminejs';
// or
import { Workbook } from '@eredzik/calaminejs/node';

// Browser
import { Workbook } from '@eredzik/calaminejs/web';

Performance Tips

1. Use progress callbacks for large files to provide user feedback and avoid blocking
2. Process sheets on-demand instead of loading all sheets at once
3. Use get_cell() for sparse data instead of accessing the full rows array
4. Infer header once and reuse the result instead of calling it multiple times
5. Convert to Parquet for efficient storage and further processing with data tools

Requirements

• Node.js >= 16.0.0 (for Node.js usage)
• Modern browser with WebAssembly support (for browser usage)

Supported File Formats

• XLSX - Excel 2007+ (.xlsx)
• XLS - Excel 97-2003 (.xls)

Supported Data Types

The library preserves Excel data types:

• Empty - Empty cells
• String - Text values
• Float - Floating-point numbers
• Int - Integer numbers
• Bool - Boolean values (TRUE/FALSE)
• Error - Excel error values (#N/A, #REF!, etc.)
• DateTime - Date and time values (stored as Excel serial numbers)
• Duration - Duration values

License

MIT

Repository

GitHub: https://github.com/eredzik/calaminejs

Issues

Report issues: https://github.com/eredzik/calaminejs/issues

Credits

Built on top of the excellent calamine Rust library and Polars for Parquet conversion.