Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Eventi delle transazioni IndexedDB: complete, abort ed error

Usa `complete` e `abort` per conoscere l’esito dell’intera transazione IndexedDB e `error` per capire perché una singola richiesta è fallita.

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

Sintassi

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();

Ascolta complete, abort ed error sulla transazione tx con addEventListener() o tramite le proprietà oncomplete, onabort e onerror. complete indica che è stato eseguito il commit dell’intera transazione. Il success di una singola richiesta non basta: un errore successivo può ancora annullarne le modifiche. Il commit non implica necessariamente che i dati siano già stati scritti fisicamente su disco; dipende dall’impostazione di durabilità e dall’ambiente di esecuzione.

abort indica che la transazione è terminata senza commit e che le sue modifiche sono state annullate. L’evento risale fino a IDBDatabase e non è annullabile. Può seguire una chiamata esplicita a tx.abort() o un errore. Nel gestore di abort, leggi tx.error: questa proprietà di sola lettura contiene una DOMException che descrive l’errore oppure null, come dopo una chiamata esplicita a tx.abort().

L’evento error nasce su un IDBRequest e risale fino al database passando per tx. Per conoscere la causa dell’errore della richiesta, leggi event.target.error, non tx.error, che potrebbe essere ancora null. Per impostazione predefinita, un errore di richiesta interrompe la transazione. Se l’errore è previsto, chiama event.preventDefault() nel gestore per evitare quella specifica interruzione; stopPropagation() da solo non basta. La richiesta rimane fallita. Per sapere com’è finita la transazione, usa complete o abort.

IndexedDB è un’API della piattaforma web, non una parte di ECMAScript 2024. Accoda le richieste mentre la transazione è attiva, per esempio subito dopo averla creata o nei gestori delle sue richieste. Dopo aver atteso un’operazione indipendente come fetch(), la transazione potrebbe non accettare più richieste. La disponibilità dipende dall’ambiente di esecuzione e dalle regole di accesso all’archiviazione.

Esempi

<!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>

Risultato

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

Servi l’esempio come pagina HTML tramite HTTPS e aprila in un browser in cui IndexedDB è disponibile e l’archiviazione dei dati è consentita. Entrambe le transazioni segnalano `ConstraintError` per una chiave duplicata. La prima annulla la scrittura iniziale; la seconda ne esegue il commit perché il gestore dell’errore impedisce l’azione predefinita.

Lezioni correlate

  • JavaScript · Lezione 20 · Intermedio · Versione: 3
  • JavaScript · Lezione 21 · Intermedio · Versione: 3

Fonti