@yunzai-ng/core 0.1.0

package/dist/util/deep.js

@@ -0,0 +1,275 @@
+/**
+ * 模块职责：对象深操作（合并、克隆、按路径读写、差异路径计算）
+ * 依赖方向：无
+ * 生命周期：纯函数
+ * 注意事项：配置系统的地基。`diffPaths` 算出实际变化的叶子路径，故配置变更只通知
+ *          关心那些路径的订阅者，而不是让每个读配置的地方全量重算。
+ *
+ *          **数组是整体替换，不逐元素合并。** 配置里的数组（主人列表、黑名单）语义上是
+ *          "一个值"，逐元素合并会让使用者无法删除默认项。
+ */
+/**
+ * 判断是否为普通对象（排除数组、null、Date、Buffer、类实例等）
+ * @param value 待判定值
+ * @returns 是否为普通对象
+ */
+export function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * 深克隆
+ *
+ * 优先用 `structuredClone`（Node 17+ 内置，能处理 Map/Set/Date/循环引用），
+ * 遇到函数等不可克隆值时退回浅拷贝语义。
+ * @param value 源值
+ * @returns 克隆结果
+ */
+export function deepClone(value) {
+    try {
+        return structuredClone(value);
+    }
+    catch {
+        return cloneFallback(value);
+    }
+}
+/**
+ * structuredClone 失败时的回退克隆（跳过不可克隆值）
+ * @param value 源值
+ * @returns 克隆结果
+ */
+function cloneFallback(value) {
+    if (Array.isArray(value))
+        return value.map(item => cloneFallback(item));
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = cloneFallback(v);
+        return out;
+    }
+    return value;
+}
+/**
+ * 深合并：把 `source` 覆盖到 `target` 的副本上
+ *
+ * - 普通对象递归合并
+ * - 数组、`Date` 等整体替换
+ * - `source` 中值为 `undefined` 的键被忽略（不会把 target 的值抹成 undefined）
+ * @param target 基准值（不被修改）
+ * @param source 覆盖值
+ * @returns 合并后的新对象
+ */
+export function deepMerge(target, source) {
+    if (!source)
+        return deepClone(target);
+    const out = deepClone(target);
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined)
+            continue;
+        // 拒绝原型链污染：合并的数据可能来自 WebUI 提交的 JSON
+        if (key === "__proto__" || key === "constructor" || key === "prototype")
+            continue;
+        const existing = out[key];
+        if (isPlainObject(value) && isPlainObject(existing)) {
+            out[key] = deepMerge(existing, value);
+        }
+        else {
+            out[key] = deepClone(value);
+        }
+    }
+    return out;
+}
+/**
+ * 深比较
+ * @param a 左值
+ * @param b 右值
+ * @returns 是否深度相等
+ */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEqual(item, b[i]));
+    }
+    if (a instanceof Date || b instanceof Date) {
+        return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const ao = a;
+        const bo = b;
+        const aKeys = Object.keys(ao);
+        const bKeys = Object.keys(bo);
+        if (aKeys.length !== bKeys.length)
+            return false;
+        return aKeys.every(k => Object.prototype.hasOwnProperty.call(bo, k) && deepEqual(ao[k], bo[k]));
+    }
+    return false;
+}
+/**
+ * 把点分路径切成键数组
+ *
+ * 支持 `a.b[0].c` 与 `a.b.0.c` 两种写法。
+ * @param path 路径字符串
+ * @returns 键数组
+ */
+export function splitPath(path) {
+    if (path === "")
+        return [];
+    return path
+        .replace(/\[(\d+)\]/g, ".$1")
+        .split(".")
+        .filter(seg => seg !== "");
+}
+/**
+ * 按路径取值
+ * @param obj 源对象
+ * @param path 点分路径；空串返回 obj 本身
+ * @returns 值；路径不存在时 undefined
+ */
+export function getPath(obj, path) {
+    const keys = splitPath(path);
+    let cur = obj;
+    for (const key of keys) {
+        if (cur === null || cur === undefined)
+            return undefined;
+        if (typeof cur !== "object")
+            return undefined;
+        cur = cur[key];
+    }
+    return cur;
+}
+/**
+ * 按路径写值（原地修改）
+ *
+ * 中间层不存在时自动创建：下一级键是纯数字则建数组，否则建对象。
+ * @param obj 目标对象
+ * @param path 点分路径
+ * @param value 值
+ * @throws 当路径为空或中间层是不可写入的标量时
+ */
+export function setPath(obj, path, value) {
+    const keys = splitPath(path);
+    if (keys.length === 0)
+        throw new Error("setPath: 路径不能为空");
+    let cur = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            throw new Error(`setPath: 非法路径片段 ${key}`);
+        }
+        const next = cur[key];
+        if (isPlainObject(next) || Array.isArray(next)) {
+            cur = next;
+        }
+        else if (next === undefined || next === null) {
+            const created = /^\d+$/.test(keys[i + 1]) ? [] : {};
+            cur[key] = created;
+            cur = created;
+        }
+        else {
+            throw new Error(`setPath: ${keys.slice(0, i + 1).join(".")} 已是标量，无法继续写入`);
+        }
+    }
+    const last = keys[keys.length - 1];
+    if (last === "__proto__" || last === "constructor" || last === "prototype") {
+        throw new Error(`setPath: 非法路径片段 ${last}`);
+    }
+    ;
+    cur[last] = value;
+}
+/**
+ * 按路径删除（原地修改）
+ * @param obj 目标对象
+ * @param path 点分路径
+ * @returns 是否确实删掉了什么
+ */
+export function deletePath(obj, path) {
+    const keys = splitPath(path);
+    if (keys.length === 0)
+        return false;
+    const parentPath = keys.slice(0, -1).join(".");
+    const parent = parentPath === "" ? obj : getPath(obj, parentPath);
+    if (parent === null || typeof parent !== "object")
+        return false;
+    const last = keys[keys.length - 1];
+    if (Array.isArray(parent)) {
+        const index = Number(last);
+        if (!Number.isInteger(index) || index < 0 || index >= parent.length)
+            return false;
+        parent.splice(index, 1);
+        return true;
+    }
+    if (!Object.prototype.hasOwnProperty.call(parent, last))
+        return false;
+    delete parent[last];
+    return true;
+}
+/**
+ * 计算两个对象间发生变化的**叶子路径**
+ *
+ * 这是细粒度配置失效的核心：改了 `bot.masterQQ` 就只通知订阅
+ * `bot.masterQQ`（或其祖先 `bot`）的人，不打扰订阅 `render.*` 的人。
+ *
+ * 数组视为叶子（整体变化），不下钻元素。
+ * @param before 旧值
+ * @param after 新值
+ * @param prefix 内部递归用的路径前缀
+ * @returns 变化路径列表，已去重
+ */
+export function diffPaths(before, after, prefix = "") {
+    if (deepEqual(before, after))
+        return [];
+    // 任一侧不是普通对象 → 当前节点整体变化
+    if (!isPlainObject(before) || !isPlainObject(after)) {
+        return prefix === "" ? [""] : [prefix];
+    }
+    const out = [];
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of keys) {
+        const path = prefix === "" ? key : `${prefix}.${key}`;
+        out.push(...diffPaths(before[key], after[key], path));
+    }
+    return out;
+}
+/**
+ * 判断某条变化路径是否影响到订阅路径
+ *
+ * 双向前缀匹配：改 `bot` 影响订阅 `bot.masterQQ` 的人（父变子受影响），
+ * 改 `bot.masterQQ` 也影响订阅 `bot` 的人（子变父受影响）。
+ * @param changed 发生变化的路径
+ * @param watched 订阅的路径；空串表示订阅全部
+ * @returns 是否受影响
+ */
+export function pathAffects(changed, watched) {
+    if (watched === "" || changed === "")
+        return true;
+    if (changed === watched)
+        return true;
+    return changed.startsWith(`${watched}.`) || watched.startsWith(`${changed}.`);
+}
+/**
+ * 摘出对象里的指定路径，组成新对象
+ * @param obj 源对象
+ * @param paths 路径列表
+ * @returns 只含这些路径的新对象
+ */
+export function pickPaths(obj, paths) {
+    const out = {};
+    for (const path of paths) {
+        const value = getPath(obj, path);
+        if (value !== undefined)
+            setPath(out, path, deepClone(value));
+    }
+    return out;
+}
+//# sourceMappingURL=deep.js.map

package/dist/util/deep.js.map

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

package/dist/util/defer.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 模块职责：Promise 原语（外部可控 Promise、超时、休眠、重试）
+ * 依赖方向：仅依赖类型包
+ * 生命周期：纯函数 / 短生命周期对象
+ * 注意事项：所有会挂起的等待均必须可被取消，否则热重载时插件已卸载、
+ *          而 Promise 仍持有定时器，即构成内存泄漏。因此 `Deferred` 暴露
+ *          `reject`，`withTimeout` 必定清除 timer，`sleep` 支持 signal。
+ */
+/** 超时错误：与普通业务错误相区分，便于上层决定"重试"或"放弃" */
+export declare class TimeoutError extends Error {
+    /** 错误名，便于 `err.name === "TimeoutError"` 判定 */
+    readonly name = "TimeoutError";
+    /**
+     * @param message 错误信息
+     */
+    constructor(message?: string);
+}
+/** 中止错误：signal 触发时抛出 */
+export declare class AbortError extends Error {
+    /** 错误名 */
+    readonly name = "AbortError";
+    /**
+     * @param message 错误信息
+     */
+    constructor(message?: string);
+}
+/** 外部可控的 Promise */
+export interface Deferred<T> {
+    /** Promise 本体 */
+    readonly promise: Promise<T>;
+    /**
+     * 兑现
+     * @param value 结果值
+     */
+    resolve(value: T | PromiseLike<T>): void;
+    /**
+     * 拒绝
+     * @param reason 原因
+     */
+    reject(reason?: unknown): void;
+    /** 是否已结束（兑现或拒绝） */
+    readonly settled: boolean;
+}
+/**
+ * 创建外部可控的 Promise
+ *
+ * 用于把"回调/事件"风格的等待（如适配器 echo 应答、`e.prompt`）转成 await。
+ * 重复调用 resolve/reject 会被忽略，不会抛错。
+ * @returns Deferred 句柄
+ */
+export declare function defer<T>(): Deferred<T>;
+/**
+ * 休眠
+ * @param ms 毫秒
+ * @param signal 可选中止信号；触发时以 AbortError 拒绝
+ * @returns 到期后兑现
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * 给 Promise 套超时
+ *
+ * 注意：超时只是让调用方不再等待，**并不能真正取消**底层操作。需要真取消
+ * 的场景（HTTP 请求）请把 signal 传给底层。
+ * @param promise 被包装的 Promise
+ * @param ms 超时毫秒；<=0 表示不限时
+ * @param message 超时错误信息
+ * @returns 原结果，或以 TimeoutError 拒绝
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+/** 重试选项 */
+export interface RetryOptions {
+    /** 最大尝试次数（含首次），缺省 3 */
+    attempts?: number;
+    /** 首次退避毫秒，缺省 500 */
+    baseDelay?: number;
+    /** 退避上限毫秒，缺省 30000 */
+    maxDelay?: number;
+    /** 退避倍率，缺省 2 */
+    factor?: number;
+    /** 抖动比例 0~1，缺省 0.2；用于避免多账号重连时步调一致而对服务端造成过载 */
+    jitter?: number;
+    /** 中止信号 */
+    signal?: AbortSignal;
+    /**
+     * 每次失败后的回调
+     * @param err 本次错误
+     * @param attempt 已尝试次数（从 1 开始）
+     * @param delay 即将等待的毫秒
+     */
+    onRetry?: (err: unknown, attempt: number, delay: number) => void;
+}
+/**
+ * 计算指数退避（带抖动）的等待时长
+ * @param attempt 已尝试次数（从 1 开始）
+ * @param opts 退避参数
+ * @returns 毫秒
+ */
+export declare function backoffDelay(attempt: number, opts?: RetryOptions): number;
+/**
+ * 带指数退避的重试
+ * @param task 任务；参数为已尝试次数（从 1 开始）
+ * @param opts 重试选项
+ * @returns 任务结果
+ * @throws 最后一次的错误
+ */
+export declare function retry<T>(task: (attempt: number) => Promise<T>, opts?: RetryOptions): Promise<T>;
+//# sourceMappingURL=defer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"defer.d.ts","sourceRoot":"","sources":["../../src/util/defer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,sCAAsC;AACtC,qBAAa,YAAa,SAAQ,KAAK;IACrC,8CAA8C;IAC9C,SAAkB,IAAI,kBAAiB;IAEvC;;OAEG;gBACS,OAAO,SAAS;CAG7B;AAED,wBAAwB;AACxB,qBAAa,UAAW,SAAQ,KAAK;IACnC,UAAU;IACV,SAAkB,IAAI,gBAAe;IAErC;;OAEG;gBACS,OAAO,SAAW;CAG/B;AAED,oBAAoB;AACpB,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,iBAAiB;IACjB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IAC5B;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IACxC;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IAC9B,mBAAmB;IACnB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CA0BtC;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAgB5F;AAED,WAAW;AACX,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oBAAoB;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gBAAgB;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW;IACX,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACjE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,MAAM,CAU7E;AAED;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAiBzG"}

package/dist/util/defer.js

@@ -0,0 +1,163 @@
+/**
+ * 模块职责：Promise 原语（外部可控 Promise、超时、休眠、重试）
+ * 依赖方向：仅依赖类型包
+ * 生命周期：纯函数 / 短生命周期对象
+ * 注意事项：所有会挂起的等待均必须可被取消，否则热重载时插件已卸载、
+ *          而 Promise 仍持有定时器，即构成内存泄漏。因此 `Deferred` 暴露
+ *          `reject`，`withTimeout` 必定清除 timer，`sleep` 支持 signal。
+ */
+/** 超时错误：与普通业务错误相区分，便于上层决定"重试"或"放弃" */
+export class TimeoutError extends Error {
+    /** 错误名，便于 `err.name === "TimeoutError"` 判定 */
+    name = "TimeoutError";
+    /**
+     * @param message 错误信息
+     */
+    constructor(message = "操作超时") {
+        super(message);
+    }
+}
+/** 中止错误：signal 触发时抛出 */
+export class AbortError extends Error {
+    /** 错误名 */
+    name = "AbortError";
+    /**
+     * @param message 错误信息
+     */
+    constructor(message = "操作已被取消") {
+        super(message);
+    }
+}
+/**
+ * 创建外部可控的 Promise
+ *
+ * 用于把"回调/事件"风格的等待（如适配器 echo 应答、`e.prompt`）转成 await。
+ * 重复调用 resolve/reject 会被忽略，不会抛错。
+ * @returns Deferred 句柄
+ */
+export function defer() {
+    let resolveFn;
+    let rejectFn;
+    let settled = false;
+    const promise = new Promise((res, rej) => {
+        resolveFn = res;
+        rejectFn = rej;
+    });
+    return {
+        promise,
+        resolve(value) {
+            if (settled)
+                return;
+            settled = true;
+            resolveFn(value);
+        },
+        reject(reason) {
+            if (settled)
+                return;
+            settled = true;
+            rejectFn(reason);
+        },
+        get settled() {
+            return settled;
+        }
+    };
+}
+/**
+ * 休眠
+ * @param ms 毫秒
+ * @param signal 可选中止信号；触发时以 AbortError 拒绝
+ * @returns 到期后兑现
+ */
+export function sleep(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new AbortError());
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        // Node 下 unref 让"只剩一个 sleep"时进程仍能退出
+        if (typeof timer.unref === "function")
+            timer.unref();
+        /** 中止回调 */
+        function onAbort() {
+            clearTimeout(timer);
+            reject(new AbortError());
+        }
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * 给 Promise 套超时
+ *
+ * 注意：超时只是让调用方不再等待，**并不能真正取消**底层操作。需要真取消
+ * 的场景（HTTP 请求）请把 signal 传给底层。
+ * @param promise 被包装的 Promise
+ * @param ms 超时毫秒；<=0 表示不限时
+ * @param message 超时错误信息
+ * @returns 原结果，或以 TimeoutError 拒绝
+ */
+export function withTimeout(promise, ms, message) {
+    if (ms <= 0)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new TimeoutError(message)), ms);
+        if (typeof timer.unref === "function")
+            timer.unref();
+        promise.then(value => {
+            clearTimeout(timer);
+            resolve(value);
+        }, reason => {
+            clearTimeout(timer);
+            reject(reason);
+        });
+    });
+}
+/**
+ * 计算指数退避（带抖动）的等待时长
+ * @param attempt 已尝试次数（从 1 开始）
+ * @param opts 退避参数
+ * @returns 毫秒
+ */
+export function backoffDelay(attempt, opts = {}) {
+    const base = opts.baseDelay ?? 500;
+    const factor = opts.factor ?? 2;
+    const max = opts.maxDelay ?? 30_000;
+    const jitter = opts.jitter ?? 0.2;
+    const raw = Math.min(max, base * factor ** Math.max(0, attempt - 1));
+    // 抖动只往下浮动，保证不会超过 maxDelay
+    const delta = raw * jitter * Math.random();
+    return Math.round(raw - delta);
+}
+/**
+ * 带指数退避的重试
+ * @param task 任务；参数为已尝试次数（从 1 开始）
+ * @param opts 重试选项
+ * @returns 任务结果
+ * @throws 最后一次的错误
+ */
+export async function retry(task, opts = {}) {
+    const attempts = Math.max(1, opts.attempts ?? 3);
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        if (opts.signal?.aborted)
+            throw new AbortError();
+        try {
+            return await task(attempt);
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt >= attempts)
+                break;
+            const delay = backoffDelay(attempt, opts);
+            opts.onRetry?.(err, attempt, delay);
+            await sleep(delay, opts.signal);
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=defer.js.map

package/dist/util/defer.js.map

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

package/dist/util/dispose.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 模块职责：资源回收登记簿
+ * 依赖方向：依赖类型包的 Disposer
+ * 生命周期：与其宿主（插件实例 / 账号连接 / 应用）同寿
+ * 注意事项：**内核提供给插件的每一个注册型 API 都返回 Disposer**，并自动登记到该插件的
+ *          registry。插件卸载时逆序全量回收，故插件作者不需要（也无从忘记）手工清理 ——
+ *          否则改十次代码就有十份定时器在跑同一件事。
+ *
+ *          逆序回收是有意的：后注册的往往依赖先注册的（如先 provide 服务再
+ *          注册用到它的命令），倒着拆才不会拆到一半引用空对象。
+ */
+import type { Disposer } from "@yunzai-ng/types";
+/** 回收过程中收集到的错误 */
+export interface DisposeFailure {
+    /** 登记时的标签 */
+    label: string;
+    /** 抛出的错误 */
+    error: unknown;
+}
+/**
+ * 资源回收登记簿
+ *
+ * 线程模型：同进程单线程，无需加锁；但 `dispose()` 可能重入
+ * （插件在 disposer 里又触发卸载），故有 `#disposed` 幂等保护。
+ */
+export declare class DisposalRegistry {
+    #private;
+    /**
+     * @param owner 归属标识（插件名等），出错时用于定位
+     */
+    constructor(owner: string);
+    /** 是否已回收 */
+    get disposed(): boolean;
+    /** 尚未回收的登记项数量 */
+    get size(): number;
+    /**
+     * 登记一个回收器
+     *
+     * 若 registry 已回收，传入的 disposer 会**立即执行** —— 这防止"卸载竞态"：
+     * 异步初始化的插件在卸载后才完成注册，资源没人回收。
+     * @param dispose 回收函数
+     * @param label 标签，用于报错定位
+     * @returns 取消登记并执行回收的函数；重复调用无副作用
+     */
+    add(dispose: Disposer, label?: string): Disposer;
+    /**
+     * 登记一个 `Map`/`Set` 条目的清理
+     * @param collection 容器
+     * @param key 键
+     * @param label 标签
+     * @returns 回收函数
+     */
+    addEntry<K>(collection: {
+        delete(key: K): unknown;
+    }, key: K, label?: string): Disposer;
+    /**
+     * 登记一个定时器
+     *
+     * 顺带 `unref`，让"只剩定时器"时进程能正常退出。
+     * @param timer 定时器句柄
+     * @param label 标签
+     * @returns 回收函数
+     */
+    addTimer(timer: NodeJS.Timeout, label?: string): Disposer;
+    /**
+     * 创建从属子登记簿
+     *
+     * 父簿回收时自动带走子簿。用于"插件里的账号连接"这类嵌套生命周期。
+     * @param owner 子簿归属标识
+     * @returns 子登记簿
+     */
+    child(owner: string): DisposalRegistry;
+    /**
+     * 逆序回收全部登记项
+     *
+     * 单个 disposer 抛错**不会**中断后续回收 —— 一个插件写错清理逻辑不应该
+     * 导致其余资源全部泄漏。所有错误汇总返回，由调用方（插件宿主）记日志。
+     * @returns 回收过程中发生的错误列表；无错时为空数组
+     */
+    dispose(): DisposeFailure[];
+}
+/**
+ * 把多个 Disposer 合成一个
+ * @param disposers 回收函数列表（可含 undefined，便于条件注册）
+ * @returns 合成后的回收函数；逆序执行，单个抛错不影响其余
+ */
+export declare function combineDisposers(...disposers: (Disposer | undefined)[]): Disposer;
+//# sourceMappingURL=dispose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dispose.d.ts","sourceRoot":"","sources":["../../src/util/dispose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAEhD,kBAAkB;AAClB,MAAM,WAAW,cAAc;IAC7B,aAAa;IACb,KAAK,EAAE,MAAM,CAAA;IACb,YAAY;IACZ,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;;IAQ3B;;OAEG;gBACS,KAAK,EAAE,MAAM;IAIzB,YAAY;IACZ,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,iBAAiB;IACjB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;OAQG;IACH,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,SAAc,GAAG,QAAQ;IAmBrD;;;;;;OAMG;IACH,QAAQ,CAAC,CAAC,EAAE,UAAU,EAAE;QAAE,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAA;KAAE,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,SAAU,GAAG,QAAQ;IAIvF;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,SAAU,GAAG,QAAQ;IAK1D;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB;IAMtC;;;;;;OAMG;IACH,OAAO,IAAI,cAAc,EAAE;CA2B5B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,SAAS,EAAE,CAAC,QAAQ,GAAG,SAAS,CAAC,EAAE,GAAG,QAAQ,CAUjF"}