Konventionen der Prüfungen

Der größte Teil dieser Bibliothek besteht aus Prüfungen, und fast alle folgen einem einzigen Namensschema. Lernen Sie die vier Präfixe einmal, und der Name einer Funktion verrät ihre Signatur, ihren Rückgabewert und ob sie werfen kann.

Die vier Präfixe

Präfix	Beantwortet	Gibt zurück	Wirft
`isX`	Ist dieser Wert ein `X`?	`boolean`	Nein
`nonX`	Ist dieser Wert kein `X`?	`boolean`	Nein
`requireX`	Gib mir diesen Wert als `X`.	den Wert, typisiert als `X`	Ja, wenn er kein `X` ist
`requireNonX`	Gib mir den Wert, im Wissen, dass er kein `X` ist.	den Wert ohne `X` im Typ	Ja, wenn er ein `X` ist

isX und nonX sind Prädikate: sie beantworten eine Frage und unterbrechen den Ablauf nie. requireX und requireNonX sind Behauptungen: sie geben den Wert zurück, sodass der Aufruf in einem Ausdruck stehen kann, oder sie werfen.

Prädikate verengen Typen

Die isX-Prüfungen sind als TypeScript-Typprädikate deklariert, der Compiler verengt den Wert also innerhalb des Zweigs:

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

function describe(value: unknown): string {
  if (isString(value)) {
    return value.toUpperCase(); // value ist hier string
  }

  return "not a string";
}

nonX verengt in die Gegenrichtung — es entfernt X aus dem Typ, statt ihn zu bestätigen:

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

function lengthOf(value: string | number): number {
  if (nonString(value)) {
    return value; // value ist hier number
  }

  return value.length;
}

nonX(value) zu schreiben ist dieselbe Prüfung wie !isX(value). Der Sinn des Präfixes ist, dass eine Wächterklausel sich wie ein Satz liest und nicht wie eine Verneinung — was dort zählt, wo die Alternative if (!isConsistent2DArray(rows)) hieße.

Behauptungen geben den Wert zurück

requireX prüft und gibt zurück, der Aufruf fügt sich also in einen Ausdruck, statt eine eigene Anweisung zu verlangen:

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

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

Jedes requireX nimmt ein optionales letztes Argument message, das bei einer fehlgeschlagenen Prüfung zur Meldung der Ausnahme wird:

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

Welche Ausnahme jede einzelne wirft, steht in Ausnahmebehandlung.

`X` und `XLike`

Einige Prädikate gibt es in einer strengen und einer nachsichtigen Form. Der schlichte Name prüft den Typ, das Suffix Like prüft, ob sich der Wert als dieser Typ verwenden lässt:

Funktion	Akzeptiert
`isNumber`	jeden Wert, dessen `typeof` `number` ist, auch `NaN` und `Infinity`
`isNumberLike`	endliche Zahlen und nicht leere Zeichenketten, die sich in eine endliche Zahl umwandeln
`isObject`	jeden nicht-nil Wert, dessen `typeof` `object` ist — Arrays und Daten eingeschlossen
`isObjectLike`	dasselbe, zuzüglich Funktionen
`isFunction`	Werte mit dem Tag einer Funktion, Generatorfunktion, Async-Funktion oder eines Proxys
`isFunctionLike`	jeden nicht-nil Wert, dessen `typeof` `function` ist

Zur Like-Form greift man, wenn der Wert aus einer Tabellenzelle, einer Formularantwort oder einem URL-Parameter kommt — dort ist eine Zahl meist als Zeichenkette angekommen.

Null, undefined und nil

Drei Namen decken die leeren Fälle ab, und die Unterscheidung ist genau:

Funktion	Wahr für
`isNull`	nur `null`
`isUndefined`	nur `undefined`
`isNil`	beides

requireNonNull ist die Behauptung zu isNil, nicht zu isNull: sie weist null und undefined gleichermaßen zurück und wirft NullPointerException:

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

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

isEmpty ist noch weiter gefasst. Sie ist wahr für null und undefined, für eine leere Zeichenkette und eine aus reinem Leerraum, für ein leeres Array, für ein Set oder eine Map der Größe null und für ein einfaches Objekt ohne aufzählbare Eigenschaften. Für alles andere, auch für 0 und false, ist sie falsch. Mit true als zweitem Argument gilt nur eine Zeichenkette der Länge null als leer:

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

Abdeckung

Die vier Präfixe beschreiben ein Raster, und es ist weitgehend gefüllt: zu jedem Typ mit isX gibt es ein nonX, requireX deckt die Typen ab, die ein Aufruf üblicherweise prüft, und requireNonX existiert für das ganze lang/base ebenso wie für die numerischen Arten. Eine fehlende Kombination fehlt, weil sie noch niemand gebraucht hat, nicht weil sie ausgeschlossen wäre — ein Issue genügt.

Jede in der Referenz aufgeführte Funktion hat eine eigene Seite, und jede Seite entsteht aus einem Symbol, das das Paket tatsächlich exportiert: ein Name aus den Tabellen lässt sich also importieren.

Eine Ausnahme von der Regel

nonEmptyString folgt der Konvention nicht. Trotz des Präfixes non prüft sie einen Wert, gibt ihn zurück und wirft im Fehlerfall — sie ist eine requireX-Funktion unter irreführendem Namen. Sie ist zugunsten von requireNonEmptyString veraltet, die sich unter dem richtigen Namen genauso verhält, und wird in einem künftigen Major-Release entfernt.

// Veraltet
const name = nonEmptyString(input);

// Stattdessen
const name = requireNonEmptyString(input);

23 September 2026

Diese Dokumentation wurde mit KI (Claude) aus dem Quellcode der Bibliothek erzeugt.