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

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)
+});

package/src/undo-redo-apply.ts

@@ -0,0 +1,260 @@
+import {
+  buildPushableRepositoryRules,
+  type FindOptions,
+  type HistoryItem,
+  type IRepository,
+  isAdapterShutdownError,
+  type RxDB,
+  type RxDBAdapterLocalBase,
+  RxDBBranch,
+  RxDBChange,
+  type RxDBChangeRuleGroup,
+  RxDBSync,
+  type RxDBSyncOrderByField,
+  type RxDBSyncRuleGroup
+} from '@aiao/rxdb';
+import { BehaviorSubject, firstValueFrom, Subject } from 'rxjs';
+import { buildLastPushedMap } from './history-filters.js';
+import { convertChangesToHistories } from './history-item-builder.js';
+import type { ActiveUndoSession, UndoBoundary } from './history-undo-session.types.js';
+import { get_switch_version_actions } from './switch-branch-actions.js';
+type LocalRxDBSyncRepository = IRepository<typeof RxDBSync> & {
+  find(options: FindOptions<typeof RxDBSync, RxDBSyncRuleGroup, RxDBSyncOrderByField>): Promise<RxDBSync[]>;
+};
+
+export const getLocalRxDBSyncRepository = (adapter: RxDBAdapterLocalBase): LocalRxDBSyncRepository =>
+  adapter.getRepository<typeof RxDBSync, LocalRxDBSyncRepository>(RxDBSync);
+
+/**
+ * undo / redo / pushableCount 所需的可变状态。
+ *
+ * `#` 字段必须通过 getter/setter 关闭 captured 实例；Map / Subject 用类持有的同一份引用。
+ */
+export interface UndoRedoApplyHost {
+  readonly rxdb: RxDB;
+  readonly destroyed: boolean;
+  isUndoRedoInProgress: boolean;
+  redoInvalidationFloor: number;
+  pushableGeneration: number;
+  readonly pushableCount$: BehaviorSubject<number>;
+  readonly pushableCountTrigger$: BehaviorSubject<number>;
+  readonly errors$: Subject<Error>;
+  getFirstConnectedAt(): Date;
+  isUndoSessionCurrent(session: ActiveUndoSession): boolean;
+  getNextRevertStateUpdatedAt(changes: RxDBChange[]): Date;
+  setRevertStateWatermarks(changes: RxDBChange[], reverted: boolean, updatedAt: Date): void;
+  pushToRedoStack(items: HistoryItem[]): void;
+  removeFromRedoStack(items: HistoryItem[]): HistoryItem[];
+}
+
+/** 绕过 Observable 缓存，直接查最新变更再转成历史项。 */
+export async function fetchLatestHistories(
+  host: UndoRedoApplyHost,
+  undoBoundary: UndoBoundary
+): Promise<{ histories: HistoryItem[]; lastPushedMap: Map<string, number> }> {
+  const { changeRepository: adapter, branchRepository } = await host.rxdb.versionManager.getLocalRepositories();
+
+  const branches = await branchRepository.find({
+    where: {
+      combinator: 'and',
+      rules: [{ field: 'activated', operator: '=', value: true }]
+    }
+  });
+
+  if (branches.length === 0) {
+    return { histories: [], lastPushedMap: new Map() };
+  }
+
+  const branch = branches[0];
+
+  const localAdapter = await firstValueFrom(host.rxdb.localAdapter$);
+  const repoSyncRepo = getLocalRxDBSyncRepository(localAdapter);
+  const repoSyncs = await repoSyncRepo.find({
+    where: {
+      combinator: 'and',
+      rules: [{ field: 'branchId', operator: '=', value: branch.id }]
+    }
+  });
+
+  // 带上在飞认领：远端往返途中的变更视同已推，否则这段窗口里的 undo 会造成永久分叉
+  const lastPushedMap = buildLastPushedMap(repoSyncs, host.rxdb.versionManager.pushInFlight.snapshot());
+
+  const rules: RxDBChangeRuleGroup['rules'] = [
+    {
+      field: 'branchId',
+      operator: '=',
+      value: branch.id
+    },
+    {
+      field: 'createdAt',
+      operator: '>=',
+      value: host.getFirstConnectedAt()
+    }
+  ];
+  if (undoBoundary.changeId > 0) {
+    rules.push({ field: 'id', operator: '>', value: undoBoundary.changeId });
+  }
+  const allChanges = await adapter.find({
+    where: {
+      combinator: 'and',
+      rules
+    },
+    orderBy: [{ field: 'id', sort: 'desc' }]
+  });
+
+  return { histories: convertChangesToHistories(allChanges), lastPushedMap };
+}
+
+/**
+ * 应用 undo/redo：提取排序 → switchBranch actions → 元数据 → 身份检查 → 切分支 → 栈。
+ *
+ * undo 在 `adapter.switchBranch` 前必须做 session 对象身份检查。
+ */
+export async function applyUndoRedoHistories(
+  host: UndoRedoApplyHost,
+  operation: 'undo' | 'redo',
+  histories: HistoryItem[],
+  undoSession?: ActiveUndoSession
+): Promise<void> {
+  host.isUndoRedoInProgress = true;
+
+  try {
+    const changes = histories
+      .flatMap(h => h.changes)
+      .sort((a, b) => (operation === 'undo' ? b.id - a.id : a.id - b.id));
+
+    const actions = get_switch_version_actions(changes, operation === 'redo');
+    const stateUpdatedAt = host.getNextRevertStateUpdatedAt(changes);
+
+    if (operation === 'undo') {
+      const { adapter } = await host.rxdb.versionManager.getLocalRepositories();
+      const seq = await adapter.getRxDBChangeSequence();
+      const revertChangedAt = new Date();
+
+      changes.forEach((change, index) => {
+        const changeKey = `rxdb:RxDBChange:${change.id}`;
+        const existingUpdate = actions.updates.get(changeKey) || { patch: {}, inversePatch: null };
+        actions.updates.set(changeKey, {
+          patch: {
+            ...existingUpdate.patch,
+            revertChangeId: seq + index + 1,
+            revertChangedAt,
+            updatedAt: stateUpdatedAt
+          },
+          inversePatch: existingUpdate.inversePatch
+        });
+      });
+      actions.updateRxDBChangeSequence = seq + changes.length;
+      host.redoInvalidationFloor = seq + changes.length;
+    } else {
+      changes.forEach(change => {
+        const changeKey = `rxdb:RxDBChange:${change.id}`;
+        const existingUpdate = actions.updates.get(changeKey) || { patch: {}, inversePatch: null };
+        actions.updates.set(changeKey, {
+          patch: {
+            ...existingUpdate.patch,
+            revertChangeId: null,
+            updatedAt: stateUpdatedAt
+          },
+          inversePatch: existingUpdate.inversePatch
+        });
+      });
+    }
+
+    const { adapter } = await host.rxdb.versionManager.getLocalRepositories();
+    if (operation === 'undo') {
+      if (undoSession === undefined || !host.isUndoSessionCurrent(undoSession)) return;
+    }
+    // 不传 branchId：回放只作用于当前分支。在事务外采样分支 id 会让这次写入在并发切换时
+    // 把 activated 与全部触发器倒回旧分支（见 SwitchBranchOptions.branchId）。
+    await adapter.switchBranch({ actions });
+
+    host.pushableCountTrigger$.next(Date.now());
+    host.setRevertStateWatermarks(changes, operation === 'undo', stateUpdatedAt);
+
+    if (operation === 'undo') {
+      host.pushToRedoStack(histories);
+    } else {
+      host.removeFromRedoStack(histories);
+    }
+  } finally {
+    host.isUndoRedoInProgress = false;
+  }
+}
+
+/**
+ * 按 repository 水位线异步刷新 pushableCount。
+ *
+ * 只有仍是最新那次刷新才有资格改写计数。失败字符串 `'[#updatePushableCount] error'` 不得改。
+ */
+export async function updatePushableCount(host: UndoRedoApplyHost): Promise<void> {
+  const generation = ++host.pushableGeneration;
+  const publish = (count: number): void => {
+    if (generation === host.pushableGeneration) {
+      host.pushableCount$.next(count);
+    }
+  };
+
+  try {
+    const connected = await firstValueFrom(host.rxdb.connected$);
+    if (!connected) {
+      publish(0);
+      return;
+    }
+
+    const localAdapter = await firstValueFrom(host.rxdb.localAdapter$);
+    const RxDBSyncRepo = getLocalRxDBSyncRepository(localAdapter);
+    const changeRepository = host.rxdb.entityManager.getRepository(RxDBChange);
+    const branch = await firstValueFrom(
+      host.rxdb.entityManager.getRepository(RxDBBranch).findOne({
+        where: {
+          combinator: 'and',
+          rules: [{ field: 'activated', operator: '=', value: true }]
+        }
+      })
+    );
+
+    if (!branch) {
+      publish(0);
+      return;
+    }
+
+    const repoSyncs = await RxDBSyncRepo.find({
+      where: {
+        combinator: 'and',
+        rules: [{ field: 'branchId', operator: '=', value: branch.id }]
+      }
+    });
+
+    const repoRules = buildPushableRepositoryRules(host.rxdb.config.entities, host.rxdb.config.sync, repoSyncs);
+    if (repoRules.length === 0) {
+      publish(0);
+      return;
+    }
+
+    const count = await firstValueFrom(
+      changeRepository.count({
+        where: {
+          combinator: 'and',
+          rules: [
+            { field: 'branchId', operator: '=', value: branch.id },
+            { field: 'revertChangeId', operator: '=', value: null },
+            { field: 'remoteId', operator: '=', value: null },
+            {
+              combinator: 'or',
+              rules: repoRules
+            }
+          ]
+        }
+      })
+    );
+
+    publish(count);
+  } catch (error) {
+    if (!host.destroyed && !isAdapterShutdownError(error)) {
+      console.error('[#updatePushableCount] error', error);
+      host.errors$.next(error instanceof Error ? error : new Error(String(error)));
+    }
+    publish(0);
+  }
+}

package/src/version-manager.utils.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview 版本管理器的纯函数工具集
+ *
+ * 从 {@link VersionManager} 抽出的无状态辅助函数，供变更事件处理流程复用。
+ *
+ * @remarks
+ * 同步侧那两个（`hasSyncedData` / `partialResultOf`）随 US-025 阶段 D 去了
+ * `@aiao/rxdb-plugin-sync` 的 `sync-manager.utils.ts`：它们的形参是
+ * `SyncRepositoryResult`，留在这里会让历史包反向依赖同步包。
+ */
+
+const getPositiveSafeInteger = (value: unknown): number | null =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : null;
+
+/**
+ * 从变更事件里提取数字 id。
+ *
+ * @param change - 变更事件，优先取 `change.id`，缺失时回退到 `change.patch.id`
+ * @returns 正整数 id，无法提取时返回 null
+ */
+export const getRxDBChangeEventId = (change: { id: unknown; patch?: unknown }): number | null => {
+  const eventId = getPositiveSafeInteger(change.id);
+  if (eventId !== null) return eventId;
+  if (typeof change.patch !== 'object' || change.patch === null || !('id' in change.patch)) return null;
+  return getPositiveSafeInteger(change.patch.id);
+};
+
+/**
+ * 取一组变更里最早的 `recordAt` 时间。
+ *
+ * @param changes - 变更数组
+ * @returns 最早的有效 `recordAt`，没有有效记录时返回 null
+ */
+export const getEarliestRecordAt = (changes: readonly { recordAt?: unknown }[]): Date | null => {
+  let earliest: Date | null = null;
+  for (const change of changes) {
+    if (!(change.recordAt instanceof Date) || !Number.isFinite(change.recordAt.getTime())) continue;
+    if (earliest === null || change.recordAt.getTime() < earliest.getTime()) {
+      earliest = change.recordAt;
+    }
+  }
+  return earliest;
+};