Соглашения о проверках

Большая часть библиотеки — это проверки, и почти все они подчиняются одной схеме имён. Выучите четыре префикса один раз, и имя функции само расскажет её сигнатуру, возвращаемое значение и то, может ли она бросить исключение.

Четыре префикса

Префикс	Отвечает на вопрос	Возвращает	Бросает
`isX`	Является ли значение `X`?	`boolean`	Нет
`nonX`	Значение не является `X`?	`boolean`	Нет
`requireX`	Дай мне это значение как `X`.	значение с типом `X`	Да, если это не `X`
`requireNonX`	Дай мне значение, зная, что это не `X`.	значение с исключённым `X`	Да, если это `X`

Пара isX и nonX — предикаты: они отвечают на вопрос и никогда не прерывают выполнение. Пара requireX и requireNonX — утверждения: они возвращают значение, чтобы вызов можно было встроить в выражение, либо бросают исключение.

Предикаты сужают типы

Стражи isX объявлены как type predicates в TypeScript, поэтому внутри ветки компилятор сужает тип значения:

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

function describe(value: unknown): string {
  if (isString(value)) {
    return value.toUpperCase(); // здесь value имеет тип string
  }

  return "not a string";
}

nonX сужает в обратную сторону — он убирает X из типа, а не подтверждает его:

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

function lengthOf(value: string | number): number {
  if (nonString(value)) {
    return value; // здесь value имеет тип number
  }

  return value.length;
}

Запись nonX(value) — та же проверка, что и !isX(value). Смысл префикса в том, что охранное условие читается как утверждение, а не как отрицание, — и это заметно там, где альтернатива выглядела бы как if (!isConsistent2DArray(rows)).

Утверждения возвращают значение

requireX проверяет и возвращает, поэтому вызов встраивается в выражение, а не требует отдельного оператора:

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

function repeat(text: unknown, times: unknown): string {
  return requireString(text).repeat(requireNumber(times));
}

У каждой функции requireX есть необязательный последний аргумент message — сообщение исключения на случай неудачной проверки:

requireString(config.sheetName, "sheetName must be a string");

Какое исключение бросает каждая из них, перечислено в Обработка исключений.

`X` и `XLike`

Некоторые предикаты существуют в строгой и мягкой форме. Простое имя проверяет тип, суффикс Like — можно ли использовать значение как этот тип:

Функция	Принимает
`isNumber`	любое значение, у которого `typeof` равен `number`, включая `NaN` и `Infinity`
`isNumberLike`	конечные числа и непустые строки, которые превращаются в конечное число
`isObject`	любое не-nil значение, у которого `typeof` равен `object`, — массивы и даты в том числе
`isObjectLike`	то же плюс функции
`isFunction`	значения с тегом функции, генератора, асинхронной функции или прокси
`isFunctionLike`	любое не-nil значение, у которого `typeof` равен `function`

Форма Like нужна там, где значение пришло из ячейки таблицы, из ответа формы или из параметра URL, — там число обычно приходит строкой.

Null, undefined и nil

Три имени покрывают пустые случаи, и различие между ними точное:

Функция	Истинна для
`isNull`	только `null`
`isUndefined`	только `undefined`
`isNil`	для любого из двух

requireNonNull — утверждение в паре с isNil, а не с isNull: оно отвергает и null, и undefined и бросает NullPointerException:

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

const sheet = requireNonNull(spreadsheet.getSheetByName("Data"), "sheet 'Data' is missing");

isEmpty — проверка ещё более широкая. Она истинна для null и undefined, для пустой строки и строки из одних пробелов, для пустого массива, для Set или Map нулевого размера и для простого объекта без перечислимых свойств. Для всего остального, включая 0 и false, она ложна. Передайте вторым аргументом true, чтобы пустой считалась только строка нулевой длины:

isEmpty("   "); // true
isEmpty("   ", true); // false
isEmpty(0); // false

Покрытие

Четыре префикса описывают сетку, и заполнена она почти целиком: у каждого типа с isX есть nonX, requireX покрывает типы, которые обычно и проверяют при вызове, а requireNonX существует для всего lang/base и для числовых видов. Отсутствующая комбинация отсутствует потому, что ещё никому не понадобилась, а не потому, что запрещена: заведите issue — её добавят.

У каждой функции из справочника есть собственная страница, и каждая страница порождается символом, который пакет действительно экспортирует, — значит, имя из таблицы можно импортировать.

Одно исключение из правила

nonEmptyString соглашению не подчиняется. Несмотря на префикс non, она проверяет и возвращает значение, а при неудаче бросает исключение, — то есть это функция requireX под неверным именем. Она объявлена устаревшей в пользу requireNonEmptyString, которая делает то же самое под правильным именем, и будет удалена в одном из будущих мажорных выпусков.

// Устарело
const name = nonEmptyString(input);

// Используйте вместо этого
const name = requireNonEmptyString(input);

23 September 2026

Эта документация сгенерирована нейросетью (Claude) на основе исходного кода библиотеки.