Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

IDBRequest: resultado e erro de um pedido

Aprende quando ler `result` e `error` no IndexedDB e a distinguir o sucesso de um pedido da confirmação da respetiva transação.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

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 e error são duas propriedades só de leitura de uma instância de IDBRequest. Um pedido do IndexedDB representa uma operação assíncrona. Não é uma promessa (Promise), pelo que await request não espera pelo fim da operação. O IndexedDB é uma API da plataforma web, não faz parte do ECMAScript 2024 e a sua disponibilidade depende do ambiente de execução.

Enquanto request.readyState for "pending", ler qualquer das propriedades lança uma DOMException com o nome InvalidStateError. O estado "done" não indica, por si só, sucesso. Normalmente, lê o resultado no manipulador de success. Há uma exceção: no manipulador de upgradeneeded de um pedido indexedDB.open(), result já está disponível para alterar o esquema, embora o evento success final ainda não tenha ocorrido.

No evento success, error é null e result depende da operação: open() fornece uma ligação IDBDatabase, add() dá a chave do registo guardado e get() pode dar undefined se nenhum registo corresponder à chave. No evento error, result é undefined e error contém uma DOMException. Consulta request.error.name para identificar um erro como ConstraintError. Um resultado undefined, por si só, não indica uma falha. Um try...catch à volta da chamada à API apanha exceções síncronas, não as falhas comunicadas mais tarde por um evento error.

O sucesso de um pedido de escrita não significa que a transação tenha sido confirmada. Escuta complete para confirmar o commit e abort para detetar uma reversão. Por omissão, um erro de um pedido dentro de uma transação provoca o cancelamento da mesma. Se o erro for esperado e puder ser tratado em segurança, chama event.preventDefault() no manipulador de error do pedido para impedir esse cancelamento por omissão. O pedido continua a ter falhado.

Exemplos

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

Resultado

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

Abre o exemplo como uma página HTML servida por HTTPS em que estejam disponíveis IndexedDB e `crypto.randomUUID()`. Consulta as mensagens na consola do navegador. A segunda chamada a `add()` tenta usar a mesma chave. O manipulador impede o cancelamento por omissão apenas no caso do `ConstraintError` esperado, permitindo confirmar a primeira escrita. Quando a transação termina, o código fecha a ligação e pede a eliminação da base de dados de teste.

Lições relacionadas

  • JavaScript · Lição 20 · Intermédio · Versão: 3
  • JavaScript · Lição 21 · Intermédio · Versão: 3

Fontes