Обробка винятків

Будь-яка помилка, яку підіймає ця бібліотека, — екземпляр класу Exception або його нащадка. Тому одного блоку catch досить, щоб відрізнити збої бібліотеки від усього іншого, що кидає середовище виконання.

Ієрархія

Error
└── Exception
    └── RuntimeException
        ├── EmptyStringException
        ├── IllegalArgumentException
        ├── InvalidEmailFormatException
        ├── InvalidStringException
        ├── NullPointerException
        ├── RepositoryIsNotDefinedException
        ├── ServiceIsNotDefinedException
        ├── AuthenticationException
        ├── AdminDirectoryException
        ├── InvalidGridRangeException
        ├── InvalidRangeException
        ├── InvalidSheetException
        ├── InvalidSpreadsheetException
        ├── InvalidPresentationException
        └── SlideNotFoundException

Сенс несуть два рівні. Exception — корінь, він позначає помилку як таку, що надійшла з цієї бібліотеки. RuntimeException позначає її як збій під час роботи скрипта, і від нього успадковує кожен конкретний клас, — тому catch на RuntimeException ловить усе, що бібліотека наразі кидає.

Як ловити

У Exception є статичний страж типу — рекомендована перевірка, бо вона заодно звужує тип:

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

try {
  requireString(input);
} catch (error) {
  if (Exception.isException(error)) {
    Logger.log(`${error.name}: ${error.getMessage()}`);
  } else {
    throw error;
  }
}

instanceof теж працює — ним ловлять один конкретний збій:

import { NullPointerException, requireNonNull } from "apps-script-utils";

try {
  const sheet = requireNonNull(spreadsheet.getSheetByName("Data"));
} catch (error) {
  if (error instanceof NullPointerException) {
    Logger.log("Sheet 'Data' does not exist.");
  }
}

Кожен підклас задає name у власному конструкторі, тому error.name показує конкретний клас — "NullPointerException", а не "Exception".

Як створювати

Кожен виняток приймає необов'язкове повідомлення: рядок, готову помилку Error, чиє повідомлення буде перевикористано, або будь-яке інше значення, яке просто ігнорується:

throw new IllegalArgumentException("size must be a positive integer");
throw new IllegalArgumentException(caughtError); // перевикористовує caughtError.message
throw new IllegalArgumentException(); // без повідомлення

Exception.create() — фабрика з тим самим сенсом, для випадків, коли вираз із new не підходить.

Під капотом це звичайні об'єкти Error, тому getMessage(), toString() та Object.prototype.toString.call() поводяться як очікується:

const error = new EmptyStringException("name is required");

error.getMessage(); // "name is required"
error.toString(); // "name is required"
Object.prototype.toString.call(error); // "[object EmptyStringException]"

Хто що кидає

Виняток	Кидають
`IllegalArgumentException`	перевірки `requireX` для масивів, логічних значень, лічильних чисел, функцій, цілих, чисел, об'єктів, скалярів і символів, а також більшість помічників для нотації A1 та аркушів
`InvalidStringException`	`requireString` і застаріла `nonEmptyString`
`EmptyStringException`	`requireNonEmptyString`, `escapeRegExp`
`NullPointerException`	`requireNonNull`
`InvalidEmailFormatException`	`requireValidEmail`
`RepositoryIsNotDefinedException`	`requireRepository`
`ServiceIsNotDefinedException`	`requireService`
`AuthenticationException`	`requireValidToken`
`AdminDirectoryException`	створюється всередині `isAdmin`, коли сервіс Admin SDK Directory не увімкнено, і там же потрапляє в журнал, а не назовні
`InvalidSheetException`	`requireSheet`
`InvalidSpreadsheetException`	`requireSpreadsheet`
`InvalidRangeException`	`requireRange`
`InvalidGridRangeException`	`toA1Notation` і помічники порівняння `GridRange`
`SlideNotFoundException`	`requireSlide`

Винятки перелічує всі класи з посиланням на вихідний код.

Як обрати поведінку за збою

Предикати ніколи не кидають, твердження кидають завжди. Що брати — залежить від того, чи очікуваний хибний ввід:

// Очікувано: поле форми цілком може виявитися порожнім.
if (nonEmpty(response)) {
  process(response);
}

// Неочікувано: відсутній аркуш — це зламана конфігурація, а не випадок для обробки.
const sheet = requireNonNull(spreadsheet.getSheetByName("Data"), "sheet 'Data' is missing");

Передати необов'язковий аргумент message варто витрачених натискань: це єдиний контекст, який отримає читач журналу виконання.

23 September 2026

Цю документацію згенеровано нейромережею (Claude) на основі вихідного коду бібліотеки.