Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

IDBRequest: risultato ed errore di una richiesta

Scopri quando leggere `result` ed `error` in IndexedDB e come distinguere il successo di una richiesta dal commit della transazione.

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

Sintassi

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 ed error sono due proprietà di sola lettura di un’istanza di IDBRequest. Una richiesta IndexedDB rappresenta un’operazione asincrona. Non è una Promise, quindi await request non attende che l’operazione termini. IndexedDB è un’API della piattaforma web, non fa parte di ECMAScript 2024 e la sua disponibilità dipende dall’ambiente di esecuzione.

Finché request.readyState vale "pending", leggere una delle due proprietà genera una DOMException chiamata InvalidStateError. Lo stato "done" non indica di per sé un successo. Di norma si legge il risultato nel gestore di success. Un’eccezione: nel gestore di upgradeneeded di una richiesta indexedDB.open(), result è già disponibile per modificare lo schema, anche se l’evento success finale non è ancora scattato.

Con success, error vale null e result dipende dall’operazione: open() fornisce una connessione IDBDatabase, add() restituisce la chiave del record salvato e get() può restituire undefined se nessun record corrisponde alla chiave. Con error, result vale undefined ed error contiene una DOMException. Esamina request.error.name per riconoscere un errore come ConstraintError. Un risultato undefined da solo non indica un fallimento. Un try...catch attorno alla chiamata all’API intercetta le eccezioni sincrone, non gli errori segnalati in seguito da un evento error.

Il successo di una richiesta di scrittura non significa che la transazione sia stata confermata. Ascolta complete per accertare il commit e abort per rilevare un rollback. Per impostazione predefinita, un errore di una richiesta all’interno di una transazione la interrompe. Se l’errore è previsto e puoi gestirlo in sicurezza, chiama event.preventDefault() nel gestore di error della richiesta per evitare l’interruzione predefinita. La richiesta rimane comunque fallita.

Esempi

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

Risultato

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

Apri l’esempio come pagina HTML servita tramite HTTPS in cui siano disponibili IndexedDB e `crypto.randomUUID()`. Controlla i messaggi nella console del browser. La seconda chiamata a `add()` tenta di usare la stessa chiave. Il gestore impedisce l’interruzione predefinita solo per il `ConstraintError` atteso, così la prima scrittura può essere confermata. Al termine della transazione il codice chiude la connessione e richiede la rimozione del database di prova.

Lezioni correlate

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

Fonti