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

CKTIS / JavaScript

Événements de transaction IndexedDB : complete, abort et error

Utilisez `complete` et `abort` pour connaître l’issue de toute la transaction IndexedDB, et `error` pour diagnostiquer l’échec d’une requête.

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

Syntaxe

tx.addEventListener("complete", onComplete);
tx.addEventListener("abort", onAbort);
tx.addEventListener("error", onRequestError);

// Property-based alternatives:
tx.oncomplete = onComplete;
tx.onabort = onAbort;
tx.onerror = onRequestError;

// Read the transaction's error, if any:
const failure = tx.error;

// To explicitly roll back a transaction that can still be aborted:
tx.abort();

Écoutez complete, abort et error sur la transaction tx avec addEventListener() ou les propriétés oncomplete, onabort et onerror. complete indique que la transaction entière a été validée. Le success d’une requête ne suffit pas : un échec ultérieur peut encore annuler ses modifications. La validation ne garantit pas toujours que les données ont été écrites physiquement sur le disque ; cela dépend du réglage de durabilité et de l’environnement d’exécution.

abort indique que la transaction s’est terminée sans validation et que ses modifications ont été annulées. L’événement remonte jusqu’à IDBDatabase et n’est pas annulable. Il peut suivre un appel explicite à tx.abort() ou un échec. Dans le gestionnaire de abort, lisez tx.error : cette propriété en lecture seule contient une DOMException décrivant l’échec, ou null, notamment après un appel explicite à tx.abort().

Un événement error provient d’un IDBRequest et remonte à la base de données via tx. Pour connaître la cause de l’échec de la requête, lisez event.target.error, et non tx.error, qui peut encore valoir null. Par défaut, l’échec d’une requête interrompt la transaction. Pour une erreur attendue, appelez event.preventDefault() dans le gestionnaire afin d’empêcher cette interruption précise ; stopPropagation() seul ne suffit pas. La requête reste en échec. Fiez-vous à complete ou à abort pour connaître l’issue finale.

IndexedDB est une API de la plateforme web, pas une partie d’ECMAScript 2024. Ajoutez les requêtes pendant que la transaction est active, par exemple juste après sa création ou dans les gestionnaires de ses requêtes. Après avoir attendu une opération indépendante comme fetch(), il se peut que la transaction n’accepte plus de requêtes. La disponibilité dépend de l’environnement d’exécution et de la politique de stockage.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IndexedDB transaction events</title>
</head>
<body>
<pre id="output"></pre>
<script>
void (async () => {
  const output = document.getElementById("output");
  function log(line) {
    console.log(line);
    output.textContent += `${line}\n`;
  }

  const name = `cktis-tx-${Date.now()}-${Math.random().toString(36).slice(2)}`;
  const indexedDB = window.indexedDB;
  const open = indexedDB.open(name, 1);
  open.onupgradeneeded = () => open.result.createObjectStore("items");
  const db = await new Promise((resolve, reject) => {
    open.onsuccess = () => resolve(open.result);
    open.onerror = () => reject(open.error);
  });

  function write(label, cancelError) {
    return new Promise((resolve) => {
      const tx = db.transaction("items", "readwrite");
      tx.oncomplete = () => resolve("complete");
      tx.onabort = () => resolve(`abort: ${tx.error?.name ?? "no error"}`);
      tx.onerror = (event) => {
        log(`${label} error: ${event.target.error.name}`);
      };

      const items = tx.objectStore("items");
      items.add("first", label);
      const duplicate = items.add("second", label);
      if (cancelError) {
        duplicate.onerror = (event) => {
          if (duplicate.error.name === "ConstraintError") event.preventDefault();
        };
      }
    });
  }

  try {
    for (const [label, cancelError] of [["rollback", false], ["recover", true]]) {
      log(`${label} ${await write(label, cancelError)}`);
    }

    const values = await new Promise((resolve, reject) => {
      const tx = db.transaction("items", "readonly");
      const items = tx.objectStore("items");
      const rolledBack = items.get("rollback");
      const recovered = items.get("recover");
      tx.oncomplete = () => resolve([rolledBack.result, recovered.result]);
      tx.onabort = () => reject(tx.error ?? new Error("Read aborted"));
    });
    log(`stored: ${values.map(String).join(",")}`);
  } finally {
    db.close();
    await new Promise((resolve, reject) => {
      const deletion = indexedDB.deleteDatabase(name);
      deletion.onsuccess = () => resolve();
      deletion.onerror = () => reject(deletion.error);
    });
  }
})().catch(console.error);
</script>
</body>
</html>

Résultat

rollback error: ConstraintError
rollback abort: ConstraintError
recover error: ConstraintError
recover complete
stored: undefined,first

Servez l’exemple sous forme de page HTML via HTTPS et ouvrez-la dans un navigateur où IndexedDB est disponible et où le stockage est autorisé. Les deux transactions signalent `ConstraintError` pour une clé en double. La première annule son écriture initiale ; la seconde la valide parce que le gestionnaire d’erreur empêche l’action par défaut.

Leçons associées

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

Sources