@flowgram.ai/history 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,639 @@
+import * as _flowgram_ai_utils from '@flowgram.ai/utils';
+import { Emitter, Disposable, DisposableCollection } from '@flowgram.ai/utils';
+import { ContainerModule } from 'inversify';
+import * as _flowgram_ai_core from '@flowgram.ai/core';
+import { PluginContext } from '@flowgram.ai/core';
+
+declare class HistoryContext {
+    /**
+     * 所属uri
+     */
+    uri?: string;
+    /**
+     * 操作触发的源对象，如编辑器对象
+     */
+    source?: unknown;
+}
+
+declare class HistoryConfig {
+    generateId: () => string;
+    getSnapshot: () => unknown;
+}
+
+declare class OperationService {
+    readonly operationRegistry: OperationRegistry;
+    readonly context: HistoryContext;
+    config: HistoryConfig;
+    readonly applyEmitter: Emitter<Operation<unknown>>;
+    readonly onApply: _flowgram_ai_utils.Event<Operation<unknown>>;
+    private _toDispose;
+    init(): void;
+    /**
+     * 执行操作
+     * @param op
+     * @returns
+     */
+    applyOperation(op: Operation, options?: {
+        noApply?: boolean;
+    }): any;
+    /**
+     * 根据操作类型获取操作的label
+     * @param operation 操作
+     * @returns
+     */
+    getOperationLabel(operation: Operation): string | undefined;
+    /**
+     * 根据操作类型获取操作的description
+     * @param operation 操作
+     * @returns
+     */
+    getOperationDescription(operation: Operation): string | undefined;
+    /**
+     * 操作取反
+     * @param operations
+     * @returns
+     */
+    inverseOperations(operations: Operation[]): Operation<unknown>[];
+    inverseOperation(op: Operation): Operation;
+    dispose(): void;
+}
+
+/**
+ * 历史栈，聚合所有历史操作
+ */
+declare class HistoryStack {
+    historyConfig: HistoryConfig;
+    private _items;
+    readonly onChangeEmitter: Emitter<HistoryStackChangeEvent>;
+    readonly onChange: _flowgram_ai_utils.Event<HistoryStackChangeEvent>;
+    private _toDispose;
+    limit: number;
+    constructor();
+    get items(): HistoryItem[];
+    add(service: HistoryService, item: HistoryStackItem): HistoryItem;
+    findById(id: string): HistoryItem | undefined;
+    changeByIndex(index: number, service: HistoryService, item: HistoryStackItem): void;
+    addOperation(service: HistoryService, id: string, op: OperationWithId): void;
+    updateOperation(service: HistoryService, id: string, op: OperationWithId): void;
+    clear(): void;
+    dispose(): void;
+    private _getHistoryItem;
+    private _getHistoryOperation;
+    static dateFormat(timestamp: number): string;
+}
+
+declare class HistoryManager implements IHistoryManager {
+    readonly historyStack: HistoryStack;
+    readonly historyConfig: HistoryConfig;
+    private _historyServices;
+    private _toDispose;
+    registerHistoryService(service: HistoryService): void;
+    unregisterHistoryService(service: HistoryService): void;
+    getHistoryServiceByURI(uri: string): HistoryService | undefined;
+    getFirstHistoryService(): HistoryService | undefined;
+    dispose(): void;
+    _handleMerge(service: HistoryService, event: HistoryMergeEvent): void;
+}
+
+declare class HistoryService implements IHistoryService {
+    readonly undoRedoService: UndoRedoService;
+    readonly operationRegistry: OperationRegistry;
+    readonly operationService: OperationService;
+    readonly context: HistoryContext;
+    readonly config: HistoryConfig;
+    historyManager: HistoryManager;
+    private _toDispose;
+    private _transacting;
+    private _transactOperation;
+    private _locked;
+    private _willDisposeEmitter;
+    private _mergeEmitter;
+    onWillDispose: _flowgram_ai_utils.Event<HistoryService>;
+    onMerge: _flowgram_ai_utils.Event<HistoryMergeEvent>;
+    get onApply(): _flowgram_ai_utils.Event<Operation<unknown>>;
+    init(): void;
+    start(): void;
+    stop(): void;
+    limit(num: number): void;
+    startTransaction(): void;
+    endTransaction(): void;
+    transact(transaction: () => void): void;
+    pushOperation(operation: Operation, options?: PushOperationOptions): any;
+    getHistoryOperations(): Operation<unknown>[];
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getSnapshot(): unknown;
+    getRecords(): Promise<HistoryRecord[]>;
+    restore(historyRecord: HistoryRecord): Promise<void>;
+    clear(): void;
+    dispose(): void;
+    private _canPush;
+    private _pushStackOperation;
+    private _shouldMerge;
+}
+
+interface HistoryRecord {
+    snapshot: any;
+    stack: any[];
+}
+interface HistoryItem extends HistoryStackItem {
+    id: string;
+    time: string;
+    operations: HistoryOperation[];
+}
+/**
+ * 历史服务管理
+ */
+interface IHistoryManager {
+    /**
+     * 注册历史服务
+     * @param service 历史服务示例
+     */
+    registerHistoryService(service: IHistoryService): void;
+    /**
+     * 取消注册历史服务
+     * @param service 历史服务示例
+     */
+    unregisterHistoryService(service: HistoryService): void;
+}
+/**
+ * 历史服务
+ */
+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;
+}
+interface IOperationService {
+    pushOperation(operation: Operation): void;
+}
+/**
+ * UndoRedo服务
+ */
+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元素
+ */
+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[];
+}
+/**
+ * 操作注册
+ */
+interface IOperationRegistry {
+    register(type: string, factory: IUndoRedoElementFactory<unknown>): void;
+}
+/**
+ * 操作工厂
+ */
+type IUndoRedoElementFactory<OperationValue> = (operation: Operation<OperationValue>) => IUndoRedoElement;
+/**
+ * undo redo 类型
+ */
+declare enum UndoRedoChangeType {
+    UNDO = "undo",
+    REDO = "redo",
+    PUSH = "push",
+    CLEAR = "clear"
+}
+/**
+ * 带element的事件
+ */
+interface UndoRedoChangeElementEvent {
+    type: UndoRedoChangeType.PUSH | UndoRedoChangeType.UNDO | UndoRedoChangeType.REDO;
+    element: IUndoRedoElement;
+}
+/**
+ * 清空事件
+ */
+interface UndoRedoClearEvent {
+    type: UndoRedoChangeType.CLEAR;
+}
+/**
+ * undo redo变化事件
+ */
+type UndoRedoChangeEvent = UndoRedoChangeElementEvent | UndoRedoClearEvent;
+interface HistoryStackItem {
+    id: string;
+    type: UndoRedoChangeType;
+    timestamp: number;
+    operations: Operation[];
+    uri?: string;
+}
+/**
+ * 历史栈变化类型
+ */
+declare enum HistoryStackChangeType {
+    ADD = "add",
+    UPDATE = "update",
+    CLEAR = "clear",
+    ADD_OPERATION = "add_operation",
+    UPDATE_OPERATION = "update_operation"
+}
+/**
+ * 历史栈变化事件基础
+ */
+interface HistoryStackBaseEvent {
+    type: HistoryStackChangeType;
+    value?: any;
+    service: HistoryService;
+}
+/**
+ * 添加历史事件
+ */
+interface HistoryStackAddEvent extends HistoryStackBaseEvent {
+    type: HistoryStackChangeType.ADD;
+    value: HistoryItem;
+}
+/**
+ * 更新历史事件
+ */
+interface HistoryStackUpdateEvent extends HistoryStackBaseEvent {
+    type: HistoryStackChangeType.UPDATE;
+    value: HistoryItem;
+}
+/**
+ * 添加操作事件
+ */
+interface HistoryStackAddOperationEvent extends HistoryStackBaseEvent {
+    type: HistoryStackChangeType.ADD_OPERATION;
+    value: {
+        historyItem: HistoryItem;
+        operation: HistoryOperation;
+    };
+}
+/**
+ * 更新操作事件
+ */
+interface HistoryStackUpdateOperationEvent extends HistoryStackBaseEvent {
+    type: HistoryStackChangeType.UPDATE_OPERATION;
+    value: {
+        historyItem: HistoryItem;
+        operation: HistoryOperation;
+    };
+}
+/**
+ * 历史记录变化事件
+ */
+type HistoryStackChangeEvent = HistoryStackAddEvent | HistoryStackUpdateEvent | HistoryStackAddOperationEvent | HistoryStackUpdateOperationEvent;
+declare enum HistoryMergeEventType {
+    ADD = "ADD",
+    UPDATE = "UPDATE"
+}
+/**
+ * 历史合并事件
+ */
+type HistoryMergeEvent = {
+    type: HistoryMergeEventType.ADD;
+    value: {
+        element: IUndoRedoElement;
+        operation: Operation;
+    };
+} | {
+    type: HistoryMergeEventType.UPDATE;
+    value: {
+        element: IUndoRedoElement;
+        operation: Operation;
+        value: any;
+    };
+};
+
+declare class UndoRedoService implements IUndoRedoService {
+    private _undoStack;
+    private _redoStack;
+    private _undoing;
+    private _redoing;
+    private _limit;
+    protected onChangeEmitter: Emitter<UndoRedoChangeEvent>;
+    readonly onChange: _flowgram_ai_utils.Event<UndoRedoChangeEvent>;
+    readonly _toDispose: DisposableCollection;
+    constructor();
+    setLimit(limit: number): void;
+    pushElement(element: IUndoRedoElement): void;
+    getUndoStack(): IUndoRedoElement[];
+    getRedoStack(): IUndoRedoElement[];
+    getLastElement(): IUndoRedoElement;
+    /**
+     * 执行undo
+     * @returns void
+     */
+    undo(): Promise<void>;
+    /**
+     * 执行redo
+     * @returns void
+     */
+    redo(): Promise<void>;
+    /**
+     * 是否可undo
+     * @returns true代表可以，false代表不可以
+     */
+    canUndo(): boolean;
+    /**
+     * 是否可redo
+     * @returns true代表可以，false代表不可以
+     */
+    canRedo(): boolean;
+    /**
+     * 是否可以push
+     * @returns true代表可以，false代表不可以
+     */
+    canPush(): boolean;
+    /**
+     * 清空
+     */
+    clear(): void;
+    /**
+     * 清空redo栈
+     */
+    clearRedoStack(): void;
+    /**
+     * 清空undo栈
+     */
+    clearUndoStack(): void;
+    /**
+     * 销毁
+     */
+    dispose(): void;
+    private _stackPush;
+    private _emitChange;
+}
+
+declare class StackOperation implements IUndoRedoElement {
+    label?: string | undefined;
+    description?: string | undefined;
+    private _operations;
+    private _toDispose;
+    private _timestamp;
+    private _operationService;
+    private _id;
+    get id(): string;
+    constructor(operationService: OperationService, operations?: Operation[]);
+    getTimestamp(): number;
+    pushOperation(operation: Operation): OperationWithId;
+    getOperations(): Operation[];
+    getChangeOperations(type: UndoRedoChangeType): Operation[];
+    getFirstOperation(): Operation;
+    getLastOperation(): Operation<unknown>;
+    undo(): Promise<void>;
+    redo(): Promise<void>;
+    revert(type: UndoRedoChangeType): void | Promise<void>;
+    private _inverse;
+    private _apply;
+    private _operation;
+    dispose(): void;
+}
+
+/**
+ * 操作
+ */
+interface Operation<OperationValue = unknown> {
+    /**
+     * 操作的类型 如insert_node, move_node等
+     */
+    type: string;
+    /**
+     * 操作的值 外部自定义
+     */
+    value: OperationValue;
+    /**
+     * 资源唯一标志
+     */
+    uri?: string;
+    /**
+     * 操作触发源头
+     */
+    origin?: string | Symbol;
+}
+type OperationWithId = Operation & {
+    id: string;
+};
+/**
+ * push操作配置
+ */
+interface PushOperationOptions {
+    noApply?: boolean;
+}
+/**
+ * 操作历史
+ */
+interface HistoryOperation extends Operation {
+    /**
+     * 唯一id
+     */
+    id: string;
+    /**
+     * 显示名称
+     */
+    label?: string;
+    /**
+     * 描述
+     */
+    description?: string;
+    /**
+     * 时间戳
+     */
+    timestamp: number;
+}
+/**
+ * 操作元数据
+ */
+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;
+}
+
+declare class OperationRegistry {
+    private readonly _operationMetas;
+    protected readonly contributions: OperationContribution[];
+    protected init(): void;
+    /**
+     * 注册操作的元数据
+     * @param operationMeta 操作的元数据
+     * @returns 销毁函数
+     */
+    registerOperationMeta(operationMeta: OperationMeta): Disposable;
+    /**
+     * 获取操作的元数据
+     * @param type 操作类型
+     * @returns 操作的元数据
+     */
+    getOperationMeta(type: string): OperationMeta | undefined;
+    private _doRegisterOperationMetaMeta;
+}
+
+declare const OperationContribution: unique symbol;
+interface OperationContribution {
+    registerOperationMeta?(operationRegistry: OperationRegistry): void;
+}
+
+declare const HistoryContainerModule: ContainerModule;
+
+interface HistoryPluginOptions<T = PluginContext> {
+    enable?: boolean;
+    onApply?: (ctx: T, operation: Operation) => void;
+}
+declare const createHistoryPlugin: _flowgram_ai_core.PluginCreator<HistoryPluginOptions<PluginContext>>;
+
+export { HistoryConfig, HistoryContainerModule, HistoryContext, type HistoryItem, HistoryManager, type HistoryMergeEvent, HistoryMergeEventType, type HistoryOperation, type HistoryPluginOptions, type HistoryRecord, HistoryService, HistoryStack, type HistoryStackAddEvent, type HistoryStackAddOperationEvent, type HistoryStackBaseEvent, type HistoryStackChangeEvent, HistoryStackChangeType, type HistoryStackItem, type HistoryStackUpdateEvent, type HistoryStackUpdateOperationEvent, type IHistoryManager, type IHistoryService, type IOperationRegistry, type IOperationService, type IUndoRedoElement, type IUndoRedoElementFactory, type IUndoRedoService, type Operation, OperationContribution, type OperationMeta, OperationRegistry, OperationService, type OperationWithId, type PushOperationOptions, StackOperation, type UndoRedoChangeElementEvent, type UndoRedoChangeEvent, UndoRedoChangeType, type UndoRedoClearEvent, UndoRedoService, createHistoryPlugin };