@aiao/rxdb-plugin-tree 0.0.0-stage → 0.0.28

package/dist/query/merge-update-tree.d.ts

@@ -0,0 +1,80 @@
+import { EntityType, QueryTask, RxDBEntityLocalUpdatedEventData, UpdateClassification, UpdateDataCache } from '@aiao/rxdb';
+/**
+ * 处理 findDescendants 查询的增量更新
+ *
+ * UPDATE 场景下的复杂性:
+ * 1. 实体的 parentId 可能变化，导致树形结构重组
+ * 2. 实体可能从不是后代变成后代，或从后代变成非后代
+ * 3. 实体仍然是后代，但字段值变化（如名称、描述等）
+ * 4. 需要考虑 level 限制（只查询特定层级的后代）
+ *
+ * 更新策略:
+ * - 移除: 不再匹配 where 条件 或 不再是后代 或 超出 level 范围
+ * - 更新: 仍在结果集中的实体，更新其字段值
+ * - 添加: 新匹配 where 条件 且 成为后代 且 在 level 范围内
+ *
+ * @param task 查询任务
+ * @param data 更新的实体数据列表
+ * @param classification 更新分类结果
+ * @param cache 更新数据缓存
+ */
+export declare const handleFindDescendantsUpdate: <T extends EntityType>(task: QueryTask<T>, data: RxDBEntityLocalUpdatedEventData<T>[], classification: UpdateClassification, cache: UpdateDataCache<T>) => void;
+/**
+ * 处理 findAncestors 查询的增量更新
+ *
+ * UPDATE 场景下的复杂性:
+ * 1. 目标实体的祖先链路可能因为其他实体的 parentId 变化而改变
+ * 2. 实体可能从不是祖先变成祖先，或从祖先变成非祖先
+ * 3. 实体仍然是祖先，但字段值变化
+ * 4. 目标实体本身也是结果的一部分（level=0）
+ *
+ * 特殊情况:
+ * - 如果目标实体的 parentId 变化，整个祖先链都会改变，需要完全刷新
+ *
+ * @param task 查询任务
+ * @param data 更新的实体数据列表
+ * @param classification 更新分类结果
+ * @param cache 更新数据缓存
+ */
+export declare const handleFindAncestorsUpdate: <T extends EntityType>(task: QueryTask<T>, data: RxDBEntityLocalUpdatedEventData<T>[], classification: UpdateClassification, cache: UpdateDataCache<T>) => void;
+/**
+ * 处理 countDescendants 查询的增量更新
+ *
+ * 计数查询的特点:
+ * - 只需要返回数量，不需要返回具体实体
+ * - 没有实体级追踪，看不到不在本批事件里的子孙
+ *
+ * UPDATE 场景下的计数变化:
+ * 1. scope 内（或无法判定）的非基准节点 parentId 变化 → 子树整体进出 / 平移深度，触发 SQL 刷新
+ * 2. scope 内（或无法判定）的非基准节点 where 命中翻转 → 递归遍历在它这里被截断或放开，
+ *    名下子孙随之进出，触发 SQL 刷新
+ * 3. 只改了其他字段、或变化发生在 scope 之外 → 计数不变，不通知
+ *
+ * @param task 查询任务
+ * @param data 更新的实体数据列表
+ * @param classification 更新分类结果
+ * @param cache 更新数据缓存
+ */
+export declare const handleCountDescendantsUpdate: <T extends EntityType>(task: QueryTask<T>, data: RxDBEntityLocalUpdatedEventData<T>[], classification: UpdateClassification, cache: UpdateDataCache<T>) => void;
+/**
+ * 处理 countAncestors 查询的增量更新
+ *
+ * 计数查询的特点:
+ * - 只需要返回数量，不需要返回具体实体
+ * - 没有实体级追踪，看不到不在本批事件里的上方祖先
+ * - 如果无法确定关系（父实体链中断）或目标实体的 parentId 变化，则触发 SQL 刷新
+ *
+ * UPDATE 场景下的计数变化:
+ * 1. 目标实体的 parentId 变化 → 整个祖先链改变，必须触发刷新
+ * 2. 链上（或无法判定）的祖先 parentId 变化 → 它上方整段链被换掉，触发刷新
+ * 3. 链上（或无法判定）的祖先 where 命中翻转 → 递归遍历在它这里被截断或放开，
+ *    上方祖先随之进出，触发刷新
+ * 4. 只改了其他字段、或变化发生在链外 → 计数不变，不通知
+ *
+ * @param task 查询任务
+ * @param data 更新的实体数据列表
+ * @param classification 更新分类结果
+ * @param cache 更新数据缓存
+ */
+export declare const handleCountAncestorsUpdate: <T extends EntityType>(task: QueryTask<T>, data: RxDBEntityLocalUpdatedEventData<T>[], classification: UpdateClassification, cache: UpdateDataCache<T>) => void;
+//# sourceMappingURL=merge-update-tree.d.ts.map

package/dist/query/merge-update-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-update-tree.d.ts","sourceRoot":"","sources":["../../src/query/merge-update-tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,UAAU,EAEV,SAAS,EAET,+BAA+B,EAC/B,oBAAoB,EACpB,eAAe,EAChB,MAAM,YAAY,CAAC;AAgBpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,2BAA2B,GAAI,CAAC,SAAS,UAAU,EAC9D,MAAM,SAAS,CAAC,CAAC,CAAC,EAClB,MAAM,+BAA+B,CAAC,CAAC,CAAC,EAAE,EAC1C,gBAAgB,oBAAoB,EACpC,OAAO,eAAe,CAAC,CAAC,CAAC,SA6M1B,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,GAAI,CAAC,SAAS,UAAU,EAC5D,MAAM,SAAS,CAAC,CAAC,CAAC,EAClB,MAAM,+BAA+B,CAAC,CAAC,CAAC,EAAE,EAC1C,gBAAgB,oBAAoB,EACpC,OAAO,eAAe,CAAC,CAAC,CAAC,SAoG1B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GAAI,CAAC,SAAS,UAAU,EAC/D,MAAM,SAAS,CAAC,CAAC,CAAC,EAClB,MAAM,+BAA+B,CAAC,CAAC,CAAC,EAAE,EAC1C,gBAAgB,oBAAoB,EACpC,OAAO,eAAe,CAAC,CAAC,CAAC,SA2D1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,0BAA0B,GAAI,CAAC,SAAS,UAAU,EAC7D,MAAM,SAAS,CAAC,CAAC,CAAC,EAClB,MAAM,+BAA+B,CAAC,CAAC,CAAC,EAAE,EAC1C,gBAAgB,oBAAoB,EACpC,OAAO,eAAe,CAAC,CAAC,CAAC,SAwE1B,CAAC"}

package/dist/query/merge_create.d.ts

@@ -0,0 +1,9 @@
+import { EntityType, QueryTask, RxDBEntityLocalCreatedEventData } from '@aiao/rxdb';
+/**
+ * 处理树查询 CREATE 事件的缓存合并
+ *
+ * @param task 查询任务
+ * @param entities 创建的实体事件数据
+ */
+export declare const merge_create: <T extends EntityType>(task: QueryTask<T>, entities: RxDBEntityLocalCreatedEventData<T>[]) => void;
+//# sourceMappingURL=merge_create.d.ts.map

package/dist/query/merge_create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge_create.d.ts","sourceRoot":"","sources":["../../src/query/merge_create.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,UAAU,EAIV,SAAS,EAET,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAwDpB;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,UAAU,EAC/C,MAAM,SAAS,CAAC,CAAC,CAAC,EAClB,UAAU,+BAA+B,CAAC,CAAC,CAAC,EAAE,SA6C/C,CAAC"}

package/dist/query/merge_remove.d.ts

@@ -0,0 +1,9 @@
+import { EntityType, QueryTask, RxDBEntityLocalRemovedEventData } from '@aiao/rxdb';
+/**
+ * 处理树查询 REMOVE 事件的缓存合并
+ *
+ * @param task 查询任务
+ * @param entities 删除的实体事件数据
+ */
+export declare const merge_remove: <T extends EntityType>(task: QueryTask<T>, entities: RxDBEntityLocalRemovedEventData<T>[]) => void;
+//# sourceMappingURL=merge_remove.d.ts.map

package/dist/query/merge_remove.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge_remove.d.ts","sourceRoot":"","sources":["../../src/query/merge_remove.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,UAAU,EAGV,SAAS,EAGT,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAkGpB;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,UAAU,EAC/C,MAAM,SAAS,CAAC,CAAC,CAAC,EAClB,UAAU,+BAA+B,CAAC,CAAC,CAAC,EAAE,SA2C/C,CAAC"}

package/dist/query/merge_update.d.ts

@@ -0,0 +1,9 @@
+import { EntityType, QueryTask, RxDBEntityLocalUpdatedEventData } from '@aiao/rxdb';
+/**
+ * 处理树查询 UPDATE 事件的缓存合并
+ *
+ * @param task 查询任务
+ * @param entities 更新的实体事件数据
+ */
+export declare const merge_update: <T extends EntityType>(task: QueryTask<T>, entities: RxDBEntityLocalUpdatedEventData<T>[]) => void;
+//# sourceMappingURL=merge_update.d.ts.map

package/dist/query/merge_update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge_update.d.ts","sourceRoot":"","sources":["../../src/query/merge_update.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,UAAU,EAGV,SAAS,EAET,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAmCpB;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,SAAS,UAAU,EAC/C,MAAM,SAAS,CAAC,CAAC,CAAC,EAClB,UAAU,+BAA+B,CAAC,CAAC,CAAC,EAAE,SA0E/C,CAAC"}

package/dist/query/query-tree.utils.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 树形遍历配置
+ */
+interface TreeTraversalOptions {
+    maxLevel?: number;
+    maxDepth?: number;
+}
+/**
+ * 获取实体的父级 ID
+ * 处理 parentId 可能是对象或字符串的情况
+ */
+export declare const get_tree_parent_id: <ID = string>(entity: object | null | undefined) => ID | null;
+/**
+ * 判断一条更新事件是否**真的**改动了 `parentId`
+ *
+ * @param event 带 `patch` / `inversePatch` 的更新事件
+ * @returns `true` 表示父节点发生了位移
+ *
+ * @remarks
+ * 两条都不能省：
+ *
+ * - **key 存在 ≠ 值变了**：只改 `isActive` 时 patch 仍可能带上未变的 `parentId`，
+ *   单看 `'parentId' in patch` 会把纯字段更新误判成"移动"，触发不必要的 refresh。
+ * - **两侧都要归一**：在树语义里「缺失」「`null`」「`undefined`」都是「挂在根上」，
+ *   所以两侧统一走 {@link get_tree_parent_id}。裸 `Reflect.get` 比较会把
+ *   `undefined → null` 这种无变化算成移动。
+ *
+ * 这是全插件判断"父节点变了没有"的**唯一**实现：此前 `merge_update.ts` 与
+ * `merge-update-tree.ts` 各有一套拼写，null/undefined 语义在两套之间分叉。
+ */
+export declare const hasTreeParentChanged: (event: {
+    patch: object;
+    inversePatch: object;
+}) => boolean;
+/**
+ * 向上遍历父级链路
+ *
+ * @param entity 起始实体
+ * @param entitiesMap 实体 ID 映射表
+ * @param options 遍历配置
+ * @yields 每一层的父级实体和层级
+ */
+export declare function traverseAncestors<T extends object, ID>(entity: T, entitiesMap: Map<ID, T>, options?: TreeTraversalOptions): Generator<{
+    entity: T;
+    level: number;
+}>;
+/**
+ * 检查实体是否是目标实体的后代
+ *
+ * @param entity 要检查的实体
+ * @param targetId 目标实体 ID (为 null 或 undefined 时表示查找根节点)
+ * @param entitiesMap 实体 ID 映射表
+ * @param maxLevel 最大层级 (undefined 表示无限制)
+ * @returns 如果是后代则返回 true
+ */
+export declare function isDescendantOf<T extends object, ID>(entity: T, targetId: ID | null | undefined, entitiesMap: Map<ID, T>, maxLevel?: number): boolean;
+/**
+ * 检查实体是否是目标实体的祖先
+ *
+ * @param candidateEntity 候选祖先实体
+ * @param targetId 目标实体 ID (为 null 或 undefined 时直接返回 false，无 isDescendantOf 那种"查找根节点"语义)
+ * @param entitiesMap 实体 ID 映射表
+ * @param maxLevel 最大层级
+ * @returns 如果是祖先则返回 true
+ */
+export declare function isAncestorOf<T extends object, ID>(candidateEntity: T, targetId: ID | null | undefined, entitiesMap: Map<ID, T>, maxLevel?: number): boolean;
+/**
+ * 顺序串联多个可迭代源，不物化中间数组
+ *
+ * @param sources 按顺序遍历的可迭代源
+ * @yields 各源中的元素，顺序与传入顺序一致
+ *
+ * @remarks
+ * 专为 {@link buildEntityMap} 的「旧结果 `Set` + 本批事件数组」场景而设：
+ * `Array.from(set)` 再展开拼接会把旧结果集整体物化两遍，只为建一张查找表。
+ */
+export declare function concatIterables<T>(...sources: Iterable<T>[]): Generator<T>;
+/**
+ * 构建实体 ID 映射表（优化查找性能）
+ *
+ * @param entities 实体来源；接受任意可迭代对象（数组、`Set`、{@link concatIterables} 的产物）
+ * @param getIdFn 获取实体 ID 的函数
+ * @returns 实体 ID 到实体的映射表
+ */
+export declare function buildEntityMap<T, ID>(entities: Iterable<T>, getIdFn: (entity: T) => ID | null | undefined): Map<ID, T>;
+export {};
+//# sourceMappingURL=query-tree.utils.d.ts.map

package/dist/query/query-tree.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-tree.utils.d.ts","sourceRoot":"","sources":["../../src/query/query-tree.utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,EAAE,GAAG,MAAM,EAAE,QAAQ,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,EAAE,GAAG,IAGxF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,KAAG,OACmB,CAAC;AAE1G;;;;;;;GAOG;AACH,wBAAiB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EACrD,MAAM,EAAE,CAAC,EACT,WAAW,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EACvB,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAwBzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EACjD,MAAM,EAAE,CAAC,EACT,QAAQ,EAAE,EAAE,GAAG,IAAI,GAAG,SAAS,EAC/B,WAAW,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EACvB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAmDT;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAC/C,eAAe,EAAE,CAAC,EAClB,QAAQ,EAAE,EAAE,GAAG,IAAI,GAAG,SAAS,EAC/B,WAAW,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EACvB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAWT;AAED;;;;;;;;;GASG;AACH,wBAAiB,eAAe,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAI3E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,EAAE,EAClC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,EACrB,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,IAAI,GAAG,SAAS,GAC5C,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAOZ"}

package/dist/query/tree-helper.d.ts

@@ -0,0 +1,143 @@
+import { EntityType, RxDBEntityId, UpdateDataCache } from '@aiao/rxdb';
+/**
+ * 目标实体的祖先 id 集合，{@link TreeHelper.collectAncestorIdsForCount} 的产物
+ */
+export interface TreeAncestorIdSet {
+    /** 自目标向上、`maxLevel` 以内解析到的全部祖先 id */
+    ids: ReadonlySet<RxDBEntityId>;
+    /**
+     * 父链是否走到了尽头。
+     *
+     * `false` 表示中途有一环取不到实体 —— 集合**之外**的候选无从判定，只能回 SQL；
+     * 集合**之内**的候选仍是确定的 `true`（走链在断点之前就已经经过它）。
+     */
+    complete: boolean;
+}
+/**
+ * 用预先收集的祖先集合判定单个候选实体（`count` 口径）
+ *
+ * @param ancestors {@link TreeHelper.collectAncestorIdsForCount} 的结果
+ * @param candidateEntity 候选祖先实体
+ * @returns true=是祖先, false=不是祖先, undefined=无法确定（调用方回 SQL 重算）
+ */
+export declare const resolveAncestorForCount: <T extends EntityType>(ancestors: TreeAncestorIdSet, candidateEntity: InstanceType<T> | null | undefined) => boolean | undefined;
+/**
+ * 树形结构辅助函数管理器
+ *
+ * 提供树形查询所需的核心功能：
+ * - 解析父实体引用
+ * - 判断后代/祖先关系（普通 + count 专用变体）
+ * - 支持层级限制和循环检测
+ *
+ * @template T 实体类型
+ *
+ * @internal 由 merge-update-tree.ts 的 handle*Update 函数使用
+ */
+export declare class TreeHelper<T extends EntityType> {
+    private cache;
+    private oldResultMap;
+    constructor(cache: UpdateDataCache<T>, oldResultMap: Map<RxDBEntityId, InstanceType<T>>);
+    /**
+     * 解析父实体
+     *
+     * 从更新缓存或旧结果集中获取父实体，避免重复查询数据库
+     *
+     * @param id 父实体ID
+     * @returns 父实体实例，如果不存在则返回 undefined
+     *
+     * @remarks
+     * **更新缓存优先，旧结果集兜后**。`oldResultMap` 是本批事件**之前**的快照；
+     * 同一批里父节点自己也被移动时（`Y.parentId A→null` 与 `M.parentId Z→Y` 同批到达），
+     * 先读旧结果集会顺着过期的 `parentId` 往上走，把已经移出子树的节点判成仍在子树内。
+     * `cache.getSerializedUpdate` 给的是本批应用后的状态，与 `merge-update-tree.ts`
+     * 孤儿复查里的 `resolveParent` 同口径。
+     */
+    resolveParentEntity(id: RxDBEntityId): InstanceType<T> | undefined;
+    /**
+     * 检查实体是否是目标实体的后代
+     *
+     * 从实体向上遍历父级链，检查是否能到达目标实体
+     * 包含循环检测，防止无限递归
+     *
+     * @param entity 要检查的实体
+     * @param targetEntityId 目标实体ID (潜在的祖先)，为 null 或 undefined 时表示查找所有树（所有节点都有效）
+     * @returns 包含是否为后代和层级深度的对象
+     */
+    isEntityDescendant(entity: InstanceType<T>, targetEntityId: RxDBEntityId | null | undefined): {
+        isDescendant: boolean;
+        level: number;
+    };
+    /**
+     * 检查实体是否是目标的祖先
+     *
+     * 从目标实体向上遍历父级链，检查是否能到达候选实体
+     *
+     * @param targetEntity 目标实体 (要查找其祖先)
+     * @param candidateEntity 候选祖先实体
+     * @param maxLevel 层级上限，口径同 `FindTreeOptions.level`：目标自身为 0、父节点为 1。
+     *   `undefined` 表示不限层级。
+     * @returns true 表示候选实体是目标的祖先
+     *
+     * @remarks
+     * `maxLevel` 不是可选的性能优化，而是正确性要求：调用方给了 `level` 时，
+     * 适配器的递归成员带 `c.__level < level`，`__level` 超出上限的祖先 SQL 根本不会返回；
+     * 这里不跟着截断就会把深处的祖先并进增量结果，与全量刷新分叉。
+     * 调用方没给 `level`（不限深度）时传 `undefined`，两边都走到根。
+     */
+    isEntityAncestor(targetEntity: InstanceType<T>, candidateEntity: InstanceType<T>, maxLevel?: number): boolean;
+    /**
+     * 检查实体是否是目标的后代 (用于 count 查询)
+     *
+     * 与 isEntityDescendant 类似，但返回 undefined 表示无法确定
+     * 当父实体链中有实体不在更新数据中时，无法继续追踪，返回 undefined
+     * 此时需要触发 SQL 刷新以获取准确结果
+     *
+     * @param entity 要检查的实体
+     * @param targetEntityId 目标实体ID，为 null 或 undefined 时表示查找所有树（所有节点都有效）
+     * @returns true=是后代, false=不是后代, undefined=无法确定
+     */
+    isEntityDescendantForCount(entity: InstanceType<T> | null | undefined, targetEntityId: RxDBEntityId | null | undefined): boolean | undefined;
+    /**
+     * 计算实体相对目标实体的后代深度 (用于 count 查询)
+     *
+     * @param entity 要检查的实体
+     * @param targetEntityId 目标实体ID；为 null 或 undefined 时表示查询所有树，深度从根节点算起
+     * @returns `{ isDescendant, depth }`；无法确定时返回 `undefined`
+     *
+     * @remarks
+     * {@link isEntityDescendantForCount} 只回答「是不是后代」，答不出「隔了几层」，
+     * 于是 `countDescendants` 的 `level` 限制在增量合并里整个缺席：`{ entityId, level: 0 }`
+     * （只数目标节点自己，后代一个都不算）会被一个直接子节点的 where 翻转加成 1。
+     *
+     * 深度口径与 `FindTreeOptions.level` 一致：给了 `entityId` 时目标节点自身深度为 0、
+     * 直接子节点为 1；没给 `entityId` 时根节点深度为 0。调用方用 `depth <= level` 过滤。
+     *
+     * 与 {@link isEntityDescendantForCount} 一样，父链上任何一环取不到就返回 `undefined`
+     * 让调用方回 SQL 重算 —— 深度算不准时不能猜。
+     */
+    descendantDepthForCount(entity: InstanceType<T> | null | undefined, targetEntityId: RxDBEntityId | null | undefined): {
+        isDescendant: boolean;
+        depth: number;
+    } | undefined;
+    /**
+     * 收集目标实体的祖先 id 集合 (用于 count 查询)
+     *
+     * @param targetEntity 目标实体（要查找其祖先）
+     * @param maxLevel 层级上限，口径同 {@link isEntityAncestor}；`undefined` 表示不限层级。
+     * @returns 祖先 id 集合 + 「父链是否完整」标记，交给 {@link resolveAncestorForCount} 判定候选
+     *
+     * @remarks
+     * `countAncestors` 的目标祖先链在一批事件内是**不变**的（目标自己改父会被调用方
+     * 提前 `refresh()` 拦掉），而这条链只取决于起点的 `parentId` 加逐跳的
+     * `cache.getSerializedUpdate` —— 对批内每个候选各走一遍是 O(N×depth) 的逐字节重复。
+     * 走一次建 Set，候选判定降到 O(1)。
+     *
+     * 与 {@link isEntityAncestor} 同因，`maxLevel` 不是性能优化而是正确性要求：
+     * `countAncestors` 数的是 `__level <= level` 的祖先，不带上限会把超深祖先也计进去。
+     * 超出 `maxLevel` 时停止收集并标记 `complete: true` —— 更上方的祖先 SQL 不会返回，
+     * 「不是祖先」是能确定的答案，不必为此回一次 SQL。只有父链中途取不到实体
+     * 才标记 `complete: false`。环由 `ids` 自身兜住，无需额外的跳数上限。
+     */
+    collectAncestorIdsForCount(targetEntity: InstanceType<T>, maxLevel?: number): TreeAncestorIdSet;
+}
+//# sourceMappingURL=tree-helper.d.ts.map

package/dist/query/tree-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-helper.d.ts","sourceRoot":"","sources":["../../src/query/tree-helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAe,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGpF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,GAAG,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAAI,CAAC,SAAS,UAAU,EAC1D,WAAW,iBAAiB,EAC5B,iBAAiB,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,KAClD,OAAO,GAAG,SASZ,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,UAAU;IAExC,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,YAAY;gBADZ,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,EACzB,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAG1D;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS;IAWlE;;;;;;;;;OASG;IACH,kBAAkB,CAChB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,cAAc,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAC9C;QAAE,YAAY,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IA+C3C;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO;IAwC7G;;;;;;;;;;OAUG;IACH,0BAA0B,CACxB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAC1C,cAAc,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAC9C,OAAO,GAAG,SAAS;IAkCtB;;;;;;;;;;;;;;;;;OAiBG;IACH,uBAAuB,CACrB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAC1C,cAAc,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAC9C;QAAE,YAAY,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IA6BvD;;;;;;;;;;;;;;;;;;OAkBG;IACH,0BAA0B,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,iBAAiB;CAwBhG"}

package/dist/query/tree-query.interface.d.ts

@@ -0,0 +1,53 @@
+import { EntityType } from '@aiao/rxdb';
+import { TreeQueryType } from '../constants.js';
+import { FindTreeOptions } from '../repository/tree-repository.interface.js';
+/**
+ * FindDescendants 查询任务
+ * 查找指定实体的所有后代节点
+ */
+export interface FindDescendantsQuery<T extends EntityType> {
+    type: Extract<TreeQueryType, 'findDescendants'>;
+    options: FindTreeOptions<T>;
+}
+/**
+ * FindAncestors 查询任务
+ * 查找指定实体的所有祖先节点
+ */
+export interface FindAncestorsQuery<T extends EntityType> {
+    type: Extract<TreeQueryType, 'findAncestors'>;
+    options: FindTreeOptions<T>;
+}
+/**
+ * CountDescendants 查询任务
+ * 统计指定实体的后代节点数量
+ */
+export interface CountDescendantsQuery<T extends EntityType> {
+    type: Extract<TreeQueryType, 'countDescendants'>;
+    options: FindTreeOptions<T>;
+}
+/**
+ * CountAncestors 查询任务
+ * 统计指定实体的祖先节点数量
+ */
+export interface CountAncestorsQuery<T extends EntityType> {
+    type: Extract<TreeQueryType, 'countAncestors'>;
+    options: FindTreeOptions<T>;
+}
+/**
+ * 四支树查询任务的联合。
+ *
+ * @remarks
+ * 与 {@link TreeQueryType} 的双向一致性由
+ * `__tests__/contracts/tree-query-type-parity.spec.ts` 钉死：这里加一支而
+ * {@link TREE_QUERY_TYPE_LIST} 没加（或反过来），那条断言编译失败。
+ */
+export type TreeQuery<T extends EntityType> = FindDescendantsQuery<T> | FindAncestorsQuery<T> | CountDescendantsQuery<T> | CountAncestorsQuery<T>;
+declare module '@aiao/rxdb' {
+    interface RepositoryQueryExtensions<T extends EntityType> {
+        treeFindDescendants: FindDescendantsQuery<T>;
+        treeFindAncestors: FindAncestorsQuery<T>;
+        treeCountDescendants: CountDescendantsQuery<T>;
+        treeCountAncestors: CountAncestorsQuery<T>;
+    }
+}
+//# sourceMappingURL=tree-query.interface.d.ts.map

package/dist/query/tree-query.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-query.interface.d.ts","sourceRoot":"","sources":["../../src/query/tree-query.interface.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAE7E;;;GAGG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,UAAU;IACxD,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,iBAAiB,CAAC,CAAC;IAChD,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,UAAU;IACtD,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;IAC9C,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,UAAU;IACzD,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;IACjD,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,UAAU;IACvD,IAAI,EAAE,OAAO,CAAC,aAAa,EAAE,gBAAgB,CAAC,CAAC;IAC/C,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,UAAU,IACxC,oBAAoB,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAEtG,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,yBAAyB,CAAC,CAAC,SAAS,UAAU;QACtD,mBAAmB,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;QAC7C,iBAAiB,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;QACzC,oBAAoB,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;QAC/C,kBAAkB,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;KAC5C;CACF"}

package/dist/repository/TreeRepository.d.ts

@@ -0,0 +1,56 @@
+import { EntityType, Repository, RxDB } from '@aiao/rxdb';
+import { Observable } from 'rxjs';
+import { ITreeEntity } from '../entity/tree-entity.interface.js';
+import { FindTreeOptions, ITreeRepository } from './tree-repository.interface.js';
+/**
+ * 树结构实体仓库
+ * 根据配置决策实体的具体操作
+ *
+ * @template T - 必须是实现 ITreeEntity 接口的实体类型（通常继承 TreeAdjacencyListEntityBase）
+ *
+ * @example
+ * ```typescript
+ * // ✅ 正确：继承 TreeAdjacencyListEntityBase
+ * // 不必写 repository：`repository: 'TreeRepository'` 与 `features.tree` 都由基类声明，
+ * // 沿原型链继承下来（要覆盖就在自己的 @Entity 里显式声明）
+ * @Entity({ name: 'Category' })
+ * class Category extends TreeAdjacencyListEntityBase {
+ *   name!: string;
+ * }
+ *
+ * // 可以使用树查询方法
+ * Category.findDescendants({ entityId: 'root-id' });
+ * Category.findAncestors({ entityId: 'leaf-id' });
+ *
+ * // ❌ 错误：只继承 EntityBase，没有实现 ITreeEntity
+ * @Entity({ name: 'User' })
+ * class User extends EntityBase {
+ *   name!: string;
+ * }
+ *
+ * // 编译错误：User 不满足 TreeRepository 的类型约束
+ * // User.findDescendants({ entityId: 'id' }); // TypeScript 错误
+ * ```
+ */
+export declare class TreeRepository<T extends EntityType & (new (...args: never[]) => ITreeEntity), RepositoryType extends ITreeRepository<T> = ITreeRepository<T>> extends Repository<T, RepositoryType> {
+    #private;
+    protected static _STATIC_METHODS: string[];
+    constructor(rxdb: RxDB, EntityType: T);
+    /**
+     * 查询子孙
+     */
+    findDescendants(options: FindTreeOptions<T>): Observable<InstanceType<T>[]>;
+    /**
+     * 查询子孙数量
+     */
+    countDescendants(options: FindTreeOptions<T>): Observable<number>;
+    /**
+     * 查询祖先
+     */
+    findAncestors(options: FindTreeOptions<T>): Observable<InstanceType<T>[]>;
+    /**
+     * 查询祖先数量
+     */
+    countAncestors(options: FindTreeOptions<T>): Observable<number>;
+}
+//# sourceMappingURL=TreeRepository.d.ts.map

package/dist/repository/TreeRepository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeRepository.d.ts","sourceRoot":"","sources":["../../src/repository/TreeRepository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAqD,UAAU,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC7G,OAAO,EAAE,UAAU,EAAkB,MAAM,MAAM,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAKjE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,qBAAa,cAAc,CACzB,CAAC,SAAS,UAAU,GAAG,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,WAAW,CAAC,EAC9D,cAAc,SAAS,eAAe,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAC9D,SAAQ,UAAU,CAAC,CAAC,EAAE,cAAc,CAAC;;IAGrC,iBAA0B,eAAe,WAAuD;gBAEpF,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAYrC;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAc3E;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;IAUjE;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAczE;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;CAqBhE"}

package/dist/repository/tree-level.utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 校验树查询深度，未提供时保留不限深度的语义。
+ *
+ * @param level - 查询深度
+ * @returns 非负安全整数；未提供时返回 `undefined`
+ * @throws 当深度不是非负安全整数时抛出 `RxDBError`
+ */
+export declare const assertTreeLevel: (level: number | undefined) => number | undefined;
+//# sourceMappingURL=tree-level.utils.d.ts.map

package/dist/repository/tree-level.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-level.utils.d.ts","sourceRoot":"","sources":["../../src/repository/tree-level.utils.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,MAAM,GAAG,SAIlE,CAAC"}

package/dist/repository/tree-repository.interface.d.ts

@@ -0,0 +1,70 @@
+import { EntityStaticType, EntityType, IRepository, RuleGroup } from '@aiao/rxdb';
+/**
+ * 树结构查询配置
+ */
+export interface FindTreeOptions<T extends EntityType = EntityType, WhereType = RuleGroup<InstanceType<T>>> {
+    /**
+     * 查询的根实体 ID
+     */
+    entityId?: EntityStaticType<T, 'idType'> | null;
+    /**
+     * 查询条件
+     */
+    where?: WhereType;
+    /**
+     * 查询深度（层级数包含当前节点本身）
+     *
+     * - 不传：**不限深度** —— `findDescendants` 返回整棵子树、`findAncestors` 返回整条祖先链
+     * - `0`：仅当前节点（`entityId` 为空时即所有根节点）
+     * - `1`：当前节点 + 直接子节点
+     * - `n`：查询到第 n 层深度
+     *
+     * @defaultValue `undefined`（不限深度）
+     *
+     * @remarks
+     * 不裁剪、不兜底：非负整数以外的值（负数、小数、`NaN`、字符串）一律抛 `RxDBError`。
+     * `level` 是树查询里唯一被直接插值进递归 CTE 比较式的选项，悄悄改写它等于把注入
+     * 变成一次静默的错误查询。插件的 `assertTreeLevel` 与各适配器复用核心的通用数值校验，
+     * 绕过 Repository 直接调适配器时同样抛错。
+     *
+     * 不传时递归深度由各 SQL 适配器内部的失控保护常量兜底（防脏数据把 `parentId` 连成环），
+     * 那是实现细节而非查询语义：正常树不会触到。
+     */
+    level?: number;
+}
+/**
+ * 树结构仓库接口
+ */
+export interface ITreeRepository<T extends EntityType> extends IRepository<T> {
+    /**
+     * 查询子孙实体
+     *
+     * @remarks
+     * - 指定 entityId 时：包含当前节点 + 子孙节点
+     * - 不指定 entityId 时：返回所有根节点及其子孙
+     */
+    findDescendants(options: FindTreeOptions<T>): Promise<InstanceType<T>[]>;
+    /**
+     * 查询子孙实体数量
+     *
+     * @remarks
+     * - 指定 entityId 时：**不包含当前节点**，只统计后代数量
+     * - 不指定 entityId 时：统计所有根节点及其后代的总数
+     */
+    countDescendants(options: FindTreeOptions<T>): Promise<number>;
+    /**
+     * 查询祖先节点
+     *
+     * @remarks
+     * 指定 entityId 时：包含当前节点 + 祖先节点
+     */
+    findAncestors(options: FindTreeOptions<T>): Promise<InstanceType<T>[]>;
+    /**
+     * 查询祖先节点数量
+     *
+     * @remarks
+     * 指定 entityId 时：**不包含当前节点**，只统计祖先数量
+     */
+    countAncestors(options: FindTreeOptions<T>): Promise<number>;
+}
+//# sourceMappingURL=tree-repository.interface.d.ts.map

package/dist/repository/tree-repository.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-repository.interface.d.ts","sourceRoot":"","sources":["../../src/repository/tree-repository.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAElF;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,EAAE,SAAS,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACxG;;OAEG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,IAAI,CAAC;IAEhD;;OAEG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,UAAU,CAAE,SAAQ,WAAW,CAAC,CAAC,CAAC;IAC3E;;;;;;OAMG;IACH,eAAe,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAEzE;;;;;;OAMG;IACH,gBAAgB,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/D;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAEvE;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9D"}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@aiao/rxdb-plugin-tree",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.28",
+  "description": "Tree entities, hierarchy queries and incremental merge for Aiao RxDB.",
+  "homepage": "https://rxdb.aiao.io/docs/plugins",
+  "bugs": {
+    "url": "https://github.com/aiao-io/rxdb/issues"
+  },
+  "keywords": [
+    "aiao",
+    "rxdb",
+    "tree",
+    "hierarchy",
+    "query",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aiao-io/rxdb.git",
+    "directory": "packages/rxdb-plugin-tree"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./generator": {
+      "@aiao/source": "./src/generator/index.ts",
+      "import": "./dist/generator.js",
+      "types": "./dist/generator/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.spec.*",
+    "!src/**/*.test.*",
+    "!src/**/__tests__/**",
+    "!**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "nx": {
+    "name": "rxdb-plugin-tree",
+    "tags": [
+      "js-lib"
+    ]
+  },
+  "dependencies": {
+    "rxjs": "^7.8.2",
+    "@aiao/rxdb-client-generator": "^0.0.28",
+    "@aiao/utils": "^0.0.28"
+  },
+  "peerDependencies": {
+    "@aiao/rxdb": "^0.0.28"
+  }
 }