Домовленості про перевірки

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

Чотири префікси

Префікс	Відповідає на питання	Повертає	Кидає
`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) на основі вихідного коду бібліотеки.