La API de KV: get, put, delete y list

La API de KV es minúscula y esa es su virtud: no hay lenguaje de consulta, ni transacciones, ni índices que mantener. Hay un objeto —el binding env.MI_KV, que apunta al namespace declarado en wrangler.jsonc— y sobre él cuatro métodos asíncronos: get para leer, put para escribir, delete para borrar y list para enumerar claves. Toda la potencia y todos los límites de KV se expresan en esa superficie diminuta. Dominarla es sobre todo entender los detalles que no saltan a la vista: qué tipo pides al leer, qué formatos admite el valor al escribir, y por qué list no es una consulta sino un recorrido paginado.

Leer con get y sus tipos

get recibe una clave y devuelve una promesa con su valor, o null si la clave no existe. El detalle que marca la diferencia es el segundo argumento: el tipo en que quieres el valor. Por defecto es text, que te da una cadena; json deserializa el valor y te devuelve el objeto ya parseado; stream te entrega un ReadableStream para valores grandes que prefieres no cargar enteros en memoria; y arrayBuffer te da los bytes crudos.

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // texto plano: el retorno es string o null
    const nombre = await env.MI_KV.get("usuario:42:nombre");

    // json: KV deserializa y te da el objeto directamente
    const perfil = await env.MI_KV.get("usuario:42", { type: "json" });

    // stream: para valores grandes, sin cargarlos enteros en memoria
    const imagen = await env.MI_KV.get("logo.png", { type: "stream" });

    return Response.json({ nombre, perfil, tieneImagen: imagen !== null });
  },
};

La elección del tipo no es cosmética. Pedir json te ahorra el JSON.parse manual pero falla si el valor no es JSON válido. Pedir stream o arrayBuffer es la forma correcta de servir binarios —una imagen, un PDF cacheado— sin materializarlos en memoria, algo que importa cuando te acercas al límite de 25 MiB por valor. La regla práctica: text para cadenas, json para objetos que tú mismo serializaste, stream para lo grande y binario.

Escribir con put y borrar con delete

put toma una clave y un valor. El valor puede ser una cadena, un ArrayBuffer o un ReadableStream, así que puedes guardar tanto texto y JSON serializado como binarios. Un tercer argumento opcional lleva la configuración de expiración y metadata que veremos en la siguiente lección. delete es aún más simple: recibe la clave y la borra, sin quejarse si no existía.

// guardar texto o JSON (serializado a mano)
await env.MI_KV.put("usuario:42:nombre", "Ada");
await env.MI_KV.put("usuario:42", JSON.stringify({ nombre: "Ada", plan: "pro" }));

// guardar binario desde un ReadableStream (por ejemplo, el body de un fetch)
const origen = await fetch("https://ejemplo.com/logo.png");
await env.MI_KV.put("logo.png", origen.body);

// borrar
await env.MI_KV.delete("usuario:42:nombre");

Aquí conviene recordar la asimetría del nivel: get es la operación barata y put la cara. Escribir la misma clave muchas veces por segundo no solo es lento en propagar, sino que está desaconsejado —KV admite del orden de una escritura por segundo y clave—. Si te descubres llamando a put en un bucle caliente sobre la misma clave, la herramienta correcta no es KV.

Enumerar con list

list no es una consulta: es un recorrido del espacio de claves. Devuelve las claves —no los valores— ordenadas lexicográficamente, filtradas opcionalmente por un prefix, y en páginas de como mucho 1000 elementos. Cuando hay más, el resultado trae list_complete: false y un cursor con el que pides la página siguiente. Cada clave listada incluye su nombre, su expiración si la tiene y su metadata.

async function todasLasClaves(env: Env, prefijo: string): Promise<string[]> {
  const claves: string[] = [];
  let cursor: string | undefined;
  do {
    const pagina = await env.MI_KV.list({ prefix: prefijo, cursor });
    for (const k of pagina.keys) claves.push(k.name);
    cursor = pagina.list_complete ? undefined : pagina.cursor;
  } while (cursor);
  return claves;
}

El diseño del prefijo es tu único “índice”. Nombrando las claves con jerarquía —usuario:42:sesion, usuario:42:carrito— puedes listar todo lo de un usuario con prefix: "usuario:42:". Y cuando necesitas el valor junto a su contexto, getWithMetadata te da ambos en una sola lectura, sin una segunda ida al almacén:

const { value, metadata } = await env.MI_KV.getWithMetadata("usuario:42", {
  type: "json",
});

flowchart LR
L[list con prefix] --> P[pagina de hasta 1000 claves]
P --> Q{list_complete}
Q -- si --> FIN[recorrido terminado]
Q -- no --> N[pide de nuevo con el cursor]
N --> P
style P fill:#89b4fa,color:#11111b
style FIN fill:#a6e3a1,color:#11111b
style Q fill:#fab387,color:#11111b