@yunzai-ng/core 0.1.0

package/dist/testing/mock-adapter.d.ts

@@ -0,0 +1,205 @@
+/**
+ * 模块职责：内存 Mock 适配器 —— 不连接任何平台，在进程内直接收发消息
+ * 依赖方向：只依赖 `@yunzai-ng/types` 与 message/segment；不依赖内核其余任何模块，
+ *          因此任何一层的测试均可引用它，不会反向将被测模块引入
+ * 生命周期：一次 `createMockAdapter()` 对应一个测试用例；驱动实例由内核在连接账号时创建
+ * 注意事项：三项设计取舍，使用前应先阅读：
+ *
+ *          1) **这是真实实现，而非 `vi.fn()` 拼装出的替身对象**。它在编译期即必须满足
+ *             `AdapterProvider` / `BotDriver`，因而同时是测试替身与"编写一个新适配器
+ *             至少需实现哪些方法"的可执行文档 —— 编写 adapter-napcat 时可直接参照。
+ *             以 `as unknown as BotDriver` 强制转换得到的替身对象无法做到这一点：接口新增成员后，
+ *             测试仍能编译通过，直至真实适配器上线方发现存在未实现的方法。
+ *
+ *          2) **投递是单向的，断言必须等待回调**。`host.submit()` 同步返回，内核内部
+ *             异步处理（见 kernel/runtime.ts 第 3 步的 `dispatch` 未 await），因此
+ *             `await receiveGroup(...)` 无法等到回复，需等待时应使用 `waitForSend()`。
+ *
+ *          3) **`waitForSend()` 超时会将已发出的内容写入错误信息**。否则 vitest
+ *             仅报告一句 "test timed out"，无从区分是命令未匹配、插件抛出错误、
+ *             还是回复内容不符 —— 这三种情形的排查方向完全不同。
+ */
+import type { AdapterHost, AdapterProvider, BotCapability, BotDriver, ForwardNode, GroupRole, IncomingEvent, IncomingMessageEvent, MessageContent, Segment, SendOptions, SendTarget } from "@yunzai-ng/types";
+/**
+ * Mock 账号配置
+ *
+ * 写成 `type` 而不是 `interface` 是必要的：`AdapterProvider<T>` 的默认实参是
+ * `Record<string, unknown>`，而 TS 只给**类型别名**隐式索引签名，interface 没有 ——
+ * 用 interface 的话 `AdapterProvider<MockAccountConfig>` 赋给 `AdapterProvider`
+ * （`ctx.registerAdapter` 的形参类型）会编译不过。
+ */
+export type MockAccountConfig = {
+    /** 账号在"平台"上的 id，会成为 `bot.selfId` */
+    selfId: string;
+    /** 账号昵称 */
+    nickname?: string;
+};
+/** 一条被 Mock 记下来的发送 */
+export interface SentMessage {
+    /** 发出这条消息的账号 selfId */
+    selfId: string;
+    /** 发送目标 */
+    target: SendTarget;
+    /** 已展平的消息段 */
+    message: Segment[];
+    /** 纯文本视图，断言基本都用它 */
+    text: string;
+    /** 发送选项（内核填的分片/引用信息也在里面） */
+    opts: SendOptions | undefined;
+    /** Mock 生成的消息 id */
+    messageId: string;
+    /** 合并转发的节点；普通消息为 undefined */
+    nodes: readonly ForwardNode[] | undefined;
+}
+/** 一次被记下来的原生 API 调用 */
+export interface RecordedCall {
+    /** API 名 */
+    action: string;
+    /** 参数 */
+    params: Record<string, unknown> | undefined;
+}
+/** 构造一条私聊消息的选项 */
+export interface MockPrivateOptions {
+    /** 发送者 id，缺省 `"20000"` */
+    uid?: string;
+    /** 发送者昵称 */
+    name?: string;
+    /** 直接指定消息段；给了就忽略 `text` 参数 */
+    message?: Segment[];
+    /** 引用的消息 id */
+    quote?: string;
+    /** 平台细分类型，如 `"friend"` / `"temp"` */
+    subType?: string;
+}
+/** 构造一条群消息的选项 */
+export interface MockGroupOptions extends MockPrivateOptions {
+    /** 群 id，缺省 `"700000"` */
+    gid?: string;
+    /** 发送者在群里的角色，缺省 `"member"`；测 `e.isGroupAdmin` 时改这里 */
+    role?: GroupRole;
+    /** 是否 @ 了机器人：true 时在消息最前面插一个 at 段 */
+    atMe?: boolean;
+}
+/**
+ * Mock 驱动
+ *
+ * 除 `BotDriver` 的能力外，多出一组"从平台方向往内核里灌事件"的方法 ——
+ * 真适配器里这件事由 socket 回调触发，测试里由这些方法代劳。
+ */
+export interface MockDriver extends BotDriver {
+    /** 内核给这个账号的宿主对象（`kv` / `signal` / `route` 都在上面） */
+    readonly host: AdapterHost;
+    /** 校验后的账号配置 */
+    readonly config: MockAccountConfig;
+    /** `connect()` 被调用过几次，测退避重连用 */
+    readonly connects: number;
+    /** `disconnect()` 被调用过几次 */
+    readonly disconnects: number;
+    /**
+     * 投递一个任意事件
+     * @param event 已经是通用模型的事件
+     */
+    receive(event: IncomingEvent): void;
+    /**
+     * 投递一条私聊消息
+     * @param text 消息内容，支持裸字符串与嵌套数组
+     * @param opts 构造选项
+     * @returns 投递出去的那个事件，便于断言 `messageId`
+     */
+    receivePrivate(text: MessageContent, opts?: MockPrivateOptions): IncomingMessageEvent;
+    /**
+     * 投递一条群消息
+     * @param text 消息内容
+     * @param opts 构造选项
+     * @returns 投递出去的那个事件
+     */
+    receiveGroup(text: MessageContent, opts?: MockGroupOptions): IncomingMessageEvent;
+    /**
+     * 模拟"连接被对端关闭"
+     *
+     * 经由 `host.setStatus("offline")`，因此内核会执行完整的下线流程
+     * （摘除 Bot 注册表条目、派发 `bot/offline`、安排退避重连），而不仅是修改一个状态字段。
+     * @param reason 下线原因，会出现在账号状态里
+     */
+    goOffline(reason?: string): void;
+}
+/** 创建 Mock 适配器的选项 */
+export interface MockAdapterOptions {
+    /** 适配器 id，缺省 `"mock"` */
+    id?: string;
+    /** 平台标识，缺省与 id 相同 */
+    platform?: string;
+    /** 本账号声明的可选能力，缺省撤回 + 合并转发 */
+    caps?: readonly BotCapability[];
+    /**
+     * 让 `connect()` 固定失败
+     *
+     * 给了字符串就以它为错误消息抛出，用来测"连接失败不进 Bot 注册表、
+     * 账号状态变 error、排了退避重连"这条路径。
+     */
+    failConnect?: string;
+    /**
+     * `callApi` 的实现
+     *
+     * 缺省抛错 —— 内存 Mock 没有"平台原生 API"这回事，静默返回 undefined
+     * 只会让依赖它的测试以一个更难懂的形式失败。
+     * @param action API 名
+     * @param params 参数
+     * @returns 平台返回值
+     */
+    callApi?: (action: string, params?: Record<string, unknown>) => unknown;
+}
+/** Mock 适配器句柄 */
+export interface MockAdapter {
+    /** 交给 `ctx.registerAdapter()` 的提供方 */
+    readonly provider: AdapterProvider<MockAccountConfig>;
+    /** 已创建的全部驱动，按创建顺序 */
+    readonly drivers: readonly MockDriver[];
+    /** 全部发送记录（多账号共用一份，按 `selfId` 区分） */
+    readonly sent: readonly SentMessage[];
+    /** 全部发送记录的纯文本视图 */
+    readonly texts: readonly string[];
+    /** 被撤回过的消息 id */
+    readonly recalled: readonly string[];
+    /** 被调用过的原生 API */
+    readonly calls: readonly RecordedCall[];
+    /**
+     * 唯一那个驱动
+     *
+     * 单账号测试里省一次 `drivers[0]!`。
+     * @throws 还没有账号连上来时；错误信息里写了该先调什么
+     */
+    readonly driver: MockDriver;
+    /**
+     * 等到累计发出了 `count` 条消息
+     *
+     * @param count 期望的累计条数，缺省 1
+     * @param timeoutMs 等待上限，缺省 2000
+     * @returns 前 `count` 条发送记录
+     * @throws 超时；错误信息里带上实际已发出的内容
+     */
+    waitForSend(count?: number, timeoutMs?: number): Promise<readonly SentMessage[]>;
+    /**
+     * 最后一条发送记录
+     * @returns 发送记录；一条都没发过时 undefined
+     */
+    last(): SentMessage | undefined;
+    /** 清空发送/撤回/调用记录（驱动本身保留） */
+    reset(): void;
+}
+/**
+ * 创建一个内存 Mock 适配器
+ *
+ * 典型用法（完整例子见 kernel/runtime.test.ts）：
+ * ```ts
+ * const mock = createMockAdapter()
+ * app.runtime.adapters.register(mock.provider, "test-plugin")
+ * await app.runtime.accounts.create("mock", { selfId: "10000" })
+ * mock.driver.receivePrivate("#ping")
+ * const [reply] = await mock.waitForSend()
+ * ```
+ * @param opts 选项
+ * @returns Mock 适配器句柄
+ */
+export declare function createMockAdapter(opts?: MockAdapterOptions): MockAdapter;
+//# sourceMappingURL=mock-adapter.d.ts.map

package/dist/testing/mock-adapter.d.ts.map

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

package/dist/testing/mock-adapter.js

@@ -0,0 +1,309 @@
+import { seg, textOf, toSegments } from "../message/segment.js";
+/** 缺省适配器 id */
+const DEFAULT_ID = "mock";
+/** 缺省账号昵称 */
+const DEFAULT_NICKNAME = "Mock Bot";
+/** 缺省的消息发送者 id */
+const DEFAULT_UID = "20000";
+/** 缺省群 id */
+const DEFAULT_GID = "700000";
+/** `waitForSend()` 的缺省等待上限毫秒 */
+const DEFAULT_WAIT = 2000;
+/** 缺省声明的可选能力：撤回与合并转发，正好对应下面真的实现了的两个可选方法 */
+const DEFAULT_CAPS = ["recall", "forward"];
+/** 账号配置的表单描述，WebUI 的"添加账号"表单由它生成 */
+const ACCOUNT_SCHEMA = {
+    type: "object",
+    title: "内存 Mock 账号",
+    properties: {
+        selfId: {
+            type: "string",
+            title: "账号 id",
+            description: "该字段取值任意，Mock 适配器不执行实际登录",
+            default: "10000",
+            required: true,
+            placeholder: "10000"
+        },
+        nickname: {
+            type: "string",
+            title: "昵称",
+            default: DEFAULT_NICKNAME
+        }
+    }
+};
+/**
+ * 创建一个内存 Mock 适配器
+ *
+ * 典型用法（完整例子见 kernel/runtime.test.ts）：
+ * ```ts
+ * const mock = createMockAdapter()
+ * app.runtime.adapters.register(mock.provider, "test-plugin")
+ * await app.runtime.accounts.create("mock", { selfId: "10000" })
+ * mock.driver.receivePrivate("#ping")
+ * const [reply] = await mock.waitForSend()
+ * ```
+ * @param opts 选项
+ * @returns Mock 适配器句柄
+ */
+export function createMockAdapter(opts = {}) {
+    const id = opts.id ?? DEFAULT_ID;
+    const platform = opts.platform ?? id;
+    const caps = new Set(opts.caps ?? DEFAULT_CAPS);
+    /** 发送记录 */
+    const sent = [];
+    /** 撤回记录 */
+    const recalled = [];
+    /** 原生 API 调用记录 */
+    const calls = [];
+    /** 已创建的驱动 */
+    const drivers = [];
+    /** 挂起的 `waitForSend()` */
+    const waiters = new Set();
+    /** 自增序号，用来生成消息 id；不用时间戳是为了让断言可预期 */
+    let counter = 0;
+    /**
+     * 取下一个消息 id
+     * @returns 形如 `mock-msg-1` 的 id
+     */
+    const nextId = () => {
+        counter += 1;
+        return `${id}-msg-${counter}`;
+    };
+    /** 唤醒条件已满足的等待者 */
+    const notify = () => {
+        for (const waiter of [...waiters]) {
+            if (sent.length >= waiter.count) {
+                waiters.delete(waiter);
+                waiter.wake();
+            }
+        }
+    };
+    /**
+     * 记一条发送
+     * @param selfId 发出者
+     * @param target 目标
+     * @param message 消息段
+     * @param sendOpts 发送选项
+     * @param nodes 合并转发节点
+     * @returns 发送结果
+     */
+    const record = (selfId, target, message, sendOpts, nodes) => {
+        const messageId = nextId();
+        sent.push({ selfId, target, message, text: textOf(message), opts: sendOpts, messageId, nodes });
+        notify();
+        return { ok: true, messageId, time: Date.now() };
+    };
+    /**
+     * 造一个 Mock 驱动
+     * @param config 账号配置
+     * @param host 内核给的宿主
+     * @returns 驱动
+     */
+    const createDriver = (config, host) => {
+        const selfId = config.selfId;
+        const nickname = config.nickname ?? DEFAULT_NICKNAME;
+        /** 是否在线 */
+        let online = false;
+        /** connect 次数 */
+        let connects = 0;
+        /** disconnect 次数 */
+        let disconnects = 0;
+        /**
+         * 造一个群成员
+         * @param gid 群 id
+         * @param uid 用户 id
+         * @param role 角色
+         * @returns 成员信息
+         */
+        const member = (gid, uid, role = "member") => ({
+            uid,
+            gid,
+            role,
+            name: uid === selfId ? nickname : `用户${uid}`
+        });
+        const driver = {
+            host,
+            config,
+            selfId,
+            platform,
+            adapterId: id,
+            nickname,
+            caps,
+            get online() {
+                return online;
+            },
+            get connects() {
+                return connects;
+            },
+            get disconnects() {
+                return disconnects;
+            },
+            async connect() {
+                connects += 1;
+                if (opts.failConnect !== undefined)
+                    throw new Error(opts.failConnect);
+                online = true;
+                return Promise.resolve();
+            },
+            async disconnect() {
+                disconnects += 1;
+                online = false;
+                return Promise.resolve();
+            },
+            async sendMessage(target, content, sendOpts) {
+                return Promise.resolve(record(selfId, target, toSegments(content), sendOpts));
+            },
+            async sendForward(target, nodes) {
+                // 转发的文本视图取各节点正文拼接，以使 `texts` 断言对转发同样有效
+                const flat = nodes.flatMap(node => node.message ?? []);
+                return Promise.resolve(record(selfId, target, flat, undefined, nodes));
+            },
+            async recallMessage(messageId) {
+                recalled.push(messageId);
+                return Promise.resolve(true);
+            },
+            async getSelfInfo() {
+                return Promise.resolve({ uid: selfId, name: nickname });
+            },
+            async getFriend(uid) {
+                return Promise.resolve({ uid, name: `用户${uid}` });
+            },
+            async getFriendList() {
+                return Promise.resolve([{ uid: DEFAULT_UID, name: `用户${DEFAULT_UID}` }]);
+            },
+            async getGroup(gid) {
+                return Promise.resolve({ gid, name: `Mock 群 ${gid}`, memberCount: 2 });
+            },
+            async getGroupList() {
+                return Promise.resolve([{ gid: DEFAULT_GID, name: `Mock 群 ${DEFAULT_GID}`, memberCount: 2 }]);
+            },
+            async getGroupMember(gid, uid) {
+                return Promise.resolve(member(gid, uid));
+            },
+            async getGroupMemberList(gid) {
+                return Promise.resolve([member(gid, selfId), member(gid, DEFAULT_UID)]);
+            },
+            async callApi(action, params) {
+                calls.push({ action, params });
+                if (!opts.callApi) {
+                    throw new Error(`内存 Mock 适配器没有平台原生 API（收到调用 ${action}）；需要的话给 createMockAdapter 传 callApi`);
+                }
+                return (await opts.callApi(action, params));
+            },
+            receive(event) {
+                host.submit(event);
+            },
+            receivePrivate(text, o = {}) {
+                const uid = o.uid ?? DEFAULT_UID;
+                const event = {
+                    kind: "message",
+                    scene: "private",
+                    subType: o.subType ?? "friend",
+                    messageId: nextId(),
+                    message: o.message ?? toSegments(text),
+                    sender: { uid, name: o.name ?? `用户${uid}` }
+                };
+                if (o.quote !== undefined)
+                    event.quote = { messageId: o.quote };
+                host.submit(event);
+                return event;
+            },
+            receiveGroup(text, o = {}) {
+                const gid = o.gid ?? DEFAULT_GID;
+                const uid = o.uid ?? DEFAULT_UID;
+                const body = o.message ?? toSegments(text);
+                const event = {
+                    kind: "message",
+                    scene: "group",
+                    subType: o.subType ?? "normal",
+                    messageId: nextId(),
+                    message: o.atMe === true ? [seg.at(selfId), ...body] : body,
+                    sender: { uid, gid, role: o.role ?? "member", name: o.name ?? `用户${uid}` },
+                    group: { gid, name: `Mock 群 ${gid}` }
+                };
+                if (o.quote !== undefined)
+                    event.quote = { messageId: o.quote };
+                host.submit(event);
+                return event;
+            },
+            goOffline(reason) {
+                online = false;
+                host.setStatus("offline", { error: reason ?? "Mock 主动下线" });
+            }
+        };
+        return driver;
+    };
+    const provider = {
+        id,
+        name: "内存 Mock 适配器",
+        description: "不连任何平台，事件由测试代码直接灌进来",
+        platform,
+        accountSchema: ACCOUNT_SCHEMA,
+        validateAccount(input) {
+            if (typeof input !== "object" || input === null)
+                throw new Error("Mock 账号配置必须是一个对象");
+            const raw = input;
+            const selfId = raw.selfId;
+            if (typeof selfId !== "string" || selfId === "")
+                throw new Error("Mock 账号配置缺少 selfId");
+            const nickname = raw.nickname;
+            return { selfId, nickname: typeof nickname === "string" ? nickname : DEFAULT_NICKNAME };
+        },
+        createBot(account, host) {
+            const driver = createDriver(account, host);
+            drivers.push(driver);
+            return driver;
+        }
+    };
+    return {
+        provider,
+        drivers,
+        sent,
+        recalled,
+        calls,
+        get texts() {
+            return sent.map(item => item.text);
+        },
+        get driver() {
+            const first = drivers[0];
+            if (!first)
+                throw new Error("还没有 Mock 驱动：先注册 provider 再 accounts.create()，且要等 create() 返回");
+            return first;
+        },
+        async waitForSend(count = 1, timeoutMs = DEFAULT_WAIT) {
+            if (sent.length < count) {
+                await new Promise((resolve, reject) => {
+                    // wake 要清定时器、定时器要摘等待者，两边互相引用；用一个小盒子打断这个循环
+                    const box = {};
+                    const waiter = {
+                        count,
+                        wake: () => {
+                            clearTimeout(box.timer);
+                            resolve();
+                        }
+                    };
+                    box.timer = setTimeout(() => {
+                        waiters.delete(waiter);
+                        // 附带已发出的内容：见文件头第 3 条
+                        const got = sent.length === 0 ? "（尚无任何发送）" : sent.map(item => JSON.stringify(item.text)).join("、");
+                        reject(new Error(`等待第 ${count} 条发送超过 ${timeoutMs}ms 仍未到达，目前已发出 ${sent.length} 条：${got}`));
+                    }, timeoutMs);
+                    // 用例断言完毕后，该定时器不应继续阻塞 vitest 的收尾流程
+                    box.timer.unref?.();
+                    waiters.add(waiter);
+                });
+            }
+            return sent.slice(0, count);
+        },
+        last() {
+            return sent[sent.length - 1];
+        },
+        reset() {
+            sent.length = 0;
+            recalled.length = 0;
+            calls.length = 0;
+            counter = 0;
+        }
+    };
+}
+//# sourceMappingURL=mock-adapter.js.map

package/dist/testing/mock-adapter.js.map

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

package/dist/util/deep.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 模块职责：对象深操作（合并、克隆、按路径读写、差异路径计算）
+ * 依赖方向：无
+ * 生命周期：纯函数
+ * 注意事项：配置系统的地基。`diffPaths` 算出实际变化的叶子路径，故配置变更只通知
+ *          关心那些路径的订阅者，而不是让每个读配置的地方全量重算。
+ *
+ *          **数组是整体替换，不逐元素合并。** 配置里的数组（主人列表、黑名单）语义上是
+ *          "一个值"，逐元素合并会让使用者无法删除默认项。
+ */
+/** 可作为配置节点的普通对象 */
+export type PlainObject = Record<string, unknown>;
+/**
+ * 判断是否为普通对象（排除数组、null、Date、Buffer、类实例等）
+ * @param value 待判定值
+ * @returns 是否为普通对象
+ */
+export declare function isPlainObject(value: unknown): value is PlainObject;
+/**
+ * 深克隆
+ *
+ * 优先用 `structuredClone`（Node 17+ 内置，能处理 Map/Set/Date/循环引用），
+ * 遇到函数等不可克隆值时退回浅拷贝语义。
+ * @param value 源值
+ * @returns 克隆结果
+ */
+export declare function deepClone<T>(value: T): T;
+/**
+ * 深合并：把 `source` 覆盖到 `target` 的副本上
+ *
+ * - 普通对象递归合并
+ * - 数组、`Date` 等整体替换
+ * - `source` 中值为 `undefined` 的键被忽略（不会把 target 的值抹成 undefined）
+ * @param target 基准值（不被修改）
+ * @param source 覆盖值
+ * @returns 合并后的新对象
+ */
+export declare function deepMerge<T extends PlainObject>(target: T, source: PlainObject | undefined): T;
+/**
+ * 深比较
+ * @param a 左值
+ * @param b 右值
+ * @returns 是否深度相等
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * 把点分路径切成键数组
+ *
+ * 支持 `a.b[0].c` 与 `a.b.0.c` 两种写法。
+ * @param path 路径字符串
+ * @returns 键数组
+ */
+export declare function splitPath(path: string): string[];
+/**
+ * 按路径取值
+ * @param obj 源对象
+ * @param path 点分路径；空串返回 obj 本身
+ * @returns 值；路径不存在时 undefined
+ */
+export declare function getPath(obj: unknown, path: string): unknown;
+/**
+ * 按路径写值（原地修改）
+ *
+ * 中间层不存在时自动创建：下一级键是纯数字则建数组，否则建对象。
+ * @param obj 目标对象
+ * @param path 点分路径
+ * @param value 值
+ * @throws 当路径为空或中间层是不可写入的标量时
+ */
+export declare function setPath(obj: PlainObject, path: string, value: unknown): void;
+/**
+ * 按路径删除（原地修改）
+ * @param obj 目标对象
+ * @param path 点分路径
+ * @returns 是否确实删掉了什么
+ */
+export declare function deletePath(obj: PlainObject, path: string): boolean;
+/**
+ * 计算两个对象间发生变化的**叶子路径**
+ *
+ * 这是细粒度配置失效的核心：改了 `bot.masterQQ` 就只通知订阅
+ * `bot.masterQQ`（或其祖先 `bot`）的人，不打扰订阅 `render.*` 的人。
+ *
+ * 数组视为叶子（整体变化），不下钻元素。
+ * @param before 旧值
+ * @param after 新值
+ * @param prefix 内部递归用的路径前缀
+ * @returns 变化路径列表，已去重
+ */
+export declare function diffPaths(before: unknown, after: unknown, prefix?: string): string[];
+/**
+ * 判断某条变化路径是否影响到订阅路径
+ *
+ * 双向前缀匹配：改 `bot` 影响订阅 `bot.masterQQ` 的人（父变子受影响），
+ * 改 `bot.masterQQ` 也影响订阅 `bot` 的人（子变父受影响）。
+ * @param changed 发生变化的路径
+ * @param watched 订阅的路径；空串表示订阅全部
+ * @returns 是否受影响
+ */
+export declare function pathAffects(changed: string, watched: string): boolean;
+/**
+ * 摘出对象里的指定路径，组成新对象
+ * @param obj 源对象
+ * @param paths 路径列表
+ * @returns 只含这些路径的新对象
+ */
+export declare function pickPaths(obj: PlainObject, paths: readonly string[]): PlainObject;
+//# sourceMappingURL=deep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deep.d.ts","sourceRoot":"","sources":["../../src/util/deep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,mBAAmB;AACnB,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEjD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAKlE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAMxC;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,CAAC,CAiB9F;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAwBzD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMhD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAS3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CA2B5E;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAkBlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,MAAM,EAAE,CAehF;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAIrE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAOjF"}