CKTIS / JavaScript
IDBTransaction — uma transação IndexedDB
IDBTransaction agrupa operações IndexedDB para que as alterações sejam confirmadas em conjunto ou revertidas. Saiba mais sobre o âmbito dos armazéns de objetos, o evento complete, o cancelamento com abort() e a propriedade error.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
const tx = db.transaction("items", "readwrite");
const store = tx.objectStore("items");
tx.addEventListener("complete", () => {});
tx.addEventListener("abort", () => { console.error(tx.error); });
// To cancel before committing: tx.abort();IDBTransaction agrupa operações IndexedDB de forma atómica: todas as alterações são confirmadas ou revertidas. db.transaction() especifica o âmbito dos armazéns de objetos e o modo: readonly para leitura, readwrite também para escrita. É uma Web API, não faz parte de ECMAScript; o Node 24 não comprova a sua disponibilidade no navegador. Verifique se indexedDB existe no ambiente de destino.
IDBTransaction.objectStore(name) devolve uma referência a um armazém de objetos dentro do âmbito da transação; outro nome provoca NotFoundError. Agende operações enquanto a transação estiver ativa, normalmente logo após a criação ou nos processadores de eventos dos seus pedidos. Esperar por operações assíncronas não relacionadas pode permitir que a transação termine automaticamente.
IDBTransaction.complete designa o evento complete, processado através de oncomplete ou addEventListener, e não um método. Confirma a conclusão; o success de um pedido individual não a garante. IDBTransaction.abort() reverte as alterações e provoca um evento abort; chamá-lo durante a confirmação ou após a conclusão provoca InvalidStateError.
IDBTransaction.error é uma propriedade que contém uma DOMException que descreve a falha, ou null, inclusive após um abort() manual. Não a confunda com o evento error: os erros dos pedidos podem propagar-se até à transação.
Se a base de dados abrir e as operações decorrerem como previsto, o código escreve 42 com a chave "answer" e aguarda pelo evento complete, que confirma a transação. Em seguida, cancela outra transação que escreve 99, lê o valor que se manteve, 42, e apresenta-o. Na execução apresentada, a abertura da base de dados falha com SecurityError antes de se iniciar qualquer transação. O resultado Transaction not started: SecurityError não mostra, portanto, qualquer escrita ou confirmação.
Exemplos
(async () => {
const name = `cktis-transaction-${crypto.getRandomValues(new Uint32Array(4)).join('-')}`;
const result = request => new Promise((resolve, reject) => {
request.onsuccess = () => resolve(request.result);
request.onerror = () => reject(request.error);
});
const completed = tx => new Promise((resolve, reject) => {
tx.oncomplete = resolve;
tx.onabort = () => reject(tx.error ?? new DOMException('Transaction aborted', 'AbortError'));
});
let db;
try {
const open = indexedDB.open(name, 1);
open.onupgradeneeded = () => open.result.createObjectStore('items');
db = await result(open);
const write = db.transaction('items', 'readwrite');
const scope = Array.from(write.objectStoreNames).join(', ');
const committed = completed(write);
write.objectStore('items').put(42, 'answer');
await committed;
const undo = db.transaction('items', 'readwrite');
const aborted = new Promise((resolve, reject) => {
undo.onabort = () => resolve(undo.error);
undo.oncomplete = () => reject(new Error('Expected an abort'));
});
const update = undo.objectStore('items').put(99, 'answer');
update.onsuccess = () => undo.abort();
const abortError = await aborted;
const read = db.transaction('items', 'readonly');
const [stored] = await Promise.all([
result(read.objectStore('items').get('answer')),
completed(read)
]);
console.log(`Scope: ${scope}; stored after rollback: ${stored}; abort error: ${abortError?.name ?? 'null'}`);
} catch (error) {
if (!db && error.name === 'SecurityError') {
console.log(`Transaction not started: ${error.name}`);
} else {
console.log(`Transaction example failed: ${error.name}`);
}
} finally {
if (db) {
db.close();
await result(indexedDB.deleteDatabase(name));
}
}
})();Resultado
Transaction not started: SecurityError
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.