@aiao/rxdb-plugin-history 0.0.0-stage → 0.0.26

package/src/find-switch-branch-step.ts

@@ -0,0 +1,277 @@
+import { RxDBBranch, RxDBError } from '@aiao/rxdb';
+/**
+ * 分支切换步骤
+ */
+export interface SwitchBranchStep {
+  /**
+   * 分支对象
+   */
+  branch: RxDBBranch;
+  /**
+   * 开始变更 ID
+   */
+  fromChangeId: number;
+
+  /**
+   * 目标变更 ID
+   */
+  toChangeId: number;
+}
+
+/**
+ * 查找分支切换路径的参数
+ */
+export interface FindBranchPathOptions {
+  /**
+   * 所需分支列表
+   */
+  branches: RxDBBranch[];
+
+  /**
+   * 当前分支
+   */
+  currentBranch: RxDBBranch;
+
+  /**
+   * 当前分支的变更 ID
+   */
+  currentChangeId: number | null;
+
+  /**
+   * 目标分支
+   */
+  nextBranch: RxDBBranch;
+
+  /**
+   * 目标分支的变更 ID
+   */
+  nextChangeId: number | null;
+}
+
+/**
+ * 计算出树的两个节点之间的切换路径
+ * 规则如下:
+ *  1, 如果两个树节点有共同的祖先节点,则路径为从当前节点到共同祖先节点,再到目标节点
+ *  2, 如果没有共同祖先节点,则路径为从当前节点到根节点,再到目标节点
+ *  3, 需要计算出路径内每个节点需要变更过程，也就是 fromChangeId -> toChangeId
+ *  4, 由于 changeId 在不同分支的变化都是是递增的, 所以如果逆向还原数据那么 fromChangeId 会大于 toChangeId, 正向应用数据则相反
+ */
+/**
+ * 读取分支的分叉点变更 id。
+ *
+ * `fromChangeId === null` 的含义是**分叉于根**（这条分支不是从某条变更上长出来的）。
+ * 变更 id 从 1 开始递增，所以用 0 表示「根」既不会和任何真实变更撞上，又能让它
+ * 直接参与后面的区间运算。
+ *
+ * 抽成具名函数是为了让这个约定只存在一处：从前它以 `branch.fromChangeId ?? 0` 的形式
+ * 在本文件出现十余次，读的人无法判断哪一处是「表达根」、哪一处只是随手兜底。
+ *
+ * @param branch - 分支行
+ * @returns 分叉点变更 id，分叉于根时为 0
+ */
+const forkPointOf = (branch: RxDBBranch): number => branch.fromChangeId ?? 0;
+
+export const find_switch_branch_step = (options: FindBranchPathOptions): SwitchBranchStep[] => {
+  const { branches, currentBranch, nextBranch } = options;
+
+  // 如果分支没有自己的变更记录，使用 fromChangeId 作为当前状态
+  // 否则使用该分支的最大 changeId
+  const currentChangeId = options.currentChangeId ?? forkPointOf(currentBranch);
+  const nextChangeId = options.nextChangeId ?? forkPointOf(nextBranch);
+
+  // 任意分支只要变更 id 相同，都无需切换数据
+  if (currentChangeId === nextChangeId) {
+    return [];
+  }
+
+  // 如果是同一个分支但变更 id 不同，直接在当前分支上移动
+  if (currentBranch.id === nextBranch.id) {
+    return [
+      {
+        branch: currentBranch,
+        fromChangeId: currentChangeId,
+        toChangeId: nextChangeId
+      }
+    ];
+  }
+
+  // 构建分支映射表
+  const branchMap = new Map<string, RxDBBranch>();
+  for (const branch of branches) {
+    branchMap.set(branch.id, branch);
+  }
+
+  // 获取从某个分支到根的路径
+  //
+  // 断链（parentId 指不到分支）与成环都是**持久化完整性错误**：调用方传进来的 `branches`
+  // 是全量无过滤查询的结果，不存在「父分支被过滤掉了」这种正常情况。
+  // 曾经这两种情况都是 `break` —— 相当于把坏数据当成「已经到根」，继续算出一条通往
+  // 并不存在的根的完整 action 序列，调用方照单全收地写库，半条路径被应用而没有任何报错。
+  // 切分支失败远好过静默切错，因此这里必须终止且不产生任何 action。
+  const getPathToRoot = (branch: RxDBBranch): RxDBBranch[] => {
+    const path: RxDBBranch[] = [branch];
+    const visited = new Set<string>([branch.id]);
+    let current = branch;
+    while (current.parentId) {
+      if (visited.has(current.parentId)) {
+        throw new RxDBError(
+          `Branch history is corrupt: cycle detected at branch '${current.id}' (parentId '${current.parentId}' already visited)`
+        );
+      }
+      const parent = branchMap.get(current.parentId);
+      if (!parent) {
+        throw new RxDBError(
+          `Branch history is corrupt: branch '${current.id}' references missing parent '${current.parentId}'`
+        );
+      }
+      visited.add(parent.id);
+      path.push(parent);
+      current = parent;
+    }
+    return path;
+  };
+
+  // 获取当前分支和目标分支到根的路径
+  const currentPath = getPathToRoot(currentBranch);
+  const nextPath = getPathToRoot(nextBranch);
+
+  // 找到最近的共同祖先
+  let commonAncestor: RxDBBranch | null = null;
+  let commonAncestorIndex = -1;
+
+  for (let i = 0; i < currentPath.length; i++) {
+    const idx = nextPath.findIndex(b => b.id === currentPath[i].id);
+    if (idx !== -1) {
+      commonAncestor = currentPath[i];
+      commonAncestorIndex = i;
+      break;
+    }
+  }
+
+  const steps: SwitchBranchStep[] = [];
+
+  if (commonAncestor) {
+    // 从当前分支回退到共同祖先
+    for (let i = 0; i < commonAncestorIndex; i++) {
+      const branch = currentPath[i];
+      const fromId = i === 0 ? currentChangeId : forkPointOf(currentPath[i - 1]);
+      const toId = forkPointOf(branch);
+
+      // 只有当需要实际变更时才添加步骤
+      if (fromId !== toId) {
+        steps.push({
+          branch,
+          fromChangeId: fromId,
+          toChangeId: toId
+        });
+      }
+    }
+
+    // 在共同祖先上可能也需要移动
+    const ancestorIndexInNext = nextPath.findIndex(b => b.id === commonAncestor!.id);
+
+    if (ancestorIndexInNext === 0) {
+      // 共同祖先就是目标分支，需要移动到目标 changeId
+      const ancestorFromId =
+        commonAncestorIndex === 0 ? currentChangeId : forkPointOf(currentPath[commonAncestorIndex - 1]);
+      const ancestorToId = nextChangeId;
+
+      if (ancestorFromId !== ancestorToId) {
+        steps.push({
+          branch: commonAncestor,
+          fromChangeId: ancestorFromId,
+          toChangeId: ancestorToId
+        });
+      }
+    } else if (ancestorIndexInNext > 0) {
+      // 需要从当前位置移动到目标分支的 fromChangeId
+      const ancestorFromId =
+        commonAncestorIndex === 0 ? currentChangeId : forkPointOf(currentPath[commonAncestorIndex - 1]);
+      const ancestorToId = forkPointOf(nextPath[ancestorIndexInNext - 1]);
+
+      if (ancestorFromId !== ancestorToId) {
+        steps.push({
+          branch: commonAncestor,
+          fromChangeId: ancestorFromId,
+          toChangeId: ancestorToId
+        });
+      }
+    }
+
+    // 从共同祖先前进到目标分支
+    const forwardPath = nextPath.slice(0, ancestorIndexInNext).reverse();
+
+    for (let i = 0; i < forwardPath.length; i++) {
+      const branch = forwardPath[i];
+      const fromId = forkPointOf(branch);
+      const toId = i === forwardPath.length - 1 ? nextChangeId : forkPointOf(forwardPath[i + 1]);
+
+      // 只有当需要实际变更时才添加步骤
+      if (fromId !== toId) {
+        steps.push({
+          branch,
+          fromChangeId: fromId,
+          toChangeId: toId
+        });
+      }
+    }
+  } else {
+    // 没有共同祖先，回退到当前分支的根，然后前进到目标分支
+    // 1. 回退当前分支的所有节点到根
+    for (let i = 0; i < currentPath.length; i++) {
+      const branch = currentPath[i];
+      const fromId = i === 0 ? currentChangeId : forkPointOf(currentPath[i - 1]);
+      const toId = forkPointOf(branch);
+
+      if (fromId !== toId) {
+        steps.push({
+          branch,
+          fromChangeId: fromId,
+          toChangeId: toId
+        });
+      }
+    }
+
+    // 2. 将当前树的根节点回退到 0
+    const currentRoot = currentPath[currentPath.length - 1];
+    const currentRootFromId = forkPointOf(currentRoot);
+
+    if (currentRootFromId !== 0) {
+      steps.push({
+        branch: currentRoot,
+        fromChangeId: currentRootFromId,
+        toChangeId: 0
+      });
+    }
+
+    // 3. 从目标树的根节点开始前进到目标分支
+    const nextRoot = nextPath[nextPath.length - 1];
+    const nextRootTargetId = nextPath.length > 1 ? forkPointOf(nextPath[nextPath.length - 2]) : nextChangeId;
+
+    if (nextRootTargetId !== 0) {
+      steps.push({
+        branch: nextRoot,
+        fromChangeId: 0,
+        toChangeId: nextRootTargetId
+      });
+    }
+
+    // 4. 前进目标树的所有子节点
+    const forwardPath = nextPath.slice(0, nextPath.length - 1).reverse();
+    for (let i = 0; i < forwardPath.length; i++) {
+      const branch = forwardPath[i];
+      const fromId = forkPointOf(branch);
+      const toId = i === forwardPath.length - 1 ? nextChangeId : forkPointOf(forwardPath[i + 1]);
+
+      if (fromId !== toId) {
+        steps.push({
+          branch,
+          fromChangeId: fromId,
+          toChangeId: toId
+        });
+      }
+    }
+  }
+
+  return steps;
+};

package/src/history-filters.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview 历史记录过滤与作用域键的纯函数集合
+ *
+ * 这些函数不持有任何状态，供 {@link HistoryManager} 与单元测试共用：
+ * - {@link filterHistoriesByScope}：按作用域裁切历史
+ * - {@link buildLastPushedMap}：合成每个仓库的「视同已推」水位线
+ * - {@link filterUndoableHistories}：过滤可撤销的历史
+ * - {@link getScopeKey}：生成作用域缓存键
+ *
+ * @module rxdb/version/history-filters
+ */
+
+import { getRxDBEntityIdentityKey, type HistoryItem, type HistoryScope } from '@aiao/rxdb';
+import { generateHistoryDescription } from './history-item-builder.js';
+/**
+ * 生成 repository 的缓存键（纯函数）
+ *
+ * @param repository - 带 namespace / entity 的仓储标识
+ * @returns 'namespace:entity' 形式的缓存键
+ *
+ * @internal 供 HistoryManager 与同文件的过滤函数使用
+ */
+export const getRepositoryKey = (repository: { namespace: string; entity: string }): string =>
+  `${repository.namespace}:${repository.entity}`;
+
+/**
+ * 合成「每个仓库推到哪了」的水位线映射：已提交的 `RxDBSync` 水位线与正在飞的认领取较大者。
+ *
+ * @param repoSyncs - 当前分支下的 `RxDBSync` 行
+ * @param inFlight - `PushInFlightRegistry.snapshot()`，`namespace:entity` -> 正在飞的最大 change id
+ * @returns `namespace:entity` -> 该仓库「视同已推」的最大 change id
+ *
+ * @remarks
+ * `undoHistories$` 与 `fetchLatestHistories` 两条路径都要这份映射，此前各写一份循环。
+ * 两份必须逐字一致：一边认在飞、另一边不认，反应式的「可撤销」列表就会和真正执行撤销时
+ * 的判定分家 —— UI 上还亮着的那一项点下去什么也不会发生，或者更糟，真的撤销了一条
+ * 已经在飞的变更。
+ *
+ * 取最大值而不是「有在飞就用在飞」：上一轮推到 30、这一轮只在飞到 20 时，
+ * 水位线不许倒退。
+ *
+ * 在飞认领先进 map，因此**没有** `RxDBSync` 行的仓库也报得出来：`RxDBSync` 行由
+ * `planRepositoryPush` 现建，行还没落到本次查询的结果集里时，认领仍然必须生效。
+ */
+export function buildLastPushedMap(
+  repoSyncs: readonly { namespace: string; entity: string; lastPushedChangeId: number | null }[],
+  inFlight: ReadonlyMap<string, number>
+): Map<string, number> {
+  const lastPushedMap = new Map(inFlight);
+
+  for (const repoSync of repoSyncs) {
+    if (repoSync.lastPushedChangeId === null) continue;
+    const key = getRepositoryKey(repoSync);
+    const claimed = lastPushedMap.get(key);
+    if (claimed !== undefined && claimed >= repoSync.lastPushedChangeId) continue;
+    lastPushedMap.set(key, repoSync.lastPushedChangeId);
+  }
+
+  return lastPushedMap;
+}
+
+/**
+ * 按作用域过滤历史记录（纯函数）
+ *
+ * @param histories - 原始历史记录数组
+ * @param scope - 作用域配置
+ * @returns 过滤后的历史记录数组
+ *
+ * @internal 供 HistoryManager 和单元测试使用
+ */
+export function filterHistoriesByScope(histories: HistoryItem[], scope: HistoryScope): HistoryItem[] {
+  if (scope.type === 'database') {
+    return histories;
+  }
+
+  return histories
+    .map(history => {
+      const filtered_changes = history.changes.filter(change => {
+        if (scope.type === 'repository') {
+          return change.namespace === scope.namespace && change.entity === scope.entity;
+        }
+        // 实体作用域
+        return (
+          change.namespace === scope.namespace && change.entity === scope.entity && change.entityId === scope.entityId
+        );
+      });
+
+      if (filtered_changes.length === 0) return null;
+
+      return {
+        ...history,
+        changes: filtered_changes,
+        count: filtered_changes.length,
+        description: generateHistoryDescription(filtered_changes)
+      };
+    })
+    .filter((h): h is HistoryItem => h !== null);
+}
+
+/**
+ * 过滤出可撤销的历史记录（纯函数）
+ *
+ * @param histories - 原始历史记录数组
+ * @param lastPushedMap - namespace:entity -> lastPushedChangeId 的 repository 级水位线映射
+ * @param undoBoundaryChangeId - 同步清空后的永久撤销边界
+ * @param undoBoundaryCreatedAfter - 无数字 change id 时使用的严格时间边界
+ * @returns 可撤销的历史记录数组
+ *
+ * @remarks
+ * undoHistories$（UI 展示）与 undo()（实际执行）共用同一套规则，
+ * 保证 UI 上看不到的历史不会被 undo() 撤销：
+ * 1. history.reverted == false（按 updatedAt 水位合并持久态与本地态，未被撤销）
+ * 2. remoteId == null（只有本地创建的变更才能撤销）
+ * 3. id > 该 repository 的 lastPushedChangeId（未推送到远程；按 repository 独立判断）
+ * 4. id > undoBoundaryChangeId（同步清空前的历史永久不可撤销）
+ * 5. createdAt > undoBoundaryCreatedAfter（无数字 id 时保守隔离旧 session）
+ *
+ * @internal 供 HistoryManager 和单元测试使用
+ */
+export function filterUndoableHistories(
+  histories: HistoryItem[],
+  lastPushedMap: Map<string, number>,
+  undoBoundaryChangeId = 0,
+  undoBoundaryCreatedAfter: Date | null = null
+): HistoryItem[] {
+  return histories.filter(history => {
+    if (history.reverted) return false;
+
+    return history.changes.every(change => {
+      const isLocal = change.remoteId == null;
+      const lastPushedId = lastPushedMap.get(getRepositoryKey(change));
+      const notPushed = lastPushedId == null || change.id > lastPushedId;
+      const afterUndoBoundary = change.id > undoBoundaryChangeId;
+      const afterUndoTimeBoundary =
+        undoBoundaryCreatedAfter === null || change.createdAt.getTime() > undoBoundaryCreatedAfter.getTime();
+      return isLocal && notPushed && afterUndoBoundary && afterUndoTimeBoundary;
+    });
+  });
+}
+
+/**
+ * 生成作用域缓存键（纯函数）
+ *
+ * @param scope - 作用域配置
+ * @returns 缓存键字符串：'database' | 'namespace:entity' | 'namespace:entity:id'
+ *
+ * @internal 供 HistoryManager 和单元测试使用
+ */
+export function getScopeKey(scope: HistoryScope): string {
+  if (scope.type === 'database') {
+    return 'database';
+  }
+  if (scope.type === 'repository') {
+    return `${scope.namespace}:${scope.entity}`;
+  }
+  return `${scope.namespace}:${scope.entity}:${getRxDBEntityIdentityKey(scope.entityId)}`;
+}

package/src/history-item-builder.ts

@@ -0,0 +1,101 @@
+import { getRxDBEntityIdentityKey, HistoryItem, RxDBChange, UUID } from '@aiao/rxdb';
+import { isNil } from '@aiao/utils';
+/**
+ * 生成历史项的描述文本
+ *
+ * 规则：
+ * - 单条 INSERT/UPDATE/DELETE → 「创建 Foo」「更新 Foo」「删除 Foo」
+ * - 事务（多条变更）→ 「事务: 创建2条, 更新3条」
+ */
+export function generateHistoryDescription(changes: RxDBChange[]): string {
+  if (changes.length === 1) {
+    const change = changes[0];
+    const action =
+      change.type === 'INSERT' ? '创建'
+      : change.type === 'UPDATE' ? '更新'
+      : '删除';
+    return `${action} ${change.entity}`;
+  }
+
+  const operations: Record<string, number> = {};
+  for (const change of changes) {
+    const key = change.type.toLowerCase();
+    operations[key] = (operations[key] ?? 0) + 1;
+  }
+
+  const parts: string[] = [];
+  if (operations['insert']) parts.push(`创建${operations['insert']}条`);
+  if (operations['update']) parts.push(`更新${operations['update']}条`);
+  if (operations['delete']) parts.push(`删除${operations['delete']}条`);
+
+  return `事务: ${parts.join(', ')}`;
+}
+
+/**
+ * 从一组同事务的变更构造单个 HistoryItem
+ *
+ * @param changes - 属于同一事务的变更记录（至少一条）
+ * @returns 结构化的历史项，包含描述、类型、状态等信息
+ */
+export function createHistoryItem(changes: RxDBChange[]): HistoryItem {
+  const first_change = changes[0]!;
+  const count = changes.length;
+  const transactionId = first_change.transactionId ?? null;
+  const createdAt = first_change.createdAt!;
+  const namespace = first_change.namespace;
+  const entity = first_change.entity;
+  const type = transactionId ? 'TRANSACTION' : first_change.type;
+  const fingerprint = [type, getRxDBEntityIdentityKey(first_change.entityId), createdAt.getTime()].join(':');
+  const reverted = changes.some(c => isNil(c.revertChangeId) === false);
+  const redoInvalidated = changes.some(c => isNil(c.redoInvalidatedAt) === false);
+
+  return {
+    transactionId,
+    changeId: changes.reduce((max, c) => (c.id > max ? c.id : max), changes[0].id),
+    fingerprint,
+    changes,
+    type,
+    count,
+    createdAt,
+    description: generateHistoryDescription(changes),
+    namespace,
+    entity,
+    reverted,
+    redoInvalidated
+  };
+}
+
+/**
+ * 把按 id 降序排列的变更列表，转换为按事务分组的 HistoryItem 数组
+ *
+ * 转换逻辑：
+ * - 相同 transactionId 的连续变更合并为一个 HistoryItem
+ * - 无 transactionId 的变更单独成为一个 HistoryItem
+ */
+export function convertChangesToHistories(changes: RxDBChange[]): HistoryItem[] {
+  const histories: HistoryItem[] = [];
+  const next_transaction: RxDBChange[] = [];
+  let _transaction_id: UUID | undefined | null = undefined;
+
+  changes.forEach(d => {
+    if (d.transactionId && d.transactionId === _transaction_id) {
+      next_transaction.push(d);
+    } else {
+      _transaction_id = d.transactionId;
+      if (next_transaction.length) {
+        histories.push(createHistoryItem([...next_transaction]));
+        next_transaction.length = 0;
+      }
+      if (d.transactionId) {
+        next_transaction.push(d);
+      } else {
+        histories.push(createHistoryItem([d]));
+      }
+    }
+  });
+  if (next_transaction.length) {
+    histories.push(createHistoryItem([...next_transaction]));
+  }
+
+  return histories;
+}