@flowgram-vue/history 0.2.0

package/src/history/undo-redo-service.ts

@@ -0,0 +1,189 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable } from 'inversify';
+import { Emitter, DisposableCollection } from '@flowgram-vue/utils';
+
+import {
+  IUndoRedoElement,
+  IUndoRedoService,
+  UndoRedoChangeType,
+  UndoRedoChangeEvent,
+  UndoRedoClearEvent,
+} from './types';
+
+@injectable()
+export class UndoRedoService implements IUndoRedoService {
+  private _undoStack: IUndoRedoElement[];
+
+  private _redoStack: IUndoRedoElement[];
+
+  private _undoing: boolean = false;
+
+  private _redoing: boolean = false;
+
+  private _limit: number = 100;
+
+  protected onChangeEmitter = new Emitter<UndoRedoChangeEvent>();
+
+  readonly onChange = this.onChangeEmitter.event;
+
+  readonly _toDispose = new DisposableCollection();
+
+  constructor() {
+    this._undoStack = [];
+    this._redoStack = [];
+    this._toDispose.push(this.onChangeEmitter);
+  }
+
+  setLimit(limit: number) {
+    this._limit = limit;
+  }
+
+  pushElement(element: IUndoRedoElement): void {
+    this._redoStack = [];
+    this._stackPush(this._undoStack, element);
+    this._toDispose.push(element);
+    this._emitChange(UndoRedoChangeType.PUSH, element);
+  }
+
+  getUndoStack() {
+    return this._undoStack;
+  }
+
+  getRedoStack() {
+    return this._redoStack;
+  }
+
+  getLastElement() {
+    return this._undoStack[this._undoStack.length - 1];
+  }
+
+  /**
+   * 执行undo
+   * @returns void
+   */
+  async undo(): Promise<void> {
+    if (!this.canUndo()) {
+      return;
+    }
+
+    if (this._undoing) {
+      return;
+    }
+    this._undoing = true;
+
+    const item = this._undoStack.pop() as IUndoRedoElement;
+
+    try {
+      await item.undo();
+    } finally {
+      this._stackPush(this._redoStack, item);
+      this._emitChange(UndoRedoChangeType.UNDO, item);
+      this._undoing = false;
+    }
+  }
+
+  /**
+   * 执行redo
+   * @returns void
+   */
+  async redo(): Promise<void> {
+    if (!this.canRedo()) {
+      return;
+    }
+
+    if (this._redoing) {
+      return;
+    }
+    this._redoing = true;
+
+    const item = this._redoStack.pop() as IUndoRedoElement;
+
+    try {
+      await item.redo();
+    } finally {
+      this._stackPush(this._undoStack, item);
+      this._emitChange(UndoRedoChangeType.REDO, item);
+      this._redoing = false;
+    }
+  }
+
+  /**
+   * 是否可undo
+   * @returns true代表可以，false代表不可以
+   */
+  canUndo(): boolean {
+    return this._undoStack.length > 0;
+  }
+
+  /**
+   * 是否可redo
+   * @returns true代表可以，false代表不可以
+   */
+  canRedo(): boolean {
+    return this._redoStack.length > 0;
+  }
+
+  /**
+   * 是否可以push
+   * @returns true代表可以，false代表不可以
+   */
+  canPush(): boolean {
+    return !this._redoing && !this._undoing;
+  }
+
+  /**
+   * 清空
+   */
+  clear() {
+    this.clearRedoStack();
+    this.clearUndoStack();
+    this._emitChange(UndoRedoChangeType.CLEAR);
+  }
+
+  /**
+   * 清空redo栈
+   */
+  clearRedoStack(): void {
+    this._redoStack.forEach(element => {
+      element.dispose();
+    });
+    this._redoStack = [];
+  }
+
+  /**
+   * 清空undo栈
+   */
+  clearUndoStack(): void {
+    this._undoStack.forEach(element => {
+      element.dispose();
+    });
+    this._undoStack = [];
+  }
+
+  /**
+   * 销毁
+   */
+  dispose(): void {
+    this.clear();
+    this._toDispose.dispose();
+  }
+
+  private _stackPush(stack: IUndoRedoElement[], element: IUndoRedoElement) {
+    stack.push(element);
+    if (stack.length > this._limit) {
+      stack.shift();
+    }
+  }
+
+  private _emitChange(type: UndoRedoChangeType, element?: IUndoRedoElement) {
+    if (element) {
+      this.onChangeEmitter.fire({ type, element });
+    } else {
+      this.onChangeEmitter.fire({ type } as UndoRedoClearEvent);
+    }
+  }
+}

package/src/history-config.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { nanoid } from 'nanoid';
+import { injectable } from 'inversify';
+
+@injectable()
+export class HistoryConfig {
+  generateId: () => string = () => nanoid();
+
+  getSnapshot: () => unknown = () => '';
+}

package/src/history-container-module.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ContainerModule } from 'inversify';
+
+import { OperationRegistry, OperationService } from './operation';
+import { HistoryContext } from './history-context';
+import {
+  HistoryService,
+  HistoryStack,
+  HistoryManager,
+  UndoRedoService,
+  HistoryConfig,
+} from './history';
+
+export const HistoryContainerModule = new ContainerModule(
+  (bind, _unbind, _isBound, _rebind, _unbindAsync, onActivation, _onDeactivation) => {
+    bind(OperationRegistry).toSelf().inSingletonScope();
+    bind(OperationService).toSelf().inSingletonScope();
+    bind(UndoRedoService).toSelf().inSingletonScope();
+    bind(HistoryService).toSelf().inSingletonScope();
+    bind(HistoryContext).toSelf().inSingletonScope();
+    bind(HistoryManager).toSelf().inSingletonScope();
+    bind(HistoryStack).toSelf().inSingletonScope();
+    bind(HistoryConfig).toSelf().inSingletonScope();
+
+    onActivation(HistoryService, (ctx, historyService) => {
+      let historyManager;
+
+      if (ctx.container?.parent?.isBound(HistoryManager)) {
+        historyManager = ctx.container?.parent?.get(HistoryManager);
+      } else {
+        historyManager = ctx.container.get(HistoryManager);
+      }
+
+      if (!historyManager) {
+        return historyService;
+      }
+
+      historyService.historyManager = historyManager;
+      historyManager.registerHistoryService(historyService);
+      return historyService;
+    });
+  }
+);

package/src/history-context.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable } from 'inversify';
+
+@injectable()
+export class HistoryContext {
+  /**
+   * 所属uri
+   */
+  uri?: string;
+
+  /**
+   * 操作触发的源对象，如编辑器对象
+   */
+  source?: unknown;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './operation';
+export * from './history';
+export * from './history-container-module';
+export * from './create-history-plugin';
+export * from './history-context';

package/src/operation/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './operation-contribution';
+export * from './operation-registry';
+export * from './operation-service';
+export * from './types';

package/src/operation/operation-contribution.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { OperationRegistry } from './operation-registry';
+
+export const OperationContribution = Symbol('OperationContribution');
+
+export interface OperationContribution {
+  registerOperationMeta?(operationRegistry: OperationRegistry): void;
+}

package/src/operation/operation-registry.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable, multiInject, optional, postConstruct } from 'inversify';
+import { Disposable, DisposableCollection } from '@flowgram-vue/utils';
+
+import { OperationMeta } from './types';
+import { OperationContribution } from './operation-contribution';
+
+@injectable()
+export class OperationRegistry {
+  private readonly _operationMetas: Map<string, OperationMeta> = new Map();
+
+  @multiInject(OperationContribution)
+  @optional()
+  protected readonly contributions: OperationContribution[] = [];
+
+  @postConstruct()
+  protected init() {
+    for (const contrib of this.contributions) {
+      contrib.registerOperationMeta?.(this);
+    }
+  }
+
+  /**
+   * 注册操作的元数据
+   * @param operationMeta 操作的元数据
+   * @returns 销毁函数
+   */
+  registerOperationMeta(operationMeta: OperationMeta): Disposable {
+    if (this._operationMetas.has(operationMeta.type)) {
+      console.warn(`A operation meta ${operationMeta.type} is already registered.`);
+      return Disposable.NULL;
+    }
+    const toDispose = new DisposableCollection(this._doRegisterOperationMetaMeta(operationMeta));
+    return toDispose;
+  }
+
+  /**
+   * 获取操作的元数据
+   * @param type 操作类型
+   * @returns 操作的元数据
+   */
+  getOperationMeta(type: string): OperationMeta | undefined {
+    return this._operationMetas.get(type);
+  }
+
+  private _doRegisterOperationMetaMeta(operationMeta: OperationMeta): Disposable {
+    this._operationMetas.set(operationMeta.type, operationMeta);
+    return {
+      dispose: () => {
+        this._operationMetas.delete(operationMeta.type);
+      },
+    };
+  }
+}

package/src/operation/operation-service.ts

@@ -0,0 +1,105 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable, inject, postConstruct } from 'inversify';
+import { DisposableCollection, Emitter } from '@flowgram-vue/utils';
+
+import { HistoryContext } from '../history-context';
+import { HistoryConfig } from '../history-config';
+import { Operation } from './types';
+import { OperationRegistry } from './operation-registry';
+
+@injectable()
+export class OperationService {
+  @inject(OperationRegistry)
+  readonly operationRegistry: OperationRegistry;
+
+  @inject(HistoryContext)
+  readonly context: HistoryContext;
+
+  @inject(HistoryConfig)
+  config: HistoryConfig;
+
+  readonly applyEmitter = new Emitter<Operation>();
+
+  readonly onApply = this.applyEmitter.event;
+
+  private _toDispose = new DisposableCollection();
+
+  @postConstruct()
+  init() {
+    this._toDispose.push(this.applyEmitter);
+  }
+
+  /**
+   * 执行操作
+   * @param op
+   * @returns
+   */
+  applyOperation(op: Operation, options?: { noApply?: boolean }): any {
+    const meta = this.operationRegistry.getOperationMeta(op.type);
+
+    if (!meta) {
+      throw new Error(`Operation meta ${op.type} has not registered.`);
+    }
+
+    let res;
+    if (!options?.noApply) {
+      res = meta.apply(op, this.context.source);
+    }
+
+    this.applyEmitter.fire(op);
+
+    return res;
+  }
+
+  /**
+   * 根据操作类型获取操作的label
+   * @param operation 操作
+   * @returns
+   */
+  getOperationLabel(operation: Operation): string | undefined {
+    const operationMeta = this.operationRegistry.getOperationMeta(operation.type);
+
+    if (operationMeta && operationMeta.getLabel) {
+      return operationMeta.getLabel(operation, this.context.source);
+    }
+  }
+
+  /**
+   * 根据操作类型获取操作的description
+   * @param operation 操作
+   * @returns
+   */
+  getOperationDescription(operation: Operation): string | undefined {
+    const operationMeta = this.operationRegistry.getOperationMeta(operation.type);
+
+    if (operationMeta && operationMeta.getDescription) {
+      return operationMeta.getDescription(operation, this.context.source);
+    }
+  }
+
+  /**
+   * 操作取反
+   * @param operations
+   * @returns
+   */
+  inverseOperations(operations: Operation[]) {
+    return operations.map(op => this.inverseOperation(op)).reverse();
+  }
+
+  inverseOperation(op: Operation): Operation {
+    const meta = this.operationRegistry.getOperationMeta(op.type);
+
+    if (!meta) {
+      throw new Error(`Operation meta ${op.type} has not registered.`);
+    }
+    return meta.inverse(op);
+  }
+
+  dispose() {
+    this._toDispose.dispose();
+  }
+}

package/src/operation/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { StackOperation } from '../history';
+
+/**
+ * 操作
+ */
+export interface Operation<OperationValue = unknown> {
+  /**
+   * 操作的类型 如insert_node, move_node等
+   */
+  type: string;
+  /**
+   * 操作的值 外部自定义
+   */
+  value: OperationValue;
+  /**
+   * 资源唯一标志
+   */
+  uri?: string;
+  /**
+   * 操作触发源头
+   */
+  origin?: string | Symbol;
+}
+
+export type OperationWithId = Operation & { id: string };
+
+/**
+ * push操作配置
+ */
+export interface PushOperationOptions {
+  noApply?: boolean;
+}
+
+/**
+ * 操作历史
+ */
+export interface HistoryOperation extends Operation {
+  /**
+   * 唯一id
+   */
+  id: string;
+  /**
+   * 显示名称
+   */
+  label?: string;
+  /**
+   * 描述
+   */
+  description?: string;
+  /**
+   * 时间戳
+   */
+  timestamp: number;
+}
+
+/**
+ * 操作元数据
+ */
+export interface OperationMeta<OperationValue = any, Source = any, ApplyResult = any> {
+  /**
+   * 操作类型 需要唯一
+   */
+  type: string;
+  /**
+   * 将一个操作转换成另一个逆操作， 如insert转成delete
+   * @param op 操作
+   * @returns 逆操作
+   */
+  inverse: (op: Operation<OperationValue>) => Operation<OperationValue>;
+  /**
+   * 判断是否可以合并
+   * @param op 操作
+   * @param prev 上一个操作
+   * @returns true表示可以合并 返回一个操作表示直接用新操作替换之前的操作
+   */
+  shouldMerge?: (
+    op: Operation<OperationValue>,
+    prev: Operation<OperationValue> | undefined,
+    stackItem: StackOperation
+  ) => boolean | Operation;
+  /**
+   * 判断是否需要保存，如选中等操作可以不保存
+   * @param op 操作
+   * @returns true表示可以保存
+   */
+  shouldSave?: (op: Operation<OperationValue>) => boolean;
+  /**
+   * 执行操作
+   * @param operation 操作
+   */
+  apply(operation: Operation<OperationValue>, source: Source): ApplyResult | Promise<ApplyResult>;
+  /**
+   * 获取标签
+   */
+  getLabel?: (operation: Operation<OperationValue>, source: Source) => string;
+  /**
+   * 获取描述
+   */
+  getDescription?: (operation: Operation<OperationValue>, source: Source) => string;
+  /**
+   * 获取uri
+   */
+  getURI?: (operation: Operation<OperationValue>, source: Source) => string | undefined;
+}