SheetKit

A minimalistic spreadsheet library with zero dependencies. One function to read. One function to write. It just works.

Read returns array of objects by default (JSON-like format), with optional 2D array support.

Features

✅ Zero Dependencies - Only Node.js standard library
✅ Minimalistic API - sheet.read() and sheet.write()
✅ Auto-Detection - Format detected from file extension or content
✅ CSV/TSV/XLSX - Full read/write support
✅ Buffer Support - Read from Buffer, write to Buffer
✅ TypeScript Support - Full type definitions included
✅ Pure JavaScript - No external libraries

Installation

npm install sheetkit

Or using yarn:

yarn add sheetkit

Zero dependencies - Only uses Node.js standard library!

Quick Start

ES Modules

import sheet from "sheetkit";

// Read any format (returns array of objects by default)
const result = await sheet.read("input.xlsx");
console.log(result.data); // Array of objects: [{Name: "Alice", Age: 30}, ...]
console.log(result.meta.format); // "xlsx"

CommonJS

const sheet = require("sheetkit");

// Read any format (returns array of objects by default)
const result = await sheet.read("input.xlsx");
console.log(result.data); // Array of objects: [{Name: "Alice", Age: 30}, ...]
console.log(result.meta.format); // "xlsx"

// Write any format - supports 2D arrays or array of objects await sheet.write("output.csv", result.data); await sheet.write("output.xlsx", result.data);

// Array of objects automatically converts to 2D array with headers await sheet.write("sample.xlsx", [ { name: "Alice", age: 30 }, { name: "Bob", age: 25 } ]);

// Read from Buffer const buffer = await readFile("input.xlsx"); const result = await sheet.read(buffer);

// Write to Buffer (returns XLSX by default) const xlsxBuffer = await sheet.write(data); const csvBuffer = await sheet.write(data, { format: "csv" });

## API

### `sheet.read(pathOrBuffer, options?)`

Reads a spreadsheet file or Buffer. Format is auto-detected from file extension or buffer content.

**Parameters:**
- `pathOrBuffer` (string|Buffer): File path (`.csv`, `.tsv`, or `.xlsx`) or Buffer containing file data
- `options` (object, optional):
  - `sheet` (number|string): Sheet index or name for XLSX (default: 0)
  - `sheets` (boolean): Read all sheets for XLSX (default: false)
  - `delimiter` (string): Override delimiter for CSV/TSV
  - `headers` (boolean): Treat first row as headers (default: false for CSV/TSV)
  - `atoa` (boolean): Return 2D array instead of array of objects (default: false, returns array of objects)
  - `dateFormat` (string): "excel", "iso", or SSF format string (e.g., "yyyy-mm-dd", default: "excel" for XLSX, "iso" for CSV/TSV)

**Returns:**
```javascript
// Single sheet (default: array of objects)
{
  data: Array<Object>,  // Array of objects: [{Name: "Alice", Age: 30}, ...]
  meta: {
    format: "csv" | "tsv" | "xlsx",
    sheetName?: string  // For XLSX files
  }
}

// Single sheet (with atoa: true - 2D array)
{
  data: any[][],  // 2D array: [["Name", "Age"], ["Alice", 30], ...]
  meta: {
    format: "csv" | "tsv" | "xlsx",
    sheetName?: string
  }
}

// Multiple sheets (XLSX with sheets: true)
{
  sheets: [
    { name: "Sheet1", data: Array<Object> | any[][] },
    { name: "Sheet2", data: Array<Object> | any[][] }
  ],
  meta: {
    format: "xlsx"
  }
}

Examples:

// Read from file (default: array of objects)
const result = await sheet.read("data.xlsx");
// result.data = [{Name: "Alice", Age: 30}, {Name: "Bob", Age: 25}]
// result.meta = { format: "xlsx", sheetName: "Sheet1" }

// Read as 2D array (with atoa: true)
const result2 = await sheet.read("data.xlsx", { atoa: true });
// result2.data = [["Name", "Age"], ["Alice", 30], ["Bob", 25]]

// Read from Buffer
const buffer = await readFile("data.xlsx");
const result3 = await sheet.read(buffer);

sheet.write(pathOrData, dataOrOptions?, options?)

Writes a spreadsheet file or returns a Buffer. Format is auto-detected from file extension, or defaults to XLSX when writing to buffer.

Parameters:

• pathOrData (string|any[][]|Array):
  • File path (string): Output file path (.csv, .tsv, or .xlsx) - writes to file
  • Data (array): 2D array or array of objects - returns Buffer (XLSX by default)
• dataOrOptions (any[][]|Array|Object, optional):
  • If first arg is path: Data (2D array or array of objects)
  • If first arg is data: Options object
• options (object, optional): Only used when first arg is path
  • format (string): Format when writing to buffer: 'csv', 'tsv', or 'xlsx' (default: 'xlsx' when path omitted)
  • sheet (string): Sheet name for XLSX (default: "Sheet1")
  • delimiter (string): Override delimiter for CSV/TSV
  • dateFormat (string): "excel", "iso", or SSF format string (e.g., "yyyy-mm-dd", "mm/dd/yyyy", default: "excel" for XLSX, "iso" for CSV/TSV)

Returns:

• Promise<void> when writing to file
• Promise<Buffer> when writing to buffer (path omitted)

Data Formats:

• 2D array: [["Name", "Age"], ["Alice", 30], ["Bob", 25]]
• Array of objects: [{name: "Alice", age: 30}, {name: "Bob", age: 25}] (automatically converts to 2D array with headers)

Examples:

// Write to file (2D array)
await sheet.write("output.xlsx", [
  ["Name", "Age", "City"],
  ["Alice", 30, "New York"],
  ["Bob", 25, "San Francisco"]
]);

// Write to file (array of objects - automatically adds headers)
await sheet.write("output.csv", [
  { name: "Alice", age: 30 },
  { name: "Bob", age: 25 }
]);
// Creates: name,age\nAlice,30\nBob,25

// Write to Buffer (defaults to XLSX)
const xlsxBuffer = await sheet.write([
  ["Name", "Age"],
  ["Alice", 30],
  ["Bob", 25]
]);

// Write to Buffer with specific format
const csvBuffer = await sheet.write([
  ["Name", "Age"],
  ["Alice", 30],
  ["Bob", 25]
], { format: "csv" });

// Round-trip through buffers
const buffer1 = await sheet.write(data, { format: "csv" });
const result = await sheet.read(buffer1);
const buffer2 = await sheet.write(result.data, { format: "csv" });

Supported Formats

CSV / TSV

• ✅ Read and write
• ✅ UTF-8 encoding
• ✅ RFC-4180 compliant
• ✅ Quoted fields, escaped quotes, newlines

XLSX

• ✅ Read and write
• ✅ Single worksheet (default)
• ✅ String, number, boolean, date, null cells
• ✅ Excel 1900 date system
• ❌ Multiple worksheets (not supported)
• ❌ Formulas, charts, images (not supported)

Examples

Basic Usage

import sheet from "sheetkit";

// Read CSV (returns array of objects by default)
const csv = await sheet.read("data.csv");
// csv.data = [{Name: "Alice", Age: 30}, {Name: "Bob", Age: 25}]

// Write XLSX
await sheet.write("output.xlsx", csv.data);

// Round-trip
const xlsx = await sheet.read("output.xlsx");
await sheet.write("output2.csv", xlsx.data);

// Get 2D array instead of objects
const data2D = await sheet.read("data.csv", { atoa: true });
// data2D.data = [["Name", "Age"], ["Alice", 30], ["Bob", 25]]

With Different Data Types

await sheet.write("data.xlsx", [
  ["Product", "Price", "In Stock", "Release Date"],
  ["Widget", 19.99, true, new Date("2023-01-15")],
  ["Gadget", 29.99, false, new Date("2023-06-20")]
]);

Buffer Support

import { readFile } from "fs/promises";

// Read from Buffer
const fileBuffer = await readFile("data.xlsx");
const result = await sheet.read(fileBuffer);

// Write to Buffer (XLSX by default)
const buffer = await sheet.write([
  ["Name", "Age"],
  ["Alice", 30],
  ["Bob", 25]
]);

// Write to Buffer with specific format
const csvBuffer = await sheet.write(data, { format: "csv" });
const xlsxBuffer = await sheet.write(data, { format: "xlsx" });

Array of Objects (Default Return Format)

// By default, read() returns array of objects (JSON-like format)
const result = await sheet.read("data.csv");
// result.data = [
//   { Name: "Alice", Age: 30, City: "New York" },
//   { Name: "Bob", Age: 25, City: "San Francisco" }
// ]

// Get 2D array instead (with atoa: true)
const result2 = await sheet.read("data.csv", { atoa: true });
// result2.data = [
//   ["Name", "Age", "City"],
//   ["Alice", 30, "New York"],
//   ["Bob", 25, "San Francisco"]
// ]

Date Formatting

// Custom date formats using SSF format strings
await sheet.write("data.csv", [
  ["Name", "Date"],
  ["Alice", new Date("2023-06-15")]
], { dateFormat: "yyyy-mm-dd" });
// Output: Name,Date\nAlice,2023-06-15

await sheet.write("data.csv", [
  ["Name", "Date"],
  ["Alice", new Date("2023-06-15T10:30:00Z")]
], { dateFormat: "mm/dd/yyyy hh:mm AM/PM" });
// Output: Name,Date\nAlice,06/15/2023 10:30 AM

Requirements

• Node.js 14.0.0 or higher (LTS recommended)
• ES Modules - Uses ES2020+ syntax

License

MIT

Built with ❤️ using only Node.js standard library