@titenq/xlsx2json

Node.js library for converting XLSX, XLS, XLSM, XLSB, ODS, and CSV files to JSON using the WebAssembly binding generated by the Rust project https://github.com/titenq/xlsx2jsonwasm.

Installation

npm install @titenq/xlsx2json

Usage

Convert a file

import { writeFile } from "node:fs/promises";
import { convertFile } from "@titenq/xlsx2json";

const data = await convertFile("./spreadsheet.xlsx");

// save JSON to disk
await writeFile("./spreadsheet.json", JSON.stringify(data, null, 2));

// or send it to an API
await fetch("https://api.com/import", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

Convert bytes

import { readFile } from "node:fs/promises";
import { convertBytes } from "@titenq/xlsx2json";

const fileBytes = await readFile("./spreadsheet.xlsx");

const data = convertBytes(fileBytes, {
  fileName: "spreadsheet.xlsx",
});

API

convertFile(filePath, options)

Use this when you have the file path on disk and want the library to read everything for you.

This is the simplest path for most users.

convertBytes(bytes, options)

Use this when you already have the bytes in memory, for example:

• upload received by an API
• file read from S3
• buffer coming from another service
• manual reading with fs.readFile

maxSizeBytes

Both convertFile and convertBytes accept an options object as the second parameter, with the maxSizeBytes property:

{
  maxSizeBytes?: number;
}

Example:

const data = await convertFile("./report.xlsx", {
  maxSizeBytes: 10 * 1024 * 1024,
});

TypeScript

In most cases, you do not need to use any types manually.

But the public types are available if you want to:

• type wrapper functions
• type options
• type the return value in more explicit TypeScript code

Example:

import {
  convertBytes,
  type ConvertBytesOptions,
  type SpreadsheetJson,
} from "@titenq/xlsx2json";

const options: ConvertBytesOptions = {
  fileName: "spreadsheet.xlsx",
};

const data: SpreadsheetJson = convertBytes(fileBytes, options);

Return Value

The return value is already parsed, not a JSON string.

• spreadsheet with one sheet: array of objects
• spreadsheet with multiple sheets: object keyed by sheet name
• CSV: array of objects

API Design

The goal of this package is to hide the wasm details.

The user does not need to:

• import the Rust-generated binding
• deal with manual initialization
• call xlsxToJson directly
• call JSON.parse manually

Benchmark

The numbers below compare total time to generate JSON across the same spreadsheet inputs.

Dataset A: 1000 rows x 10 columns

| Library | Total Time | xlsx2json-wasm Advantage | | --- | ---: | ---: | | xlsx2json-wasm | 0.046s | baseline | | xlsx (SheetJS) | 0.097s | 52.6% faster | | node-xlsx | 0.071s | 35.2% faster | | convert-excel-to-json | 0.108s | 57.4% faster |

Dataset B: 212835 rows x 37 columns

| Library | Total Time | xlsx2json-wasm Advantage | | --- | ---: | ---: | | xlsx2json-wasm | 13.603s | baseline | | xlsx (SheetJS) | 24.024s | 43.4% faster | | node-xlsx | 41.610s | 67.3% faster | | convert-excel-to-json | 52.531s | 74.1% faster |

License

Distributed under GPL-3.0. See LICENSE.txt.

⭐ Stargazers

This repository has no stargazers yet. Be the first!