Integ Docs

Appearance

@happ-integ/redis ​

Клиент для Upstash Redis.

Установка ​

bash
pnpm add @happ-integ/redis

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

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

typescript
import { RedisClient } from "@happ-integ/redis";

const redis = new RedisClient("sofa");

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

typescript
// String operations
await redis.set("user:1", { name: "John" }, 3600); // TTL 1 час
const user = await redis.get<User>("user:1");
await redis.del("user:1");
await redis.delMany(["user:1", "user:2"]);

Hash (объекты) ​

typescript
// Хранить объект в виде hash
await redis.hset("user:1", {
	name: "John",
	email: "john@example.com",
});

// Получить все поля
const user = await redis.hgetall<User>("user:1");

// Получить одно поле
const name = await redis.hget("user:1", "name");

// Удалить поле
await redis.hdel("user:1", "email");

List (очередь) ​

typescript
// Добавить элементы
await redis.lpush("tasks", { id: "1", action: "send-email" });
await redis.lpush("tasks", { id: "2", action: "notify" });

// Получить и удалить элемент
const task = await redis.rpop("tasks");

// Длина списка
const len = await redis.llen("tasks");

Set (уникальные элементы) ​

typescript
// Добавить элементы
await redis.sadd("tags", "urgent", "important");

// Проверить наличие
const hasTag = await redis.sismember("tags", "urgent"); // true

// Удалить элемент
await redis.srem("tags", "important");

Rate Limiting ​

typescript
// 100 запросов в минуту
const result = await redis.rateLimit("user:123", 100, 60);

if (!result.allowed) {
	throw new Error("Rate limit exceeded");
}

console.log(result.current); // текущее значение
console.log(result.limit); // лимит

Cache-Aside Pattern ​

typescript
const data = await redis.cache(
	"expensive:key",
	3600, // TTL
	async () => {
		return await expensiveOperation();
	}
);

Health Check ​

typescript
const isHealthy = await redis.healthCheck();

API ​

RedisClient ​

typescript
new RedisClient(project: string, credentials?: RedisCredentials)

Параметры:

ПараметрТипОписание
projectstringИмя проекта (префикс ключей)
credentialsRedisCredentials{url, token} (опционально, если используются env)

Требуемые переменные (если credentials не переданы):

UPSTASH_REDIS_URL=https://...
UPSTASH_REDIS_TOKEN=...

Методы ​

String операции ​

  • get<T>(key): Promise<T | null>
  • set(key, value, ttlSeconds?): Promise<void>
  • del(key): Promise<void>
  • delMany(keys[]): Promise<void>

Hash операции ​

  • hset(key, data): Promise<void>
  • hget<T>(key, field): Promise<T | null>
  • hgetall<T>(key): Promise<T | null>
  • hdel(key, field): Promise<void>

List операции ​

  • lpush(key, ...values): Promise<void>
  • rpop<T>(key): Promise<T | null>
  • llen(key): Promise<number>

Set операции ​

  • sadd(key, ...members): Promise<void>
  • sismember(key, member): Promise<boolean>
  • srem(key, member): Promise<void>

Специальные ​

  • rateLimit(key, limit, windowSeconds): Promise<IRateLimitResult>
  • cache<T>(key, ttl, fn): Promise<T>
  • healthCheck(): Promise<boolean>

Преимущества Redis vs KV ​

  • ✅ Atomic operations (rate limiting, counters)
  • ✅ Hash, List, Set структуры
  • ✅ Pub/Sub
  • ✅ Rate limiting
  • ❌ Медленнее для простого кэша

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

  • ✅ Rate limiting
  • ✅ Очереди задач
  • ✅ Сложные структуры (hash, list, set)
  • ✅ Atomic counters
  • ❌ Простое кэширование — используйте KV (быстрее)

Получить Upstash ​

  1. Регистрация: https://console.upstash.com
  2. Создать Redis базу
  3. Скопировать URL и Token
  4. Добавить в Doppler / env