kv-one: almacén de claves sin dependencias que funciona en navegador, Node.js y Cloudflare Workers
El autor lanzó kv-one, una biblioteca de KV con API unificada, soporte TTL y sin dependencias externas, compatible con los tres entornos más usados.
El proyecto kv-one llega para acabar con la fragmentación de APIs de caché que obliga a los desarrolladores a escribir código diferente para cada entorno. Con una sola importación import { kv } from 'kv-one' la misma llamada kv.set() o kv.get() funciona en el navegador, en Node.js y en Cloudflare Workers.
Un API única y asíncrona
Todas las operaciones son promesas, por lo que nunca bloquean el bucle de eventos. El código de ejemplo muestra cómo guardar un usuario y recuperarlo con tipado TypeScript sin preocuparse del backend subyacente:
await kv.set('user', { name: 'Alice', role: 'admin' })
const user = await kv.get<{ name: string; role: string }>('user')
TTL integrado y sin dependencia del motor
El tiempo de vida (TTL) se define en segundos y se gestiona a nivel de biblioteca, lo que garantiza el mismo comportamiento tanto si el backend es localStorage, memoria en proceso o Cloudflare KV. Un set con { ttl: 3600 } expirará automáticamente después de una hora en cualquier runtime.
Namespaces para evitar colisiones
kv.namespace('users') crea un almacén aislado que antepone el prefijo a cada clave. Esto permite construir aplicaciones multi‑tenant sin riesgos de sobrescritura y simplifica la enumeración de claves mediante keys().
Soporte nativo para Cloudflare Workers
El paquete expone un adaptador específico que se integra en el archivo workers.ts:
import { createKV, CloudflareAdapter } from 'kv-one'
export default {
async fetch(request, env) {
const store = createKV({ adapter: new CloudflareAdapter({ namespace: env.MY_KV }) })
await store.set('visits', count, { ttl: 86400 })
const visits = await store.get<number>('visits')
return new Response(String(visits))
}
}
Hook de React para estado reactivo
Con useKV los componentes pueden suscribirse a un valor KV y reaccionar a cambios sin código adicional. El hook devuelve value, setValue y loading, facilitando la implementación de UI que dependen de datos persistentes.
Seguridad y tipado de errores
La biblioteca incluye validación de claves, detección de referencias circulares y protección contra contaminación de prototipos. Los errores se exponen como clases tipadas (KVError, TTLError, KeyValidationError, AdapterError), evitando silencios que dificultan la depuración.
Instalación y tamaño
npm i kv-one instala solo 31 KB de código, sin dependencias externas como idb-keyval o better-sqlite3. Para pruebas se pueden forzar adaptadores en memoria o localStorage mediante createKV.
En resumen, kv-one unifica la gestión de claves en los entornos más habituales, añade TTL y namespaces de serie, y lo hace con un paquete extremadamente ligero. Queda por ver cómo evoluciona la comunidad y si el proyecto ganará tracción frente a los adaptadores más especializados.
