@yunzai-ng/core 0.1.0

package/dist/util/id.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 生成随机字符串
+ * @param size 长度，缺省 12
+ * @returns 随机 id
+ */
+export declare function randomId(size?: number): string;
+/**
+ * 生成事件 id
+ *
+ * 形如 `"m9x2k1qa-7Kd3"`：前段是 36 进制毫秒时间戳，后段随机。
+ * @param prefix 可选前缀，如 `"evt"`
+ * @returns 事件 id
+ */
+export declare function createEventId(prefix?: string): string;
+/**
+ * 生成 UUID v4
+ * @returns 标准 uuid 字符串
+ */
+export declare function uuid(): string;
+/**
+ * 单调递增的自增 id 工厂
+ *
+ * 用于适配器的 `echo` 序号等只需进程内唯一的场景，比随机串更省。
+ * @param prefix 前缀
+ * @returns 每次调用返回下一个 id
+ */
+export declare function createSeqFactory(prefix?: string): () => string;
+/**
+ * 计算字符串的 sha256 十六进制摘要
+ * @param input 输入
+ * @param length 截断长度，缺省完整 64 位
+ * @returns 十六进制摘要
+ */
+export declare function sha256(input: string, length?: number): string;
+/**
+ * 计算字符串的 md5 十六进制摘要
+ *
+ * 仅用于兼容米游社等平台的签名算法，**不要用于任何安全用途**。
+ * @param input 输入
+ * @returns 十六进制摘要
+ */
+export declare function md5(input: string): string;
+/**
+ * 稳定的短哈希，用于给任意字符串生成缓存键
+ * @param input 输入
+ * @returns 12 位十六进制
+ */
+export declare function shortHash(input: string): string;
+//# sourceMappingURL=id.d.ts.map

package/dist/util/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/util/id.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,SAAK,GAAG,MAAM,CAQ1C;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED;;;GAGG;AACH,wBAAgB,IAAI,IAAI,MAAM,CAE7B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,SAAK,GAAG,MAAM,MAAM,CAK1D;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/util/id.js

@@ -0,0 +1,87 @@
+/**
+ * 模块职责：id 生成与哈希
+ * 依赖方向：仅依赖 node:crypto
+ * 生命周期：纯函数
+ * 注意事项：事件 id 采用"时间前缀 + 随机后缀"而非纯 uuid —— 排障时可直接
+ *          按时间排序，且在日志中可直接辨识所属批次。
+ *          刻意不引入 nanoid：一个 60 行的功能不值得增加一个依赖，在
+ *          Termux 上安装依赖时尤为如此。
+ */
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+/** id 字符表：去掉了易混淆的 0/O/1/l/I */
+const ALPHABET = "23456789abcdefghijkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ";
+/**
+ * 生成随机字符串
+ * @param size 长度，缺省 12
+ * @returns 随机 id
+ */
+export function randomId(size = 12) {
+    const bytes = randomBytes(size);
+    let out = "";
+    for (let i = 0; i < size; i++) {
+        // 取模引入的偏差在 56/256 上可忽略；这里不用于密码学场景
+        out += ALPHABET[bytes[i] % ALPHABET.length];
+    }
+    return out;
+}
+/**
+ * 生成事件 id
+ *
+ * 形如 `"m9x2k1qa-7Kd3"`：前段是 36 进制毫秒时间戳，后段随机。
+ * @param prefix 可选前缀，如 `"evt"`
+ * @returns 事件 id
+ */
+export function createEventId(prefix) {
+    const stamp = Date.now().toString(36);
+    const tail = randomId(4);
+    return prefix ? `${prefix}-${stamp}-${tail}` : `${stamp}-${tail}`;
+}
+/**
+ * 生成 UUID v4
+ * @returns 标准 uuid 字符串
+ */
+export function uuid() {
+    return randomUUID();
+}
+/**
+ * 单调递增的自增 id 工厂
+ *
+ * 用于适配器的 `echo` 序号等只需进程内唯一的场景，比随机串更省。
+ * @param prefix 前缀
+ * @returns 每次调用返回下一个 id
+ */
+export function createSeqFactory(prefix = "") {
+    let seq = 0;
+    // 加一个进程内随机段，避免重启后与对端残留的旧 echo 撞号
+    const salt = randomId(4);
+    return () => `${prefix}${salt}${(++seq).toString(36)}`;
+}
+/**
+ * 计算字符串的 sha256 十六进制摘要
+ * @param input 输入
+ * @param length 截断长度，缺省完整 64 位
+ * @returns 十六进制摘要
+ */
+export function sha256(input, length) {
+    const hex = createHash("sha256").update(input, "utf8").digest("hex");
+    return length ? hex.slice(0, length) : hex;
+}
+/**
+ * 计算字符串的 md5 十六进制摘要
+ *
+ * 仅用于兼容米游社等平台的签名算法，**不要用于任何安全用途**。
+ * @param input 输入
+ * @returns 十六进制摘要
+ */
+export function md5(input) {
+    return createHash("md5").update(input, "utf8").digest("hex");
+}
+/**
+ * 稳定的短哈希，用于给任意字符串生成缓存键
+ * @param input 输入
+ * @returns 12 位十六进制
+ */
+export function shortHash(input) {
+    return sha256(input, 12);
+}
+//# sourceMappingURL=id.js.map

package/dist/util/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/util/id.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEjE,+BAA+B;AAC/B,MAAM,QAAQ,GAAG,0DAA0D,CAAA;AAE3E;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAI,GAAG,EAAE;IAChC,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAA;IAC/B,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9B,kCAAkC;QAClC,GAAG,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAA;IAC9C,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IACrC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;IACxB,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,IAAI,EAAE,CAAA;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI;IAClB,OAAO,UAAU,EAAE,CAAA;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAM,GAAG,EAAE;IAC1C,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,iCAAiC;IACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;IACxB,OAAO,GAAG,EAAE,CAAC,GAAG,MAAM,GAAG,IAAI,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAA;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,MAAe;IACnD,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACpE,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;AAC5C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,GAAG,CAAC,KAAa;IAC/B,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,OAAO,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;AAC1B,CAAC"}

package/dist/util/lru.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 模块职责：LRU + TTL 缓存，带并发去重
+ * 依赖方向：仅依赖类型包
+ * 生命周期：随创建者（插件 / 账号）一起被回收
+ * 注意事项：三项机制合起来使缓存的内存占用具备上界 —— 裸 Map 存群成员表且从不淘汰时，
+ *          数十个千人群即是数百 MB 常驻：
+ *          1) 硬性上限 + LRU 淘汰；
+ *          2) TTL 惰性过期；
+ *          3) single-flight 合并同 key 的并发请求，避免一条群消息中多处判定权限时
+ *             各发一次平台请求。
+ *
+ *          **不采用定时器扫描**：定时器或造成泄漏，或需额外的生命周期管理。改为每次写入时
+ *          清理队首若干过期项，摊还成本 O(1)。
+ */
+import type { ContactCache, ContactCacheOptions } from "@yunzai-ng/types";
+/**
+ * LRU + TTL 缓存
+ *
+ * 利用 `Map` 的插入顺序实现 LRU：读命中时把条目挪到队尾，
+ * 于是队首恒为最久未使用者，淘汰只需 `keys().next()`。
+ */
+export declare class LruCache<V> implements ContactCache<V> {
+    #private;
+    /**
+     * @param opts 缓存参数；`max` 至少为 1，`ttl` 为 0 表示不过期
+     */
+    constructor(opts: ContactCacheOptions);
+    /** 当前条目数（含尚未被清理的过期项） */
+    get size(): number;
+    /** 命中率统计，供 `/api/diagnostics` 展示缓存是否配得合理 */
+    get stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+        max: number;
+    };
+    /**
+     * 取缓存
+     * @param key 键
+     * @returns 值；未命中或已过期时 undefined
+     */
+    get(key: string): V | undefined;
+    /**
+     * 写缓存
+     * @param key 键
+     * @param value 值
+     * @param ttl 覆盖默认存活时长（毫秒）
+     */
+    set(key: string, value: V, ttl?: number): void;
+    /**
+     * 删除
+     * @param key 键
+     */
+    delete(key: string): void;
+    /**
+     * 取缓存，未命中时用 loader 拉取并回填
+     *
+     * 同一 key 的并发调用共享同一个 loader promise。loader 抛错时不缓存，
+     * 但会把错误传播给所有等待者——避免"一次网络抖动被缓存成永久失败"。
+     * @param key 键
+     * @param loader 拉取函数
+     * @returns 值；loader 返回 undefined 时不缓存
+     */
+    fetch(key: string, loader: (key: string) => Promise<V | undefined>): Promise<V | undefined>;
+    /** 清空全部条目与进行中的 loader 记录 */
+    clear(): void;
+}
+/**
+ * 创建 LRU + TTL 缓存
+ * @param opts 缓存参数
+ * @returns 缓存实例
+ */
+export declare function createCache<V>(opts: ContactCacheOptions): LruCache<V>;
+//# sourceMappingURL=lru.d.ts.map

package/dist/util/lru.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru.d.ts","sourceRoot":"","sources":["../../src/util/lru.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAczE;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC,CAAE,YAAW,YAAY,CAAC,CAAC,CAAC;;IAejD;;OAEG;gBACS,IAAI,EAAE,mBAAmB;IAMrC,wBAAwB;IACxB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,4CAA4C;IAC5C,IAAI,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAEvE;IAED;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAkB/B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAgB9C;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;;;;;;;OAQG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAqBjG,4BAA4B;IAC5B,KAAK,IAAI,IAAI;CAuBd;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,mBAAmB,GAAG,QAAQ,CAAC,CAAC,CAAC,CAErE"}

package/dist/util/lru.js

@@ -0,0 +1,156 @@
+import { parseDuration } from "./duration.js";
+/** 每次写入时顺带检查的队首条目数 */
+const SWEEP_PER_WRITE = 4;
+/**
+ * LRU + TTL 缓存
+ *
+ * 利用 `Map` 的插入顺序实现 LRU：读命中时把条目挪到队尾，
+ * 于是队首恒为最久未使用者，淘汰只需 `keys().next()`。
+ */
+export class LruCache {
+    /** 主存储，键序即 LRU 序（队首最久未用） */
+    #map = new Map();
+    /** 进行中的 loader，用于并发去重 */
+    #pending = new Map();
+    /** 条目上限 */
+    #max;
+    /** 默认存活毫秒 */
+    #ttl;
+    /** 命中次数（诊断用） */
+    #hits = 0;
+    /** 未命中次数（诊断用） */
+    #misses = 0;
+    /**
+     * @param opts 缓存参数；`max` 至少为 1，`ttl` 为 0 表示不过期
+     */
+    constructor(opts) {
+        this.#max = Math.max(1, Math.floor(opts.max));
+        const ttl = parseDuration(opts.ttl, 0);
+        this.#ttl = ttl > 0 ? ttl : Number.POSITIVE_INFINITY;
+    }
+    /** 当前条目数（含尚未被清理的过期项） */
+    get size() {
+        return this.#map.size;
+    }
+    /** 命中率统计，供 `/api/diagnostics` 展示缓存是否配得合理 */
+    get stats() {
+        return { hits: this.#hits, misses: this.#misses, size: this.#map.size, max: this.#max };
+    }
+    /**
+     * 取缓存
+     * @param key 键
+     * @returns 值；未命中或已过期时 undefined
+     */
+    get(key) {
+        const entry = this.#map.get(key);
+        if (!entry) {
+            this.#misses++;
+            return undefined;
+        }
+        if (entry.expireAt <= Date.now()) {
+            this.#map.delete(key);
+            this.#misses++;
+            return undefined;
+        }
+        // 命中即挪到队尾：delete + set 是 Map 上唯一能改插入序的手段
+        this.#map.delete(key);
+        this.#map.set(key, entry);
+        this.#hits++;
+        return entry.value;
+    }
+    /**
+     * 写缓存
+     * @param key 键
+     * @param value 值
+     * @param ttl 覆盖默认存活时长（毫秒）
+     */
+    set(key, value, ttl) {
+        this.#sweep();
+        const expireAt = ttl === undefined ? this.#ttl : ttl;
+        this.#map.delete(key);
+        this.#map.set(key, {
+            value,
+            expireAt: Number.isFinite(expireAt) ? Date.now() + expireAt : Number.POSITIVE_INFINITY
+        });
+        // 超限时从队首淘汰，直到回到上限内
+        while (this.#map.size > this.#max) {
+            const oldest = this.#map.keys().next();
+            if (oldest.done)
+                break;
+            this.#map.delete(oldest.value);
+        }
+    }
+    /**
+     * 删除
+     * @param key 键
+     */
+    delete(key) {
+        this.#map.delete(key);
+    }
+    /**
+     * 取缓存，未命中时用 loader 拉取并回填
+     *
+     * 同一 key 的并发调用共享同一个 loader promise。loader 抛错时不缓存，
+     * 但会把错误传播给所有等待者——避免"一次网络抖动被缓存成永久失败"。
+     * @param key 键
+     * @param loader 拉取函数
+     * @returns 值；loader 返回 undefined 时不缓存
+     */
+    async fetch(key, loader) {
+        const cached = this.get(key);
+        if (cached !== undefined)
+            return cached;
+        const inflight = this.#pending.get(key);
+        if (inflight)
+            return inflight;
+        const task = (async () => {
+            try {
+                const value = await loader(key);
+                if (value !== undefined)
+                    this.set(key, value);
+                return value;
+            }
+            finally {
+                this.#pending.delete(key);
+            }
+        })();
+        this.#pending.set(key, task);
+        return task;
+    }
+    /** 清空全部条目与进行中的 loader 记录 */
+    clear() {
+        this.#map.clear();
+        this.#pending.clear();
+        this.#hits = 0;
+        this.#misses = 0;
+    }
+    /**
+     * 清理队首若干个过期条目
+     *
+     * 只看队首是因为 LRU 序下队首最可能已经过期；全量扫描在千级条目上
+     * 会让每次写入都变成 O(n)。
+     */
+    #sweep() {
+        if (this.#ttl === Number.POSITIVE_INFINITY)
+            return;
+        const now = Date.now();
+        let checked = 0;
+        for (const [key, entry] of this.#map) {
+            if (checked++ >= SWEEP_PER_WRITE)
+                break;
+            if (entry.expireAt <= now)
+                this.#map.delete(key);
+            else
+                break; // 队首未过期时后续项更不可能过期（近似成立，满足本场景需要）
+        }
+    }
+}
+/**
+ * 创建 LRU + TTL 缓存
+ * @param opts 缓存参数
+ * @returns 缓存实例
+ */
+export function createCache(opts) {
+    return new LruCache(opts);
+}
+//# sourceMappingURL=lru.js.map

package/dist/util/lru.js.map

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

package/dist/util/queue.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 按 key 串行的任务队列
+ *
+ * 同一 key 的任务严格按提交顺序逐个执行；不同 key 之间并行。
+ * key 上没有任务时会自动清理链表头，不会随 key 数量无限增长。
+ */
+export declare class KeyedQueue {
+    #private;
+    /** 当前有排队任务的 key 数量 */
+    get size(): number;
+    /**
+     * 排队执行
+     * @param key 串行域；同 key 串行，异 key 并行
+     * @param task 任务
+     * @returns 任务结果
+     */
+    run<T>(key: string, task: () => Promise<T> | T): Promise<T>;
+    /**
+     * 等待某个 key 上的所有任务结束
+     * @param key 串行域
+     * @returns 全部结束后兑现
+     */
+    drain(key: string): Promise<void>;
+    /**
+     * 等待全部 key 的任务结束
+     * @returns 全部结束后兑现
+     */
+    drainAll(): Promise<void>;
+}
+/**
+ * 计数信号量
+ *
+ * 用于限制昂贵操作的并发上限。务必用 `use()` 而不是手工 acquire/release ——
+ * 手工写法一旦任务抛错忘了 release，闸门就永久关闭。
+ */
+export declare class Semaphore {
+    #private;
+    /**
+     * @param limit 并发上限，至少 1
+     */
+    constructor(limit: number);
+    /** 当前正在执行的任务数 */
+    get active(): number;
+    /** 当前排队等待的任务数 */
+    get pending(): number;
+    /**
+     * 在信号量保护下执行任务
+     * @param task 任务
+     * @returns 任务结果
+     */
+    use<T>(task: () => Promise<T> | T): Promise<T>;
+}
+/**
+ * 并发受限地映射一组任务
+ *
+ * 与 `Promise.all` 的区别是**同时在跑的任务数有上限**；
+ * 结果顺序与输入一致。任一任务抛错则整体拒绝。
+ * @param items 输入项
+ * @param limit 并发上限
+ * @param mapper 映射函数
+ * @returns 结果数组，顺序与输入一致
+ */
+export declare function mapLimit<T, R>(items: readonly T[], limit: number, mapper: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=queue.d.ts.map

package/dist/util/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/util/queue.ts"],"names":[],"mappings":"AAaA;;;;;GAKG;AACH,qBAAa,UAAU;;IAIrB,sBAAsB;IACtB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAsB3D;;;;OAIG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAMhC;AAED;;;;;GAKG;AACH,qBAAa,SAAS;;IAQpB;;OAEG;gBACS,KAAK,EAAE,MAAM;IAIzB,iBAAiB;IACjB,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,iBAAiB;IACjB,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;OAIG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAiCrD;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,EAAE,CAAC,CAGd"}

package/dist/util/queue.js

@@ -0,0 +1,147 @@
+/**
+ * 模块职责：串行队列与并发闸门
+ * 依赖方向：仅依赖 util/defer
+ * 生命周期：随持有者回收；`clear()` 会拒绝所有排队任务
+ * 注意事项：两个必须串行的场景：
+ *          1) **KV 自增**。内嵌 KV 没有原子 INCR，"读-改-写"必须按 key 串行，否则统计会掉数。
+ *          2) **同群发消息**。并发发送会乱序，且更容易触发平台风控。
+ *
+ *          `Semaphore` 用于限制渲染、HTTP 拉取等昂贵操作的并发数 ——
+ *          在 1G 内存的安卓机上，同时开 8 个 puppeteer 页面就是 OOM。
+ */
+import { defer } from "./defer.js";
+/**
+ * 按 key 串行的任务队列
+ *
+ * 同一 key 的任务严格按提交顺序逐个执行；不同 key 之间并行。
+ * key 上没有任务时会自动清理链表头，不会随 key 数量无限增长。
+ */
+export class KeyedQueue {
+    /** key → 该 key 上最后一个任务的完成信号 */
+    #tails = new Map();
+    /** 当前有排队任务的 key 数量 */
+    get size() {
+        return this.#tails.size;
+    }
+    /**
+     * 排队执行
+     * @param key 串行域；同 key 串行，异 key 并行
+     * @param task 任务
+     * @returns 任务结果
+     */
+    run(key, task) {
+        const prev = this.#tails.get(key) ?? Promise.resolve();
+        // 以 catch 捕获前一个任务的错误：前者失败不应阻断其后排队的任务，
+        // 但错误本身仍会经由各自的返回 Promise 抛给对应调用方。
+        const next = prev.then(() => task(), () => task());
+        this.#tails.set(key, next);
+        // 队尾未发生变化说明自身即最后一个 → 可摘除该 key
+        void next
+            .catch(() => undefined)
+            .finally(() => {
+            if (this.#tails.get(key) === next)
+                this.#tails.delete(key);
+        });
+        return next;
+    }
+    /**
+     * 等待某个 key 上的所有任务结束
+     * @param key 串行域
+     * @returns 全部结束后兑现
+     */
+    async drain(key) {
+        const tail = this.#tails.get(key);
+        if (tail)
+            await tail.catch(() => undefined);
+    }
+    /**
+     * 等待全部 key 的任务结束
+     * @returns 全部结束后兑现
+     */
+    async drainAll() {
+        while (this.#tails.size > 0) {
+            const tails = [...this.#tails.values()];
+            await Promise.allSettled(tails);
+        }
+    }
+}
+/**
+ * 计数信号量
+ *
+ * 用于限制昂贵操作的并发上限。务必用 `use()` 而不是手工 acquire/release ——
+ * 手工写法一旦任务抛错忘了 release，闸门就永久关闭。
+ */
+export class Semaphore {
+    /** 并发上限 */
+    #limit;
+    /** 当前占用数 */
+    #active = 0;
+    /** 等待队列 */
+    #waiting = [];
+    /**
+     * @param limit 并发上限，至少 1
+     */
+    constructor(limit) {
+        this.#limit = Math.max(1, Math.floor(limit));
+    }
+    /** 当前正在执行的任务数 */
+    get active() {
+        return this.#active;
+    }
+    /** 当前排队等待的任务数 */
+    get pending() {
+        return this.#waiting.length;
+    }
+    /**
+     * 在信号量保护下执行任务
+     * @param task 任务
+     * @returns 任务结果
+     */
+    async use(task) {
+        await this.#acquire();
+        try {
+            return await task();
+        }
+        finally {
+            this.#release();
+        }
+    }
+    /**
+     * 获取一个许可
+     * @returns 拿到许可后兑现
+     */
+    async #acquire() {
+        if (this.#active < this.#limit) {
+            this.#active++;
+            return;
+        }
+        const waiter = defer();
+        this.#waiting.push(waiter);
+        await waiter.promise;
+    }
+    /** 释放许可并唤醒下一个等待者 */
+    #release() {
+        const next = this.#waiting.shift();
+        if (next) {
+            // 许可直接移交，不经过 active-- 再 ++，避免中间态被别人插队
+            next.resolve();
+            return;
+        }
+        this.#active--;
+    }
+}
+/**
+ * 并发受限地映射一组任务
+ *
+ * 与 `Promise.all` 的区别是**同时在跑的任务数有上限**；
+ * 结果顺序与输入一致。任一任务抛错则整体拒绝。
+ * @param items 输入项
+ * @param limit 并发上限
+ * @param mapper 映射函数
+ * @returns 结果数组，顺序与输入一致
+ */
+export async function mapLimit(items, limit, mapper) {
+    const sem = new Semaphore(limit);
+    return Promise.all(items.map((item, index) => sem.use(() => mapper(item, index))));
+}
+//# sourceMappingURL=queue.js.map

package/dist/util/queue.js.map

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