@millionfor/redis

A tool library based on the ioredis extension.

Installation

$ npm i @millionfor/redis

Usage

import { Redis, CacheBitField, CacheHash, CacheHyperLogLog, CacheList, CacheSet, CacheSortedSet, CacheString } from '@millionfor/redis'

// 创建 Redis 客户端实例
const redisClient = new Redis({
  port: 6379, // Redis port
  host: '192.168.2.172', // Redis host
  username: '', // needs Redis >= 6
  password: 'quanquan',
  db: 8 // Defaults to 0
})

// 创建缓存选项
const cacheOption = {
  appName: 'myApp',
  funcName: 'myFunc'
}

// 创建缓存实例
const cacheString = new CacheString('str', cacheOption, redisClient)
const cacheSet = new CacheSet('set', cacheOption, redisClient)
const cacheList = new CacheList('list', cacheOption, redisClient)
const cacheHash = new CacheHash('hash', cacheOption, redisClient)
const cacheSortedSet = new CacheSortedSet('ss', cacheOption, redisClient)
const cacheBitField = new CacheBitField('bf', cacheOption, redisClient)
const cacheHyperLogLog = new CacheHyperLogLog('hll', cacheOption, redisClient)

export { cacheString, cacheSet, cacheList, cacheHash, cacheSortedSet, cacheBitField, cacheHyperLogLog }

/**
 * 基础缓存类
 */
export declare class BaseCache {
  protected option: CacheOption
  protected redis: RedisClient
  protected prefix: string
  /**
   * 构造函数
   * @param prefix - 缓存键前缀
   * @param option - 缓存选项
   * @param redisClient - Redis 客户端实例
   */
  constructor(prefix: string, option: CacheOption, redisClient: RedisClient)
  /**
   * 创建缓存键
   * @param value - 可选的键值
   * @returns 生成的缓存键
   */
  protected createKey(value?: string | number | boolean): string
  /**
   * 将数据转换为字符串
   * @param data - 要转换的数据
   * @returns 转换后的字符串
   */
  protected dataToString(data: any): string
  /**
   * 创建管道操作
   * @returns 创建的管道实例
   */
  createPipeline(): ChainableCommander
  /**
   * 执行事务操作
   * @param commands - 包含事务命令的回调函数
   * @returns 事务执行结果的 Promise
   */
  executeTransaction(commands: (pipeline: ChainableCommander) => void): Promise<any>
}

export declare class CacheBitField extends BaseCache {
  /**
   * 设置位域的某一位
   * @param offset - 位的偏移量
   * @param value - 位的值（true 或 false）
   * @param suffix - 可选的键后缀
   * @returns 之前的位值
   */
  setbit(offset: number, value: boolean, suffix?: string): Promise<boolean>
  /**
   * 获取位域的某一位
   * @param offset - 位的偏移量
   * @param suffix - 可选的键后缀
   * @returns 位值（0 或 1）
   */
  getbit(offset: number, suffix?: string): Promise<number>
  /**
   * 计算位域中指定范围内的位数
   * @param option - 位数计算范围和模式
   * @param suffix - 可选的键后缀
   * @returns 位数
   */
  count(option: BitCountRange, suffix?: string): Promise<number>
  /**
   * 对位域执行位操作
   * @param operation - 位操作类型（AND, OR, XOR, NOT）
   * @param destKey - 目标键
   * @param keys - 源键数组
   * @returns 结果位数
   */
  bitop(operation: 'AND' | 'OR' | 'XOR' | 'NOT', destKey: string, keys: string[]): Promise<number>
}

export declare class CacheHash extends BaseCache {
  /**
   * 设置哈希表中的字段值
   * @param key - 字段名
   * @param value - 字段值
   * @param suffix - 可选的键后缀
   * @returns 是否成功设置
   */
  set(key: string, value: Record<string, any>, suffix?: string): Promise<boolean>
  /**
   * 获取哈希表中的字段值
   * @param key - 字段名
   * @param suffix - 可选的键后缀
   * @returns 字段值或 null
   */
  get(key: string, suffix?: string): Promise<Record<string, any> | null>
  /**
   * 获取哈希表中的所有字段和值
   * @param suffix - 可选的键后缀
   * @returns 哈希表中的所有字段和值
   */
  getAll(suffix?: string): Promise<Record<string, any>>
  /**
   * 检查哈希表中是否存在指定字段
   * @param key - 字段名
   * @param suffix - 可选的键后缀
   * @returns 是否存在
   */
  exists(key: string, suffix?: string): Promise<number>
  /**
   * 删除哈希表中的指定字段
   * @param key - 字段名
   * @param suffix - 可选的键后缀
   * @returns 是否成功删除
   */
  delete(key: string, suffix?: string): Promise<boolean>
  /**
   * 获取哈希表中所有字段的数量
   * @param suffix - 可选的键后缀
   * @returns 字段数量
   */
  length(suffix?: string): Promise<number>
  /**
   * 获取哈希表中的所有字段名
   * @param suffix - 可选的键后缀
   * @returns 所有字段名
   */
  keys(suffix?: string): Promise<string[]>
  /**
   * 获取哈希表中的所有字段值
   * @param suffix - 可选的键后缀
   * @returns 所有字段值
   */
  values(suffix?: string): Promise<any[]>
  /**
   * 为哈希表中的字段值加上指定增量
   * @param key - 字段名
   * @param increment - 增量
   * @param suffix - 可选的键后缀
   * @returns 增加后的值
   */
  incrementBy(key: string, increment: number, suffix?: string): Promise<number>
  /**
   * 为哈希表中的字段值加上指定浮点增量
   * @param key - 字段名
   * @param increment - 浮点增量
   * @param suffix - 可选的键后缀
   * @returns 增加后的值
   */
  incrementByFloat(key: string, increment: number, suffix?: string): Promise<string>
}

export declare class CacheHyperLogLog extends BaseCache {
  /**
   * 添加元素到 HyperLogLog
   * @param suffix - 可选的键后缀
   * @param values - 要添加的元素
   * @returns 是否成功添加
   */
  add(suffix?: string, ...values: any[]): Promise<boolean>
  /**
   * 获取 HyperLogLog 中的基数估算值
   * @param suffix - 可选的键后缀
   * @returns 基数估算值
   */
  count(suffix?: string): Promise<number>
  /**
   * 合并多个 HyperLogLog
   * @param suffix - 目标 HyperLogLog 的键后缀
   * @param keys - 要合并的 HyperLogLog 的键
   * @returns 是否成功合并
   */
  merge(suffix?: string, ...keys: string[]): Promise<boolean>
  /**
   * 删除 HyperLogLog
   * @param suffix - 可选的键后缀
   * @returns 是否成功删除
   */
  delete(suffix?: string): Promise<boolean>
  /**
   * 重命名 HyperLogLog
   * @param oldSuffix - 旧的键后缀
   * @param newSuffix - 新的键后缀
   * @returns 是否成功重命名
   */
  rename(oldSuffix: string, newSuffix: string): Promise<boolean>
  /**
   * 获取 HyperLogLog 的内存使用情况
   * @param suffix - 可选的键后缀
   * @returns 内存使用情况（字节）
   */
  memoryUsage(suffix?: string): Promise<number | null>
}

export declare class CacheList extends BaseCache {
  /**
   * 从右侧推入元素到列表
   * @param suffix - 可选的键后缀
   * @param values - 要推入的元素
   * @returns 列表的长度
   */
  push(suffix?: string, ...values: any[]): Promise<number>
  /**
   * 从右侧弹出元素
   * @param suffix - 可选的键后缀
   * @returns 弹出的元素
   */
  pop(suffix?: string): Promise<string | null>
  /**
   * 获取列表的长度
   * @param suffix - 可选的键后缀
   * @returns 列表的长度
   */
  length(suffix?: string): Promise<number>
  /**
   * 获取列表的指定范围内的元素
   * @param start - 起始索引
   * @param stop - 结束索引
   * @param suffix - 可选的键后缀
   * @returns 指定范围内的元素
   */
  range(start: number, stop: number, suffix?: string): Promise<string[]>
  /**
   * 从左侧推入元素到列表
   * @param suffix - 可选的键后缀
   * @param values - 要推入的元素
   * @returns 列表的长度
   */
  lpush(suffix?: string, ...values: any[]): Promise<number>
  /**
   * 从左侧弹出元素
   * @param suffix - 可选的键后缀
   * @returns 弹出的元素
   */
  lpop(suffix?: string): Promise<string | null>
  /**
   * 修剪列表，只保留指定范围内的元素
   * @param start - 起始索引
   * @param stop - 结束索引
   * @param suffix - 可选的键后缀
   * @returns 修剪结果
   */
  trim(start: number, stop: number, suffix?: string): Promise<string>
  /**
   * 设置指定索引处的值
   * @param index - 索引
   * @param value - 新值
   * @param suffix - 可选的键后缀
   * @returns 设置结果
   */
  set(index: number, value: any, suffix?: string): Promise<string>
  /**
   * 根据值移除元素
   * @param count - 移除的元素数量
   * @param value - 要移除的元素
   * @param suffix - 可选的键后缀
   * @returns 移除的元素数量
   */
  remove(count: number, value: any, suffix?: string): Promise<number>
  /**
   * 在指定元素前或后插入新元素
   * @param pivot - 参考元素
   * @param value - 新元素
   * @param position - 插入位置（"BEFORE" 或 "AFTER"）
   * @param suffix - 可选的键后缀
   * @returns 插入后列表的长度
   */
  insert(pivot: any, value: any, position: 'BEFORE' | 'AFTER', suffix?: string): Promise<number>
}

export declare class CacheSet extends BaseCache {
  /**
   * 添加一个元素到集合
   * @param value - 要添加的元素
   * @param suffix - 可选的键后缀
   * @returns 是否成功添加
   */
  add(value: any, suffix?: string): Promise<boolean>
  /**
   * 批量添加元素到集合
   * @param values - 要添加的元素数组
   * @param suffix - 可选的键后缀
   * @returns 是否成功添加
   */
  addBatch(values: any[], suffix?: string): Promise<boolean>
  /**
   * 从集合中移除一个元素
   * @param value - 要移除的元素
   * @param suffix - 可选的键后缀
   * @returns 是否成功移除
   */
  remove(value: any, suffix?: string): Promise<boolean>
  /**
   * 批量移除集合中的元素
   * @param values - 要移除的元素数组
   * @param suffix - 可选的键后缀
   * @returns 是否成功移除
   */
  removeBatch(values: any[], suffix?: string): Promise<boolean>
  /**
   * 获取集合中的所有元素
   * @param suffix - 可选的键后缀
   * @returns 集合中的所有元素
   */
  members(suffix?: string): Promise<string[]>
  /**
   * 检查元素是否在集合中
   * @param value - 要检查的元素
   * @param suffix - 可选的键后缀
   * @returns 元素是否存在
   */
  exists(value: any, suffix?: string): Promise<number>
  /**
   * 获取集合的大小
   * @param suffix - 可选的键后缀
   * @returns 集合的大小
   */
  size(suffix?: string): Promise<number>
  /**
   * 随机弹出一个元素
   * @param suffix - 可选的键后缀
   * @returns 弹出的元素
   */
  pop(suffix?: string): Promise<string | null>
  /**
   * 随机弹出多个元素
   * @param count - 要弹出的元素数量
   * @param suffix - 可选的键后缀
   * @returns 弹出的元素数组
   */
  popMultiple(count: number, suffix?: string): Promise<string[]>
  /**
   * 随机获取一个元素
   * @param suffix - 可选的键后缀
   * @returns 随机获取的元素
   */
  randomMember(suffix?: string): Promise<string | null>
  /**
   * 随机获取多个元素
   * @param count - 要获取的元素数量
   * @param suffix - 可选的键后缀
   * @returns 随机获取的元素数组
   */
  randomMembers(count: number, suffix?: string): Promise<string[]>
  /**
   * 获取多个集合的并集
   * @param suffixes - 键后缀数组
   * @returns 并集结果
   */
  union(...suffixes: string[]): Promise<string[]>
  /**
   * 获取多个集合的交集
   * @param suffixes - 键后缀数组
   * @returns 交集结果
   */
  intersect(...suffixes: string[]): Promise<string[]>
  /**
   * 获取多个集合的差集
   * @param suffixes - 键后缀数组
   * @returns 差集结果
   */
  difference(...suffixes: string[]): Promise<string[]>
}

export declare class CacheSortedSet extends BaseCache {
  /**
   * 添加一个成员到有序集合
   * @param score - 成员的分数
   * @param value - 成员的值
   * @param suffix - 可选的键后缀
   * @returns 是否成功添加
   */
  add(score: number, value: any, suffix?: string): Promise<boolean>
  /**
   * 添加多个成员到有序集合
   * @param members - 成员数组
   * @param suffix - 可选的键后缀
   * @returns 是否成功添加
   */
  adds(members: ZMember[], suffix?: string): Promise<boolean>
  /**
   * 移除有序集合中的一个成员
   * @param value - 成员的值
   * @param suffix - 可选的键后缀
   * @returns 是否成功移除
   */
  remove(value: any, suffix?: string): Promise<boolean>
  /**
   * 计算有序集合中指定分数范围的成员数量
   * @param min - 最小分数
   * @param max - 最大分数
   * @param suffix - 可选的键后缀
   * @returns 成员数量
   */
  count(min: number, max: number, suffix?: string): Promise<number>
  /**
   * 获取有序集合中指定分数范围的成员
   * @param min - 最小分数
   * @param max - 最大分数
   * @param suffix - 可选的键后缀
   * @returns 成员数组
   */
  rangeByScore(min: number, max: number, suffix?: string): Promise<string[]>
  /**
   * 获取有序集合中的元素数量
   * @param suffix - 可选的键后缀
   * @returns 元素数量
   */
  length(suffix?: string): Promise<number>
  /**
   * 获取有序集合中指定范围内的元素
   * @param start - 起始索引
   * @param stop - 结束索引
   * @param suffix - 可选的键后缀
   * @returns 元素数组
   */
  range(start: number, stop: number, suffix?: string): Promise<string[]>
  /**
   * 获取有序集合中指定范围内的元素及其分数
   * @param start - 起始索引
   * @param stop - 结束索引
   * @param suffix - 可选的键后缀
   * @returns 元素及其分数数组
   */
  rangeWithScores(
    start: number,
    stop: number,
    suffix?: string
  ): Promise<
    {
      value: string
      score: number
    }[]
  >
  /**
   * 获取有序集合中指定成员的分数
   * @param value - 成员的值
   * @param suffix - 可选的键后缀
   * @returns 成员的分数
   */
  score(value: any, suffix?: string): Promise<number | null>
  /**
   * 为有序集合中的成员的分数加上指定增量
   * @param value - 成员的值
   * @param increment - 增量
   * @param suffix - 可选的键后缀
   * @returns 增加后的分数
   */
  incrementBy(value: any, increment: number, suffix?: string): Promise<string>
  /**
   * 删除有序集合中指定分数范围的成员
   * @param min - 最小分数
   * @param max - 最大分数
   * @param suffix - 可选的键后缀
   * @returns 删除的成员数量
   */
  removeRangeByScore(min: number, max: number, suffix?: string): Promise<number>
  /**
   * 删除有序集合中指定排名范围的成员
   * @param start - 起始索引
   * @param stop - 结束索引
   * @param suffix - 可选的键后缀
   * @returns 删除的成员数量
   */
  removeRangeByRank(start: number, stop: number, suffix?: string): Promise<number>
}

export declare class CacheString extends BaseCache {
  /**
   * 设置字符串值
   * @param key - 缓存键
   * @param value - 缓存值
   * @param EX - 过期时间（秒），可选
   * @returns 设置结果
   */
  set(key: string, value: any, EX?: number): Promise<string | null>
  /**
   * 获取字符串值
   * @param key - 缓存键
   * @returns 缓存值
   */
  get(key: string): Promise<string | null>
  /**
   * 检查键是否存在
   * @param key - 缓存键
   * @returns 键是否存在
   */
  exists(key: string): Promise<number>
  /**
   * 删除键
   * @param key - 缓存键
   * @returns 删除的键数量
   */
  delete(key: string): Promise<number>
  /**
   * 增加键的值
   * @param key - 缓存键
   * @param increment - 增加的值
   * @returns 增加后的值
   */
  increment(key: string, increment?: number): Promise<number>
  /**
   * 减少键的值
   * @param key - 缓存键
   * @param decrement - 减少的值
   * @returns 减少后的值
   */
  decrement(key: string, decrement?: number): Promise<number>
  /**
   * 获取并设置新值
   * @param key - 缓存键
   * @param value - 新值
   * @returns 旧值
   */
  getSet(key: string, value: any): Promise<string | null>
  /**
   * 设置多个键值对
   * @param keyValuePairs - 键值对数组
   * @returns 设置结果
   */
  setMultiple(
    keyValuePairs: {
      key: string
      value: any
    }[]
  ): Promise<string>
  /**
   * 获取多个键值对
   * @param keys - 键数组
   * @returns 值数组
   */
  getMultiple(keys: string[]): Promise<(string | null)[]>
  /**
   * 设置键值对，如果键不存在
   * @param key - 缓存键
   * @param value - 缓存值
   * @returns 是否成功设置
   */
  setnx(key: string, value: any): Promise<number>
  /**
   * 设置键值对，如果键不存在，并设置过期时间
   * @param key - 缓存键
   * @param value - 缓存值
   * @param EX - 过期时间（秒）
   * @returns 是否成功设置
   */
  setnxWithExpire(key: string, value: any, EX: number): Promise<string | null>
}

export type CacheOption = {
  appName: string
  funcName: string
}
export type ZMember = {
  score: number
  value: any
}
export type BitCountRange = {
  start: number
  end: number
  mode: string
}

License

MIT