Lorsque vous travaillez avec l’interface FormData en JavaScript, où les données sont ajoutées sous forme de paires clé/valeur, il n’existe pas de moyen intégré pour garantir la sécurité des types sur les clés que vous ajoutez. Cela peut entraîner des fautes de frappe, des clés manquantes et des erreurs d’exécution inattendues. Mais en TypeScript, nous pouvons résoudre ce problème en imposant une validation stricte des clés.

J’avais besoin de cette solution moi-même lorsque j’envoyais mes valeurs de formulaire à une API. J’ai ensuite réalisé que j’avais fait plusieurs erreurs typographiques dans plus d’une paire clé/valeur que j’essayais d’ajouter à ma charge utile. Parce que FormData accepte n’importe quelle chaîne comme clé, j’ai pu passer des chaînes incorrectes et poursuivre la demande à l’API.

Après cela, j’ai cherché un moyen de m’assurer que TypeScript ne permettait pas ces erreurs.

Cet article vous montrera comment rendre les clés FormData sûres pour les types en utilisant TypeScript.

Conditions préalables

Pour tirer le meilleur parti de cet article, vous devriez avoir une compréhension de base des éléments suivants :

  1. Programmation JavaScript

  2. Fondamentaux de TypeScript, en particulier le fonctionnement des interfaces, des types et de l’opérateur keyof

  3. l’interface FormData

Si vous êtes nouveau en TypeScript ou FormData, je recommande de consulter la documentation officielle de TypeScript et le guide de MDN sur FormData avant de continuer.

Étape 1 : Définir vos clés autorisées

L’Ancienne Méthode

La méthode par défaut pour ajouter des données avec FormData est de le faire manuellement, avec des chaînes de caractères simples :

const payload = new FormData();

payload.append("id", "1122");
payload.append("name", "Clark Kent");

payload.append("agge", "36"); // Une faute de frappe dans la clé est autorisée

Dans l’exemple de code ci-dessus, vous pouvez voir qu’il y avait une faute de frappe lors de la définition d’une clé pour age. Mais TypeScript ne le signalera pas en tant qu’erreur, et cela pourrait conduire à des erreurs lorsque ces données sont envoyées avec une requête API.

La Meilleure Méthode

Au lieu de taper manuellement les clés, définissez-les dans un schéma d’objet avec une interface TypeScript.

interface MyAllowedData {
    id: number;
    name: string;
    age: number;
}

Alternativement, vous pouvez les définir avec des types :

type MyAllowedData = {
    id: number;
    name: string;
    age: number;
}

Vous pouvez utiliser des types ou des interfaces, c’est juste une question de préférence. Vous pouvez en savoir plus sur leurs différences dans ce bac à sable de documentation officiel de TypeScript.

Ensuite, définissez un type union pour chaque clé dans votre interface.

type MyFormDataKeys = keyof MyAllowedData
// c'est la même chose que `type MyFormDataKeys = 'id' | 'name' | 'age'`

L’opérateur keyof aide à créer un type union des clés d’un type d’objet, il est donc très utile si vous ne voulez pas définir manuellement un type union pour un objet plus grand avec de nombreuses clés.

Étape 2 : Créer une fonction d’aide à l’ajout

Maintenant que vous avez défini vos clés strictement typées, la prochaine étape consiste à créer une fonction d’aide qui garantit que seules les clés valides sont ajoutées à FormData.

function appendToFormData (formData: FormData, key: MyFormDataKeys, value: string) {
  formData.append(key, value);
};

La fonction appendToFormData prend trois arguments. Voici comment cela fonctionne :

  • Le premier argument, formData, est une instance de l’objet FormData. C’est ici que les paires clé/valeur seront ajoutées avant de les envoyer dans une requête API.

  • Le deuxième argument, key, est le nom de la clé du champ que vous souhaitez ajouter. Son type est MyFormDataKeys, le type union que nous avons créé pour garantir que seules les clés que nous avons définies sont ajoutées à FormData.

  • Le troisième argument est une chaîne de caractères value qui représente la valeur à ajouter avec la clé.

Notez que FormData n’accepte que les string et Blob types comme valeurs dans chaque paire clé/valeur. Dans ce guide, nous travaillons uniquement avec des valeurs de chaîne – mais gardez à l’esprit que vous pouvez utiliser des valeurs blob pour ajouter des fichiers aux requêtes API.

Maintenant, testons la fonction :

const payload = new FormData();

appendToFormData(payload, "id", "19282"); // ✅ Autorisé
appendToFormData(payload, "name", "Lenny Brown"); // ✅ Autorisé
appendToFormData(payload, "age", "20"); // ✅ Autorisé

appendToFormData(payload, "someOtherKey", "89"); // ❌ Erreur TypeScript : L'argument de type 'someOtherKey' n'est pas assignable.

Étape 3 : Utilisez la fonction d’assistance après la soumission du formulaire

Maintenant, ajoutons nos champs à FormData avant de les envoyer à une API.

const handleSubmitForm = () => {
  const payload = new FormData();
   appendToFormData(payload, "id", "19282");
   appendToFormData(payload, "name", "Lenny Brown");
   appendToFormData(payload, "age", "20");

  // Envoyer la charge utile via l'API
  fetch("/api/submit", { method: "POST", body: payload });
};

Ajout de champs à partir d’un objet

Alternativement, si vous avez déjà toute votre charge utile dans un objet, vous pouvez éviter d’ajouter chaque champ un par un en implémentant la fonction comme ceci :

const handleSubmitForm = () => {
  // tous vos champs dans un objet
  const formValues: MyAllowedData = {
    id: 1123,
    name: 'John Doe',
    age: 56
  }
  const payload = new FormData();

  Object.entries(formValues).forEach(([key, value]) => {
    appendToFormData(payload, key as MyFormDataKeys, `${value}`); // utilisez des littéraux de modèle pour passer la valeur
  });

  // Envoyer la charge utile via l'API
  fetch("/api/submit", { method: "POST", body: payload });
};

Dans l’extrait ci-dessus, nous utilisons Object.entries pour itérer sur chaque paire clé/valeur dans un objet afin de pouvoir l’ajouter à l’objet FormData. Notez que la valeur dans chaque paire, que ce soit une chaîne de caractères ou un nombre, est passée en tant que chaîne en utilisant les expressions littérales pour éviter un conflit de types TypeScript avec l’argument valeur dans notre fonction d’aide.

Conclusion

En exploitant l’opérateur keyof de TypeScript, nous pouvons rendre FormData.append() entièrement sûr en termes de types. Cette technique simple aide à éviter les incohérences de clés et rend vos requêtes API plus fiables.

Faites-moi part de vos réflexions sur l’article, et n’hésitez pas à faire des suggestions pour améliorer ma solution.

Merci de votre lecture!