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

package/src/query/merge_remove.ts

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview 树查询的 REMOVE 事件合并
+ *
+ * `findDescendants` 要顺着祖先链判定「父节点被删 ⇒ 子节点整棵脱离结果集」，
+ * 这条判定本地就能做，所以走真增量；`count*` 仍只能刷新。
+ */
+import {
+  EntityType,
+  isStaleEntityRemoveEvent,
+  queryNeedRefreshRemove,
+  QueryTask,
+  RefreshMatchRules,
+  RxDBEntityId,
+  RxDBEntityLocalRemovedEventData
+} from '@aiao/rxdb';
+import { TREE_QUERY_TYPES } from '../constants.js';
+import { FindTreeOptions } from '../repository/tree-repository.interface.js';
+import { buildEntityMap, traverseAncestors } from './query-tree.utils.js';
+
+/**
+ * JS 增量更新查询结果
+ */
+const _recalculate = <T extends EntityType>(task: QueryTask<T>, data: RxDBEntityLocalRemovedEventData<T>[]) => {
+  const removed_ids = new Set(data.map(e => e.id));
+
+  switch (task.type) {
+    case 'findDescendants': {
+      const old_result = Array.from(task.resultEntitySet.values());
+      const entities_map = buildEntityMap(old_result, e => e.id);
+
+      // 批级记忆：同一条父链会被所有兄弟节点反复走一遍，逐节点回溯是 O(n·depth)。
+      // `detached_map` 记「这个 id 是否已因自身或祖先被删而脱离结果集」，
+      // 每条链只算一次，整批摊平成 O(n)。
+      const detached_map = new Map<RxDBEntityId, boolean>();
+
+      // 判定不能写成 `ancestor.id && removed_ids.has(...)`：`RxDBEntityId` 允许
+      // `0` / `0n` / `''`，真值判断会把这些合法主键当成"没有 id"跳过，被删节点
+      // 名下的子树就整棵留在结果里。`traverseAncestors` 本身只 yield 已解析到的
+      // 父实体（取不到就 break），所以 `ancestor` 恒非空，无需可选链。
+      const is_detached = (entity: InstanceType<T>): boolean => {
+        const cached = detached_map.get(entity.id);
+        if (cached !== undefined) return cached;
+
+        // `chain` 收集「结论未知」的节点：它们都是断点的后代，共享同一个结论，
+        // 循环结束后统一回填。
+        const chain: RxDBEntityId[] = [entity.id];
+        let detached = removed_ids.has(entity.id);
+
+        if (!detached) {
+          for (const { entity: ancestor } of traverseAncestors(entity, entities_map)) {
+            const known = detached_map.get(ancestor.id);
+            if (known !== undefined) {
+              detached = known;
+              break;
+            }
+            if (removed_ids.has(ancestor.id)) {
+              detached = true;
+              break;
+            }
+            chain.push(ancestor.id);
+          }
+        }
+
+        for (const id of chain) detached_map.set(id, detached);
+        return detached;
+      };
+
+      const filtered = old_result.filter(entity => !is_detached(entity));
+      if (filtered.length === old_result.length) return;
+
+      task.next(filtered, true);
+      break;
+    }
+
+    case 'findAncestors': {
+      const old_result = Array.from(task.resultEntitySet.values());
+      const filtered = old_result.filter(e => !removed_ids.has(e.id));
+      if (filtered.length === old_result.length) return;
+
+      const { entityId } = task.options as FindTreeOptions<T>;
+      if (entityId === null || entityId === undefined) {
+        // 查根节点的祖先：CTE 基准成员是 `parentId IS NULL` 的各个根，递归成员
+        // 往上找不到东西，结果就是这些根本身。彼此无链路关系，删谁摘谁。
+        task.next(filtered, true);
+        break;
+      }
+
+      // 祖先链是一条自 target 向上的单链。适配器的递归成员是
+      // `children.id = c.parentId`，走到被删节点就再也接不上，断点**上方**的祖先
+      // 不会出现在重跑结果里。只把被删的那一个过滤掉会把它们留下（结果比 SQL 多）。
+      // 这里改为从 target 出发、在幸存节点里重建可达链路：target 自己被删则结果为空，
+      // 与基准成员取不到行时 CTE 返回 0 行一致。
+      const survivors = buildEntityMap(filtered, e => e.id);
+      const reachable: InstanceType<T>[] = [];
+      const target = survivors.get(entityId);
+      if (target) {
+        reachable.push(target);
+        for (const { entity: ancestor } of traverseAncestors(target, survivors)) {
+          reachable.push(ancestor);
+        }
+      }
+      task.next(reachable, true);
+      break;
+    }
+
+    case 'countDescendants':
+    case 'countAncestors':
+      // count 查询无法 JS 增量更新，由上层触发 SQL 刷新
+      break;
+  }
+};
+
+/**
+ * 处理树查询 REMOVE 事件的缓存合并
+ *
+ * @param task 查询任务
+ * @param entities 删除的实体事件数据
+ */
+export const merge_remove = <T extends EntityType>(
+  task: QueryTask<T>,
+  entities: RxDBEntityLocalRemovedEventData<T>[]
+) => {
+  if (!TREE_QUERY_TYPES.has(task.type)) return;
+
+  // 与 merge_create / merge_update 的同款守卫：首个权威结果落地前不做增量。
+  // runner 的快照可能取自删除提交之前，静默丢弃会让这行死数据永远留在活查询里。
+  if (task.result === undefined) {
+    task.refresh();
+    return;
+  }
+
+  // 旧删除事件不能撤掉比它新的缓存实体（例如 undo/redo 用同一 id 重建实体后又被更新，
+  // 姗姗来迟的过期 DELETE 才追上）。逐条过滤而非整批回退：DELETE 在 _recalculate 里
+  // 按 id 独立处理，不存在跨实体 patch 合并的正确性风险。
+  const freshEntities = entities.filter(event => !isStaleEntityRemoveEvent(task.rxdb, event));
+  if (freshEntities.length === 0) return;
+
+  const refresh_rules: RefreshMatchRules = [];
+  const recalculate_rules: RefreshMatchRules = [];
+
+  switch (task.type) {
+    case 'findAncestors':
+      recalculate_rules.push(['result_contains']);
+      refresh_rules.push(['match_relation_where']);
+      break;
+
+    case 'findDescendants':
+      recalculate_rules.push(['result_contains'], ['match_where']);
+      refresh_rules.push(['match_relation_where']);
+      break;
+
+    case 'countDescendants':
+    case 'countAncestors':
+      refresh_rules.push(['match_where'], ['match_relation_where']);
+      break;
+  }
+
+  const result = queryNeedRefreshRemove(task, freshEntities, refresh_rules, recalculate_rules);
+  if (result.refresh) {
+    task.refresh();
+  } else if (result.recalculate) {
+    _recalculate(task, result.current_entities);
+  }
+};

package/src/query/merge_update.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview 树查询的 UPDATE 事件合并
+ *
+ * 四个任务类型全部走真增量：`parentId` 变更导致的树重组、where 命中翻转、字段值变化，
+ * 都由 {@link handleFindDescendantsUpdate} 等四个处理器在本地算清。
+ * 增量所需的判定原语（分类、外部更新落盘、过期事件）取自核心公开面，不复刻。
+ */
+import {
+  EntityType,
+  prepareIncrementalUpdate,
+  queryNeedRefreshUpdate,
+  QueryTask,
+  RefreshMatchRules,
+  RxDBEntityLocalUpdatedEventData
+} from '@aiao/rxdb';
+import { TREE_QUERY_TYPES } from '../constants.js';
+import {
+  handleCountAncestorsUpdate,
+  handleCountDescendantsUpdate,
+  handleFindAncestorsUpdate,
+  handleFindDescendantsUpdate
+} from './merge-update-tree.js';
+import { hasTreeParentChanged } from './query-tree.utils.js';
+
+/**
+ * 重新计算查询结果（JS 增量更新）
+ */
+const _recalculate = <T extends EntityType>(task: QueryTask<T>, data: RxDBEntityLocalUpdatedEventData<T>[]) => {
+  const { cache, classification } = prepareIncrementalUpdate(task, data);
+
+  switch (task.type) {
+    case 'findDescendants':
+      handleFindDescendantsUpdate(task, data, classification, cache);
+      break;
+
+    case 'findAncestors':
+      handleFindAncestorsUpdate(task, data, classification, cache);
+      break;
+
+    case 'countDescendants':
+      handleCountDescendantsUpdate(task, data, classification, cache);
+      break;
+
+    case 'countAncestors':
+      handleCountAncestorsUpdate(task, data, classification, cache);
+      break;
+  }
+};
+
+/**
+ * 处理树查询 UPDATE 事件的缓存合并
+ *
+ * @param task 查询任务
+ * @param entities 更新的实体事件数据
+ */
+export const merge_update = <T extends EntityType>(
+  task: QueryTask<T>,
+  entities: RxDBEntityLocalUpdatedEventData<T>[]
+) => {
+  if (!TREE_QUERY_TYPES.has(task.type)) return;
+
+  // 与 merge_create 的同款守卫：首个权威结果尚未落地时不做增量——此刻 resultEntitySet
+  // 还是空的，增量合并会把事件负载当成完整结果发射。交给 `refresh()` 而不是直接 `return`：
+  // runner 的快照可能取自更新提交之前，直接丢弃会让这次更新在活查询里永远缺席。
+  if (task.result === undefined) {
+    task.refresh();
+    return;
+  }
+
+  // `findAncestors` 的结果就是一条祖先链。链上任一节点改父，整条链都要重算，
+  // 而新链上方那些节点从未进过结果集、也不在本批事件里，本地只能摘不能补。
+  //
+  // 这一层必须放在 `queryNeedRefreshUpdate` 之前：链上某个**不匹配 where**、
+  // 因而不在结果集里的中间节点改父，同样会让它上方匹配 where 的祖先整体进出结果，
+  // 但它既不满足 `result_contains` 也不满足 `match_where`，连 recalculate 的门都进不来。
+  // {@link handleFindAncestorsUpdate} 开头按同一条规则（同一个 `hasTreeParentChanged`）
+  // 再判一次，是为了让处理器脱离本调用方也成立，不是兜底：两处判的是同一条规则。
+  if (task.type === 'findAncestors' && entities.some(hasTreeParentChanged)) {
+    task.refresh();
+    return;
+  }
+
+  const refresh_rules: RefreshMatchRules = [];
+  const recalculate_rules: RefreshMatchRules = [];
+
+  switch (task.type) {
+    case 'findDescendants':
+      // 处理 parentId 变化导致的树形结构重组
+      // result_contains: 更新的实体在当前结果中
+      // match_where: 更新后匹配条件的实体
+      // match_where_before: 更新前匹配条件的实体
+      // not_match_relation_where: 关系实体没有变更时才能使用 JS 更新
+      recalculate_rules.push(
+        ['result_contains', 'not_match_relation_where'],
+        ['match_where', 'not_match_relation_where'],
+        ['match_where_before', 'not_match_relation_where']
+      );
+      refresh_rules.push(['match_relation_where']);
+      break;
+
+    case 'findAncestors':
+      // result_contains: 更新的实体在当前结果中
+      // match_where: 更新后匹配条件的实体
+      // not_match_relation_where: 关系实体没有变更时才能使用 JS 更新
+      recalculate_rules.push(
+        ['result_contains', 'not_match_relation_where'],
+        ['match_where', 'not_match_relation_where']
+      );
+      refresh_rules.push(['match_relation_where']);
+      break;
+
+    case 'countDescendants':
+    case 'countAncestors':
+      // match_where: 更新后匹配条件的实体
+      // match_where_before: 更新前匹配条件的实体
+      // not_match_relation_where: 关系实体没有变更时才能使用 JS 更新
+      recalculate_rules.push(
+        ['match_where', 'not_match_relation_where'],
+        ['match_where_before', 'not_match_relation_where']
+      );
+      refresh_rules.push(['match_relation_where']);
+      break;
+  }
+
+  const result = queryNeedRefreshUpdate(task, entities, refresh_rules, recalculate_rules);
+
+  if (result.refresh) {
+    task.refresh();
+  } else if (result.recalculate) {
+    _recalculate(task, entities);
+  }
+};

package/src/query/query-tree.utils.ts

@@ -0,0 +1,204 @@
+/**
+ * 树形遍历配置
+ */
+interface TreeTraversalOptions {
+  maxLevel?: number; // 最大层级限制
+  maxDepth?: number; // 最大跳数；不传则不限（环由 visited 兜住）
+}
+
+/**
+ * 获取实体的父级 ID
+ * 处理 parentId 可能是对象或字符串的情况
+ */
+export const get_tree_parent_id = <ID = string>(entity: object | null | undefined): ID | null => {
+  if (!entity) return null;
+  return (Reflect.get(entity, 'parentId') as ID | null | undefined) ?? 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 const hasTreeParentChanged = (event: { patch: object; inversePatch: object }): boolean =>
+  'parentId' in event.patch && get_tree_parent_id(event.patch) !== get_tree_parent_id(event.inversePatch);
+
+/**
+ * 向上遍历父级链路
+ *
+ * @param entity 起始实体
+ * @param entitiesMap 实体 ID 映射表
+ * @param options 遍历配置
+ * @yields 每一层的父级实体和层级
+ */
+export function* traverseAncestors<T extends object, ID>(
+  entity: T,
+  entitiesMap: Map<ID, T>,
+  options: TreeTraversalOptions = {}
+): Generator<{ entity: T; level: number }> {
+  const { maxLevel, maxDepth } = options;
+  const visited = new Set<ID>();
+  let currentParentId = get_tree_parent_id<ID>(entity);
+  let level = 1;
+
+  while (
+    currentParentId !== null &&
+    !visited.has(currentParentId) &&
+    (maxDepth === undefined || visited.size < maxDepth)
+  ) {
+    visited.add(currentParentId);
+
+    const parent = entitiesMap.get(currentParentId);
+    if (!parent) break;
+
+    // 检查层级限制
+    if (maxLevel !== undefined && level > maxLevel) break;
+
+    yield { entity: parent, level };
+
+    currentParentId = get_tree_parent_id<ID>(parent);
+    level++;
+  }
+}
+
+/**
+ * 检查实体是否是目标实体的后代
+ *
+ * @param entity 要检查的实体
+ * @param targetId 目标实体 ID (为 null 或 undefined 时表示查找根节点)
+ * @param entitiesMap 实体 ID 映射表
+ * @param maxLevel 最大层级 (undefined 表示无限制)
+ * @returns 如果是后代则返回 true
+ */
+export function isDescendantOf<T extends object, ID>(
+  entity: T,
+  targetId: ID | null | undefined,
+  entitiesMap: Map<ID, T>,
+  maxLevel?: number
+): boolean {
+  // 特殊情况: targetId 为 null 或 undefined 时,计算节点相对根节点的层级
+  if (targetId === null || targetId === undefined) {
+    const visited = new Set<ID>();
+    let currentEntity = entity;
+    let level = 0;
+
+    while (maxLevel === undefined || level <= maxLevel) {
+      const currentParentId = get_tree_parent_id<ID>(currentEntity);
+      if (currentParentId === null) return true;
+      if (visited.has(currentParentId)) return false;
+
+      visited.add(currentParentId);
+      const parent = entitiesMap.get(currentParentId);
+      if (!parent) return false;
+
+      currentEntity = parent;
+      level++;
+    }
+
+    return false;
+  }
+
+  // 向上遍历父级链路
+  const visited = new Set<ID>();
+  let currentParentId = get_tree_parent_id<ID>(entity);
+  let level = 1;
+
+  while (currentParentId !== null && !visited.has(currentParentId)) {
+    // 找到目标实体
+    if (currentParentId === targetId) {
+      // 检查层级限制
+      if (maxLevel === undefined || level <= maxLevel) {
+        return true;
+      }
+      return false;
+    }
+
+    visited.add(currentParentId);
+    level++;
+
+    // 从映射表中获取父实体以继续遍历
+    const parent = entitiesMap.get(currentParentId);
+    if (parent) {
+      currentParentId = get_tree_parent_id<ID>(parent);
+    } else {
+      break; // 找不到父实体，中断遍历
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 检查实体是否是目标实体的祖先
+ *
+ * @param candidateEntity 候选祖先实体
+ * @param targetId 目标实体 ID (为 null 或 undefined 时直接返回 false，无 isDescendantOf 那种"查找根节点"语义)
+ * @param entitiesMap 实体 ID 映射表
+ * @param maxLevel 最大层级
+ * @returns 如果是祖先则返回 true
+ */
+export function isAncestorOf<T extends object, ID>(
+  candidateEntity: T,
+  targetId: ID | null | undefined,
+  entitiesMap: Map<ID, T>,
+  maxLevel?: number
+): boolean {
+  if (targetId === null || targetId === undefined) return false;
+  const targetEntity = entitiesMap.get(targetId);
+  if (!targetEntity) return false;
+  for (const { entity: parent } of traverseAncestors(targetEntity, entitiesMap, { maxLevel })) {
+    if (Reflect.get(parent, 'id') === Reflect.get(candidateEntity, 'id')) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 顺序串联多个可迭代源，不物化中间数组
+ *
+ * @param sources 按顺序遍历的可迭代源
+ * @yields 各源中的元素，顺序与传入顺序一致
+ *
+ * @remarks
+ * 专为 {@link buildEntityMap} 的「旧结果 `Set` + 本批事件数组」场景而设：
+ * `Array.from(set)` 再展开拼接会把旧结果集整体物化两遍，只为建一张查找表。
+ */
+export function* concatIterables<T>(...sources: Iterable<T>[]): Generator<T> {
+  for (const source of sources) {
+    yield* source;
+  }
+}
+
+/**
+ * 构建实体 ID 映射表（优化查找性能）
+ *
+ * @param entities 实体来源；接受任意可迭代对象（数组、`Set`、{@link concatIterables} 的产物）
+ * @param getIdFn 获取实体 ID 的函数
+ * @returns 实体 ID 到实体的映射表
+ */
+export function buildEntityMap<T, ID>(
+  entities: Iterable<T>,
+  getIdFn: (entity: T) => ID | null | undefined
+): Map<ID, T> {
+  const map = new Map<ID, T>();
+  for (const entity of entities) {
+    const id = getIdFn(entity);
+    if (id !== null && id !== undefined) map.set(id, entity);
+  }
+  return map;
+}