Artist: Daryna Mikhailenko

Utilities for Google Apps Script™ projects

Introduction

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.

How to Install

To get started, install the dependencies:

npm install github:MaksymStoianov/apps-script-utils#main

Note: It's recommended to use tags (#vX.Y.Z) for production environments to ensure version stability.

For example:

npm install github:MaksymStoianov/apps-script-utils#v1.6.0

Functions by Category

1. Google Apps Script Module

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

Functions

1.1. Google Base Methods

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

Functions

Function	Description
getByteSize	Returns the size of a string in bytes.

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.

Functions

Function	Description

1.4. Google Docs Methods

Functions that enable various operations on Google Docs.

Functions

Function	Description

1.5. Google Forms Methods

Functions that enable various operations on Google Forms.

Functions

Function	Description

1.6. Google Sheets Methods

Functions that enable various operations on Google Sheets.

Functions

Function	Description
appendColumn	Appends a single column of data to the sheet.
appendColumns	Appends multiple columns of data to the sheet.
appendRow	Appends a single row of data to the sheet.
appendRows	Appends multiple rows of data to the sheet.
convertRichTextToHtml	Converts a RichTextValue to an HTML string.
doGridRangesIntersect	Checks if two GridRange objects intersect.
extractRangeFromA1Notation 🆕	Extracts the range part from a full A1 notation string (e.g., 'Sheet1!A1:B2' returns 'A1:B2').
extractSheetNameFromA1Notation 🆕	Extracts the sheet name from an A1 notation string (e.g., Sheet1!A1:B2).
getColumnIndexByLetter	Gets the column index by its letter (e.g., 'A' -> 1).
getColumnLetterByIndex	Gets the column letter by its index (e.g., 1 -> 'A').
getColumnLetterByPosition	Gets the column letter by its position.
getColumnPositionByLetter	Gets the column position by its letter.
getSheetById	Gets a sheet by its ID.
highlightHtml	Adds syntax highlighting to an HTML string.
isCellGridRange	Checks if a GridRange represents a single cell.
isGridRangeContainedIn	Checks if one GridRange is contained within another.
isGridRangeSameDimensions	Checks if two GridRange objects have the same dimensions.
isRange	Checks if an object is a Range.
isRichTextValue	Checks if an object is a RichTextValue.
isSheet	Checks if an object is a Sheet.
isSpreadsheet	Checks if an object is a Spreadsheet.
isTextStyle	Checks if an object is a TextStyle.
isValidSheetId	Checks if a sheet id is valid.
isValidSheetName	Checks if a sheet name is valid.
isValidSpreadsheetId	Checks if a spreadsheet ID is valid.
nonRange	Checks if an object is not a Range.
nonSheet	Checks if an object is not a Sheet.
parseA1Notation 🆕	Parses an A1 notation (e.g., 'A1:B2') into GridRange components.
parseA1Notations 🆕	Parses a comma-separated string of A1 notations into an array of GridRange objects.
prependRow	Prepends a single row of data to the sheet.
prependRows	Prepends multiple rows of data to the sheet.
requireRange	Checks if an object is not a Range, otherwise throws an exception.
requireSheet	Checks if an object is not a Sheet, otherwise throws an exception.
sortSheets	Sorts all sheets in a spreadsheet alphabetically by name.
toA1Notation	Converts a GridRange to A1 notation.
updateSheetNameInA1Notation 🆕	Updates or sets the sheet name within an A1 notation string, while preserving the range information (e.g., A1:B2).

1.7. Google Slides Methods

Functions that enable various operations on Google Slides.

Functions

Function	Description

1.8. Google UI Methods

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

Functions

Function	Description
checkMultipleAccount	Checks if multiple Google accounts are in use.
isHtmlOutput	Checks if an object is an HtmlOutput.
isTextOutput	Checks if an object is a TextOutput.
isUi	Checks if an object is a Ui.

2. `Base Utilities

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

Functions

Function	Description
chunk	Splits an array into chunks of a specified size.
decodeHtml	Decodes HTML entities.
encodeHtml	Encodes a string for safe use in HTML.
escapeHtml	Escapes HTML special characters.
escapeRegExp	Escapes special characters for use in regular expressions.
escapeXml	Escapes XML special characters.
hashCode	Calculates a hash code for a string.
is2DArray	Checks if a variable is a 2D array.
isArray	Checks if a variable is a Array.
isBoolean	Checks if a variable is a boolean value.
isConsistent2DArray	Checks if a 2D array has consistent inner array lengths.
isEmail	Checks if a string is a valid email address.
isEmpty	Checks if a value is empty (for strings, arrays, objects).
isException	Checks if an object is an instance of Exception or its subclass.
isFunction	Checks if a variable is a function.
isFunctionLike	Checks if a variable is a function in a broader sense.
isLength	Checks if a value is "length-like" (arrays, strings, etc.).
isNil	Checks if a value is null or undefined.
isNull	Checks if a value is null.
isNumber	Checks if a variable is a number.
isNumberLike	Checks if a value can be converted to a number.
isObject	Checks if a variable is an object (but not null or an array).
isObjectLike	Checks if a variable is object-like (objects, arrays, functions).
isRegExp	Checks if a variable is a regular expression.
isScalar	Checks if a variable is a scalar value (string, number, boolean, symbol and bigint).
isString	Checks if a variable is a string.
isSymbol	Checks if a variable is a symbol.
isUndefined	Checks if a value is undefined.
isUrl	Checks if a string is a valid URL.
isValidLocale	Checks if a string is a valid locale code.
isValidSlug	Checks if a string is a valid "slug" (URL-friendly string).
isValidVersion	Checks if a string is a valid version number (semantic versioning).
isVersionCompatible	Checks version compatibility.
nonArray	Returns true if not Array.
nonBoolean	Returns true if not boolean.
nonEmpty	Returns true if not "empty".
nonFunction 🆕	Returns true if not Function.
nonNil	Returns true if not null or undefined.
nonNull	Returns true if not null.
nonNumber	Returns true if not a number.
nonScalar	Returns true if not a scalar value (string, number, boolean, symbol and bigint).
nonString	Returns true if not a string.
nonSymbol	Returns true if not a Symbol.
nonUndefined	Returns true if not a undefined.
parseJson	Safely parses a JSON string.
requireNonEmptyString	Checks if a string is non-empty, otherwise throws an exception.
requireNonNull	Checks that a value is not null, otherwise throws an exception.
requireString	Checks that a value is a string, otherwise throws an exception.
requireValidEmail	Checks that a string is a valid email, otherwise throws an exception.
stringifyJson	Safely converts an object to a JSON string.
toCamelCase	Converts a string to camelCase.
toInteger	Converts a value to an integer.
toKebabCase	Converts a string to kebab-case.
toLowerCase	Converts a string to lowercase.
toProperCase	Converts a string to Proper Case (first letter of each word capitalized).
toSnakeCase	Converts a string to snake_case.
toString	Converts a value to a string.
toUpperCase	Converts a string to uppercase.
transpose	Transposes a 2D array (matrix).
versionCompare	Compares two versions.

3. Exceptions Module

This package is for all exception classes.

Functions

Exception	Description
AdminDirectoryException	Represents an exception thrown when the Admin SDK Directory Service is not available or enabled.
InvalidGridRangeException	Represents an exception thrown when an invalid GridRange object is provided.
InvalidRangeException	Represents an exception thrown when an invalid range object is provided.
InvalidSheetException	Represents an exception thrown when an invalid sheet object is provided.

Exception	Description
Exception	Base exception class.
RuntimeException	Exception for runtime errors.
EmptyStringException	Exception for empty strings.
IllegalArgumentException	Exception for invalid arguments.
InvalidEmailFormatException	Exception for invalid email format.
InvalidStringException	An exception thrown when a function expects a string, but receives a value of a different type.
NullPointerException	Exception for null values.

4. path Module

Functions for working with file paths and URLs.

Functions

Function	Description
isAbsolute	Checks if a path is absolute.
isRelative	Checks if a path is relative.
isValidDomain	Checks if a string is a valid domain name.
join	Joins multiple path segments.
normalize	Normalizes a path, resolving . and ...
parse	Parses a path into its components (root, dir, base, ext, name).

5. abstracts and interfaces

Functions

Abstract	Description
Class

Functions

Interface	Description
Iterator	Interface for iterators.

Tasks

More

• appsscript/base/sprintf
• appsscript/base/formatDate
• appsscript/sheets/prependColumn
• appsscript/sheets/prependColumns
• appsscript/sheets/insertSchema
• appsscript/sheets/getSchema(sheet: Sheet)
• appsscript/sheets/removeSchema(sheet: Sheet)
• appsscript/sheets/getValues(sheet: Sheet, config: Object)
• appsscript/sheets/clearColumnsByConditional(sheet: Sheet, callback: Function)
• appsscript/sheets/clearRowsByConditional(sheet: Sheet, callback: Function)
• appsscript/sheets/deleteRowsByConditional(sheet: Sheet, callback: Function)
• appsscript/sheets/deleteColumnsByConditional(sheet: Sheet, callback: Function)
• appsscript/sheets/updateFormulas(sheet: Sheet)
• appsscript/sheets/getNamedRangeByName(name: string)
• appsscript/sheets/abstract/Sheet
• appsscript/sheets/abstract/Menu
• appsscript/net/abstract/URL
• appsscript/net/abstract/URLSearchParams
• appsscript/crypto/base64decode
• appsscript/crypto/base64encode
• appsscript/crypto/md5
• appsscript/crypto/sha1
• appsscript/crypto/sha256
• appsscript/crypto/sha512
• appsscript/dive/createFolder(path: string, rootFolder?: Folder)
• appsscript/classroom/getCourses()
• base/getTriggerById(id)
• base/flat(value: Array | Object, depth?: number)
• base/namespace(obj: Object | Array, path: string | number | Array)
• base/unique(arr: Array)
• base/first(arr: Array)
• base/last(arr: Array)
• base/compact(arr: Array)
• base/without(arr: Array, ...values: any)
• base/intersect(arr: Array)
• base/merge(text: string, fields: Object) - Merges fields with text.
• base/date/now
• base/date/diff
• base/date/getDaysInMonth
• base/date/getDaysLeftInMonth
• base/date/offset
• abstract/EventEmitter

Changelog

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

License

This project is licensed under the LICENSE file.

---

⭐ Like this project? Star our awesome repo »