Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

IDBRequest: risultato, errore e gestori di eventi

Leggi `result` quando una richiesta IndexedDB riesce e `error` quando fallisce. Il successo di una singola richiesta non significa che la transazione sia stata confermata.

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

Sintassi

// Read-only members; do not read either while readyState is "pending".
// request.result
// request.error

request.onsuccess = (event) => { /* read request.result */ };
request.onerror = (event) => { /* read request.error */ };

// Alternative registration; event names omit the "on" prefix.
request.addEventListener("success", handleSuccess);
request.addEventListener("error", handleError);

IDBRequest è un oggetto richiesta di IndexedDB, non una promessa (Promise). IndexedDB è un’API Web, non fa parte di ECMAScript 2024 e la sua disponibilità dipende dall’ambiente di esecuzione. Finché readyState vale "pending", leggere una delle proprietà di sola lettura result o error genera una DOMException con nome InvalidStateError. Lo stato "done" consente di leggere queste proprietà, ma non garantisce che la richiesta sia riuscita. Una richiesta IDBOpenDBRequest può risultare "done" durante upgradeneeded, prima dell’evento finale success o error.

Assegna funzioni a request.onsuccess e request.onerror per gestire rispettivamente success ed error. Una nuova assegnazione sostituisce il gestore precedente; con addEventListener() puoi aggiungere listener distinti usando il nome dell’evento senza on. In caso di successo, leggi request.result: il suo valore dipende dall’operazione. Ad esempio, add() restituisce la chiave tramite result, mentre get() può riuscire con undefined se la chiave è assente. In caso di successo, request.error vale null; in caso di fallimento, contiene una DOMException e request.result vale undefined. Un try...catch attorno alla chiamata può intercettare un’eccezione sincrona della chiamata, non un successivo fallimento della richiesta.

L’evento success non si propaga verso l’alto e non è annullabile. Per una richiesta in una transazione, error si propaga verso l’alto e per impostazione predefinita causa l’interruzione della transazione. Chiama event.preventDefault() nel gestore di un errore previsto e recuperabile per impedire tale interruzione predefinita. La richiesta rimane fallita e l’evento continua a propagarsi.

Il successo di una scrittura non implica che la transazione sia stata confermata. Invia altre richieste finché la transazione è attiva, ad esempio direttamente in un gestore di eventi della richiesta. Sulla transazione, ascolta complete per rilevare la conferma e abort per rilevare l’annullamento delle modifiche.

Esempi

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>IDBRequest: success and error</title>
</head>
<body>
  <p>Open the browser developer console to see the output.</p>
  <script>
    (() => {
      const name = `cktis-idbrequest-${window.crypto.randomUUID()}`;
      const open = window.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");

        function cleanup() {
          db.close();
          const deletion = window.indexedDB.deleteDatabase(name);
          deletion.onerror = () => console.error("cleanup:", deletion.error.name);
        }

        tx.oncomplete = () => {
          console.log("transaction: complete");
          cleanup();
        };
        tx.onabort = () => {
          console.error("transaction: aborted", tx.error?.name);
          cleanup();
        };

        const first = store.add("first", 1);
        first.onsuccess = () => console.log(`success: ${first.result}`);

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

Risultato

success: 1
error: ConstraintError
transaction: complete

Salva l’esempio in un file HTML e servilo tramite HTTPS. Apri la pagina in un browser in cui sono disponibili IndexedDB e `crypto.randomUUID()` e controlla l’output nella console di sviluppo. Il primo `add()` restituisce la chiave `1` tramite `result`; il secondo fallisce con `ConstraintError`. `preventDefault()` impedisce a quell’errore di interrompere la transazione, che può quindi emettere `complete`. Al termine della transazione il codice chiude la connessione e richiede l’eliminazione del database creato per questa esecuzione.

Lezioni correlate

  • JavaScript · Lezione 31 · Avanzato · Versione: 4

Fonti