Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

IDBRequest : résultat et erreur d’une requête

Découvrez quand lire `result` et `error` dans IndexedDB et comment distinguer la réussite d’une requête de la validation de sa transaction.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

request.readyState; // "pending" or "done"
request.result;     // operation-specific value on success; undefined on failure
request.error;      // null on success; DOMException on failure
// Reading result or error while readyState is "pending" throws InvalidStateError.

result et error sont deux propriétés en lecture seule d’une instance de IDBRequest. Une requête IndexedDB représente une opération asynchrone. Ce n’est pas une promesse (Promise) : await request n’attend donc pas la fin de l’opération. IndexedDB est une API de la plateforme web, distincte d’ECMAScript 2024 ; sa disponibilité dépend de l’environnement d’exécution.

Tant que request.readyState vaut "pending", lire l’une ou l’autre propriété lève une DOMException nommée InvalidStateError. L’état "done" n’indique pas à lui seul une réussite. En général, lisez le résultat dans le gestionnaire de success. Exception : dans le gestionnaire de upgradeneeded d’une requête indexedDB.open(), result est déjà accessible pour modifier le schéma, même si l’évènement success final n’a pas encore été déclenché.

Lors de success, error vaut null et result dépend de l’opération : open() fournit une connexion IDBDatabase, add() donne la clé de l’enregistrement ajouté et get() peut donner undefined si aucun enregistrement ne correspond à la clé. Lors de error, result vaut undefined et error contient une DOMException. Examinez request.error.name pour identifier une erreur telle que ConstraintError. Un résultat undefined ne suffit pas à conclure à un échec. Un bloc try...catch autour de l’appel à l’API intercepte les exceptions synchrones, pas les échecs signalés plus tard par un évènement error.

La réussite d’une requête d’écriture ne signifie pas que la transaction a été validée. Écoutez complete pour confirmer sa validation et abort pour détecter son annulation. Par défaut, une erreur de requête dans une transaction annule cette dernière. Si l’erreur est attendue et peut être traitée sans risque, appelez event.preventDefault() dans le gestionnaire de error de la requête pour éviter cette annulation par défaut, sans pour autant faire réussir la requête.

Exemples

<!doctype html>
<meta charset="utf-8">
<title>IDBRequest result and error</title>
<script>
  (() => {
    const { indexedDB, crypto } = window;
    const name = `cktis-idbrequest-${crypto.randomUUID()}`;
    const open = indexedDB.open(name, 1);
    open.onupgradeneeded = () => open.result.createObjectStore("items");
    open.onerror = () => console.error("open:", open.error.name);

    open.onsuccess = () => {
      const db = open.result;
      const tx = db.transaction("items", "readwrite");
      const store = tx.objectStore("items");
      const cleanup = () => {
        db.close();
        const removal = indexedDB.deleteDatabase(name);
        removal.onerror = () => console.error("cleanup:", removal.error.name);
      };
      tx.oncomplete = () => {
        console.log("transaction: complete");
        cleanup();
      };
      tx.onabort = () => {
        console.error("transaction: abort", tx.error?.name);
        cleanup();
      };

      const first = store.add("first", 1);
      first.onsuccess = () => {
        console.log(`first: result=${first.result}, error=${first.error}`);
        const second = store.add("second", 1);
        second.onerror = (event) => {
          if (second.error.name === "ConstraintError") event.preventDefault();
          console.log(`second: result=${second.result}, error=${second.error.name}`);
        };
      };
    };
  })();
</script>

Résultat

first: result=1, error=null
second: result=undefined, error=ConstraintError
transaction: complete

Ouvrez l’exemple en tant que page HTML servie en HTTPS où IndexedDB et `crypto.randomUUID()` sont disponibles. Consultez les messages dans la console du navigateur. Le second `add()` tente d’utiliser la même clé. Le gestionnaire empêche l’annulation par défaut uniquement pour le `ConstraintError` attendu, de sorte que la première écriture peut être validée. Une fois la transaction terminée, le code ferme la connexion et demande la suppression de la base de test.

Leçons associées

  • JavaScript · Leçon 20 · Intermédiaire · Version : 3
  • JavaScript · Leçon 21 · Intermédiaire · Version : 3

Sources