Cursores: recorrer sin cargar en memoria

Leer con getAll es cómodo hasta el día en que el almacén tiene doscientos mil registros y la pestaña se queda sin memoria intentando materializarlos todos a la vez. El cursor es la respuesta de IndexedDB a ese problema: un iterador con posición que te entrega un registro cada vez y solo avanza cuando tú se lo pides. Pero además de resolver la memoria, el cursor resuelve algo que ya viste en la lección de transacciones —cada avance es una petición nueva que mantiene viva la transacción—, y sobre esa mecánica se construye la única paginación que no se degrada al llegar a la página doscientos.

El iterador que se alimenta

Un cursor no es una lista perezosa ni un iterador de JavaScript: es una petición que se vuelve a disparar. Llamas a openCursor una sola vez y recibes un objeto de petición; cada vez que llamas a continue sobre el cursor, esa misma petición vuelve a resolverse y su manejador de éxito se ejecuta de nuevo, ahora con el cursor apuntando al siguiente registro. Cuando no queda ninguno, el resultado es null y el bucle termina.

const tx = db.transaction("notas", "readonly");
const peticion = tx.objectStore("notas").openCursor();

peticion.onsuccess = () => {
  const cursor = peticion.result;
  if (!cursor) return; // fin del recorrido
  procesar(cursor.value);
  cursor.continue();   // reencola la misma peticion
};

Esa reencolación es exactamente el mecanismo que mantiene viva la transacción: mientras haya un continue pendiente, hay trabajo pendiente, y el motor no comprometerá nada. Un cursor abandonado a mitad de recorrido, en cambio, deja la transacción sin peticiones y provoca su cierre inmediato.

Direcciones y variantes únicas

El segundo argumento de openCursor decide el sentido y el tratamiento de los duplicados. Son cuatro valores y cada uno responde a un tipo de pregunta distinto.

Además de continue, el cursor admite dos movimientos más. advance(n) salta n posiciones y continue(clave) reposiciona el cursor en la primera entrada mayor o igual que esa clave, lo que permite hacer saltos dirigidos sin abrir un cursor nuevo.

flowchart TD
A[openCursor sobre un rango] --> B[Evento success con el cursor posicionado]
B --> C{El cursor es nulo}
C -->|Si| D[Fin del recorrido y autocommit]
C -->|No| E[Se procesa el registro actual]
E --> F{Que movimiento se pide}
F -->|continue| G[Siguiente entrada del rango]
F -->|continue con clave| H[Salto dirigido a esa clave]
F -->|advance con n| I[Salto de n posiciones]
G --> B
H --> B
I --> B

Cursores de índice y de solo clave

Cuando el cursor nace de un índice y no de un almacén, expone tres datos distintos que conviene no confundir: cursor.key es la clave del índice, cursor.primaryKey es la clave del registro en el almacén y cursor.value es el registro completo. El motor hace la segunda búsqueda por ti, pero la hace.

De ahí sale la optimización más rentable del capítulo. openKeyCursor abre un cursor que no deserializa el valor: solo te entrega la clave del índice y la clave primaria. Si estás contando, filtrando o recogiendo identificadores para una segunda ronda, evitas por completo el coste de clonar cada registro, que en objetos grandes domina el tiempo total.

const indice = tx.objectStore("notas").index("por_libreta_fecha");

// Solo claves: ni un solo valor se deserializa
const soloClaves = indice.openKeyCursor(rango);
const ids = [];
soloClaves.onsuccess = () => {
  const cursor = soloClaves.result;
  if (!cursor) return;
  ids.push(cursor.primaryKey);
  cursor.continue();
};

Dentro de una transacción de escritura, el cursor también modifica lo que recorre: cursor.update(valor) reescribe el registro actual y cursor.delete() lo borra, ambos sin interrumpir el recorrido. Es la forma canónica de aplicar una migración de datos registro a registro.

Paginación por asiento

El anti-patrón es evidente en cuanto se nombra: abrir un cursor y llamar a advance(2000) para llegar a la página cien. El coste es lineal en el desplazamiento, así que cada página siguiente es más cara que la anterior y la aplicación se degrada exactamente donde más datos hay.

La solución es el método del asiento: no guardas cuántos elementos saltaste, guardas dónde te quedaste. La página siguiente es un rango que empieza justo después de la última clave vista, y su coste es constante sea cual sea la página.

// Pagina siguiente a partir de la ultima posicion vista
function pagina(indice, limite, ultimaClave, ultimaPrimaria) {
  const rango = ultimaClave === undefined
    ? null
    : IDBKeyRange.lowerBound(ultimaClave);
  const peticion = indice.openCursor(rango, "next");
  const filas = [];
  let primerAvance = ultimaClave !== undefined;

  peticion.onsuccess = () => {
    const cursor = peticion.result;
    if (!cursor) return entregar(filas);
    if (primerAvance) {
      primerAvance = false;
      // Indice no unico: retomar por la pareja clave mas clave primaria
      return cursor.continuePrimaryKey(ultimaClave, ultimaPrimaria);
    }
    filas.push(cursor.value);
    if (filas.length === limite) return entregar(filas, cursor);
    cursor.continue();
  };
}

La pieza que casi nadie conoce es continuePrimaryKey. Sobre un índice no único, la última clave de índice vista no basta para retomar sin repetir ni saltar elementos, porque puede haber varios registros compartiéndola. El par formado por la clave del índice y la clave primaria sí es un asiento único, y ese método es el que permite posicionarse exactamente en él.

El asiento tiene además una propiedad que el desplazamiento no tiene y que importa mucho en local-first: es estable frente a escrituras concurrentes. Si mientras el usuario pagina llega una tanda de registros nuevos por sincronización, un desplazamiento numérico desplaza todas las páginas siguientes y produce filas repetidas o perdidas; un asiento sigue apuntando al mismo punto del orden, y lo nuevo aparece donde le corresponde.