apps-script-utils

KO | EN

gitlite — search

#javascript #python #react #go #rust #deep-learning #nodejs #windows #cli #kubernetes #awesome-list #mcp #ios #open-source

apps-script-utils

(★ 29)

Utilities for Google Apps Script™ projects.

apps-script-utils Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Project banner for Google Apps Script Utils](https://raw.githubusercontent.com/MaksymStoianov/apps-script-utils/main/docs/assets/images/banner-1280x640.jpg)

<p align="right">
    <small>
        <i>Artist: <a href="https://darynamikhailenko.com/?utm_source=github&utm_medium=readme&utm_campaign=apps-script-utils&utm_content=banner-artist-credit" title="Portfolio of Daryna Mikhailenko, the artist">Daryna Mikhailenko</a></i>
    </small>
</p>

# Utilities for Google Apps Script™

- [Utilities for Google Apps Script™ projects](#utilities-for-google-apps-script-projects)
  - [Overview](#overview)
  - [Key Features](#key-features)
  - [Requirements](#requirements)
  - [Installation](#installation)
  - [Usage Examples](#usage-examples)
  - [Development](#development)
    - [Scripts](#scripts)
    - [Testing](#testing)
  - [Project Structure](#project-structure)
  - [Functions by Category](#functions-by-category)
    - [1. Google Apps Script Module](#1-google-apps-script-module)
      - [1.1. Google Base Methods](#11-google-base-methods)
      - [1.2. Google Admin SDK Directory Methods](#12-google-admin-sdk-directory-methods)
      - [1.3. Google Drive Methods](#13-google-drive-methods)
      - [1.4. Google Docs Methods](#14-google-docs-methods)
      - [1.5. Google Forms Methods](#15-google-forms-methods)
      - [1.6. Google Sheets Methods](#16-google-sheets-methods)
      - [1.7. Google Slides Methods](#17-google-slides-methods)
      - [1.8. Network Methods](#18-network-methods)
      - [1.9. Google UI Methods](#19-google-ui-methods)
    - [2. `Base` Utilities](#2-base-utilities)
    - [3. Exceptions Module](#3-exceptions-module)
    - [4. `path` Module](#4-path-module)
    - [5. `abstracts` and `interfaces`](#5-abstracts-and-interfaces)
  - [Contributing](#contributing)
  - [Support](#support)
  - [Roadmap](#roadmap)
  - [Changelog](#changelog)
  - [License](#license)

## Overview

A set of utilities for **Google Apps Script**, as well as common functions for working with data, strings, validation
and
more. This project aims to simplify development in the Apps Script environment and provide frequently used functions in
one place.

## Key Features

- 🚀 **Optimized for GAS**: Tailored specifically for Google Apps Script environments and limitations.
- 🛠️ **Rich Utility Set**: Comprehensive collection of spreadsheet, UI, and admin SDK helpers.
- 📝 **TypeScript Support**: Full type definitions for better IDE support and safer code.
- 🧪 **Tested**: Unit tests using Vitest to ensure reliability.
- 🔗 **Linked Documentation**: Direct links to official Google documentation for all GAS types.
- 🛡️ **Robust Error Handling**: Custom exception classes for better debugging.

## Requirements

- [Node.js](https://nodejs.org/) (v20 or higher recommended)
- [npm](https://www.npmjs.com/)

## Installation

Install the package via npm:

```bash
npm install apps-script-utils
```

## Usage Examples

### 📊 Working with Sheets

Append multiple rows of data efficiently:

```typescript
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:

```typescript
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:

```typescript
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
```

## Development

### Scripts

The following scripts are available in `package.json`:

- `npm run build`: Cleans the `dist` directory and compiles the TypeScript source.
- `npm run dev`: Starts Vitest in watch mode.
- `npm test`: Runs all tests once.
- `npm run lint`: Runs ESLint with auto-fix enabled.
- `npm run format`: Formats the codebase using Prettier.
- `npm run maint`: Runs the maintenance script (`scripts/maintenance.sh`).
- `npm run prepare`: Sets up Husky for git hooks.

### Testing

The project uses [Vitest](https://vitest.dev/) for testing. You can run tests using:

```bash
npm test
```

For development with watch mode:

```bash
npm run dev
```

## Project Structure

```text
.
├── config/           # Configuration files
├── dist/             # Compiled output (after build)
├── docs/             # Documentation and assets
├── scripts/          # Maintenance and helper scripts
├── src/              # Source code
│   ├── appsscript/   # Google Apps Script specific utilities
│   ├── exception/    # Custom exception classes
│   ├── html/         # HTML utilities
│   ├── json/         # JSON utilities
│   ├── lang/         # Language-level utilities (array, string, etc.)
│   ├── net/          # Network and path utilities
│   ├── time/         # Time-related utilities
│   └── index.ts      # Main entry point
├── test/             # Unit tests
└── vitest.config.ts  # Vitest configuration
```

## Functions by Category

### 1. Google Apps Script Module

Functions specifically designed for Google Apps Script environments, including utilities for working with spreadsheets.