Getting started

Requirements

Node.js v22.14.0 or later
npm (or another Node package manager, e.g. pnpm)

Installation

npm install apps-script-utils

Everything is exported from the package root, so a single import path covers the whole library:

import { appendRows, isAdmin, parseA1Notation, requireString } from "apps-script-utils";

First examples

Working with Sheets

Append multiple rows of data efficiently:

import { appendRows } from "apps-script-utils";

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Data");
const data = [
  ["John Doe", "john@example.com", 28],
  ["Jane Smith", "jane@example.com", 32]
];

appendRows(sheet, data);

Admin SDK utilities

Check if the current user has administrative privileges:

import { isAdmin } from "apps-script-utils";

if (isAdmin()) {
  Logger.log("Access granted to admin panel.");
} else {
  Logger.log("Access denied.");
}

A1 notation parsing

Parse complex A1 notations into structured objects:

import { parseA1Notation } from "apps-script-utils";

const rangeInfo = parseA1Notation("'Sheet1'!A1:B10");

console.log(rangeInfo.sheetName); // "Sheet1"
console.log(rangeInfo.startRowIndex); // 0
console.log(rangeInfo.endColumnIndex); // 2

Validating input

Most functions in the library reject bad input rather than coercing it. The requireX family turns an unchecked value into a typed one, or throws:

import { requireString, requireNonEmptyString } from "apps-script-utils";

function greet(name: unknown): string {
  return `Hello, ${requireNonEmptyString(name)}!`;
}

greet("Ada"); // "Hello, Ada!"
greet(""); // throws EmptyStringException
greet(42); // throws InvalidStringException

Validation conventions explains the full isX/nonX/requireX/requireNonX naming scheme, and Exception handling covers the exceptions these functions throw.

Where to go next

Validation conventions — the naming convention that covers most of the library.
The Apps Script runtime — which helpers need the Apps Script runtime, and what that means for testing.
Base utilities — the full list of runtime-independent functions.
Google Apps Script module — the full list of service-bound functions.

23 September 2026

This documentation was generated with AI (Claude) from the library's source code.