@jayfong/x-server 2.119.0 → 3.1.1

package/lib/services/cache.mjs

@@ -0,0 +1,323 @@
+import { x } from "../x.mjs";
+import { ms } from "vtils";
+import cuid from "cuid";
+import superjson from "superjson";
+// src/services/cache.ts
+const nativeJsonSerializer = {
+	stringify: JSON.stringify,
+	parse: JSON.parse
+};
+const superJsonSerializer = {
+	stringify: superjson.stringify,
+	parse: superjson.parse
+};
+var CacheService = class CacheService {
+	options;
+	serviceName = "cache";
+	prefix;
+	hasMemoryCache = false;
+	hasMemoryCacheOnly = false;
+	memoryCache;
+	serializer;
+	constructor(options) {
+		this.options = options;
+		this.prefix = `${x.appId}:`;
+		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();
+	}
+	toRedisKey(key) {
+		return `${this.prefix}${Array.isArray(key) ? key.join("_") : String(key)}`;
+	}
+	serialize(value) {
+		return this.serializer.stringify(value);
+	}
+	deserialize(value) {
+		return this.serializer.parse(value);
+	}
+	/**
+	* 设置缓存内容。对象类内容尽量避免使用，以免造成问题。
+	*
+	* @memory 支持
+	* @param key 键
+	* @param value 值
+	* @param ttlOrOptions 缓存时间或选项
+	* @returns 返回设置的缓存内容
+	*/
+	async set(key, value, ttlOrOptions) {
+		const ttl = ttlOrOptions == null ? this.options.ttl : typeof ttlOrOptions === "object" ? ttlOrOptions.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 x.redis.set(redisKey, redisValue, "PX", redisTtlMs);
+				}
+				if (this.hasMemoryCache) this.memoryCache.set(redisKey, value);
+			}
+		}
+		return value;
+	}
+	/**
+	* 存储值然后返回其对应的键，该键 URL 友好。
+	*
+	* @memory 支持
+	* @param value 值
+	* @param ttl 存活时间
+	*/
+	async save(value, ttl = this.options.ttl) {
+		const key = `X__${cuid()}`;
+		await this.set(key, typeof value === "function" ? await value(key) : value, ttl);
+		return key;
+	}
+	/**
+	* 获取缓存内容。
+	*
+	* @memory 支持
+	* @param key 键
+	* @param options 选项
+	* @returns 返回获取到的缓存内容
+	*/
+	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 x.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 支持
+	* @param keys 键
+	* @returns 返回获取到的缓存内容
+	*/
+	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 x.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 x.redis.mget(...redisKeys)).map((value) => {
+			if (value == null) return null;
+			try {
+				return this.deserialize(value);
+			} catch {
+				return null;
+			}
+		});
+	}
+	/**
+	* 获取距离过期时间的毫秒数（未设置过期时间返回-1，键不存在返回-2）。
+	* memory=only 模式下内存缓存无 TTL 概念，始终返回-1。
+	*
+	* @memory 支持
+	* @param key 键
+	* @returns 返回距离过期时间的毫秒数
+	*/
+	async ttl(key) {
+		if (this.hasMemoryCacheOnly) return -1;
+		const redisKey = this.toRedisKey(key);
+		return x.redis.pttl(redisKey);
+	}
+	/**
+	* 缓存内容。
+	*
+	* @memory 支持
+	* @param key 键
+	* @param action 获取缓存内容的操作
+	* @param ttlOrOptions 缓存时间或选项
+	* @returns 返回获取到的内容
+	*/
+	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;
+	}
+	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 支持
+	* @param key 键
+	* @param increment 增量
+	*/
+	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 x.redis.incrby(redisKey, increment);
+		if (this.hasMemoryCache) this.memoryCache.delete(redisKey);
+		return result;
+	}
+	/**
+	* 自减。
+	*
+	* @memory 支持
+	* @param key 键
+	* @param decrement 减量
+	*/
+	async decrease(key, decrement = 1) {
+		return this.increase(key, -decrement);
+	}
+	/**
+	* 新增元素。
+	*
+	* @memory 支持
+	* @param key 键
+	* @param values 元素列表
+	*/
+	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 x.redis.rpush(redisKey, ...values.map((value) => this.serialize(value)));
+		if (this.hasMemoryCache) this.memoryCache.delete(redisKey);
+		return result;
+	}
+	/**
+	* 从头部弹出元素并返回。
+	*
+	* @memory 支持
+	* @param key 键
+	* @param count 弹出元素个数
+	*/
+	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 x.redis.lpop(redisKey);
+			if (item) res.push(this.deserialize(item));
+			else break;
+		}
+		if (this.hasMemoryCache && res.length) this.memoryCache.delete(redisKey);
+		return res;
+	}
+	/**
+	* 删除缓存。
+	*
+	* @memory 支持
+	* @param keys 键列表
+	*/
+	async remove(...keys) {
+		if (!keys.length) return 0;
+		const redisKeys = keys.map((key) => this.toRedisKey(key));
+		let count = 0;
+		if (!this.hasMemoryCacheOnly) count = await x.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 支持
+	*/
+	async clearAll() {
+		let count = 0;
+		if (!this.hasMemoryCacheOnly) {
+			const keys = await x.redis.keys(`${this.prefix}*`);
+			count = keys.length ? await x.redis.del(...keys) : 0;
+		}
+		if (this.hasMemoryCache) {
+			const memoryCacheSize = this.memoryCache.size;
+			this.memoryCache.clear();
+			if (this.hasMemoryCacheOnly) count = memoryCacheSize;
+		}
+		return count;
+	}
+	/**
+	* 清空指定前缀的缓存。
+	*
+	* @memory 支持
+	*/
+	async clear(...prefixes) {
+		if (!prefixes.length) return 0;
+		let count = 0;
+		if (!this.hasMemoryCacheOnly) {
+			const keys = (await Promise.all(prefixes.map((prefix) => x.redis.keys(`${this.toRedisKey(prefix)}*`)))).flat();
+			count = keys.length ? await x.redis.del(...keys) : 0;
+		}
+		if (this.options.memory) {
+			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;
+	}
+	/**
+	* 派生出一个指定类型的缓存服务。
+	*/
+	fork(options) {
+		return options ? new CacheService({
+			...this.options,
+			...options
+		}) : this;
+	}
+};
+export { CacheService };

package/lib/services/captcha.d.mts

@@ -0,0 +1,65 @@
+import { BaseService } from "./base.mjs";
+import { MsValue } from "vtils";
+export type CaptchaServiceGenerateCharset = '09' | '19' | 'az' | 'AZ' | 'aZ' | '0z' | '0Z' | '1z' | '1Z';
+export interface CaptchaServiceGeneratePayload<T> {
+  /**
+   * 场景值
+   *
+   * 比如：防止后台验证码图片登录用其他场景下的短信验证码
+   */
+  scene: string;
+  /**
+   * 验证码长度
+   */
+  size: number;
+  /**
+   * 验证码存活时长
+   */
+  ttl: MsValue;
+  /**
+   * 字符集
+   */
+  charset: CaptchaServiceGenerateCharset;
+  /**
+   * 可重试次数
+   *
+   * @default 0
+   */
+  retryCount?: number;
+  /**
+   * 其他信息
+   */
+  extra?: T;
+}
+export interface CaptchaServiceGenerateResult {
+  token: string;
+  code: string;
+}
+export interface CaptchaServiceGenerateImageResult {
+  token: string;
+  code: string;
+  svg: string;
+}
+export interface CaptchaServiceGenerateDataUrlResult {
+  token: string;
+  code: string;
+  dataUrl: string;
+}
+export interface CaptchaServiceVerifyOptions<T> {
+  token: string;
+  code: string;
+  scene: string;
+  extra?: (extra: T) => boolean;
+}
+export declare class CaptchaService implements BaseService {
+  serviceName: string;
+  private charsetMap;
+  generate<T extends Record<string, any>>(payload: CaptchaServiceGeneratePayload<T>): Promise<CaptchaServiceGenerateResult>;
+  generateDataUrl<T extends Record<string, any>>(payload: CaptchaServiceGeneratePayload<T>): Promise<CaptchaServiceGenerateDataUrlResult>;
+  verify<T extends Record<string, any>>(options: CaptchaServiceVerifyOptions<T>): Promise<boolean>;
+}
+declare module '../x.mjs' {
+  interface X {
+    captcha: CaptchaService;
+  }
+}

package/lib/services/captcha.mjs

@@ -0,0 +1,61 @@
+import { x } from "../x.mjs";
+import { sample } from "vtils";
+import svgToDataUrl from "mini-svg-data-uri";
+import svgCaptcha from "svg-captcha";
+// src/services/captcha.ts
+var CaptchaService = class {
+	serviceName = "captcha";
+	charsetMap = {
+		"09": "0123456789".split(""),
+		"19": "123456789".split(""),
+		az: "abcdefghijklmnopqrstuvwxyz".split(""),
+		AZ: "ABCDEFGHIJKLMNOPQRSTUVWXYZ".split(""),
+		aZ: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".split(""),
+		"0z": "0123456789abcdefghijklmnopqrstuvwxyz".split(""),
+		"0Z": "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".split(""),
+		"1z": "123456789abcdefghijklmnopqrstuvwxyz".split(""),
+		"1Z": "123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ".split("")
+	};
+	async generate(payload) {
+		const chars = this.charsetMap[payload.charset];
+		let code = "";
+		for (let i = 0; i < payload.size; i++) code += sample(chars);
+		return {
+			token: await x.cache.save({
+				code,
+				scene: payload.scene,
+				retryCount: payload.retryCount ?? 0,
+				extra: payload.extra
+			}, payload.ttl),
+			code
+		};
+	}
+	async generateDataUrl(payload) {
+		const { text: code, data: svg } = svgCaptcha.create({
+			size: payload.size,
+			charPreset: this.charsetMap[payload.charset].join("")
+		});
+		return {
+			token: await x.cache.save({
+				code,
+				scene: payload.scene,
+				retryCount: payload.retryCount || 0,
+				extra: payload.extra
+			}, payload.ttl),
+			code,
+			dataUrl: svgToDataUrl(svg)
+		};
+	}
+	async verify(options) {
+		const expected = await x.cache.get(options.token);
+		if (expected == null) return false;
+		if (expected.retryCount === 0) await x.cache.remove(options.token);
+		else {
+			expected.retryCount--;
+			const ttl = await x.cache.ttl(options.token);
+			await x.cache.set(options.token, expected, ttl);
+		}
+		return expected.scene === options.scene && options.code.toLowerCase() === expected.code.toLowerCase() && (options.extra ? options.extra(expected.extra) : true);
+	}
+};
+export { CaptchaService };

package/lib/services/{crypto.js → crypto.d.mts}

@@ -1,28 +1,20 @@
-import crypto from 'node:crypto';
-export class CryptoService {
-  constructor() {
-    this.serviceName = 'crypto';
-  }
+import { BaseService } from "./base.mjs";
+export declare class CryptoService implements BaseService {
+  serviceName: string;
   /**
    * 将给定的文本转换为 Base64 编码的字符串
    *
    * @param text 需要编码的原始文本
    * @returns 返回 Base64 编码后的字符串
    */
-  base64Encode(text) {
-    return Buffer.from(text).toString('base64');
-  }
-
+  base64Encode(text: string): string;
   /**
    * 将 Base64 编码的字符串转换为 UTF-8 编码的字符串
    *
    * @param text Base64 编码的字符串
    * @returns 转换后的 UTF-8 编码的字符串
    */
-  base64Decode(text) {
-    return Buffer.from(text, 'base64').toString('utf8');
-  }
-
+  base64Decode(text: string): string;
   /**
    * 将字符串文本编码为Base64 URL格式
    *
@@ -33,23 +25,7 @@ export class CryptoService {
    * @param text 需要被编码的字符串文本
    * @returns 编码后的Base64 URL安全字符串
    */
-  base64UrlEncode(text) {
-    // 将输入文本转换为Buffer对象，并进一步将其转换为Base64编码的字符串
-    let base64 = Buffer.from(text).toString('base64');
-
-    // 将Base64编码中的'+'替换为'-'，以适应URL安全要求
-    base64 = base64.replace(/\+/g, '-');
-
-    // 将Base64编码中的'/'替换为'_'，以适应URL安全要求
-    base64 = base64.replace(/\//g, '_');
-
-    // 移除Base64编码中用于填充的'='字符，以适应URL安全要求
-    base64 = base64.replace(/=/g, '');
-
-    // 返回经过URL安全处理的Base64编码字符串
-    return base64;
-  }
-
+  base64UrlEncode(text: string): string;
   /**
    * 解码base64url格式的字符串
    * base64url是一种用于URL的base64编码变体，它将标准base64中的'+'和'/'字符替换为'-'和'_'，以避免URL编码
@@ -58,22 +34,14 @@ export class CryptoService {
    * @param text 需要解码的base64url格式的字符串
    * @returns 解码后的原始字符串
    */
-  base64UrlDecode(text) {
-    // 将base64url编码中的'-'和'_'替换回标准base64编码中的'+'和'/'
-    // 然后使用Node.js的Buffer对象从base64编码转换为utf8格式的字符串
-    return Buffer.from(text.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
-  }
-
+  base64UrlDecode(text: string): string;
   /**
    * 使用MD5算法对文本进行哈希处理
    *
    * @param text 需要进行哈希处理的文本
    * @returns 返回经过MD5哈希处理后的字符串
    */
-  md5(text) {
-    return crypto.createHash('md5').update(text).digest('hex');
-  }
-
+  md5(text: string): string;
   /**
    * 使用SHA-1算法对文本进行哈希处理
    *
@@ -84,56 +52,35 @@ export class CryptoService {
    * @param text 待哈希处理的文本字符串
    * @returns 返回文本的SHA-1散列值，以十六进制字符串形式表示
    */
-  sha1(text) {
-    return crypto.createHash('sha1').update(text).digest('hex');
-  }
-
+  sha1(text: string): string;
   /**
    * 使用SHA-256算法对文本进行哈希处理
    *
    * @param text 输入的文本字符串
    * @returns 返回经过SHA-256哈希处理后的十六进制字符串
    */
-  sha256(text) {
-    return crypto.createHash('sha256').update(text).digest('hex');
-  }
-
+  sha256(text: string): string;
   /**
    * 使用SHA-512算法对文本进行哈希处理
    *
    * @param text 输入的文本字符串
    * @returns 返回经过SHA-512哈希处理后的字符串
    */
-  sha512(text) {
-    return crypto.createHash('sha512').update(text).digest('hex');
-  }
-
+  sha512(text: string): string;
   /**
    * 使用给定的密钥对给定的字符串执行 AES 加密（加密模式为 ECB，填充方式为 PKCS7）。
    *
    * @param text - 要加密的字符串。
    * @param key - 用于加密的密钥（仅支持16字节的密钥）。
    */
-  aesEncrypt(text, key) {
-    const cipher = crypto.createCipheriv('aes-128-ecb', key.substring(0, 16), null);
-    let encrypted = cipher.update(text, 'utf8', 'base64');
-    encrypted += cipher.final('base64');
-    return encrypted;
-  }
-
+  aesEncrypt(text: string, key: string): string;
   /**
    * 使用给定的密钥对给定的字符串执行 AES 解密（解密模式为 ECB，填充方式为 PKCS7）。
    *
    * @param text - 要解密的字符串。
    * @param key - 用于解密的密钥（仅支持16字节的密钥）。
    */
-  aesDecrypt(text, key) {
-    const decipher = crypto.createDecipheriv('aes-128-ecb', key.substring(0, 16), null);
-    let decrypted = decipher.update(text, 'base64', 'utf8');
-    decrypted += decipher.final('utf8');
-    return decrypted;
-  }
-
+  aesDecrypt(text: string, key: string): string;
   /**
    * 使用AES加密算法对JSON数据进行加密
    *
@@ -146,13 +93,7 @@ export class CryptoService {
    * @returns 返回加密后的字符串数据
    *          加密后的数据可以安全地进行网络传输或存储
    */
-  aesEncryptJson(payload, key) {
-    // 将payload对象序列化为JSON字符串，以便进行加密处理
-    // 使用指定的密钥对序列化后的JSON字符串进行AES加密
-    // 返回加密后的数据，确保数据在传输或存储过程中的安全性
-    return this.aesEncrypt(JSON.stringify(payload), key);
-  }
-
+  aesEncryptJson(payload: any, key: string): string;
   /**
    * 使用AES算法解密给定的文本，并将解密后的结果解析为JSON对象
    *
@@ -160,10 +101,10 @@ export class CryptoService {
    * @param key 解密用的密钥，必须与加密时使用的密钥相同
    * @returns 返回解密后的JSON对象，类型为泛型T，根据调用时指定的类型解析
    */
-  aesDecryptJson(text, key) {
-    // 使用指定的密钥对给定的加密数据进行AES解密
-    // 将解密后的数据反序列化为JSON对象，以便后续的处理
-    // 返回解密后的数据，确保数据在传输或存储过程中的安全性
-    return JSON.parse(this.aesDecrypt(text, key));
+  aesDecryptJson<T>(text: string, key: string): T;
+}
+declare module '../x.mjs' {
+  interface X {
+    crypto: CryptoService;
   }
 }