Utilities for Google Apps Script™

• Utilities for Google Apps Script™ projects
  • Overview
  • Key Features
  • Requirements
  • Installation
  • Usage Examples
  • Development
    • Scripts
    • Testing
  • Project Structure
  • Functions by Category
    • 1. Google Apps Script Module
      • 1.1. Google Base Methods
      • 1.2. Google Admin SDK Directory Methods
      • 1.3. Google Drive Methods
      • 1.4. Google Docs Methods
      • 1.5. Google Forms Methods
      • 1.6. Google Sheets Methods
      • 1.7. Google Slides Methods
      • 1.8. Network Methods
      • 1.9. Google UI Methods
    • 2. Base Utilities
    • 3. Exceptions Module
    • 4. path Module
    • 5. abstracts and interfaces
  • Contributing
  • Support
  • Roadmap
  • Changelog
  • 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 (v20 or higher recommended)
• npm

Installation

Install the package via npm:

npm install apps-script-utils

Usage 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", "[email protected]", 28],
  ["Jane Smith", "[email protected]", 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

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 for testing. You can run tests using:

npm test

For development with watch mode:

npm run dev

Project Structure

.
├── 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.

1.1. Google Base Methods

Functions that enable various operations on a collection of base utility methods.

1.2. Google Admin SDK Directory Methods

Functions that enable various operations on the Admin SDK Directory Service.

1.3. Google Drive Methods

Functions that enable various operations on Google Drive.

1.4. Google Docs Methods

Functions that enable various operations on Google Docs.

1.5. Google Forms Methods

Functions that enable various operations on Google Forms.

1.6. Google Sheets Methods

Functions that enable various operations on Google Sheets.

1.7. Google Slides Methods

Functions that enable various operations on Google Slides.

1.8. Network Methods

Functions that enable various network-related operations.

1.9. Google UI Methods

Functions that enable various operations on the user interface, including sidebars, dialogs, and web apps.

2. Base Utilities

This package contains core utility functions that are not tied to a specific Apps Script service.

3. Exceptions Module

This package is for all exception classes.

4. path Module

Functions for working with file paths and URLs.

5. abstracts and interfaces

Contributing

Contributions are welcome! If you'd like to contribute, please:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Write tests for your changes.
4. Run npm run lint and npm run format.
5. Do not modify CHANGELOG.md manually; it's updated automatically.
6. Submit a pull request.

Please make sure to follow the existing code style and naming conventions.

Support

If you encounter any issues or have questions, please:

• Open an issue on GitHub.
• Check the Changelog for recent updates.
• Support the project by giving it a ⭐ on GitHub!

Roadmap

For the project development plan and future features, please see the ROADMAP file.

Changelog

For a detailed list of changes and updates, please refer to the CHANGELOG file.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

⭐ Like this project? Star our awesome repo »