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

package/src/undo-redo-apply.ts

@@ -0,0 +1,270 @@
+import {
+  buildPushableRepositoryRules,
+  declareTrustedWrite,
+  type FindOptions,
+  type HistoryItem,
+  type IRepository,
+  isAdapterShutdownError,
+  type RxDB,
+  type RxDBAdapterLocalBase,
+  RxDBBranch,
+  RxDBChange,
+  type RxDBChangeRuleGroup,
+  RxDBSync,
+  type RxDBSyncOrderByField,
+  type RxDBSyncRuleGroup,
+  SKIP_BRANCH_SWITCH_PREPARE,
+  TrustedWriteIntent
+} 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;
+    }
+    // undo/redo 是用户可感知的编辑，矩阵行 6 要求它**产生**单元（origin='undo_redo'）。
+    declareTrustedWrite(adapter, {
+      file: 'undo-redo-apply.ts',
+      symbol: 'applyUndoRedoHistories',
+      intent: TrustedWriteIntent.undo_redo
+    });
+    // 不传 branchId：回放只作用于当前分支。在事务外采样分支 id 会让这次写入在并发切换时
+    // 把 activated 与全部触发器倒回旧分支（见 SwitchBranchOptions.branchId）。
+    // 分支一动不动，所以没有前置条件可校验——这里的豁免是一句「我确实不需要」，不是漏传。
+    await adapter.switchBranch({ actions, prepare: SKIP_BRANCH_SWITCH_PREPARE });
+
+    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.entitySync, 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;
+};