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
- IDBRequest: result property
- IDBRequest: error property
- IDBRequest
- IDBRequest: readyState property
- IDBFactory: open() method
- IDBOpenDBRequest: upgradeneeded event
- IDBObjectStore: add() method
- IDBObjectStore: get() method
- IDBTransaction
- IDBTransaction: complete event
- IDBFactory: deleteDatabase() method
- Crypto: randomUUID() method