@jayfong/x-utils 1.0.0-202510061015 → 3.4.0

package/lib/ai.d.mts

@@ -0,0 +1,103 @@
+import { PartialBy } from "vtils/types";
+/**
+ * AI 服务配置选项。
+ *
+ * 同时作为静态调用 `AiService.ask(payload)` 与实例化
+ * `new AiService(options)` 的公共配置。
+ */
+export interface AiServiceOptions {
+  /** 接口基础地址，例如 `https://dashscope.aliyuncs.com/compatible-mode/v1`。 */
+  baseUrl: string;
+  /** API 密钥，例如 `sk-xxx`；请求时会以 `Bearer <apiKey>` 形式放入 Authorization 头。 */
+  apiKey: string;
+  /** 模型名称，例如 `deepseek-v3.1`。 */
+  model: string;
+  /**
+   * 请求超时毫秒数，默认 1 分钟；
+   * 静态与实例调用均可通过该字段自定义超时时间。
+   */
+  timeoutMs?: number;
+  /**
+   * 额外请求头，会与内置的 `Authorization` 头合并；
+   * 同名键（如 `Authorization`）会覆盖内置值。
+   */
+  headers?: Record<string, string>;
+}
+/**
+ * 单次问答的请求参数。
+ *
+ * - 静态调用 `AiService.ask(payload)` 时，需要完整传入 `baseUrl` / `apiKey` / `model`；
+ * - 实例调用 `ai.ask(payload)` 时，以上配置可省略（缺省时回退到构造时的 options）。
+ */
+export interface AiServiceAskPayload extends AiServiceOptions {
+  /** 系统提示词，用于设定助手的角色或背景；不传时仅发送用户问题。 */
+  prompt?: string;
+  /** 用户提出的问题。 */
+  question: string;
+}
+/**
+ * Chat Completions 接口返回的单条消息。
+ */
+export interface AiServiceChatMessage {
+  /** 消息角色，例如 `system` / `user` / `assistant`。 */
+  role: string;
+  /** 消息内容文本。 */
+  content: string;
+}
+/**
+ * Chat Completions 接口返回的候选回答。
+ */
+export interface AiServiceChatChoice {
+  /** 候选回答中的消息内容。 */
+  message: AiServiceChatMessage;
+}
+/**
+ * Chat Completions 接口的响应体（仅保留本项目用到的字段）。
+ */
+export interface AiServiceChatResponse {
+  /** 候选回答列表，通常取第一条作为最终回答。 */
+  choices: AiServiceChatChoice[];
+}
+/**
+ * 单次问答的返回结果。
+ */
+export interface AiServiceAskResult {
+  /** 模型返回的回答文本。 */
+  answer: string;
+}
+/**
+ * 基于 OpenAI 兼容的 Chat Completions 接口封装的 AI 问答服务。
+ *
+ * 支持两种调用方式：
+ * 1. 静态调用（一次性传入全部配置）：
+ *    `await AiService.ask({ baseUrl, apiKey, model, question: '你好' })`
+ * 2. 实例调用（配置复用，仅需传入问题）：
+ *    `const ai = new AiService({ baseUrl, apiKey, model }); await ai.ask({ question: '你好' })`
+ */
+export declare class AiService {
+  private options;
+  constructor(options: AiServiceOptions);
+  /**
+   * 发送一次问答请求。
+   *
+   * 行为说明：
+   * 1. 请求地址为 `${baseUrl}/chat/completions`；
+   * 2. 自动拼接 `Authorization: Bearer <apiKey>` 头，并合并 `headers` 自定义头（自定义头优先）；
+   * 3. 若传入 `prompt`，会作为 `system` 消息放在 `user` 消息之前；否则仅发送 `user` 消息；
+   * 4. 默认 `stream: false`，一次性返回完整回答；
+   * 5. 默认请求超时为 1 分钟，可通过 `timeoutMs` 自定义（单位毫秒）；
+   *    且不自动抛出 HTTP 错误（由本方法自行判断状态码）。
+   *
+   * 异常场景：
+   * - 当接口返回非 200 状态码时，先输出原始错误信息便于排查，再抛出包含响应体的异常；
+   * - 当返回的 `choices` 为空或首条消息缺少 `content` 时，抛出提示异常的异常，避免返回空回答。
+   */
+  static ask(payload: AiServiceAskPayload): Promise<AiServiceAskResult>;
+  /**
+   * 实例问答：复用构造时传入的配置，允许按需覆盖部分配置。
+   *
+   * 最终配置为构造配置与本次参数的合并（`{ ...this.options, ...payload }`），
+   * 因此可在单次调用中覆盖 `model`、`prompt` 等任意字段。
+   */
+  ask(payload: PartialBy<AiServiceAskPayload, keyof AiServiceOptions>): Promise<AiServiceAskResult>;
+}

package/lib/ai.mjs

@@ -0,0 +1,75 @@
+import { xr } from "@jayfong/x-request";
+import { ms } from "vtils";
+// src/ai.ts
+/**
+* 基于 OpenAI 兼容的 Chat Completions 接口封装的 AI 问答服务。
+*
+* 支持两种调用方式：
+* 1. 静态调用（一次性传入全部配置）：
+*    `await AiService.ask({ baseUrl, apiKey, model, question: '你好' })`
+* 2. 实例调用（配置复用，仅需传入问题）：
+*    `const ai = new AiService({ baseUrl, apiKey, model }); await ai.ask({ question: '你好' })`
+*/
+var AiService = class AiService {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/**
+	* 发送一次问答请求。
+	*
+	* 行为说明：
+	* 1. 请求地址为 `${baseUrl}/chat/completions`；
+	* 2. 自动拼接 `Authorization: Bearer <apiKey>` 头，并合并 `headers` 自定义头（自定义头优先）；
+	* 3. 若传入 `prompt`，会作为 `system` 消息放在 `user` 消息之前；否则仅发送 `user` 消息；
+	* 4. 默认 `stream: false`，一次性返回完整回答；
+	* 5. 默认请求超时为 1 分钟，可通过 `timeoutMs` 自定义（单位毫秒）；
+	*    且不自动抛出 HTTP 错误（由本方法自行判断状态码）。
+	*
+	* 异常场景：
+	* - 当接口返回非 200 状态码时，先输出原始错误信息便于排查，再抛出包含响应体的异常；
+	* - 当返回的 `choices` 为空或首条消息缺少 `content` 时，抛出提示异常的异常，避免返回空回答。
+	*/
+	static async ask(payload) {
+		const res = await xr.postJson({
+			url: `${payload.baseUrl}/chat/completions`,
+			headers: {
+				Authorization: `Bearer ${payload.apiKey}`,
+				...payload.headers
+			},
+			data: {
+				model: payload.model,
+				messages: [...payload.prompt ? [{
+					role: "system",
+					content: payload.prompt
+				}] : [], {
+					role: "user",
+					content: payload.question
+				}],
+				stream: false
+			},
+			timeoutMs: payload.timeoutMs ?? ms("1m"),
+			noThrowHttpErrors: true
+		});
+		if (res.status !== 200) {
+			console.error(res.data);
+			throw new Error(JSON.stringify(res.data));
+		}
+		const answer = res.data?.choices?.[0]?.message?.content;
+		if (answer == null) throw new Error("AI 服务返回的 choices 为空，或首条消息缺少 content");
+		return { answer };
+	}
+	/**
+	* 实例问答：复用构造时传入的配置，允许按需覆盖部分配置。
+	*
+	* 最终配置为构造配置与本次参数的合并（`{ ...this.options, ...payload }`），
+	* 因此可在单次调用中覆盖 `model`、`prompt` 等任意字段。
+	*/
+	ask(payload) {
+		return AiService.ask({
+			...this.options,
+			...payload
+		});
+	}
+};
+export { AiService };

package/lib/cache.d.mts

@@ -0,0 +1,464 @@
+import { XRedis } from "./redis.mjs";
+import { MsValue } from "vtils";
+import { AsyncOrSync, IsEmptyArray } from "vtils/types";
+/**
+ * 序列化工具接口。
+ *
+ * 用于在写入 Redis 前将任意值转换为字符串，并在读取时还原为原值。
+ * 内置 `nativeJsonSerializer` 与 `superJsonSerializer` 两个实现，
+ * 也可自行实现以支持自定义数据格式（例如加密、压缩）。
+ */
+export interface XCacheSerializer {
+  /**
+   * 将值序列化为字符串。
+   *
+   * @param value 待序列化的值。
+   * @returns 序列化后的字符串。
+   */
+  stringify(value: unknown): string;
+  /**
+   * 将字符串反序列化为原值。
+   *
+   * @param value 待反序列化的字符串。
+   * @returns 反序列化后的值。
+   */
+  parse<T>(value: string): T;
+}
+/**
+ * {@link XCache} 的配置项。
+ */
+export interface XCacheOptions {
+  /**
+   * 缓存键前缀。
+   *
+   * 所有写入 Redis 的键都会加上该前缀，用于区分不同应用或模块的缓存，
+   * 例如 `app:` 会将键 `user_1` 落为 `app:user_1`。
+   */
+  prefix: string;
+  /**
+   * Redis 客户端实例。
+   *
+   * 仅在 `memory` 不为 `'only'` 时使用；`memory=only` 模式下可传入任意
+   * 实现，但不会被访问。
+   */
+  redis: XRedis;
+  /**
+   * 默认过期时间。
+   *
+   * 在 `set`/`remember` 等写入方法未显式指定 TTL 时使用。可为毫秒数或
+   * 时间字符串（如 `'1h'`、`'30s'`），解析规则同 `vtils` 的 `ms`。
+   */
+  ttl: MsValue;
+  /**
+   * 是否启用内存缓存。
+   *
+   * - `true`：启用内存缓存，写入时同时写 Redis 与内存，读取时优先命中内存；
+   * - `'only'`：仅使用内存缓存，完全不读写 Redis（TTL 不生效）；
+   * - 缺省：不使用内存缓存，全部走 Redis。
+   */
+  memory?: boolean | 'only';
+  /**
+   * 序列化工具。
+   *
+   * - `'nativeJson'`：使用原生 JSON 序列化/反序列化（默认），性能最好，
+   *   但无法还原 `Date`、`RegExp`、`Set` 等特殊类型；
+   * - `'superJson'`：使用 SuperJson 序列化/反序列化，支持更多数据类型，
+   *   但性能较原生 JSON 略差；
+   * - 也可直接传入自定义 `{ stringify, parse }` 实现。
+   */
+  serializer?: 'nativeJson' | 'superJson' | XCacheSerializer;
+}
+/**
+ * 缓存数据描述类型。
+ *
+ * 作为 {@link XCache} 的泛型约束：键为字符串、值为函数。函数名即缓存键，
+ * 函数入参与返回值分别用于推导完整键路径与缓存值类型。
+ *
+ * @example
+ * type UserData = {
+ *   user: (id: number) => string;
+ *   totalUser: () => number;
+ * };
+ */
+export type XCacheData = { [K in string]: (...args: any[]) => any; };
+/**
+ * 缓存数据描述中的键名集合。
+ */
+export type XCacheKey<T extends XCacheData> = keyof T;
+/**
+ * 完整缓存键路径。
+ *
+ * - 无参函数：键名本身，如 `totalUser`；
+ * - 有参函数：`[键名, ...参数]` 元组，如 `['user', 1]`。
+ */
+export type XCacheKeyPath<T extends XCacheData> = { [K in keyof T]: T[K] extends ((...args: infer X) => any) ? IsEmptyArray<X> extends true ? K : [K, ...X] : never; }[keyof T];
+/**
+ * 数字值对应的完整缓存键路径。
+ *
+ * 与 {@link XCacheKeyPath} 结构一致，但仅保留返回值为 `number` 的函数，
+ * 用于 `increase`/`decrease` 等数值操作方法。
+ */
+export type XCacheKeyPathForNumberValue<T extends XCacheData> = { [K in keyof T]: T[K] extends ((...args: infer X) => number) ? IsEmptyArray<X> extends true ? K : [K, ...X] : never; }[keyof T];
+/**
+ * 根据缓存键路径推导缓存值类型。
+ */
+export type XCacheValue<T extends XCacheData, P extends XCacheKeyPath<T>> = ReturnType<T[P extends any[] ? P[0] : P]>;
+/**
+ * 允许参数部分缺省的缓存键路径。
+ *
+ * 与 {@link XCacheKeyPath} 结构一致，但函数入参使用 `Partial`，
+ * 用于 `clear` 等按前缀（部分参数）清理的方法。
+ */
+export type XCacheKeyPartialPath<T extends XCacheData> = { [K in keyof T]: T[K] extends ((...args: infer X) => any) ? IsEmptyArray<X> extends true ? K : [K, ...Partial<X>] : never; }[keyof T];
+/**
+ * 自定义 TTL。
+ *
+ * 可直接传时间值（毫秒数或时间字符串），也可传函数，依据写入的数据与
+ * 默认 TTL 动态计算过期时间。
+ */
+export type XCacheSetTTL<V> = MsValue | ((data: V, defaultTTL: MsValue) => MsValue);
+/**
+ * `set`/`remember`/`rememberMany` 等方法中 TTL 相关选项。
+ *
+ * 可直接传 {@link XCacheSetTTL}，或传包含可选 `ttl` 字段的对象；
+ * 对象中未指定 `ttl` 时使用构造时的默认 TTL。
+ */
+export type XCacheSetOptions<V> = XCacheSetTTL<V> | {
+  /**
+   * 缓存过期时间。
+   *
+   * 缺省时使用构造时的默认 TTL（{@link XCacheOptions.ttl}）。
+   */
+  ttl?: XCacheSetTTL<V>;
+};
+/**
+ * 通用缓存服务。
+ *
+ * 基于 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'
+ */
+export declare class XCache<TData extends XCacheData = XCacheData, TKey extends XCacheKey<TData> = any, TKeyPath extends XCacheKeyPath<TData> = any, TKeyPathForNumberValue extends XCacheKeyPathForNumberValue<TData> = any, TKeyPartialPath extends XCacheKeyPartialPath<TData> = any> {
+  options: XCacheOptions;
+  private prefix;
+  private redis;
+  private hasMemoryCache;
+  private hasMemoryCacheOnly;
+  private memoryCache;
+  private serializer;
+  /**
+   * 创建缓存服务实例。
+   *
+   * @param options 缓存配置，含前缀、Redis 实例、默认 TTL 等。
+   */
+  constructor(options: XCacheOptions);
+  /**
+   * 将缓存键转换为 Redis 键。
+   *
+   * 元组键用 `_` 连接各段（如 `['user', 1]` → `user_1`），普通键直接
+   * 转为字符串，最终加上 {@link XCacheOptions.prefix} 前缀。
+   *
+   * 注意：使用 `_` 连接时，元组各段自身若含 `_`，可能与其他键发生冲突。
+   */
+  private toRedisKey;
+  /**
+   * 序列化值。
+   *
+   * @param value 待序列化的值。
+   * @returns 序列化后的字符串。
+   */
+  private serialize;
+  /**
+   * 反序列化字符串。
+   *
+   * @param value 待反序列化的字符串。
+   * @returns 反序列化后的值。
+   */
+  private deserialize;
+  /**
+   * 设置缓存内容。
+   *
+   * 对象类内容建议避免缓存，以免反序列化后类型丢失等问题；确需缓存对象时
+   * 推荐使用 `'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 毫秒后过期
+   */
+  set<K extends TKeyPath, V extends XCacheValue<TData, K>>(key: K, value: V, ttlOrOptions?: XCacheSetOptions<V>): Promise<V>;
+  /**
+   * 存储一个值并返回其对应的键。
+   *
+   * 键由 `X__` 前缀与 CUID2 随机串组成，仅包含字母与数字，URL 友好。
+   * 值可为固定值，也可为以生成键为入参的函数，便于生成引用自身的键。
+   *
+   * @param value 待存储的值，或接收生成的键并返回值的函数。
+   * @param ttl 存活时间；缺省时使用构造时的默认 TTL。
+   * @returns 生成的缓存键。
+   *
+   * @example
+   * const key = await cache.save('hello');
+   * // 'X__dj8fyuqt57ejnnbsnik8q1d6'
+   * await cache.get(key);
+   * // 'hello'
+   */
+  save<T>(value: T | ((key: string) => AsyncOrSync<T>), ttl?: MsValue): Promise<string>;
+  /**
+   * 获取缓存内容。
+   *
+   * 查找顺序：
+   * 1. 启用内存缓存时先查内存，命中直接返回；
+   * 2. `memory=only` 模式内存未命中即返回 `null`，不回源 Redis；
+   * 3. 其余情况从 Redis 读取；命中后反序列化，并在启用内存缓存时回填内存。
+   *
+   * Redis 中无该键、值为空或反序列化失败时均返回 `null`。
+   *
+   * @param key 缓存键。
+   * @returns 缓存值；不存在时返回 `null`。
+   *
+   * @example
+   * const user = await cache.get(['user', 1]);
+   * // 'Jay' | null
+   */
+  get<K extends TKeyPath, V extends XCacheValue<TData, K>>(key: K): Promise<V | null>;
+  /**
+   * 批量获取缓存内容。
+   *
+   * - 未传任何键时返回空数组；
+   * - `memory=only` 模式直接按内存缓存逐个返回；
+   * - 启用内存缓存时，内存命中的直接返回，未命中的再从 Redis 批量读取
+   *   并回填内存；
+   * - 其余情况从 Redis 批量读取。
+   *
+   * 单个键读取失败（如反序列化异常）时对应位置返回 `null`，不影响其他键。
+   *
+   * @param keys 缓存键列表。
+   * @returns 与入参顺序一致的缓存值数组，未命中的位置为 `null`。
+   *
+   * @example
+   * await cache.getMany(['user', 1], ['user', 2]);
+   * // ['Jay', 'Tom']
+   */
+  getMany<K extends TKeyPath, V extends XCacheValue<TData, K>>(...keys: K[]): Promise<Array<V | null>>;
+  /**
+   * 获取距离过期时间的毫秒数。
+   *
+   * - Redis 中未设置过期时间返回 `-1`，键不存在返回 `-2`；
+   * - `memory=only` 模式内存缓存无 TTL 概念，始终返回 `-1`。
+   *
+   * @param key 缓存键。
+   * @returns 距离过期的毫秒数。
+   *
+   * @example
+   * await cache.ttl('greeting');
+   * // 还剩多少毫秒过期；未设置过期时间时返回 -1
+   */
+  ttl<K extends TKeyPath>(key: K): Promise<number>;
+  /**
+   * 读取缓存，未命中时执行 `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) 的结果
+   */
+  remember<K extends TKeyPath, V extends XCacheValue<TData, K>>(key: K, action: () => AsyncOrSync<V>, ttlOrOptions?: XCacheSetOptions<V>): Promise<V>;
+  /**
+   * 批量读取缓存，未命中的元素执行 `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)),
+   * );
+   */
+  rememberMany<T, K extends TKeyPath, V extends XCacheValue<TData, K>>(raws: T[], key: (raw: T) => K, action: (raws: T[]) => AsyncOrSync<V[]>, ttlOrOptions?: XCacheSetOptions<V>): Promise<V[]>;
+  /**
+   * 自增。
+   *
+   * - `memory=only` 模式直接操作内存中的数字；
+   * - 其余模式调用 Redis `INCRBY`，并在启用内存缓存时删除对应内存键，
+   *   使下次读取从 Redis 回源。
+   *
+   * @param key 缓存键，对应的值类型需为 `number`。
+   * @param increment 增量，可为负数；缺省为 `1`。
+   * @returns 自增后的值。
+   *
+   * @example
+   * await cache.increase('totalUser');
+   * // 1
+   * await cache.increase('totalUser', 10);
+   * // 11
+   */
+  increase<K extends TKeyPathForNumberValue>(key: K, increment?: number): Promise<number>;
+  /**
+   * 自减。
+   *
+   * 行为与 {@link XCache.increase} 一致，仅将增量取负。
+   *
+   * @param key 缓存键，对应的值类型需为 `number`。
+   * @param decrement 减量，可为负数；缺省为 `1`。
+   * @returns 自减后的值。
+   *
+   * @example
+   * await cache.decrease('totalUser');
+   * // 10
+   */
+  decrease<K extends TKeyPathForNumberValue>(key: K, decrement?: number): Promise<number>;
+  /**
+   * 向列表尾部追加元素。
+   *
+   * - `memory=only` 模式直接操作内存数组；
+   * - 其余模式调用 Redis `RPUSH` 逐个追加（先序列化），并在启用内存缓存时
+   *   删除对应内存键，使下次读取从 Redis 回源。
+   *
+   * @param key 缓存键。
+   * @param values 待追加的元素列表。
+   * @returns 追加后列表的长度。
+   *
+   * @example
+   * await cache.push('queue', 'a', 'b');
+   * // 2
+   */
+  push<K extends TKeyPath, V extends XCacheValue<TData, K>>(key: K, ...values: V[]): Promise<number>;
+  /**
+   * 从列表头部弹出元素。
+   *
+   * - `memory=only` 模式直接操作内存数组；
+   * - 其余模式逐次调用 Redis `LPOP` 弹出并反序列化，遇到空列表提前结束；
+   *   弹出过元素且启用内存缓存时，删除对应内存键使下次读取回源。
+   *
+   * @param key 缓存键。
+   * @param count 弹出元素个数；缺省为 `1`，实际返回数量不超过列表长度。
+   * @returns 弹出的元素数组，列表为空时返回空数组。
+   *
+   * @example
+   * await cache.push('queue', 'a', 'b');
+   * await cache.shift('queue');
+   * // ['a']
+   */
+  shift<K extends TKeyPath, V extends XCacheValue<TData, K>>(key: K, count?: number): Promise<V[]>;
+  /**
+   * 删除缓存。
+   *
+   * - 未传任何键时返回 `0`；
+   * - 非 `memory=only` 模式调用 Redis `DEL`，并同步删除内存缓存；
+   * - `memory=only` 模式仅删除内存缓存，返回实际删除的内存键数量。
+   *
+   * @param keys 待删除的缓存键列表。
+   * @returns 删除的键数量。
+   *
+   * @example
+   * await cache.remove('greeting', ['user', 1]);
+   * // 2
+   */
+  remove<K extends TKeyPath>(...keys: K[]): Promise<number>;
+  /**
+   * 清空当前前缀下的全部缓存。
+   *
+   * - 非 `memory=only` 模式通过 `KEYS {prefix}*` 找出全部键后删除；
+   * - 启用内存缓存时清空内存缓存；`memory=only` 模式返回内存缓存大小。
+   *
+   * 注意：生产环境慎用 `KEYS`，键数量大时会阻塞 Redis。
+   *
+   * @returns 删除的键数量。
+   *
+   * @example
+   * await cache.clearAll();
+   * // 3
+   */
+  clearAll(): Promise<number>;
+  /**
+   * 清空指定前缀的缓存。
+   *
+   * 对每个前缀执行 `KEYS {前缀}*` 找出匹配键后删除；启用内存缓存时，
+   * 按前缀匹配清理内存缓存中的键。
+   *
+   * - 未传任何前缀时返回 `0`；
+   * - `memory=only` 模式仅清理内存缓存，返回实际删除的内存键数量。
+   *
+   * @param prefixes 缓存键或键前缀列表。
+   * @returns 删除的键数量。
+   *
+   * @example
+   * await cache.clear('user');
+   * // 删除所有以 user 开头的键
+   */
+  clear(...prefixes: Array<TKey | TKeyPartialPath>): Promise<number>;
+  /**
+   * 派生出一个指定数据类型的缓存服务。
+   *
+   * 传入 `TNextData` 后可获得带类型约束的读写方法；不传选项时直接返回
+   * 当前实例（仅调整类型），传选项时基于当前配置合并选项创建新实例。
+   *
+   * @param options 可选的配置覆盖项，会与当前实例配置合并。
+   * @returns 指定数据类型的缓存服务。
+   *
+   * @example
+   * const userCache = cache.fork<{ user: (id: number) => string }>();
+   * await userCache.set(['user', 1], 'Jay');
+   */
+  fork<TNextData extends XCacheData>(options?: Partial<XCacheOptions>): XCache<TNextData, XCacheKey<TNextData>, XCacheKeyPath<TNextData>, XCacheKeyPathForNumberValue<TNextData>, XCacheKeyPartialPath<TNextData>>;
+}