@anjianshi/utils 2.3.9 → 2.3.10

package/env-node/redis-cache.d.ts

@@ -0,0 +1,39 @@
+import { type RedisClientType } from 'redis';
+import { type Logger } from '../logging/index.js';
+export declare function initRedisLogging(redis: RedisClientType, logger?: Logger): void;
+export interface CacheOptions {
+    logger: Logger;
+    /** 数据有效期，单位秒。默认为 10 分钟。小于等于 0 代表不设有效期 */
+    expires: number;
+    /** 读取时是否自动刷新有效期，仅设置了 expire 时有效，默认为 true */
+    refreshOnRead: boolean;
+    /** 若为 true，读取数据后会立即将其删除，默认为 false */
+    oneTime: boolean;
+}
+/**
+ * 维护缓存数据
+ * 1. 每个 Cache 实例只维护一个主题的数据，且需明确定义数据类型，这样设计可明确对每一项缓存的使用、避免混乱。
+ * 2. 值在存储时会 JSON 化，读取时再进行 JSON 解析（支持 JSON 化 Date 对象）。
+ */
+export declare class Cache<T> {
+    readonly redis: RedisClientType;
+    readonly topic: string;
+    readonly options: CacheOptions;
+    constructor(redis: RedisClientType, topic: string, options?: Partial<CacheOptions>);
+    get logger(): Logger;
+    protected jsonStringify(value: T): string;
+    protected jsonParse(redisValue: string): T;
+    protected getRedisKey(identity: string): string;
+    /** 读取一项内容 */
+    get(identity: string, defaults: T): Promise<T>;
+    get(identity?: string): Promise<T | undefined>;
+    /** 写入/更新一项内容 */
+    set(value: T): Promise<void>;
+    set(identity: string, value: T): Promise<void>;
+    /** 移除一项内容 */
+    delete(identity?: string | string[]): Promise<number>;
+    /** 刷新一项内容的过期时间 */
+    refresh(identity?: string): Promise<boolean>;
+    /** 确认一项内容是否存在  */
+    exists(identity?: string): Promise<boolean>;
+}

package/env-node/redis-cache.js

@@ -0,0 +1,117 @@
+import { logger as rootLogger } from '../logging/index.js';
+export function initRedisLogging(redis, logger) {
+    if (!logger)
+        logger = rootLogger.getChild('redis');
+    redis.on('connect', () => logger.info('connecting'));
+    redis.on('ready', () => logger.info('connected'));
+    redis.on('end', () => logger.info('connection closed'));
+    redis.on('reconnecting', () => logger.info('reconnecting'));
+    redis.on('error', error => logger.error(error));
+}
+/**
+ * 维护缓存数据
+ * 1. 每个 Cache 实例只维护一个主题的数据，且需明确定义数据类型，这样设计可明确对每一项缓存的使用、避免混乱。
+ * 2. 值在存储时会 JSON 化，读取时再进行 JSON 解析（支持 JSON 化 Date 对象）。
+ */
+export class Cache {
+    redis;
+    topic;
+    options;
+    constructor(redis, topic, options) {
+        this.redis = redis;
+        this.topic = topic;
+        this.options = {
+            logger: rootLogger.getChild('cache'),
+            expires: 600,
+            refreshOnRead: true,
+            oneTime: false,
+            ...(options ?? {}),
+        };
+    }
+    get logger() {
+        return this.options.logger;
+    }
+    // 经过定制的 JSON 序列化和解析方法
+    jsonStringify(value) {
+        // 参考：https://stackoverflow.com/a/54037861/2815178
+        function replacer(key, value) {
+            // value 是经过预处理过的值，对于 Date 对象，此时已经是 string，需要通过 this[key] 才能拿到 Date 值。
+            const rawValue = this[key];
+            if (rawValue instanceof Date)
+                return { __json_type: 'date', value: rawValue.toISOString() };
+            return value;
+        }
+        return JSON.stringify(value, replacer);
+    }
+    jsonParse(redisValue) {
+        function reviver(key, value) {
+            if (typeof value === 'object' && value !== null) {
+                const obj = value;
+                if (obj.__json_type === 'date')
+                    return new Date(obj.value);
+            }
+            return value;
+        }
+        return JSON.parse(redisValue, reviver);
+    }
+    getRedisKey(identity) {
+        return `${this.topic}${identity ? ':' + identity : ''}`;
+    }
+    async get(identity = '', defaults) {
+        const redisKey = this.getRedisKey(identity);
+        const redisValue = await this.redis.get(redisKey);
+        this.logger.debug('get', redisKey, redisValue);
+        if (redisValue === null)
+            return defaults;
+        if (this.options.refreshOnRead)
+            void this.refresh(identity);
+        try {
+            const value = this.jsonParse(redisValue);
+            if (this.options.oneTime)
+                await this.delete(identity);
+            return value;
+        }
+        catch (error) {
+            this.logger.error(`解析 cache 数据失败，key=${redisKey}，value=${redisValue}`, error);
+            void this.delete(identity);
+            return defaults;
+        }
+    }
+    async set(identity, value) {
+        if (value === undefined) {
+            value = identity;
+            identity = '';
+        }
+        else {
+            identity = identity;
+        }
+        const redisKey = this.getRedisKey(identity);
+        let redisValue;
+        try {
+            redisValue = this.jsonStringify(value);
+        }
+        catch (error) {
+            this.logger.error(`格式化 cache 数据失败，key=${redisKey}`, value, error);
+            throw error;
+        }
+        this.logger.debug('set', redisKey, redisValue);
+        await this.redis.set(redisKey, redisValue, { EX: this.options.expires });
+    }
+    /** 移除一项内容 */
+    async delete(identity = '') {
+        const identities = Array.isArray(identity) ? identity : [identity];
+        this.logger.debug('delete', identities);
+        return this.redis.del(identities.map(identity => this.getRedisKey(identity)));
+    }
+    /** 刷新一项内容的过期时间 */
+    async refresh(identity = '') {
+        if (this.options.expires >= 0)
+            return this.redis.expire(this.getRedisKey(identity), this.options.expires);
+        else
+            return false;
+    }
+    /** 确认一项内容是否存在  */
+    async exists(identity = '') {
+        return (await this.redis.exists(this.getRedisKey(identity))) === 1;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anjianshi/utils",
-  "version": "2.3.9",
+  "version": "2.3.10",
   "description": "Common JavaScript Utils",
   "homepage": "https://github.com/anjianshi/js-packages/utils",
   "bugs": {
@@ -26,10 +26,10 @@
     "dotenv": "^16.4.5",
     "typescript": "^5.5.4",
     "vconsole": "^3.15.1",
-    "@anjianshi/presets-eslint-typescript": "5.0.5",
     "@anjianshi/presets-eslint-node": "4.0.8",
-    "@anjianshi/presets-prettier": "3.0.1",
+    "@anjianshi/presets-eslint-typescript": "5.0.5",
     "@anjianshi/presets-typescript": "3.2.2",
+    "@anjianshi/presets-prettier": "3.0.1",
     "@anjianshi/presets-eslint-react": "4.0.7"
   },
   "peerDependencies": {
@@ -39,7 +39,8 @@
     "@prisma/client": "^5.20.0",
     "chalk": "^5.3.0",
     "dayjs": "^1.11.10",
-    "react": "^18.3.1"
+    "react": "^18.3.1",
+    "redis": "^4.7.0"
   },
   "peerDependenciesMeta": {
     "@emotion/react": {
@@ -62,6 +63,9 @@
     },
     "react": {
       "optional": true
+    },
+    "redis": {
+      "optional": true
     }
   },
   "prettier": "@anjianshi/presets-prettier/prettierrc"