befly 3.10.18 → 3.11.1

package/dist/lib/redisHelper.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Redis 助手 - TypeScript 版本
+ * 提供 Redis 操作的便捷方法
+ */
+/**
+ * Redis 助手类
+ * 约定：除构造函数外，方法默认不抛异常；失败时返回 null/false/0/[] 并记录日志。
+ */
+export declare class RedisHelper {
+    private client;
+    private prefix;
+    private readonly slowThresholdMs;
+    /**
+     * 构造函数
+     * @param prefix - Key 前缀
+     */
+    constructor(prefix?: string);
+    private logSlow;
+    /**
+     * 设置对象到 Redis
+     * @param key - 键名
+     * @param obj - 对象
+     * @param ttl - 过期时间（秒）
+     * @returns 操作结果
+     */
+    setObject<T = any>(key: string, obj: T, ttl?: number | null): Promise<string | null>;
+    /**
+     * 从 Redis 获取对象
+     * @param key - 键名
+     * @returns 对象或 null
+     */
+    getObject<T = any>(key: string): Promise<T | null>;
+    /**
+     * 从 Redis 删除对象
+     * @param key - 键名
+     */
+    delObject(key: string): Promise<void>;
+    /**
+     * 生成基于时间的唯一 ID
+     * 格式: 毫秒时间戳(13位) + 3位后缀(100-999) = 16位纯数字
+     * 每毫秒起点基于时间戳偏移，后缀分布更均匀
+     * @returns 唯一 ID (16位纯数字)
+     */
+    genTimeID(): Promise<number>;
+    /**
+     * 设置字符串值
+     * @param key - 键名
+     * @param value - 值
+     * @param ttl - 过期时间（秒）
+     */
+    setString(key: string, value: string, ttl?: number | null): Promise<string | null>;
+    /**
+     * 获取字符串值
+     * @param key - 键名
+     */
+    getString(key: string): Promise<string | null>;
+    /**
+     * 检查键是否存在
+     * @param key - 键名
+     * @returns 是否存在（true/false）
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * 原子自增
+     * @param key - 键名
+     * @returns 自增后的值
+     */
+    incr(key: string): Promise<number>;
+    /**
+     * 原子自增并在首次自增时设置过期时间（常用于限流/计数）
+     * @param key - 键名
+     * @param seconds - 过期秒数
+     * @returns 自增后的值
+     */
+    incrWithExpire(key: string, seconds: number): Promise<number>;
+    /**
+     * 设置过期时间
+     * @param key - 键名
+     * @param seconds - 秒数
+     */
+    expire(key: string, seconds: number): Promise<number>;
+    /**
+     * 获取剩余过期时间
+     * @param key - 键名
+     */
+    ttl(key: string): Promise<number>;
+    /**
+     * 批量获取剩余过期时间（利用 Bun Redis 自动管道优化）
+     * @param keys - 键名数组
+     * @returns TTL 数组（-2 表示键不存在，-1 表示无过期时间）
+     */
+    ttlBatch(keys: string[]): Promise<number[]>;
+    /**
+     * 向 Set 中添加一个或多个成员
+     * @param key - 键名
+     * @param members - 成员数组
+     * @returns 成功添加的成员数量
+     */
+    sadd(key: string, members: string[]): Promise<number>;
+    /**
+     * 判断成员是否在 Set 中
+     * @param key - 键名
+     * @param member - 成员
+     * @returns 是否存在（true/false）
+     */
+    sismember(key: string, member: string): Promise<boolean>;
+    /**
+     * 获取 Set 的成员数量
+     * @param key - 键名
+     * @returns 成员数量
+     */
+    scard(key: string): Promise<number>;
+    /**
+     * 获取 Set 的所有成员
+     * @param key - 键名
+     * @returns 成员数组
+     */
+    smembers(key: string): Promise<string[]>;
+    /**
+     * 批量向多个 Set 添加成员（利用 Bun Redis 自动管道优化）
+     * @param items - [{ key, members }] 数组
+     * @returns 成功添加的总成员数量
+     */
+    saddBatch(items: Array<{
+        key: string;
+        members: string[];
+    }>): Promise<number>;
+    /**
+     * 批量检查成员是否在 Set 中（利用 Bun Redis 自动管道优化）
+     * @param items - [{ key, member }] 数组
+     * @returns 布尔数组（true 表示存在，false 表示不存在）
+     */
+    sismemberBatch(items: Array<{
+        key: string;
+        member: string;
+    }>): Promise<boolean[]>;
+    /**
+     * 删除键
+     * @param key - 键名
+     * @returns 删除的键数量
+     */
+    del(key: string): Promise<number>;
+    /**
+     * 批量删除键（利用 Bun Redis 自动管道优化）
+     * @param keys - 键名数组
+     * @returns 成功删除的键数量
+     */
+    delBatch(keys: string[]): Promise<number>;
+    /**
+     * 批量设置对象（利用 Bun Redis 自动管道优化）
+     * @param items - 键值对数组 [{ key, value, ttl? }]
+     * @returns 成功设置的数量
+     */
+    setBatch<T = any>(items: Array<{
+        key: string;
+        value: T;
+        ttl?: number | null;
+    }>): Promise<number>;
+    /**
+     * 批量获取对象（利用 Bun Redis 自动管道优化）
+     * @param keys - 键名数组
+     * @returns 对象数组（不存在的键返回 null）
+     */
+    getBatch<T = any>(keys: string[]): Promise<Array<T | null>>;
+    /**
+     * 批量检查键是否存在（利用 Bun Redis 自动管道优化）
+     * @param keys - 键名数组
+     * @returns 布尔数组（true 表示存在，false 表示不存在）
+     */
+    existsBatch(keys: string[]): Promise<boolean[]>;
+    /**
+     * 批量设置过期时间（利用 Bun Redis 自动管道优化）
+     * @param items - 键名和过期时间数组 [{ key, seconds }]
+     * @returns 成功设置的数量
+     */
+    expireBatch(items: Array<{
+        key: string;
+        seconds: number;
+    }>): Promise<number>;
+    /**
+     * 测试 Redis 连接
+     * @returns ping 响应结果
+     */
+    ping(): Promise<string>;
+}