@pangza/redis 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @pangza/redis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Redis / 限流 / 锁

package/dist/Redis.d.ts

@@ -0,0 +1,98 @@
+import { type LockHandle, type RedisConfig, type TryLockOption, type WithLockOption } from "./types";
+/** 创建 RESP2 客户端（standalone / cluster / sentinel） */
+declare function createRedisClient(cfg: RedisConfig): any;
+type RedisClient = ReturnType<typeof createRedisClient>;
+/**
+ * Redis 操作封装（基于 node-redis v6）。
+ * 配置来自项目根目录 application*.yaml，模块加载及首次调用时自动连接。
+ */
+declare class Redis {
+    private static client;
+    private static config;
+    private static connecting;
+    /** Pub/Sub 专用连接（subscribe 会阻塞普通命令） */
+    private static subClient;
+    private static ensureReady;
+    /** 覆盖配置；已连接时需 disconnect 后再 connect 才生效 */
+    static configure(config?: RedisConfig): void;
+    static isReady(): boolean;
+    /** PING；成功返回 true，失败抛错或返回 false（ping 自身异常时） */
+    static ping(): Promise<boolean>;
+    static connect(config?: RedisConfig): Promise<void>;
+    static disconnect(): Promise<void>;
+    static getClient(): Promise<RedisClient>;
+    static key(raw: string): string;
+    static set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    static setJSON(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    static get(key: string): Promise<string | null>;
+    static getJSON<T = unknown>(key: string): Promise<T | null>;
+    static del(...keys: string[]): Promise<number>;
+    static exists(key: string): Promise<boolean>;
+    static expire(key: string, ttlSeconds: number): Promise<boolean>;
+    static ttl(key: string): Promise<number>;
+    static setNX(key: string, value: string, ttlSeconds?: number): Promise<boolean>;
+    static setNxPx(key: string, value: string, ttlMs: number): Promise<boolean>;
+    static unlockIfMatch(key: string, expectValue: string): Promise<boolean>;
+    /** 值匹配时续期（毫秒） */
+    static renewIfMatch(key: string, expectValue: string, ttlMs: number): Promise<boolean>;
+    /**
+     * 尝试获取锁。
+     * @returns 句柄；失败返回 null
+     */
+    static tryLock(key: string, option?: TryLockOption): Promise<LockHandle | null>;
+    /**
+     * 持锁执行；可选自动续租。拿不到锁抛 LockError。
+     */
+    static withLock<T>(key: string, fn: () => Promise<T> | T, option?: WithLockOption): Promise<T>;
+    static hSet(key: string, field: string, value: string): Promise<number>;
+    static hGet(key: string, field: string): Promise<string | undefined>;
+    static hGetAll(key: string): Promise<Record<string, string>>;
+    static hDel(key: string, ...fields: string[]): Promise<number>;
+    static sAdd(key: string, ...members: string[]): Promise<number>;
+    static sMembers(key: string): Promise<string[]>;
+    static sRem(key: string, ...members: string[]): Promise<number>;
+    static lPush(key: string, ...values: string[]): Promise<number>;
+    static rPush(key: string, ...values: string[]): Promise<number>;
+    static lPop(key: string): Promise<string | null>;
+    static rPop(key: string): Promise<string | null>;
+    static lRange(key: string, start: number, stop: number): Promise<string[]>;
+    static lLen(key: string): Promise<number>;
+    static zAdd(key: string, members: Array<{
+        score: number;
+        value: string;
+    }>): Promise<number>;
+    static zRange(key: string, min: number, max: number): Promise<string[]>;
+    static zRangeByScore(key: string, min: number | string, max: number | string): Promise<string[]>;
+    static zRem(key: string, ...members: string[]): Promise<number>;
+    static zCard(key: string): Promise<number>;
+    static zScore(key: string, member: string): Promise<number | null>;
+    /**
+     * 批量命令。fn 内对 multi 链式调用，结束后自动 exec。
+     * key 需自行 `Redis.key(...)` 加前缀。
+     */
+    static pipeline(fn: (multi: ReturnType<RedisClient["multi"]>) => void): Promise<unknown[]>;
+    static publish(channel: string, message: string): Promise<number>;
+    /**
+     * 订阅频道。返回取消订阅函数。
+     * 内部使用独立连接，避免阻塞主 client。
+     */
+    static subscribe(channel: string, listener: (message: string, channel: string) => void): Promise<() => Promise<void>>;
+    static incr(key: string): Promise<number>;
+    static decr(key: string): Promise<number>;
+    static setPx(key: string, value: string, ttlMs: number): Promise<void>;
+    static setJSONPx(key: string, value: unknown, ttlMs: number): Promise<void>;
+    /**
+     * 固定窗口限流。
+     * @returns 当前窗口内计数
+     */
+    static rateLimit(key: string, timeSeconds: number, count: number): Promise<number>;
+    /**
+     * 滑动窗口限流（ZSET）。
+     * @returns 当前窗口内数量（含本次尝试）
+     */
+    static rateLimitSliding(key: string, timeSeconds: number, count: number): Promise<number>;
+    /** 按前缀扫描删除（@CacheEvict allEntries）；小规模缓存用 */
+    static deleteByPrefix(prefix: string): Promise<number>;
+}
+export default Redis;
+//# sourceMappingURL=Redis.d.ts.map

package/dist/Redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Redis.d.ts","sourceRoot":"","sources":["../src/Redis.ts"],"names":[],"mappings":"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"}