Integ Docs

Appearance

@happ-integ/kv ​

Низкоуровневый клиент для Cloudflare KV.

Установка ​

bash
pnpm add @happ-integ/kv

Использование ​

Инициализация ​

typescript
import { KVClient } from "@happ-integ/kv";

const kv = new KVClient(env.KV, "sofa");

Базовые операции ​

typescript
// Set с TTL (1 час)
await kv.set("user:1", { name: "John" }, 3600);

// Get
const user = await kv.get<User>("user:1");

// Delete
await kv.delete("user:1");

// Удалить много
await kv.delMany(["user:1", "user:2"]);

Список ключей ​

typescript
// Получить ключи по префиксу
const keys = await kv.list("user:");
// => { keys: ["user:1", "user:2"], listComplete: true }

Метаданные ​

typescript
const result = await kv.getWithMetadata<User>("user:1");
console.log(result.value); // User
console.log(result.metadata); // { expiration: 1234567890 }

Health Check ​

typescript
const isHealthy = await kv.healthCheck();

API ​

KVClient ​

typescript
new KVClient(kv: KVNamespace, project: string)

Параметры:

ПараметрТипОписание
kvKVNamespaceKV binding из env
projectstringИмя проекта (для префиксов ключей)

Методы ​

get<T>(key): Promise<T | null> ​

set(key, value, ttlSeconds?): Promise<void> ​

delete(key): Promise<void> ​

delMany(keys[]): Promise<void> ​

getWithMetadata<T>(key): Promise<{value, metadata}> ​

list(prefix?): Promise<{keys, listComplete}> ​

healthCheck(): Promise<boolean> ​

Ограничения KV ​

  • 🟡 Eventually consistent — задержка ~60 сек между регионами
  • 🟡 Лимит 25 MB на одно значение
  • ✅ Быстрый для простого кэширования

Изоляция проектов ​

Ключи автоматически префиксируются:

typescript
const kv = new KVClient(env.KV, "sofa");
await kv.set("user:1", {...}); // Ключ становится "sofa:user:1"

Когда использовать ​

  • ✅ Простое кэширование
  • ✅ Хранение конфигурации
  • ✅ Хранение состояния
  • ✅ Сессии