@flowgram-vue/history 0.2.0

package/src/history/history-stack.ts

@@ -0,0 +1,166 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { cloneDeep } from 'lodash-es';
+import { injectable, inject } from 'inversify';
+import { DisposableCollection, Emitter } from '@flowgram-vue/utils';
+
+import { HistoryOperation, Operation, OperationWithId } from '../operation';
+import { HistoryConfig } from '../history-config';
+import {
+  type HistoryItem,
+  HistoryStackChangeType,
+  type HistoryStackItem,
+  HistoryStackChangeEvent,
+  UndoRedoChangeType,
+} from './types';
+import { type HistoryService } from './history-service';
+
+/**
+ * 历史栈，聚合所有历史操作
+ */
+@injectable()
+export class HistoryStack {
+  @inject(HistoryConfig)
+  historyConfig: HistoryConfig;
+
+  private _items: HistoryItem[] = [];
+
+  readonly onChangeEmitter = new Emitter<HistoryStackChangeEvent>();
+
+  readonly onChange = this.onChangeEmitter.event;
+
+  private _toDispose: DisposableCollection = new DisposableCollection();
+
+  limit = 100;
+
+  constructor() {
+    this._toDispose.push(this.onChangeEmitter);
+  }
+
+  get items(): HistoryItem[] {
+    return this._items;
+  }
+
+  add(service: HistoryService, item: HistoryStackItem) {
+    const historyItem = this._getHistoryItem(service, item);
+    this._items.unshift(historyItem);
+    if (this._items.length > this.limit) {
+      this._items.pop();
+    }
+    this.onChangeEmitter.fire({
+      type: HistoryStackChangeType.ADD,
+      value: historyItem,
+      service,
+    });
+    return historyItem;
+  }
+
+  findById(id: string): HistoryItem | undefined {
+    return this._items.find((item) => item.id === id);
+  }
+
+  changeByIndex(index: number, service: HistoryService, item: HistoryStackItem) {
+    const historyItem = this._getHistoryItem(service, item);
+    this._items[index] = historyItem;
+    this.onChangeEmitter.fire({
+      type: HistoryStackChangeType.UPDATE,
+      value: historyItem,
+      service,
+    });
+  }
+
+  addOperation(service: HistoryService, id: string, op: OperationWithId) {
+    const historyItem = this._items.find((item) => item.id === id);
+    if (!historyItem) {
+      console.warn('no history item found');
+      return;
+    }
+
+    const newOperatopn = this._getHistoryOperation(service, op);
+    historyItem.operations.push(newOperatopn);
+
+    this.onChangeEmitter.fire({
+      type: HistoryStackChangeType.ADD_OPERATION,
+      value: {
+        historyItem,
+        operation: newOperatopn,
+      },
+      service,
+    });
+  }
+
+  updateOperation(service: HistoryService, id: string, op: OperationWithId) {
+    const historyItem = this._items.find((item) => item.id === id);
+    if (!historyItem) {
+      console.warn('no history item found');
+      return;
+    }
+    const index = historyItem.operations.findIndex((op) => op.id === op.id);
+    if (index < 0) {
+      console.warn('no operation found');
+      return;
+    }
+    const newOperatopn = this._getHistoryOperation(service, op);
+    historyItem.operations.splice(index, 1, newOperatopn);
+    this.onChangeEmitter.fire({
+      type: HistoryStackChangeType.UPDATE_OPERATION,
+      value: {
+        historyItem,
+        operation: newOperatopn,
+      },
+      service,
+    });
+  }
+
+  clear() {
+    this._items = [];
+  }
+
+  dispose() {
+    this._items = [];
+    this._toDispose.dispose();
+  }
+
+  private _getHistoryItem(service: HistoryService, item: HistoryStackItem): HistoryItem {
+    return {
+      ...item,
+      uri: service.context.uri,
+      time: HistoryStack.dateFormat(item.timestamp),
+      operations: item.operations.map((op) =>
+        this._getHistoryOperation(service, op, item.type !== UndoRedoChangeType.PUSH)
+      ),
+    };
+  }
+
+  private _getHistoryOperation(
+    service: HistoryService,
+    op: Operation,
+    generateId: boolean = false
+  ): HistoryOperation {
+    let id;
+    if (generateId) {
+      id = this.historyConfig.generateId();
+    } else {
+      const oldId = (op as OperationWithId).id;
+      if (!oldId) {
+        throw new Error('no operation id found');
+      }
+      id = oldId;
+    }
+
+    return {
+      ...cloneDeep(op),
+      id,
+      label: service.operationService.getOperationLabel(op),
+      description: service.operationService.getOperationDescription(op),
+      timestamp: Date.now(),
+    };
+  }
+
+  static dateFormat(timestamp: number) {
+    return new Date(timestamp).toLocaleString();
+  }
+}

package/src/history/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './undo-redo-service';
+export * from './types';
+export * from './history-service';
+export * from './stack-operation';
+export * from './history-manager';
+export * from './history-stack';
+export * from '../history-config';

package/src/history/stack-operation.ts

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { cloneDeep } from 'lodash-es';
+import { DisposableCollection } from '@flowgram-vue/utils';
+
+import { OperationService } from '../operation/operation-service';
+import { Operation, OperationWithId } from '../operation';
+import { IUndoRedoElement, UndoRedoChangeType } from './types';
+
+export class StackOperation implements IUndoRedoElement {
+  label?: string | undefined;
+
+  description?: string | undefined;
+
+  private _operations: OperationWithId[];
+
+  private _toDispose = new DisposableCollection();
+
+  private _timestamp: number = Date.now();
+
+  private _operationService: OperationService;
+
+  private _id: string;
+
+  get id() {
+    return this._id;
+  }
+
+  constructor(operationService: OperationService, operations: Operation[] = []) {
+    this._operationService = operationService;
+    this._operations = operations.map((op) => this._operation(op));
+    this._id = operationService.config.generateId();
+  }
+
+  getTimestamp(): number {
+    return this._timestamp;
+  }
+
+  pushOperation(operation: Operation): OperationWithId {
+    const op = this._operation(operation);
+    this._operations.push(op);
+    return op;
+  }
+
+  getOperations(): Operation[] {
+    return this._operations;
+  }
+
+  getChangeOperations(type: UndoRedoChangeType): Operation[] {
+    if (type === UndoRedoChangeType.UNDO) {
+      return this._operationService.inverseOperations(this._operations);
+    }
+    return this._operations;
+  }
+
+  getFirstOperation(): Operation {
+    return this._operations[0];
+  }
+
+  getLastOperation(): Operation<unknown> {
+    return this._operations[this._operations.length - 1];
+  }
+
+  async undo(): Promise<void> {
+    const inverseOps = this._operationService.inverseOperations(this._operations);
+
+    for (const op of inverseOps) {
+      await this._apply(op);
+    }
+  }
+
+  async redo(): Promise<void> {
+    for (const op of this._operations) {
+      await this._apply(op);
+    }
+  }
+
+  revert(type: UndoRedoChangeType): void | Promise<void> {
+    let operations: Operation[] = this._operations;
+
+    if (type !== UndoRedoChangeType.UNDO) {
+      operations = this._operations.map((op) => this._inverse(op)).reverse();
+    }
+
+    for (const op of operations) {
+      this._apply(op);
+    }
+  }
+
+  private _inverse(op: Operation): Operation {
+    return this._operationService.inverseOperation(op);
+  }
+
+  private async _apply(op: Operation) {
+    await this._operationService.applyOperation(op);
+  }
+
+  private _operation(op: Operation) {
+    return {
+      ...op,
+      value: cloneDeep(op.value),
+      id: this._operationService.config.generateId(),
+    };
+  }
+
+  dispose(): void {
+    this._toDispose.dispose();
+  }
+}

package/src/history/types.ts

@@ -0,0 +1,325 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Disposable } from '@flowgram-vue/utils';
+
+import { HistoryOperation, Operation } from '../operation';
+import { HistoryService } from './history-service';
+
+export interface HistoryRecord {
+  snapshot: any;
+  stack: any[];
+}
+
+export interface HistoryItem extends HistoryStackItem {
+  id: string;
+  time: string;
+  operations: HistoryOperation[];
+}
+
+/**
+ * 历史服务管理
+ */
+export interface IHistoryManager {
+  /**
+   * 注册历史服务
+   * @param service 历史服务示例
+   */
+  registerHistoryService(service: IHistoryService): void;
+  /**
+   * 取消注册历史服务
+   * @param service 历史服务示例
+   */
+  unregisterHistoryService(service: HistoryService): void;
+}
+
+/**
+ * 历史服务
+ */
+export interface IHistoryService extends Disposable {
+  /**
+   * 添加操作
+   * @param operation 操作
+   */
+  pushOperation(operation: Operation): void | Promise<void>;
+  /**
+   * 获取所有历史操作
+   */
+  getHistoryOperations(): Operation[];
+  /**
+   * 撤回
+   */
+  undo(): void | Promise<void>;
+  /**
+   * 重做
+   */
+  redo(): void | Promise<void>;
+  /**
+   * 是否有可撤销的操作
+   */
+  canUndo(): boolean;
+  /**
+   * 是否有可重做的操作
+   */
+  canRedo(): boolean;
+  /**
+   * 获取历史记录
+   */
+  getRecords(): Promise<HistoryRecord[]>;
+  /**
+   * 根据历史版本重新存储历史记录
+   * @param historyRecord 历史记录
+   */
+  restore(historyRecord: HistoryRecord): Promise<void>;
+  /**
+   * 清空undo/redo
+   */
+  clear(): void;
+  /**
+   * 最大数量限制
+   * @param num 数量
+   */
+  limit(num: number): void;
+  /**
+   * 返回快照
+   */
+  getSnapshot(): unknown;
+}
+
+export interface IOperationService {
+  pushOperation(operation: Operation): void;
+}
+
+/**
+ * UndoRedo服务
+ */
+export interface IUndoRedoService extends Disposable {
+  /**
+   * 添加一个undo/redo元素
+   * @param element 可undo/redo的元素
+   */
+  pushElement(element: IUndoRedoElement): void;
+  /**
+   * 获取最后一个可undo的元素
+   */
+  getLastElement(): IUndoRedoElement;
+  /**
+   * 获取undo栈
+   */
+  getUndoStack(): IUndoRedoElement[];
+  /**
+   * 获取redo栈
+   */
+  getRedoStack(): IUndoRedoElement[];
+  /**
+   * 清空redo栈
+   */
+  clearRedoStack(): void;
+  /**
+   * 是否可undo
+   */
+  canUndo(): boolean;
+  /**
+   * 执行undo
+   */
+  undo(): Promise<void> | void;
+  /**
+   * 是否可redo
+   */
+  canRedo(): boolean;
+  /**
+   * 执行redo
+   */
+  redo(): Promise<void> | void;
+  /**
+   * 清空 undo和redo栈
+   */
+  clear(): void;
+}
+
+/**
+ * UndoRedo元素
+ */
+export interface IUndoRedoElement extends Disposable {
+  /**
+   * 操作标题
+   */
+  readonly label?: string;
+  /**
+   * 操作描述
+   */
+  readonly description?: string;
+  /**
+   * 撤销
+   */
+  undo(): Promise<void> | void;
+  /**
+   * 重做
+   */
+  redo(): Promise<void> | void;
+  /**
+   * 添加一个操作
+   * @param operation 操作
+   */
+  pushOperation(operation: Operation): Operation;
+  /**
+   * 获取所有操作
+   */
+  getOperations(): Operation[];
+  /**
+   * 获取第一个操作
+   */
+  getFirstOperation(): Operation;
+  /**
+   * 获取最后一个操作
+   */
+  getLastOperation(): Operation;
+  /**
+   * 获取修改的操作
+   */
+  getChangeOperations(type: UndoRedoChangeType): Operation[];
+}
+
+/**
+ * 操作注册
+ */
+export interface IOperationRegistry {
+  register(type: string, factory: IUndoRedoElementFactory<unknown>): void;
+}
+
+/**
+ * 操作工厂
+ */
+export type IUndoRedoElementFactory<OperationValue> = (
+  operation: Operation<OperationValue>
+) => IUndoRedoElement;
+
+/**
+ * undo redo 类型
+ */
+export enum UndoRedoChangeType {
+  UNDO = 'undo',
+  REDO = 'redo',
+  PUSH = 'push',
+  CLEAR = 'clear',
+}
+
+/**
+ * 带element的事件
+ */
+export interface UndoRedoChangeElementEvent {
+  type: UndoRedoChangeType.PUSH | UndoRedoChangeType.UNDO | UndoRedoChangeType.REDO;
+  element: IUndoRedoElement;
+}
+/**
+ * 清空事件
+ */
+export interface UndoRedoClearEvent {
+  type: UndoRedoChangeType.CLEAR;
+}
+/**
+ * undo redo变化事件
+ */
+export type UndoRedoChangeEvent = UndoRedoChangeElementEvent | UndoRedoClearEvent;
+
+export interface HistoryStackItem {
+  id: string;
+  type: UndoRedoChangeType;
+  timestamp: number;
+  operations: Operation[];
+  uri?: string;
+}
+
+/**
+ * 历史栈变化类型
+ */
+export enum HistoryStackChangeType {
+  ADD = 'add',
+  UPDATE = 'update',
+  CLEAR = 'clear',
+  ADD_OPERATION = 'add_operation',
+  UPDATE_OPERATION = 'update_operation',
+}
+
+/**
+ * 历史栈变化事件基础
+ */
+export interface HistoryStackBaseEvent {
+  type: HistoryStackChangeType;
+  value?: any;
+  service: HistoryService;
+}
+
+/**
+ * 添加历史事件
+ */
+export interface HistoryStackAddEvent extends HistoryStackBaseEvent {
+  type: HistoryStackChangeType.ADD;
+  value: HistoryItem;
+}
+
+/**
+ * 更新历史事件
+ */
+export interface HistoryStackUpdateEvent extends HistoryStackBaseEvent {
+  type: HistoryStackChangeType.UPDATE;
+  value: HistoryItem;
+}
+
+/**
+ * 添加操作事件
+ */
+export interface HistoryStackAddOperationEvent extends HistoryStackBaseEvent {
+  type: HistoryStackChangeType.ADD_OPERATION;
+  value: {
+    historyItem: HistoryItem;
+    operation: HistoryOperation;
+  };
+}
+
+/**
+ * 更新操作事件
+ */
+export interface HistoryStackUpdateOperationEvent extends HistoryStackBaseEvent {
+  type: HistoryStackChangeType.UPDATE_OPERATION;
+  value: {
+    historyItem: HistoryItem;
+    operation: HistoryOperation;
+  };
+}
+
+/**
+ * 历史记录变化事件
+ */
+export type HistoryStackChangeEvent =
+  | HistoryStackAddEvent
+  | HistoryStackUpdateEvent
+  | HistoryStackAddOperationEvent
+  | HistoryStackUpdateOperationEvent;
+
+export enum HistoryMergeEventType {
+  ADD = 'ADD',
+  UPDATE = 'UPDATE',
+}
+
+/**
+ * 历史合并事件
+ */
+export type HistoryMergeEvent =
+  | {
+      type: HistoryMergeEventType.ADD;
+      value: {
+        element: IUndoRedoElement;
+        operation: Operation;
+      };
+    }
+  | {
+      type: HistoryMergeEventType.UPDATE;
+      value: {
+        element: IUndoRedoElement;
+        operation: Operation;
+        value: any;
+      };
+    };