@toxfim/xsheets

Type-safe Google Sheets access for Node.js and TypeScript.

@toxfim/xsheets is a small developer library that wraps the Google Sheets Spreadsheet API with a clean Spreadsheet class, strong TypeScript types, and a simple structure that is ready to publish to npm.

Features

• Simple Spreadsheet class API
• Works in JavaScript and TypeScript projects
• Service account authentication
• Dual package output for ESM and CommonJS
• Strong public type definitions
• Small internal architecture with clear separation of concerns
• Tests for helpers and core data-shaping utilities

Installation

npm install @toxfim/xsheets

Requirements

• Node.js 18 or later
• A Google Cloud service account with access to the target spreadsheet
• The Google Sheets API enabled for your Google Cloud project

Quick Start

import { Spreadsheet } from "@toxfim/xsheets";

const sheet = new Spreadsheet(
  process.env.GOOGLE_CLIENT_EMAIL!,
  process.env.GOOGLE_PRIVATE_KEY!,
);

const rows = await sheet.getValues({
  spreadsheetId: process.env.GOOGLE_SPREADSHEET_ID!,
  sheetName: "Users",
});

console.log(rows);

You can also import a Google service-account JSON file directly:

import { Spreadsheet } from "@toxfim/xsheets";
import credentials from "./credentials.json";

const sheet = new Spreadsheet(credentials);

Usage Examples

Read values

const values = await sheet.getValues({
  spreadsheetId: "your-spreadsheet-id",
  sheetName: "Users",
  range: "A1:C10",
});

Set values

await sheet.setValues({
  spreadsheetId: "your-spreadsheet-id",
  sheetName: "Users",
  range: "A1:B3",
  values: [
    ["name", "active"],
    ["Ada", true],
    ["Grace", false],
  ],
});

Clear values

await sheet.clear({
  spreadsheetId: "your-spreadsheet-id",
  sheetName: "Users",
  range: "A2:B100",
});

Append values

await sheet.append({
  spreadsheetId: "your-spreadsheet-id",
  sheetName: "Users",
  values: [["Linus", true]],
});

Create and delete sheets

await sheet.createSheet({
  spreadsheetId: "your-spreadsheet-id",
  name: "Archive",
});

await sheet.deleteSheet({
  spreadsheetId: "your-spreadsheet-id",
  name: "Archive",
});

API Overview

Constructor

new Spreadsheet(clientEmail: string, privateKey: string)

new Spreadsheet(
  credentials:
    | { clientEmail: string; privateKey: string }
    | { client_email: string; private_key: string }
)

Methods

• getValues(options)
• setValues(options)
• clear(options)
• append(options)
• createSheet(options)
• deleteSheet(options)

Detailed API docs live in docs/API.md.

Error Handling Notes

The library exposes custom error classes:

• GoogleSheetsError
• SpreadsheetConfigurationError
• SheetNotFoundError

These help distinguish configuration issues, missing sheets, and Google API failures.

Development Scripts

npm run dev
npm run lint
npm run test
npm run typecheck
npm run build

Build Instructions

npm install
npm run build

Build output is generated in dist/:

• dist/index.js for ESM
• dist/index.cjs for CommonJS
• dist/index.d.ts for types

Publish Readiness Notes

• package.json includes dual-package exports
• Type declarations are generated during build
• prepublishOnly runs lint, tests, and build
• Only publishable files are included through the files field

Documentation

• API Reference
• Architecture
• Release Guide
• Contributing
• Security