@jayfong/x-utils 3.3.0 → 3.4.0

package/lib/cache.mjs

@@ -0,0 +1,531 @@
+import { XRandom } from "./random.mjs";
+import { ms } from "vtils";
+import superjson from "superjson";
+// src/cache.ts
+const nativeJsonSerializer = {
+	stringify: JSON.stringify,
+	parse: JSON.parse
+};
+const superJsonSerializer = {
+	stringify: superjson.stringify,
+	parse: superjson.parse
+};
+/**
+* 通用缓存服务。
+*
+* 基于 Redis 实现，可选叠加一层进程内存缓存。通过泛型方式描述缓存键与
+* 值类型，从而获得类型安全的读写体验。
+*
+* 泛型说明：
+* - `TData`：缓存数据描述类型，形如
+*   `{ user: (id: number) => string; totalUser: () => number }`；
+* - `TKey`：所有缓存键名（由 `TData` 推导）；
+* - `TKeyPath`：完整缓存键路径（无参函数为键名本身，有参函数为
+*   `[键名, ...参数]` 元组）；
+* - `TKeyPathForNumberValue`：数字值对应的完整键路径，用于自增/自减；
+* - `TKeyPartialPath`：允许参数部分缺省的键路径，用于按前缀清理。
+*
+* 通常无需手动传泛型，直接用 `XCache` 即可；需要强类型约束时通过
+* {@link XCache.fork} 传入 `TData` 派生。
+*
+* @example
+* const cache = new XCache({
+*   prefix: 'app:',
+*   redis: new XRedis(),
+*   ttl: 600,
+* });
+*
+* const userCache = cache.fork<{ user: (id: number) => string }>();
+* await userCache.set(['user', 1], 'Jay');
+* // 'Jay'
+* const user = await userCache.get(['user', 1]);
+* // 'Jay'
+*/
+var XCache = class XCache {
+	options;
+	prefix;
+	redis;
+	hasMemoryCache = false;
+	hasMemoryCacheOnly = false;
+	memoryCache;
+	serializer;
+	/**
+	* 创建缓存服务实例。
+	*
+	* @param options 缓存配置，含前缀、Redis 实例、默认 TTL 等。
+	*/
+	constructor(options) {
+		this.options = options;
+		this.prefix = options.prefix;
+		this.redis = options.redis;
+		this.hasMemoryCache = !!options.memory;
+		this.hasMemoryCacheOnly = options.memory === "only";
+		this.serializer = options.serializer == null || options.serializer === "nativeJson" ? nativeJsonSerializer : options.serializer === "superJson" ? superJsonSerializer : options.serializer;
+		this.memoryCache = !this.hasMemoryCache ? void 0 : /* @__PURE__ */ new Map();
+	}
+	/**
+	* 将缓存键转换为 Redis 键。
+	*
+	* 元组键用 `_` 连接各段（如 `['user', 1]` → `user_1`），普通键直接
+	* 转为字符串，最终加上 {@link XCacheOptions.prefix} 前缀。
+	*
+	* 注意：使用 `_` 连接时，元组各段自身若含 `_`，可能与其他键发生冲突。
+	*/
+	toRedisKey(key) {
+		return `${this.prefix}${Array.isArray(key) ? key.join("_") : String(key)}`;
+	}
+	/**
+	* 序列化值。
+	*
+	* @param value 待序列化的值。
+	* @returns 序列化后的字符串。
+	*/
+	serialize(value) {
+		return this.serializer.stringify(value);
+	}
+	/**
+	* 反序列化字符串。
+	*
+	* @param value 待反序列化的字符串。
+	* @returns 反序列化后的值。
+	*/
+	deserialize(value) {
+		return this.serializer.parse(value);
+	}
+	/**
+	* 设置缓存内容。
+	*
+	* 对象类内容建议避免缓存，以免反序列化后类型丢失等问题；确需缓存对象时
+	* 推荐使用 `'superJson'` 序列化器。
+	*
+	* 行为与分支：
+	* - 未传 `ttlOrOptions`，或传入对象但未指定 `ttl` 时，使用构造时的默认
+	*   TTL（{@link XCacheOptions.ttl}）；
+	* - `ttl` 支持函数形式，可依据写入值与默认 TTL 动态计算；
+	* - TTL 换算后小于等于 0 时不写入任何缓存（视为禁用缓存）；
+	* - 非 `memory=only` 模式写入 Redis；启用内存缓存时同步写入内存。
+	*
+	* @param key 缓存键，可为字符串或 `[键名, ...参数]` 元组。
+	* @param value 缓存值。
+	* @param ttlOrOptions 缓存时间或选项；缺省时使用默认 TTL。
+	* @returns 返回写入的缓存值。
+	*
+	* @example
+	* await cache.set('greeting', 'hello');
+	* // 'hello'
+	* await cache.set(['user', 1], 'Jay', 500);
+	* // 'Jay'，500 毫秒后过期
+	*/
+	async set(key, value, ttlOrOptions) {
+		const ttl = ttlOrOptions == null ? this.options.ttl : typeof ttlOrOptions === "object" ? ttlOrOptions.ttl ?? this.options.ttl : ttlOrOptions;
+		const redisTtl = typeof ttl === "function" ? ttl(value, this.options.ttl) : ttl;
+		if (redisTtl) {
+			const redisTtlMs = ms(redisTtl);
+			if (redisTtlMs > 0) {
+				const redisKey = this.toRedisKey(key);
+				if (!this.hasMemoryCacheOnly) {
+					const redisValue = this.serialize(value);
+					await this.redis.set(redisKey, redisValue, "PX", redisTtlMs);
+				}
+				if (this.hasMemoryCache) this.memoryCache.set(redisKey, value);
+			}
+		}
+		return value;
+	}
+	/**
+	* 存储一个值并返回其对应的键。
+	*
+	* 键由 `X__` 前缀与 CUID2 随机串组成，仅包含字母与数字，URL 友好。
+	* 值可为固定值，也可为以生成键为入参的函数，便于生成引用自身的键。
+	*
+	* @param value 待存储的值，或接收生成的键并返回值的函数。
+	* @param ttl 存活时间；缺省时使用构造时的默认 TTL。
+	* @returns 生成的缓存键。
+	*
+	* @example
+	* const key = await cache.save('hello');
+	* // 'X__dj8fyuqt57ejnnbsnik8q1d6'
+	* await cache.get(key);
+	* // 'hello'
+	*/
+	async save(value, ttl = this.options.ttl) {
+		const key = `X__${XRandom.cuid2()}`;
+		await this.set(key, typeof value === "function" ? await value(key) : value, ttl);
+		return key;
+	}
+	/**
+	* 获取缓存内容。
+	*
+	* 查找顺序：
+	* 1. 启用内存缓存时先查内存，命中直接返回；
+	* 2. `memory=only` 模式内存未命中即返回 `null`，不回源 Redis；
+	* 3. 其余情况从 Redis 读取；命中后反序列化，并在启用内存缓存时回填内存。
+	*
+	* Redis 中无该键、值为空或反序列化失败时均返回 `null`。
+	*
+	* @param key 缓存键。
+	* @returns 缓存值；不存在时返回 `null`。
+	*
+	* @example
+	* const user = await cache.get(['user', 1]);
+	* // 'Jay' | null
+	*/
+	async get(key) {
+		const redisKey = this.toRedisKey(key);
+		if (this.hasMemoryCache) {
+			if (this.memoryCache.has(redisKey)) return this.memoryCache.get(redisKey);
+			else if (this.hasMemoryCacheOnly) return null;
+		}
+		const gotValue = await this.redis.get(redisKey);
+		if (gotValue) try {
+			const parsedValue = this.deserialize(gotValue);
+			if (this.hasMemoryCache) this.memoryCache.set(redisKey, parsedValue);
+			return parsedValue;
+		} catch {}
+		return null;
+	}
+	/**
+	* 批量获取缓存内容。
+	*
+	* - 未传任何键时返回空数组；
+	* - `memory=only` 模式直接按内存缓存逐个返回；
+	* - 启用内存缓存时，内存命中的直接返回，未命中的再从 Redis 批量读取
+	*   并回填内存；
+	* - 其余情况从 Redis 批量读取。
+	*
+	* 单个键读取失败（如反序列化异常）时对应位置返回 `null`，不影响其他键。
+	*
+	* @param keys 缓存键列表。
+	* @returns 与入参顺序一致的缓存值数组，未命中的位置为 `null`。
+	*
+	* @example
+	* await cache.getMany(['user', 1], ['user', 2]);
+	* // ['Jay', 'Tom']
+	*/
+	async getMany(...keys) {
+		const redisKeys = keys.map((key) => this.toRedisKey(key));
+		if (!redisKeys.length) return [];
+		if (this.hasMemoryCacheOnly) return redisKeys.map((redisKey) => this.memoryCache.has(redisKey) ? this.memoryCache.get(redisKey) : null);
+		if (this.hasMemoryCache) {
+			const result = new Array(keys.length).fill(null);
+			const missIndexes = [];
+			const missRedisKeys = [];
+			for (let i = 0; i < redisKeys.length; i++) if (this.memoryCache.has(redisKeys[i])) result[i] = this.memoryCache.get(redisKeys[i]);
+			else {
+				missIndexes.push(i);
+				missRedisKeys.push(redisKeys[i]);
+			}
+			if (missRedisKeys.length) (await this.redis.mget(...missRedisKeys)).forEach((value, idx) => {
+				if (value != null) try {
+					const parsed = this.deserialize(value);
+					this.memoryCache.set(missRedisKeys[idx], parsed);
+					result[missIndexes[idx]] = parsed;
+				} catch {}
+			});
+			return result;
+		}
+		return (await this.redis.mget(...redisKeys)).map((value) => {
+			if (value == null) return null;
+			try {
+				return this.deserialize(value);
+			} catch {
+				return null;
+			}
+		});
+	}
+	/**
+	* 获取距离过期时间的毫秒数。
+	*
+	* - Redis 中未设置过期时间返回 `-1`，键不存在返回 `-2`；
+	* - `memory=only` 模式内存缓存无 TTL 概念，始终返回 `-1`。
+	*
+	* @param key 缓存键。
+	* @returns 距离过期的毫秒数。
+	*
+	* @example
+	* await cache.ttl('greeting');
+	* // 还剩多少毫秒过期；未设置过期时间时返回 -1
+	*/
+	async ttl(key) {
+		if (this.hasMemoryCacheOnly) return -1;
+		const redisKey = this.toRedisKey(key);
+		return this.redis.pttl(redisKey);
+	}
+	/**
+	* 读取缓存，未命中时执行 `action` 获取值并写回缓存。
+	*
+	* 先按 {@link XCache.get} 逻辑读取；命中直接返回，否则执行 `action`，
+	* 将结果写入缓存并返回。适合「缓存优先、未命中再计算」的场景。
+	*
+	* 注意：`action` 返回 `null` 时也会写入缓存，但下次读取仍视为未命中，
+	* 会再次执行 `action`。
+	*
+	* @param key 缓存键。
+	* @param action 缓存未命中时获取内容的操作，支持同步或异步。
+	* @param ttlOrOptions 缓存时间或选项；缺省时使用默认 TTL。
+	* @returns 缓存值或 `action` 计算得到的新值。
+	*
+	* @example
+	* const user = await cache.remember(['user', 1], async () => {
+	*   return await fetchUser(1);
+	* });
+	* // 命中缓存时返回缓存值，否则返回 fetchUser(1) 的结果
+	*/
+	async remember(key, action, ttlOrOptions) {
+		let value = await this.get(key);
+		if (value === null) {
+			value = await action();
+			await this.set(key, value, ttlOrOptions);
+		}
+		return value;
+	}
+	/**
+	* 批量读取缓存，未命中的元素执行 `action` 获取值并写回缓存。
+	*
+	* 先按 {@link XCache.getMany} 批量读取；将未命中的原始元素（`raws` 中
+	* 对应下标项）交给 `action` 计算新值，再逐个写回缓存，最后返回与
+	* `raws` 顺序一致的结果数组。
+	*
+	* @param raws 原始数据列表，用于推导键并作为 `action` 的入参。
+	* @param key 从原始数据推导缓存键的函数。
+	* @param action 缓存未命中的元素批量计算新值的操作，返回数组需与
+	*   未命中元素顺序一致。
+	* @param ttlOrOptions 缓存时间或选项；缺省时使用默认 TTL。
+	* @returns 与 `raws` 顺序一致的缓存值数组。
+	*
+	* @example
+	* const users = await cache.rememberMany(
+	*   [1, 2],
+	*   id => ['user', id],
+	*   ids => ids.map(id => fetchUser(id)),
+	* );
+	*/
+	async rememberMany(raws, key, action, ttlOrOptions) {
+		const keys = raws.map(key);
+		const values = await this.getMany(...keys);
+		const shouldUpdateIndexes = [];
+		for (let i = 0, len = values.length; i < len; i++) if (values[i] === null) shouldUpdateIndexes.push(i);
+		if (shouldUpdateIndexes.length) {
+			const nextValues = await action(shouldUpdateIndexes.map((i) => raws[i]));
+			await Promise.all(nextValues.map(async (nextValue, index) => {
+				values[shouldUpdateIndexes[index]] = nextValue;
+				await this.set(keys[shouldUpdateIndexes[index]], nextValue, ttlOrOptions);
+			}));
+		}
+		return values;
+	}
+	/**
+	* 自增。
+	*
+	* - `memory=only` 模式直接操作内存中的数字；
+	* - 其余模式调用 Redis `INCRBY`，并在启用内存缓存时删除对应内存键，
+	*   使下次读取从 Redis 回源。
+	*
+	* @param key 缓存键，对应的值类型需为 `number`。
+	* @param increment 增量，可为负数；缺省为 `1`。
+	* @returns 自增后的值。
+	*
+	* @example
+	* await cache.increase('totalUser');
+	* // 1
+	* await cache.increase('totalUser', 10);
+	* // 11
+	*/
+	async increase(key, increment = 1) {
+		const redisKey = this.toRedisKey(key);
+		if (this.hasMemoryCacheOnly) {
+			const next = (this.memoryCache.get(redisKey) ?? 0) + increment;
+			this.memoryCache.set(redisKey, next);
+			return next;
+		}
+		const result = await this.redis.incrby(redisKey, increment);
+		if (this.hasMemoryCache) this.memoryCache.delete(redisKey);
+		return result;
+	}
+	/**
+	* 自减。
+	*
+	* 行为与 {@link XCache.increase} 一致，仅将增量取负。
+	*
+	* @param key 缓存键，对应的值类型需为 `number`。
+	* @param decrement 减量，可为负数；缺省为 `1`。
+	* @returns 自减后的值。
+	*
+	* @example
+	* await cache.decrease('totalUser');
+	* // 10
+	*/
+	async decrease(key, decrement = 1) {
+		return this.increase(key, -decrement);
+	}
+	/**
+	* 向列表尾部追加元素。
+	*
+	* - `memory=only` 模式直接操作内存数组；
+	* - 其余模式调用 Redis `RPUSH` 逐个追加（先序列化），并在启用内存缓存时
+	*   删除对应内存键，使下次读取从 Redis 回源。
+	*
+	* @param key 缓存键。
+	* @param values 待追加的元素列表。
+	* @returns 追加后列表的长度。
+	*
+	* @example
+	* await cache.push('queue', 'a', 'b');
+	* // 2
+	*/
+	async push(key, ...values) {
+		const redisKey = this.toRedisKey(key);
+		if (this.hasMemoryCacheOnly) {
+			const arr = this.memoryCache.get(redisKey) ?? [];
+			arr.push(...values);
+			this.memoryCache.set(redisKey, arr);
+			return arr.length;
+		}
+		const result = await this.redis.rpush(redisKey, ...values.map((value) => this.serialize(value)));
+		if (this.hasMemoryCache) this.memoryCache.delete(redisKey);
+		return result;
+	}
+	/**
+	* 从列表头部弹出元素。
+	*
+	* - `memory=only` 模式直接操作内存数组；
+	* - 其余模式逐次调用 Redis `LPOP` 弹出并反序列化，遇到空列表提前结束；
+	*   弹出过元素且启用内存缓存时，删除对应内存键使下次读取回源。
+	*
+	* @param key 缓存键。
+	* @param count 弹出元素个数；缺省为 `1`，实际返回数量不超过列表长度。
+	* @returns 弹出的元素数组，列表为空时返回空数组。
+	*
+	* @example
+	* await cache.push('queue', 'a', 'b');
+	* await cache.shift('queue');
+	* // ['a']
+	*/
+	async shift(key, count = 1) {
+		const redisKey = this.toRedisKey(key);
+		if (this.hasMemoryCacheOnly) {
+			const arr = this.memoryCache.get(redisKey) ?? [];
+			const res = arr.splice(0, count);
+			if (arr.length) this.memoryCache.set(redisKey, arr);
+			else this.memoryCache.delete(redisKey);
+			return res;
+		}
+		const res = [];
+		for (let i = 0; i < count; i++) {
+			const item = await this.redis.lpop(redisKey);
+			if (item) res.push(this.deserialize(item));
+			else break;
+		}
+		if (this.hasMemoryCache && res.length) this.memoryCache.delete(redisKey);
+		return res;
+	}
+	/**
+	* 删除缓存。
+	*
+	* - 未传任何键时返回 `0`；
+	* - 非 `memory=only` 模式调用 Redis `DEL`，并同步删除内存缓存；
+	* - `memory=only` 模式仅删除内存缓存，返回实际删除的内存键数量。
+	*
+	* @param keys 待删除的缓存键列表。
+	* @returns 删除的键数量。
+	*
+	* @example
+	* await cache.remove('greeting', ['user', 1]);
+	* // 2
+	*/
+	async remove(...keys) {
+		if (!keys.length) return 0;
+		const redisKeys = keys.map((key) => this.toRedisKey(key));
+		let count = 0;
+		if (!this.hasMemoryCacheOnly) count = await this.redis.del(...redisKeys);
+		if (this.hasMemoryCache) {
+			let deletedCount = 0;
+			redisKeys.forEach((redisKey) => {
+				if (this.memoryCache.delete(redisKey)) deletedCount++;
+			});
+			if (this.hasMemoryCacheOnly) count = deletedCount;
+		}
+		return count;
+	}
+	/**
+	* 清空当前前缀下的全部缓存。
+	*
+	* - 非 `memory=only` 模式通过 `KEYS {prefix}*` 找出全部键后删除；
+	* - 启用内存缓存时清空内存缓存；`memory=only` 模式返回内存缓存大小。
+	*
+	* 注意：生产环境慎用 `KEYS`，键数量大时会阻塞 Redis。
+	*
+	* @returns 删除的键数量。
+	*
+	* @example
+	* await cache.clearAll();
+	* // 3
+	*/
+	async clearAll() {
+		let count = 0;
+		if (!this.hasMemoryCacheOnly) {
+			const keys = await this.redis.keys(`${this.prefix}*`);
+			count = keys.length ? await this.redis.del(...keys) : 0;
+		}
+		if (this.hasMemoryCache) {
+			const memoryCacheSize = this.memoryCache.size;
+			this.memoryCache.clear();
+			if (this.hasMemoryCacheOnly) count = memoryCacheSize;
+		}
+		return count;
+	}
+	/**
+	* 清空指定前缀的缓存。
+	*
+	* 对每个前缀执行 `KEYS {前缀}*` 找出匹配键后删除；启用内存缓存时，
+	* 按前缀匹配清理内存缓存中的键。
+	*
+	* - 未传任何前缀时返回 `0`；
+	* - `memory=only` 模式仅清理内存缓存，返回实际删除的内存键数量。
+	*
+	* @param prefixes 缓存键或键前缀列表。
+	* @returns 删除的键数量。
+	*
+	* @example
+	* await cache.clear('user');
+	* // 删除所有以 user 开头的键
+	*/
+	async clear(...prefixes) {
+		if (!prefixes.length) return 0;
+		let count = 0;
+		if (!this.hasMemoryCacheOnly) {
+			const keys = (await Promise.all(prefixes.map((prefix) => this.redis.keys(`${this.toRedisKey(prefix)}*`)))).flat();
+			count = keys.length ? await this.redis.del(...keys) : 0;
+		}
+		if (this.hasMemoryCache) {
+			let deletedCount = 0;
+			this.memoryCache.forEach((_v, k) => {
+				if (prefixes.some((prefix) => k.startsWith(this.toRedisKey(prefix)))) {
+					if (this.memoryCache.delete(k)) deletedCount++;
+				}
+			});
+			if (this.hasMemoryCacheOnly) count = deletedCount;
+		}
+		return count;
+	}
+	/**
+	* 派生出一个指定数据类型的缓存服务。
+	*
+	* 传入 `TNextData` 后可获得带类型约束的读写方法；不传选项时直接返回
+	* 当前实例（仅调整类型），传选项时基于当前配置合并选项创建新实例。
+	*
+	* @param options 可选的配置覆盖项，会与当前实例配置合并。
+	* @returns 指定数据类型的缓存服务。
+	*
+	* @example
+	* const userCache = cache.fork<{ user: (id: number) => string }>();
+	* await userCache.set(['user', 1], 'Jay');
+	*/
+	fork(options) {
+		return options ? new XCache({
+			...this.options,
+			...options
+		}) : this;
+	}
+};
+export { XCache };