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

package/src/switch-branch-actions.ts

@@ -0,0 +1,319 @@
+import {
+  EntityStaticType,
+  getRxDBChangeKey,
+  RxDBBranch,
+  RxDBChange,
+  RxDBError,
+  SwitchVersionActions
+} from '@aiao/rxdb';
+import { find_switch_branch_step } from './find-switch-branch-step.js';
+import { VersionManager } from './VersionManager.js';
+/**
+ * 计算切换分支所需的操作
+ * @param version
+ * @param branchId 要切换到的分支ID
+ * @returns 返回切换分支所需的操作序列
+ */
+export const switch_branch_actions = async (version: VersionManager, branchId: string) =>
+  compute_switch_branch_actions(await version.getLocalRepositories(), branchId);
+
+/**
+ * 算切换分支所需操作要用到的最小仓库能力。
+ *
+ * @remarks
+ * 与 {@link BranchChangeReader} 同一个理由写成结构化接口：本地仓库与事务执行器给出的
+ * `IRepository` 都接得住，两边的 `find` 入参本就是同一个类型。
+ */
+export interface SwitchBranchActionReaders {
+  /** 读分支行 */
+  readonly branchRepository: {
+    /**
+     * 按条件查分支
+     *
+     * @param options - 查询选项
+     * @returns 命中的分支行
+     */
+    find(options: EntityStaticType<typeof RxDBBranch, 'findOptions'>): Promise<RxDBBranch[]>;
+  };
+
+  /** 读变更行；见 {@link BranchChangeReader} */
+  readonly changeRepository: BranchChangeReader;
+}
+
+/**
+ * 用给定的仓库算「从当前 active 分支切到 `branchId`」要落的增删改——
+ * {@link switch_branch_actions} 的本体。
+ *
+ * @param readers - 见 {@link SwitchBranchActionReaders}
+ * @param branchId - 要切换到的分支 id
+ * @returns 切换分支所需的操作序列
+ *
+ * @remarks
+ * 拆出来是给 `@aiao/rxdb-plugin-working-tree` 的物化屏障用的：屏障要先把来源分支的投影撤掉，
+ * 再铺目标分支的快照，而它跑在 `switchBranch` 的 `prepare` 里，手上只有事务执行器的仓库——
+ * 绑在适配器上的本地仓库会在同一条连接上等屏障自己那笔事务，死锁。另写一份同义计算，
+ * 迟早会在「回滚标记算不算」上与普通切换分叉。
+ *
+ * @internal
+ */
+export const compute_switch_branch_actions = async (
+  readers: SwitchBranchActionReaders,
+  branchId: string
+): Promise<SwitchVersionActions> => {
+  const { branchRepository, changeRepository } = readers;
+  const current_branch = (
+    await branchRepository.find({
+      where: {
+        combinator: 'and',
+        rules: [{ field: 'activated', operator: '=', value: true }]
+      },
+      limit: 1
+    })
+  )[0];
+  if (!current_branch) throw new RxDBError('Current branch not found');
+  const all_branches = await branchRepository.find({
+    where: {
+      combinator: 'and',
+      rules: []
+    }
+  });
+  const next_branch = all_branches.find(b => b.id === branchId);
+  if (!next_branch) throw new RxDBError(`Branch (${branchId}) not found`);
+  if (current_branch.id === next_branch.id) {
+    throw new RxDBError('Cannot switch to the same branch');
+  }
+
+  const currentChange = await get_branch_max_change(changeRepository, current_branch.id);
+  const nextChange = await get_branch_max_change(changeRepository, next_branch.id);
+
+  const steps = find_switch_branch_step({
+    branches: all_branches,
+    currentBranch: current_branch,
+    currentChangeId: currentChange ? currentChange.id : null,
+    nextBranch: next_branch,
+    nextChangeId: nextChange ? nextChange.id : null
+  });
+
+  const actions: SwitchVersionActions = {
+    deletes: new Map(),
+    updates: new Map(),
+    inserts: new Map()
+  };
+
+  for (let i = 0; i < steps.length; i++) {
+    const { branch, fromChangeId, toChangeId } = steps[i];
+    const is_patch = fromChangeId < toChangeId;
+    const is_inverse_patch = fromChangeId > toChangeId;
+
+    // 构建查询条件：查询 fromChangeId 和 toChangeId 之间的变更
+    // 注意：区间是开区间 (min, max]，不包含起点但包含终点
+    // 因为起点代表的状态已经存在，只需要应用之后的变更
+    const minId = Math.min(fromChangeId, toChangeId);
+    const maxId = Math.max(fromChangeId, toChangeId);
+
+    const options: EntityStaticType<typeof RxDBChange, 'findAllOptions'> = {
+      where: {
+        combinator: 'and',
+        rules: [
+          { field: 'branchId', operator: '=', value: branch.id },
+          { field: 'id', operator: '>', value: minId },
+          { field: 'id', operator: '<=', value: maxId },
+          { field: 'revertChangeId', operator: '=', value: null }
+        ]
+      }
+    };
+
+    // 对于子分支，需要额外限制：不处理 branch.fromChangeId 及之前的变更
+    // 因为这些变更属于父分支的历史，不属于当前子分支的变更范围
+    // 注意：这个限制对 is_patch 和 is_inverse_patch 都适用
+    if (branch.fromChangeId) {
+      // 已经通过 minId > branch.fromChangeId 限制过了
+      // 所以这里不需要额外处理，minId 已经确保大于 branch.fromChangeId
+      // 但为了代码清晰，明确检查一下
+      if (minId < branch.fromChangeId) {
+        options.where.rules.push({ field: 'id', operator: '>', value: branch.fromChangeId });
+      }
+    }
+    const changes = await changeRepository.find(options);
+    if (is_inverse_patch) {
+      inverse_patch_all(changes, actions);
+    } else if (is_patch) {
+      patch_all(changes, actions);
+    }
+  }
+  return actions;
+};
+
+/**
+ * 应用所有补丁
+ * @param changes 需要计算的 changes
+ * @param actions 现有的操作结果
+ */
+const patch_all = (changes: RxDBChange[], actions?: SwitchVersionActions) =>
+  get_switch_version_actions(changes, true, actions);
+
+/**
+ * 反向应用所有补丁
+ * @param changes 需要计算的 changes
+ * @param actions 现有的操作结果
+ */
+const inverse_patch_all = (changes: RxDBChange[], actions?: SwitchVersionActions) =>
+  get_switch_version_actions(changes, false, actions);
+
+/**
+ * 计算切换版本所需的操作
+ * @param changes 需要计算的 changes
+ * @param options
+ */
+export const get_switch_version_actions = (
+  changes: RxDBChange[],
+  isPatch: boolean,
+  actions: SwitchVersionActions = {
+    deletes: new Map(),
+    updates: new Map(),
+    inserts: new Map()
+  }
+): SwitchVersionActions => {
+  if (isPatch) {
+    const need_changes = [...changes].sort((a, b) => a.id - b.id);
+    for (const change of need_changes) {
+      const changeKey = getRxDBChangeKey(change);
+      switch (change.type) {
+        case 'INSERT':
+          // 浅拷贝：actions 不得持有 change.patch 的引用，否则后续 Object.assign 合并会原地
+          // 改写源 change（可能是 EntityManager 缓存实例），污染缓存
+          actions.inserts.set(changeKey, {
+            patch: { ...change.patch! },
+            inversePatch: null
+          });
+          break;
+        case 'UPDATE':
+          {
+            const existing = actions.inserts.get(changeKey) || actions.updates.get(changeKey);
+            if (existing) {
+              // 合并补丁：正向补丁累加，反向补丁保持最早的
+              if (existing.patch && change.patch) {
+                Object.assign(existing.patch, change.patch);
+              }
+              if (existing.inversePatch === null && change.inversePatch) {
+                existing.inversePatch = { ...change.inversePatch };
+              } else if (existing.inversePatch && change.inversePatch) {
+                Object.assign(existing.inversePatch, change.inversePatch);
+              }
+            } else {
+              actions.updates.set(changeKey, {
+                patch: { ...change.patch! },
+                inversePatch: { ...change.inversePatch! }
+              });
+            }
+          }
+          break;
+        case 'DELETE':
+          actions.deletes.set(changeKey, {
+            patch: null,
+            inversePatch: { ...change.inversePatch! }
+          });
+          actions.inserts.delete(changeKey);
+          actions.updates.delete(changeKey);
+          break;
+      }
+    }
+  } else {
+    const need_changes = [...changes].sort((a, b) => b.id - a.id);
+    for (const change of need_changes) {
+      const changeKey = getRxDBChangeKey(change);
+      switch (change.type) {
+        case 'INSERT':
+          // 浅拷贝的理由同正向分支：actions 不得持有 change 的补丁引用，
+          // 否则后续 Object.assign 合并会原地改写源 change（可能是 EntityManager 缓存实例）
+          actions.deletes.set(changeKey, {
+            patch: null,
+            inversePatch: { ...change.patch! }
+          });
+          actions.inserts.delete(changeKey);
+          actions.updates.delete(changeKey);
+          break;
+        case 'UPDATE':
+          {
+            // 同时查 inserts：逆向按 id 降序处理，撤销 DELETE 会先落一条 inserts，
+            // 紧接着更早的 UPDATE 必须并进那条 inserts。只查 updates 会让同一实体
+            // 同时出现在 inserts 与 updates 两张表里。
+            const existing = actions.inserts.get(changeKey) || actions.updates.get(changeKey);
+            if (existing) {
+              // 反向合并：正向补丁用 inversePatch，反向补丁用 patch
+              if (existing.patch && change.inversePatch) {
+                Object.assign(existing.patch, change.inversePatch);
+              }
+              if (existing.inversePatch && change.patch) {
+                Object.assign(existing.inversePatch, change.patch);
+              }
+            } else {
+              actions.updates.set(changeKey, {
+                patch: { ...change.inversePatch! },
+                inversePatch: { ...change.patch! }
+              });
+            }
+          }
+          break;
+        case 'DELETE':
+          actions.inserts.set(changeKey, {
+            patch: { ...change.inversePatch! },
+            inversePatch: null
+          });
+          break;
+      }
+    }
+  }
+  return actions;
+};
+
+/**
+ * 读一条分支 tip 所需要的最小仓库能力。
+ *
+ * @remarks
+ * 写成结构化的最小接口而不是直接用本地仓库类型，是为了让 {@link get_branch_max_change}
+ * 同时接得住事务执行器给出的 `IRepository<typeof RxDBChange>`——`enable-migration.ts`
+ * 跑在事务里，拿不到本地仓库。两边的 `find` 入参本就是同一个类型
+ * （`RxDBChangeStaticTypes['findOptions']`），所以这不是放宽，只是把已有的共同点写出来。
+ */
+export interface BranchChangeReader {
+  /**
+   * 按条件查变更
+   *
+   * @param options - 查询选项
+   * @returns 命中的变更行
+   */
+  find(options: EntityStaticType<typeof RxDBChange, 'findOptions'>): Promise<RxDBChange[]>;
+}
+
+/**
+ * 读一条分支当前的 tip：它自己那些未被回滚的变更里 id 最大的那条。
+ *
+ * @param changeRepository - 见 {@link BranchChangeReader}
+ * @param branchId - 分支 id
+ * @returns tip 变更行；该分支一条自有变更都没有时为 `undefined`（调用方据此退回分叉点）
+ *
+ * @remarks
+ * 导出是给 `enable-migration.ts` 复用的：「一条分支现在停在哪」这一问必须全局只有一个
+ * 答案（research.md R11）。迁移期另写一条同义查询，迟早会在「回滚标记算不算」
+ * 或「排序列是哪一个」上与切换路径分叉，表现为迁移放行了一条 `switchBranch` 走不通的分支。
+ *
+ * @internal
+ */
+export const get_branch_max_change = async (
+  changeRepository: BranchChangeReader,
+  branchId: string
+): Promise<RxDBChange | undefined> => {
+  const changes = await changeRepository.find({
+    where: {
+      combinator: 'and',
+      rules: [
+        { field: 'branchId', operator: '=', value: branchId },
+        { field: 'revertChangeId', operator: '=', value: null }
+      ]
+    },
+    orderBy: [{ field: 'id', sort: 'desc' }],
+    limit: 1
+  });
+  return changes[0];
+};

package/src/sync-history-bridge.ts

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview 同步插件向历史插件借的那一小块面
+ *
+ * US-025 阶段 D 把推拉同步从 `@aiao/rxdb-plugin-history` 切到
+ * `@aiao/rxdb-plugin-sync` 之后，两边仍有一条**单向**耦合：一次 pull / push 结束时，
+ * undo 边界要作废、待拉计数要结算 —— 这些状态的主人是 {@link HistoryManager}，
+ * 而触发时机只有同步侧知道。
+ *
+ * 因此不把 {@link HistoryManager} 整个交出去，只交这一张接口：
+ *
+ * - 方向是单向的。同步插件 `inject: ['plugin:history']`，历史插件对同步插件一无所知，
+ *   `@aiao/rxdb-plugin-history` 的 `dependencies` 里也不会出现同步包 —— 否则两包互指。
+ * - 面是窄的。八个成员，全部围绕「一次同步往返结束后历史该怎么变」，不透出 undo 栈、
+ *   redo 栈、作用域 API 这些同步侧根本不该碰的东西。
+ * - 结算口径留在历史侧。{@link SyncHistoryBridge.settlePull} 收 `PullOptions` /
+ *   `PullResult` 原件，「这次算不算完整同步」由 `pullable-count.ts` 判定；
+ *   同步侧不复制一份判据，两边也就不会漂。
+ */
+
+import type { PullOptions, PullResult } from '@aiao/rxdb';
+import type { HistoryManager } from './HistoryManager.js';
+import { isCompletePull } from './pullable-count.js';
+import type { PushInFlightRegistry } from './push-inflight.js';
+
+/**
+ * 同步插件可见的历史侧能力。
+ *
+ * @remarks
+ * 由 `VersionManager.syncBridge` 提供，`SyncManager` 在构造时接过去。
+ *
+ * @internal
+ */
+export interface SyncHistoryBridge {
+  /**
+   * 「哪些变更此刻正在飞往远端」的登记处。
+   *
+   * @remarks
+   * push 与 undo 唯一的会合点，主人是 {@link VersionManager} —— undo 侧经
+   * `rxdb.versionManager.pushInFlight` 读它，push 侧经本桥认领区间。
+   * 两边读的必须是同一个实例，见 {@link PushInFlightRegistry}。
+   */
+  readonly pushInFlight: PushInFlightRegistry;
+
+  /**
+   * 在可重入同步上下文中执行：期间产生的本地写入不进 undo/redo 栈。
+   *
+   * @param fn - 同步动作
+   */
+  syncing<T>(fn: () => Promise<T>): Promise<T>;
+
+  /** 与远端合并之后清空当前分支的 undo/redo —— 合并前的内容已经 undo 不回去了 */
+  clearUndoHistory(): void;
+
+  /**
+   * pull 开始前签发结算令牌。
+   *
+   * @returns 令牌，交回 {@link settlePull} / {@link settleAbortedPull} /
+   * {@link reconcilePullableCount}
+   *
+   * @remarks
+   * 必须在真正发起 pull **之前**取：拉取期间到达的远端事件描述的是快照之后的新变更，
+   * 结算时要能看出来，否则「完整同步」的归零会把它们一起吞掉。
+   */
+  beginPullableSettlement(): number;
+
+  /**
+   * 按一次成功 pull 的实际覆盖范围结算待拉计数。
+   *
+   * @param token - {@link beginPullableSettlement} 签发的令牌
+   * @param options - 发起 pull 时的选项
+   * @param result - pull 的结果
+   */
+  settlePull(token: number, options: PullOptions | undefined, result: PullResult): void;
+
+  /**
+   * 按一次抛错 pull 已落库的部分结算待拉计数。
+   *
+   * @param token - {@link beginPullableSettlement} 签发的令牌
+   * @param pulled - 抛错前已经真实落库的条数，一条都没落时传 0
+   *
+   * @remarks
+   * 令牌必须收回，否则代次永远停在旧值，后续结算全被判成「并发」。
+   */
+  settleAbortedPull(token: number, pulled: number): void;
+
+  /**
+   * 用远端水位线校准待拉计数。
+   *
+   * @param token - {@link beginPullableSettlement} 签发的令牌
+   * @param count - 按各仓库持久化水位线算出的待拉总数
+   */
+  reconcilePullableCount(token: number, count: number): void;
+
+  /**
+   * 远端事件到达时累加待拉计数。
+   *
+   * @param count - 本次事件里属于当前激活分支的条数
+   */
+  incrementPullableCount(count: number): void;
+}
+
+/**
+ * 造一座桥。
+ *
+ * @param historyManager - 取当前 {@link HistoryManager} 的闭包
+ * @param pushInFlight - 飞行登记处
+ *
+ * @remarks
+ * 第一个参数是闭包而不是实例：`VersionManager` 在 `init()` 里会重建
+ * {@link HistoryManager}（上一纪元 destroy 过），桥若捏着旧实例，重连后所有结算
+ * 都会打进一个已经拆掉事件总线的管理器。
+ *
+ * @internal
+ */
+export const createSyncHistoryBridge = (
+  historyManager: () => HistoryManager,
+  pushInFlight: PushInFlightRegistry
+): SyncHistoryBridge => ({
+  pushInFlight,
+  syncing: fn => historyManager().syncing(fn),
+  clearUndoHistory: () => historyManager().clearUndoHistory(),
+  beginPullableSettlement: () => historyManager().beginPullableSettlement(),
+  settlePull: (token, options, result) =>
+    historyManager().settlePullableCount(token, {
+      complete: isCompletePull(options, result),
+      pulled: result.pulled
+    }),
+  settleAbortedPull: (token, pulled) => historyManager().settlePullableCount(token, { complete: false, pulled }),
+  reconcilePullableCount: (token, count) => historyManager().reconcilePullableCount(token, count),
+  incrementPullableCount: count => historyManager().incrementPullableCount(count)
+});