Transacciones: alcance, modo y autocierre

En IndexedDB toda operación ocurre dentro de una transacción, incluso las que parecen triviales. No es ceremonia: es lo que da atomicidad, aislamiento y durabilidad a una base de datos que vive dentro de una pestaña que el usuario puede cerrar en cualquier instante. Pero el modelo trae una regla que no existe en ningún otro motor que hayas usado: la transacción no espera a que tú termines, sino que se compromete sola en cuanto detecta que has dejado de darle trabajo. Esa regla, invisible mientras el código es síncrono, se convierte en la fuente número uno de errores en cuanto aparece la primera espera.

Modo y alcance se declaran de una vez

Una transacción nace con dos decisiones tomadas: sobre qué almacenes actúa y en qué modo. Ninguna de las dos se puede cambiar después.

El alcance es la lista de almacenes que vas a tocar. Si intentas abrir uno que no declaraste, recibes NotFoundError. Declarar de más es tentador y caro: cada almacén incluido en un alcance de escritura queda bloqueado para las demás transacciones que lo necesiten.

El modo admite dos valores en tu código: readonly y readwrite. Existe un tercero, versionchange, pero solo lo crea el motor durante una migración y su alcance es siempre la base entera.

// Alcance de un solo almacen, solo lectura
const lectura = db.transaction("notas", "readonly");

// Alcance multiple y escritura, con durabilidad relajada
const escritura = db.transaction(["notas", "adjuntos"], "readwrite", {
  durability: "relaxed",
});

escritura.oncomplete = () => console.log("comprometida");
escritura.onabort = () => console.warn("revertida", escritura.error);

Orden y aislamiento

Las transacciones arrancan en el orden en que las creas, y ese orden es determinista. Sobre él se aplica una regla sencilla: dos transacciones de solo lectura pueden ejecutarse a la vez aunque compartan almacenes; una de escritura excluye a cualquier otra cuyo alcance se solape con el suyo, que quedará esperando su turno.

El resultado es un aislamiento equivalente al serializable, sin que tengas que pedirlo. Dentro de una transacción ves un estado congelado y coherente: nadie va a modificar bajo tus pies el almacén que estás recorriendo.

flowchart LR
A[Transaccion creada] --> B[Activa durante el turno actual]
B --> C{Quedan peticiones pendientes}
C -->|Si| D[Inactiva pero viva esperando resultados]
D --> E[Llega un evento success y vuelve a activarse]
E --> C
C -->|No| F[Autocommit y evento complete]
B --> G[Error no capturado o abort explicito]
G --> H[Reversion total y evento abort]

Las peticiones dentro de una misma transacción también se atienden en orden de emisión, lo que permite razonar sobre secuencias sin sincronizar nada a mano: si lanzas un put y luego un get de la misma clave, el segundo verá lo que escribió el primero.

La regla del autocierre

Aquí está la trampa. Una transacción de IndexedDB está activa durante el turno del bucle de eventos en que la creaste y durante el despacho de cada evento de resultado de sus peticiones. Fuera de esos momentos está inactiva. Y en cuanto queda inactiva sin peticiones pendientes, el motor la compromete y la cierra.

No hay temporizador, no hay tiempo de espera y no hay forma de mantenerla abierta artificialmente. La transacción vive exactamente mientras la alimentas: cada nueva petición emitida desde el manejador de la anterior le devuelve la vida. Es un modelo de cadena, no de sesión.

const tx = db.transaction("notas", "readwrite");
const notas = tx.objectStore("notas");

// MAL: la red devuelve el control al bucle de eventos
const respuesta = await fetch("/api/plantilla");
notas.put(await respuesta.json()); // TransactionInactiveError

// BIEN: primero lo externo, despues la transaccion
const plantilla = await (await fetch("/api/plantilla")).json();
const tx2 = db.transaction("notas", "readwrite");
tx2.objectStore("notas").put(plantilla);
tx2.commit();

El error resultante, TransactionInactiveError, es honesto pero desconcertante la primera vez, porque el código parece correcto y la transacción parece existir: el objeto sigue ahí, simplemente ya se comprometió y ha dejado de aceptar trabajo.

Convivir con promesas

Envolver la API en promesas es correcto y recomendable, siempre que el envoltorio respete la regla. La pieza mínima convierte una petición en una promesa; la pieza que falta en casi todas las implementaciones caseras es la promesa de la transacción entera, que es la única señal fiable de que los datos están comprometidos.

const prometer = (peticion) =>
  new Promise((resolver, rechazar) => {
    peticion.onsuccess = () => resolver(peticion.result);
    peticion.onerror = () => rechazar(peticion.error);
  });

const terminada = (tx) =>
  new Promise((resolver, rechazar) => {
    tx.oncomplete = () => resolver();
    tx.onabort = () => rechazar(tx.error);
    tx.onerror = () => rechazar(tx.error);
  });

async function guardarLote(db, notas) {
  const tx = db.transaction("notas", "readwrite");
  const store = tx.objectStore("notas");
  // Todas las peticiones se emiten en el mismo turno
  const escrituras = notas.map((n) => prometer(store.put(n)));
  await Promise.all(escrituras);
  await terminada(tx); // solo aqui hay durabilidad
  return escrituras.length;
}

Esperar únicamente a la última escritura no es suficiente: la petición puede haber tenido éxito y la transacción abortar después, dejándote con un valor de retorno que miente. La biblioteca idb de Jake Archibald expone exactamente esta distinción con tx.done, y esa es la razón por la que merece la pena usarla en lugar de reescribirla.