Los envoltorios: qué aportan de verdad sobre la API cruda

La API de IndexedDB se diseñó cuando las promesas todavía no formaban parte del lenguaje, y se nota en cada línea: peticiones con manejadores de eventos, transacciones que se confirman solas por una regla implícita, cambios de versión que se declaran con código imperativo y cero notificación cuando los datos cambian. Los envoltorios existen para tapar eso. Conviene saber exactamente qué tapan, qué no pueden tapar y en qué punto la dependencia deja de compensar.

Los cuatro déficits de la API cruda

De los cuatro, el primero es cosmético y el cuarto es arquitectónico. Un proyecto puede vivir perfectamente sin promesas bonitas; ninguno vive bien sin saber cuándo han cambiado sus datos. Ese es el eje sobre el que conviene elegir.

flowchart TB
A[API cruda: eventos, sin tipos, sin consultas, sin avisos] --> B[Envoltorio de clave valor]
A --> C[Envoltorio fino con promesas]
A --> D[Capa gruesa con esquema y consultas]
B --> B1[cubre: promesas]
C --> C1[cubre: promesas y ergonomia nativa]
D --> D1[cubre: promesas, tipado, consultas, observabilidad]
B1 --> Z[ninguno cambia el coste fisico de debajo]
C1 --> Z
D1 --> Z

El diagrama tiene un final deliberado. La columna de lo que cada capa cubre crece hacia abajo, pero todas terminan en el mismo nodo, y ese nodo es el que decide el rendimiento de la aplicación.

El envoltorio fino: conservar la semántica

La aproximación mínima consiste en envolver la API sin reinterpretarla: las peticiones se convierten en promesas, los cursores en iterables asíncronos, y todo lo demás —el modelo de transacciones, la regla de auto-confirmación, los índices, los rangos— sigue siendo exactamente el nativo. idb es el representante canónico de esta escuela, y su virtud es que no hay nada que desaprender: si conoces IndexedDB, ya lo conoces.

import { openDB } from "idb";

const db = await openDB("app", 3, {
  upgrade(db, anterior, nueva, tx) {
    if (anterior < 1) {
      const s = db.createObjectStore("docs", { keyPath: "id" });
      s.createIndex("porAutor", "autorId");
    }
    if (anterior < 3) tx.objectStore("docs").createIndex("porFecha", "actualizado");
  },
});

// Atajos que abren su propia transaccion, para operaciones sueltas.
const doc = await db.get("docs", 7);

// Y la transaccion explicita para los lotes, con el patron correcto.
const tx = db.transaction("docs", "readwrite", { durability: "relaxed" });
for (const r of lote) tx.store.put(r);   // sin await dentro del bucle
await tx.done;                            // una sola confirmacion

Por debajo de este nivel existe todavía un escalón: los envoltorios de clave-valor puro, que exponen get, set, del y poco más sobre un único almacén. Resuelven el caso de “quiero persistir cuatro cosas” con una superficie mínima, y son la respuesta correcta a un problema que mucha gente ataca con una base de datos entera.

La capa gruesa: cambiar de modelo

Dexie ocupa el otro extremo. No envuelve la API: propone un modelo distinto y traduce. El esquema se declara con una cadena por almacén en la que la primera posición es la clave primaria y el resto son índices, con marcas para el auto-incremento, la unicidad, la multi-entrada y las claves compuestas. Las versiones se declaran de forma acumulativa, cada una con su función de actualización opcional.

import Dexie from "dexie";

const db = new Dexie("app");
db.version(3).stores({
  docs: "id, autorId, actualizado, *etiquetas, [autorId+actualizado]",
});

// Consultas expresadas como intencion, no como recorrido de indice.
const recientes = await db.docs
  .where("[autorId+actualizado]")
  .between([3, desde], [3, hasta])
  .reverse()
  .limit(50)
  .toArray();

// Escritura por lotes en una sola transaccion, sin escribir el bucle.
await db.docs.bulkPut(lote);

Lo que aporta sobre los cuatro ejes es concreto. En consultas, un lenguaje encadenable con rangos, conjuntos de valores, ordenación y paginación, que se traduce a operaciones de índice cuando puede y cae a filtrado en memoria cuando no —conviene saber cuándo ocurre cada cosa, porque la sintaxis no lo distingue—. En tipado, tablas parametrizadas por el tipo del registro y el de su clave, de modo que el compilador verifica la forma de lo que escribes y de lo que lees. En transacciones, un bloque explícito que sobrevive a los await internos, resolviendo la trampa que el envoltorio fino conserva. En observabilidad, consultas vivas que se vuelven a ejecutar cuando cambia algo de lo que dependen, dentro de la pestaña y entre pestañas, más ganchos por operación para reaccionar a las escrituras.

// Una consulta viva: se reevalua sola cuando alguien escribe lo que observa.
const observable = Dexie.liveQuery(() => db.docs.where("autorId").equals(3).toArray());

Cuándo no compensa

Ningún envoltorio cambia la física de las cuatro lecciones anteriores. El clonado estructurado sigue recorriendo tu grafo nodo a nodo; la transacción sigue cobrando por confirmación; los índices siguen reescribiéndose en cada put; el disco sigue estando donde estaba. Un envoltorio puede empujarte a escribir el patrón correcto —bulkPut agrupa por ti, y eso ya vale mucho— pero jamás va a hacer rápido un esquema mal diseñado. Si tu problema es rendimiento, la solución está en el nivel 8.4, no en la lista de dependencias.