Conventions de validation

L'essentiel de cette bibliothèque est fait de validations, et presque toutes suivent un seul schéma de noms. Apprenez les quatre préfixes une fois, et le nom d'une fonction vous dira sa signature, sa valeur de retour et si elle peut lever.

Les quatre préfixes

Préfixe	Répond à	Renvoie	Lève
`isX`	Cette valeur est-elle un `X`?	`boolean`	Non
`nonX`	Cette valeur n'est-elle pas un `X`?	`boolean`	Non
`requireX`	Donne-moi cette valeur en tant que `X`.	la valeur, typée `X`	Oui, si ce n'est pas un `X`
`requireNonX`	Donne-moi la valeur, sachant qu'elle n'est pas un `X`.	la valeur, `X` exclu du type	Oui, si c'est un `X`

isX et nonX sont des prédicats : ils répondent à une question et n'interrompent jamais le flot. requireX et requireNonX sont des assertions : ils rendent la valeur, ce qui permet d'appeler en pleine expression, ou lèvent.

Les prédicats restreignent les types

Les gardes isX sont déclarés comme prédicats de type TypeScript : le compilateur restreint donc la valeur dans la branche.

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

function describe(value: unknown): string {
  if (isString(value)) {
    return value.toUpperCase(); // ici, value est de type string
  }

  return "not a string";
}

nonX restreint dans l'autre sens — il retire X du type plutôt que de le confirmer :

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

function lengthOf(value: string | number): number {
  if (nonString(value)) {
    return value; // ici, value est de type number
  }

  return value.length;
}

Écrire nonX(value) revient au même test que !isX(value). L'intérêt du préfixe est qu'une clause de garde se lit comme une phrase et non comme une négation — ce qui compte là où l'alternative s'écrirait if (!isConsistent2DArray(rows)).

Les assertions rendent la valeur

requireX valide et renvoie : l'appel s'insère dans une expression au lieu d'exiger une instruction séparée.

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

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

Chaque requireX accepte un dernier argument facultatif message, utilisé comme message de l'exception lorsque la validation échoue :

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

Quelle exception lève chacune d'elles est indiqué dans Gestion des exceptions.

`X` et `XLike`

Quelques prédicats existent en version stricte et en version permissive. Le nom simple teste le type ; le suffixe Like teste si la valeur peut être utilisée comme ce type :

Fonction	Accepte
`isNumber`	toute valeur dont `typeof` vaut `number`, y compris `NaN` et `Infinity`
`isNumberLike`	les nombres finis et les chaînes non vides qui se convertissent en un nombre fini
`isObject`	toute valeur non nulle dont `typeof` vaut `object` — tableaux et dates compris
`isObjectLike`	la même chose, plus les fonctions
`isFunction`	les valeurs marquées comme fonction, générateur, fonction asynchrone ou proxy
`isFunctionLike`	toute valeur non nulle dont `typeof` vaut `function`

On prend la forme Like quand la valeur vient d'une cellule, d'une réponse de formulaire ou d'un paramètre d'URL : là, un nombre est généralement arrivé sous forme de chaîne.

Null, undefined et nil

Trois noms couvrent les cas vides, et la distinction est exacte :

Fonction	Vraie pour
`isNull`	`null` seulement
`isUndefined`	`undefined` seulement
`isNil`	l'un ou l'autre

requireNonNull est l'assertion qui va avec isNil, pas avec isNull: elle rejette null comme undefined et lève NullPointerException.

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

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

isEmpty est un test plus large encore. Il est vrai pour null et undefined, pour une chaîne vide ou faite d'espaces, pour un tableau vide, pour un Set ou une Map de taille zéro, et pour un objet simple sans propriété énumérable. Il est faux pour tout le reste, 0 et false compris. Passez true en second argument pour ne considérer vide qu'une chaîne de longueur nulle :

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

Couverture

Les quatre préfixes décrivent une grille, et elle est presque remplie : chaque type doté d'un isX a son nonX, requireX couvre les types qu'un appel valide d'ordinaire, et requireNonX existe pour tout lang/base comme pour les types numériques. Une combinaison absente l'est parce que personne n'en a eu besoin, non parce qu'elle serait exclue : ouvrez une issue et elle pourra être ajoutée.

Chaque fonction listée dans la référence a sa propre page, et chaque page est engendrée à partir d'un symbole que le paquet exporte réellement — un nom figurant dans les tableaux est donc importable.

Une exception à la règle

nonEmptyString ne suit pas la convention. Malgré son préfixe non, elle valide et renvoie une valeur, et lève en cas d'échec : c'est une fonction requireX sous un nom trompeur. Elle est dépréciée au profit de requireNonEmptyString, qui se comporte à l'identique sous le bon nom, et sera retirée dans une future version majeure.

// Déprécié
const name = nonEmptyString(input);

// À utiliser à la place
const name = requireNonEmptyString(input);

23 September 2026

Cette documentation a été générée par une IA (Claude) à partir du code source de la bibliothèque.