@windrun-huaiin/backend-core 11.0.3 → 13.0.0

package/src/lib/upstash/redis-counter.ts

@@ -0,0 +1,51 @@
+import { getRedis } from '../upstash-config';
+
+/**
+ * Increment a counter (e.g. views, forwards). Returns null if Redis is unavailable.
+ */
+export const incrCounter = async (key: string, delta = 1): Promise<number | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+  return redis.incrby(key, delta);
+};
+
+/**
+ * Get a counter value. Returns null if Redis is unavailable.
+ */
+export const getCounter = async (key: string): Promise<number | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+  const value = await redis.get<number>(key);
+  return value ?? 0;
+};
+
+/**
+ * Increment a unique counter via SET (e.g. unique views). Returns null if Redis is unavailable.
+ */
+export const incrUniqueCounter = async (setKey: string, memberId: string): Promise<number | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  const added = await redis.sadd(setKey, memberId);
+  if (added === 1) {
+    return redis.scard(setKey);
+  }
+  return redis.scard(setKey);
+};
+
+/**
+ * Get unique counter value (SET cardinality). Returns null if Redis is unavailable.
+ */
+export const getUniqueCounter = async (setKey: string): Promise<number | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+  return redis.scard(setKey);
+};

package/src/lib/upstash/redis-favorite.ts

@@ -0,0 +1,75 @@
+import { getRedis } from '../upstash-config';
+
+const favoriteTargetKey = (targetId: string): string => `favorite:target:${targetId}`;
+const favoriteUserKey = (userId: string): string => `favorite:user:${userId}`;
+
+/**
+ * Favorite a target. Returns true if added, false if already favorited, null if Redis is unavailable.
+ */
+export const addFavorite = async (targetId: string, userId: string): Promise<boolean | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  const added = await redis.sadd(favoriteTargetKey(targetId), userId);
+  if (added === 1) {
+    await redis.sadd(favoriteUserKey(userId), targetId);
+    return true;
+  }
+  return false;
+};
+
+/**
+ * Remove a favorite. Returns true if removed, false if not found, null if Redis is unavailable.
+ */
+export const removeFavorite = async (targetId: string, userId: string): Promise<boolean | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  const removed = await redis.srem(favoriteTargetKey(targetId), userId);
+  if (removed === 1) {
+    await redis.srem(favoriteUserKey(userId), targetId);
+    return true;
+  }
+  return false;
+};
+
+/**
+ * Check whether a user has favorited a target. Returns null if Redis is unavailable.
+ */
+export const isFavorited = async (targetId: string, userId: string): Promise<boolean | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  const result = await redis.sismember(favoriteTargetKey(targetId), userId);
+  return result === 1;
+};
+
+/**
+ * Get favorite count for a target. Returns null if Redis is unavailable.
+ */
+export const getFavoriteCount = async (targetId: string): Promise<number | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  return redis.scard(favoriteTargetKey(targetId));
+};
+
+/**
+ * Get target ids favorited by a user. Returns null if Redis is unavailable.
+ */
+export const getUserFavorites = async (userId: string): Promise<string[] | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  return redis.smembers<string[]>(favoriteUserKey(userId));
+};

package/src/lib/upstash/redis-like.ts

@@ -0,0 +1,75 @@
+import { getRedis } from '../upstash-config';
+
+const likeTargetKey = (targetId: string): string => `like:target:${targetId}`;
+const likeUserKey = (userId: string): string => `like:user:${userId}`;
+
+/**
+ * Like a target. Returns true if the like was added, false if it already existed, null if Redis is unavailable.
+ */
+export const likeTarget = async (targetId: string, userId: string): Promise<boolean | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  const added = await redis.sadd(likeTargetKey(targetId), userId);
+  if (added === 1) {
+    await redis.sadd(likeUserKey(userId), targetId);
+    return true;
+  }
+  return false;
+};
+
+/**
+ * Unlike a target. Returns true if removed, false if it didn't exist, null if Redis is unavailable.
+ */
+export const unlikeTarget = async (targetId: string, userId: string): Promise<boolean | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  const removed = await redis.srem(likeTargetKey(targetId), userId);
+  if (removed === 1) {
+    await redis.srem(likeUserKey(userId), targetId);
+    return true;
+  }
+  return false;
+};
+
+/**
+ * Check whether a user liked a target. Returns null if Redis is unavailable.
+ */
+export const isTargetLiked = async (targetId: string, userId: string): Promise<boolean | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  const result = await redis.sismember(likeTargetKey(targetId), userId);
+  return result === 1;
+};
+
+/**
+ * Get like count for a target (unique by user). Returns null if Redis is unavailable.
+ */
+export const getTargetLikeCount = async (targetId: string): Promise<number | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  return redis.scard(likeTargetKey(targetId));
+};
+
+/**
+ * Get target ids liked by a user. Returns null if Redis is unavailable.
+ */
+export const getUserLikedTargets = async (userId: string): Promise<string[] | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  return redis.smembers<string[]>(likeUserKey(userId));
+};

package/src/lib/upstash/redis-lock.ts

@@ -0,0 +1,85 @@
+import { Lock } from '@upstash/lock';
+import type { Redis } from '@upstash/redis';
+import { getRedis } from '../upstash-config';
+
+type UpstashLock = {
+  acquire: (key: string, ttlMs: number) => Promise<string | null>;
+  release: (key: string, token: string) => Promise<boolean>;
+};
+
+let cachedLock: UpstashLock | null = null;
+let lockInitAttempted = false;
+
+const createLock = (redis: Redis): UpstashLock => {
+  const LockCtor = Lock as unknown as new (...args: any[]) => UpstashLock;
+  try {
+    return new LockCtor({ redis });
+  } catch {
+    return new LockCtor(redis);
+  }
+};
+
+const getLock = (): UpstashLock | null => {
+  if (cachedLock) {
+    return cachedLock;
+  }
+  if (lockInitAttempted) {
+    return null;
+  }
+  lockInitAttempted = true;
+
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  cachedLock = createLock(redis);
+  return cachedLock;
+};
+
+/**
+ * Acquire a distributed lock. Returns the lock token or null when unavailable.
+ */
+export const acquireLock = async (key: string, ttlMs: number): Promise<string | null> => {
+  const lock = getLock();
+  if (!lock) {
+    return null;
+  }
+  return lock.acquire(key, ttlMs);
+};
+
+/**
+ * Release a distributed lock. Returns false when the lock client is unavailable.
+ */
+export const releaseLock = async (key: string, token: string): Promise<boolean> => {
+  const lock = getLock();
+  if (!lock) {
+    return false;
+  }
+  return lock.release(key, token);
+};
+
+/**
+ * Run a function under a distributed lock. Returns null when the lock is unavailable.
+ */
+export const withLock = async <T>(
+  key: string,
+  ttlMs: number,
+  fn: () => Promise<T> | T
+): Promise<T | null> => {
+  const lock = getLock();
+  if (!lock) {
+    return null;
+  }
+
+  const token = await lock.acquire(key, ttlMs);
+  if (!token) {
+    return null;
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await lock.release(key, token);
+  }
+};

package/src/lib/upstash/redis-structures.ts

@@ -0,0 +1,249 @@
+import { getRedis } from '../upstash-config';
+
+/**
+ * Set a plain string value with optional TTL (seconds).
+ */
+export const setString = async (
+  key: string,
+  value: string,
+  ttlSec?: number
+): Promise<boolean> => {
+  const redis = getRedis();
+  if (!redis) {
+    return false;
+  }
+
+  if (ttlSec && ttlSec > 0) {
+    await redis.set(key, value, { ex: ttlSec });
+    return true;
+  }
+
+  await redis.set(key, value);
+  return true;
+};
+
+/**
+ * Get a plain string value. Returns null if Redis is unavailable or key missing.
+ */
+export const getString = async (key: string): Promise<string | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  return redis.get<string>(key);
+};
+
+/**
+ * Store an object as JSON string with optional TTL (seconds).
+ */
+export const setJson = async <T>(
+  key: string,
+  value: T,
+  ttlSec?: number
+): Promise<boolean> => {
+  const redis = getRedis();
+  if (!redis) {
+    return false;
+  }
+
+  const payload = JSON.stringify(value);
+  if (ttlSec && ttlSec > 0) {
+    await redis.set(key, payload, { ex: ttlSec });
+    return true;
+  }
+
+  await redis.set(key, payload);
+  return true;
+};
+
+/**
+ * Get an object stored as JSON string. Returns null if missing or invalid JSON.
+ */
+export const getJson = async <T>(key: string): Promise<T | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  const payload = await redis.get<string>(key);
+  if (!payload) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(payload) as T;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Delete a key. Returns false if Redis is unavailable.
+ */
+export const deleteKey = async (key: string): Promise<boolean> => {
+  const redis = getRedis();
+  if (!redis) {
+    return false;
+  }
+
+  const deleted = await redis.del(key);
+  return deleted > 0;
+};
+
+/**
+ * Set a hash field value.
+ */
+export const setHashField = async (key: string, field: string, value: string): Promise<boolean> => {
+  const redis = getRedis();
+  if (!redis) {
+    return false;
+  }
+
+  const result = await redis.hset(key, { [field]: value });
+  return result > 0;
+};
+
+/**
+ * Get a hash field value.
+ */
+export const getHashField = async (key: string, field: string): Promise<string | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  return redis.hget<string>(key, field);
+};
+
+/**
+ * Store a hash field as JSON string.
+ */
+export const setHashJson = async <T>(
+  key: string,
+  field: string,
+  value: T
+): Promise<boolean> => {
+  const redis = getRedis();
+  if (!redis) {
+    return false;
+  }
+
+  const payload = JSON.stringify(value);
+  const result = await redis.hset(key, { [field]: payload });
+  return result > 0;
+};
+
+/**
+ * Get a hash field stored as JSON string.
+ */
+export const getHashJson = async <T>(key: string, field: string): Promise<T | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  const payload = await redis.hget<string>(key, field);
+  if (!payload) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(payload) as T;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Get all hash fields.
+ */
+export const getHashAll = async (key: string): Promise<Record<string, string> | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  const result = await redis.hgetall<Record<string, string>>(key);
+  return result ?? {};
+};
+
+/**
+ * Remove a hash field.
+ */
+export const deleteHashField = async (key: string, field: string): Promise<boolean> => {
+  const redis = getRedis();
+  if (!redis) {
+    return false;
+  }
+
+  const removed = await redis.hdel(key, field);
+  return removed > 0;
+};
+
+type ListDirection = 'left' | 'right';
+
+/**
+ * Push values to a list. Returns list length or null if Redis is unavailable.
+ */
+export const pushList = async (
+  key: string,
+  values: string[],
+  direction: ListDirection = 'right'
+): Promise<number | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  if (values.length === 0) {
+    return redis.llen(key);
+  }
+
+  return direction === 'left'
+    ? redis.lpush(key, ...values)
+    : redis.rpush(key, ...values);
+};
+
+/**
+ * Pop a value from a list.
+ */
+export const popList = async (
+  key: string,
+  direction: ListDirection = 'right'
+): Promise<string | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  return direction === 'left' ? redis.lpop<string>(key) : redis.rpop<string>(key);
+};
+
+/**
+ * Get a range from a list.
+ */
+export const rangeList = async (
+  key: string,
+  start = 0,
+  stop = -1
+): Promise<string[] | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  return redis.lrange<string>(key, start, stop);
+};
+
+/**
+ * Get list length.
+ */
+export const listLength = async (key: string): Promise<number | null> => {
+  const redis = getRedis();
+  if (!redis) {
+    return null;
+  }
+
+  return redis.llen(key);
+};

package/src/lib/upstash-config.ts

@@ -0,0 +1,54 @@
+import { Redis } from '@upstash/redis';
+import { Client as QstashClient } from '@upstash/qstash';
+
+let cachedRedis: Redis | null = null;
+let cachedQstash: QstashClient | null = null;
+let redisInitAttempted = false;
+let qstashInitAttempted = false;
+
+/**
+ * Get the Upstash Redis client. Returns null when required env vars are missing.
+ */
+export const getRedis = (): Redis | null => {
+  if (cachedRedis) {
+    return cachedRedis;
+  }
+  if (redisInitAttempted) {
+    return null;
+  }
+
+  redisInitAttempted = true;
+  const { UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN } = process.env;
+  if (!UPSTASH_REDIS_REST_URL || !UPSTASH_REDIS_REST_TOKEN) {
+    console.warn('[Upstash Config] Redis Missed configration UPSTASH_REDIS_REST_URL or UPSTASH_REDIS_REST_TOKEN, then disabled');
+    return null;
+  }
+
+  cachedRedis = new Redis({
+    url: UPSTASH_REDIS_REST_URL,
+    token: UPSTASH_REDIS_REST_TOKEN,
+  });
+  return cachedRedis;
+};
+
+/**
+ * Get the Upstash QStash client. Returns null when required env vars are missing.
+ */
+export const getQstash = (): QstashClient | null => {
+  if (cachedQstash) {
+    return cachedQstash;
+  }
+  if (qstashInitAttempted) {
+    return null;
+  }
+
+  qstashInitAttempted = true;
+  const { QSTASH_TOKEN } = process.env;
+  if (!QSTASH_TOKEN) {
+    console.warn('[Upstash Config] QStash Missed configration QSTASH_TOKEN, then disabled');
+    return null;
+  }
+
+  cachedQstash = new QstashClient({ token: QSTASH_TOKEN });
+  return cachedQstash;
+};