@eclipse-glsp/server 1.1.0-next.3d7585d.42 → 1.1.0-next.42963d6.55

package/src/common/command/command-stack.spec.ts

@@ -0,0 +1,239 @@
+/********************************************************************************
+ * Copyright (c) 2023 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import { expect } from 'chai';
+import { Container, ContainerModule } from 'inversify';
+import * as sinon from 'sinon';
+import { expectToThrowAsync, StubCommand, StubLogger } from '../test/mock-util';
+import { Logger } from '../utils/logger';
+import { DefaultCommandStack } from './command-stack';
+
+describe('test DefaultCommandStack', () => {
+    const sandbox = sinon.createSandbox();
+    const container = new Container();
+
+    const command1 = sandbox.stub(new StubCommand());
+    const command2 = sandbox.stub(new StubCommand());
+    let commandStack: DefaultCommandStack;
+
+    container.load(
+        new ContainerModule(bind => {
+            bind(Logger).toConstantValue(new StubLogger());
+        })
+    );
+    commandStack = container.resolve(DefaultCommandStack);
+
+    afterEach(() => {
+        sandbox.reset();
+        commandStack = container.resolve(DefaultCommandStack);
+    });
+
+    describe('execute', () => {
+        it('should execute the given command and become dirty', async () => {
+            expect(commandStack.isDirty).to.be.false;
+            await commandStack.execute(command1);
+            expect(command1.execute.calledOnce).to.be.true;
+            expect(commandStack.isDirty).to.be.true;
+        });
+
+        it('should execute the given commands in order and become dirty', async () => {
+            expect(commandStack.isDirty).to.be.false;
+            await commandStack.execute(command1);
+            await commandStack.execute(command2);
+
+            expect(command1.execute.calledOnce).to.be.true;
+            expect(command2.execute.calledOnce).to.be.true;
+            expect(command2.execute.calledAfter(command1.execute)).to.be.true;
+            expect(commandStack.isDirty).to.be.true;
+        });
+
+        it('should be able to undo after execute', async () => {
+            expect(commandStack.canUndo()).to.be.false;
+            await commandStack.execute(command1);
+            expect(commandStack.canUndo()).to.be.true;
+        });
+
+        it('should clear the redo stack after execution', async () => {
+            commandStack['commands'].push(command2);
+            commandStack['top'] = -1;
+            expect(commandStack.canRedo()).to.be.true;
+
+            await commandStack.execute(command1);
+            expect(commandStack.canRedo()).to.be.false;
+        });
+
+        it('should flush the stack in case of an execution error', async () => {
+            command2.execute.throwsException();
+            const flushSpy = sandbox.spy(commandStack, 'flush');
+
+            await expectToThrowAsync(() => commandStack.execute(command2));
+            expect(command2.execute.calledOnce).to.be.true;
+            expect(flushSpy.calledOnce).to.be.true;
+        });
+    });
+
+    describe('undo', () => {
+        it('should do nothing if the command stack is empty', async () => {
+            expect(commandStack.isDirty).to.be.false;
+
+            await commandStack.undo();
+            expect(commandStack.canUndo()).to.be.false;
+            expect(commandStack.canRedo()).to.be.false;
+            expect(commandStack.isDirty).to.be.false;
+        });
+
+        it('should undo the command and become non-dirty again', async () => {
+            commandStack['commands'].push(command1);
+            commandStack['top'] = 0;
+            expect(commandStack.isDirty).to.be.true;
+            expect(commandStack.canUndo()).to.be.true;
+            expect(commandStack.canRedo()).to.be.false;
+
+            await commandStack.undo();
+            expect(command1.undo.calledOnce).to.be.true;
+            expect(commandStack.isDirty).to.be.false;
+            expect(commandStack.canRedo()).to.be.true;
+            expect(commandStack.canUndo()).to.be.false;
+        });
+
+        it('should undo multiple command and become non-dirty again', async () => {
+            commandStack['commands'].push(command1, command2);
+            commandStack['top'] = 1;
+            expect(commandStack.isDirty).to.be.true;
+            expect(commandStack.canUndo()).to.be.true;
+            expect(commandStack.canRedo()).to.be.false;
+
+            await commandStack.undo();
+            expect(command2.undo.calledOnce).to.be.true;
+            expect(commandStack.canRedo()).to.be.true;
+            expect(commandStack.canUndo()).to.be.true;
+            expect(commandStack.isDirty).to.be.true;
+
+            await commandStack.undo();
+            expect(command1.undo.calledOnce).to.be.true;
+            expect(command1.undo.calledAfter(command2.undo)).to.be.true;
+            expect(commandStack.isDirty).to.be.false;
+            expect(commandStack.canRedo()).to.be.true;
+            expect(commandStack.canUndo()).to.be.false;
+        });
+        it('should flush the stack in case of an execution error', async () => {
+            command2.undo.throwsException();
+            const flushSpy = sandbox.spy(commandStack, 'flush');
+            commandStack['commands'].push(command2);
+            commandStack['top'] = 0;
+
+            await expectToThrowAsync(() => commandStack.undo());
+            expect(command2.undo.calledOnce).to.be.true;
+            expect(flushSpy.calledOnce).to.be.true;
+        });
+    });
+
+    describe('redo', () => {
+        it('should do nothing if the command stack is empty', async () => {
+            expect(commandStack.isDirty).to.be.false;
+
+            await commandStack.redo();
+            expect(commandStack.canUndo()).to.be.false;
+            expect(commandStack.canRedo()).to.be.false;
+            expect(commandStack.isDirty).to.be.false;
+        });
+
+        it('should redo the command and become dirty again', async () => {
+            commandStack['commands'].push(command1);
+            commandStack['top'] = -1;
+            expect(commandStack.isDirty).to.be.false;
+            expect(commandStack.canUndo()).to.be.false;
+            expect(commandStack.canRedo()).to.be.true;
+
+            await commandStack.redo();
+            expect(command1.redo.calledOnce).to.be.true;
+            expect(commandStack.isDirty).to.be.true;
+            expect(commandStack.canRedo()).to.be.false;
+            expect(commandStack.canUndo()).to.be.true;
+        });
+
+        it('should undo multiple command and become non-dirty again', async () => {
+            commandStack['commands'].push(command2, command1);
+            commandStack['top'] = -1;
+            commandStack['saveIndex'] = -1;
+            expect(commandStack.isDirty).to.be.false;
+            expect(commandStack.canUndo()).to.be.false;
+            expect(commandStack.canRedo()).to.be.true;
+
+            await commandStack.redo();
+            expect(command2.redo.calledOnce).to.be.true;
+            expect(commandStack.canRedo()).to.be.true;
+            expect(commandStack.canUndo()).to.be.true;
+            expect(commandStack.isDirty).to.be.true;
+
+            await commandStack.redo();
+            expect(command1.redo.calledOnce).to.be.true;
+            expect(command1.redo.calledAfter(command2.redo)).to.be.true;
+            expect(commandStack.isDirty).to.be.true;
+            expect(commandStack.canRedo()).to.be.false;
+            expect(commandStack.canUndo()).to.be.true;
+        });
+        it('should flush the stack in case of an execution error', async () => {
+            command2.redo.throwsException();
+            const flushSpy = sandbox.spy(commandStack, 'flush');
+            commandStack['commands'].push(command2);
+            commandStack['top'] = -1;
+
+            await expectToThrowAsync(() => commandStack.redo());
+            expect(command2.redo.calledOnce).to.be.true;
+            expect(flushSpy.calledOnce).to.be.true;
+        });
+        it('should be able to undo after redo', async () => {
+            commandStack['commands'].push(command1);
+            commandStack['top'] = -1;
+            expect(commandStack.canUndo()).to.be.false;
+            await commandStack.redo();
+            expect(commandStack.canUndo()).to.be.true;
+        });
+    });
+
+    describe('flush', () => {
+        it('should reset the internal state of the command stack', () => {
+            commandStack['commands'].push(command1, command1);
+            commandStack['top'] = 0;
+
+            commandStack.flush();
+            expect(commandStack.isDirty).to.be.false;
+            expect(commandStack.canUndo()).to.be.false;
+            expect(commandStack.canRedo()).to.be.false;
+        });
+    });
+
+    describe('isSaveDone', () => {
+        it('should become non-dirty after execution', () => {
+            commandStack['commands'].push(command1);
+            commandStack['top'] = 0;
+            expect(commandStack.isDirty).to.be.true;
+
+            commandStack.saveIsDone();
+            expect(commandStack.isDirty).to.be.false;
+        });
+        it('should maintain undo/redo history after execution', () => {
+            commandStack['commands'].push(command1, command2);
+            commandStack['top'] = 0;
+            expect(commandStack.canUndo()).to.be.true;
+            expect(commandStack.canRedo()).to.be.true;
+
+            commandStack.saveIsDone();
+            expect(commandStack.canUndo()).to.be.true;
+            expect(commandStack.canRedo()).to.be.true;
+        });
+    });
+});

package/src/common/command/command-stack.ts

@@ -13,62 +13,148 @@
  *
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
-import { injectable } from 'inversify';
+import { MaybePromise } from '@eclipse-glsp/protocol';
+import { inject, injectable } from 'inversify';
+import { Logger } from '../utils/logger';
 import { Command } from './command';
 
 export const CommandStack = Symbol('CommandStack');
 
 /**
- * A basic implementation of an undoable stack of commands.
- * See {@link Command} for more details about the command methods that this implementation uses.
+ * A command stack keeps track of {@link Command commands} that have been executed.
+ * Executed commands can be undone in the reverse order of their original execution.
+ * Unless a new command has been executed after an undo operation, commands can be
+ * redone in the original order of their execution.
+ *
  */
 export interface CommandStack {
     /**
-     * Clears any redoable commands not yet redone, adds the command, and then executes the command.
+     * Clears any redoable commands not yet redone, adds the command to the stack and then invokes {@link Command.execute}.
      * @param command the command to execute.
      */
-    execute(command: Command): void;
+    execute(command: Command): MaybePromise<void>;
+
+    /**
+     * Removes the topmost (i.e. last executed) command from the stack and invokes {@link Command.undo}.
+     */
+    undo(): MaybePromise<void>;
 
     /**
-     * Moves the top of the stack down, undoing what was formerly the top command.
+     * Returns `true` if the top command on the stack can be undone.
      */
-    undo(): void;
+    canUndo(): boolean;
 
     /**
-     * Moves the top of the stack up, redoing the new top command.
+     * Re-adds the last undo command on top of the stack and invokes {@link Command.redo}
      */
-    redo(): void;
+    redo(): MaybePromise<void>;
 
     /**
-     * The command stack has currently unsaved changes.
+     * Returns `true` if there are  redoable commands in the stack.
      */
-    isDirty(): boolean;
+    canRedo(): boolean;
 
     /**
      * Called after a save has been successfully performed.
      */
     saveIsDone(): void;
+
+    /**
+     * Indicates wether the command stack has unsaved changes.
+     */
+    readonly isDirty: boolean;
+
+    /**
+     * Disposes all the commands in the stack.
+     */
+    flush(): void;
 }
 
 @injectable()
 export class DefaultCommandStack implements CommandStack {
-    execute(command: Command): void {
-        // no-op
+    @inject(Logger)
+    protected logger: Logger;
+
+    protected commands: Command[] = [];
+
+    /**
+     * The current position within the command list from which the next execute, undo, or redo, will be performed.
+     */
+    protected top = -1;
+
+    /**
+     * The current position within the command list when {@link DefaultCommandStack.saveIsDone} is called.
+     */
+    protected saveIndex = -1;
+
+    async execute(command: Command): Promise<void> {
+        try {
+            await command.execute();
+        } catch (error) {
+            this.handleError(error);
+        }
+        // Clear the command list past the top (i.e. the old redo list)
+        this.commands = this.commands.slice(0, this.top + 1);
+        this.commands.push(command);
+        ++this.top;
+
+        // if the saveIndex points to the old redo list we can never reach a state again
+        // where save is not necessary. => ensure that `isDirty` always returns true
+        if (this.saveIndex >= this.top) {
+            this.saveIndex = -2;
+        }
+    }
+
+    async undo(): Promise<void> {
+        if (this.canUndo()) {
+            const command = this.commands[this.top--];
+            try {
+                await command.undo();
+            } catch (error) {
+                this.handleError(error);
+            }
+        }
     }
 
-    undo(): void {
-        // no-op
+    canUndo(): boolean {
+        return this.top !== -1 //
+            ? Command.canUndo(this.commands[this.top])
+            : false;
     }
 
-    redo(): void {
-        // no-op
+    async redo(): Promise<void> {
+        if (this.canRedo()) {
+            const command = this.commands[++this.top];
+            try {
+                await command.redo();
+            } catch (error) {
+                this.handleError(error);
+            }
+        }
     }
 
-    isDirty(): boolean {
-        return false;
+    canRedo(): boolean {
+        return this.top < this.commands.length - 1;
+    }
+
+    get isDirty(): boolean {
+        return this.saveIndex !== this.top;
     }
 
     saveIsDone(): void {
-        // no-op
+        this.saveIndex = this.top;
+    }
+
+    flush(): void {
+        this.commands = [];
+        this.top = -1;
+        this.saveIndex = -1;
+    }
+
+    protected handleError(error: any): never {
+        // if an error occurred during the command execution the stack might be in an erroneous state => we have to flush the command stack
+        this.flush();
+        this.logger.error('An error occurred during command execution. CommandStack will be flushed!', error);
+        throw error;
     }
 }

package/src/common/command/command.spec.ts

@@ -0,0 +1,92 @@
+/********************************************************************************
+ * Copyright (c) 2023 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import { expect } from 'chai';
+import * as sinon from 'sinon';
+import { expectToThrowAsync, StubCommand } from '../test/mock-util';
+import { CompoundCommand } from './command';
+
+describe('CompoundCommand', () => {
+    const sandbox = sinon.createSandbox();
+
+    const command1 = sandbox.stub(new StubCommand());
+    const command2 = sandbox.stub(new StubCommand());
+    const command3 = sandbox.stub(new StubCommand());
+
+    const compoundCommand = new CompoundCommand(command1, command2, command3);
+
+    afterEach(() => {
+        sandbox.reset();
+    });
+
+    describe('execute', () => {
+        it('Should execute the subcommands in order', async () => {
+            await compoundCommand.execute();
+            expect(command1.execute.calledOnce).to.be.true;
+            expect(command2.execute.calledOnce).to.be.true;
+            expect(command3.execute.calledOnce).to.be.true;
+            expect(command1.execute.calledBefore(command2.execute)).to.be.true;
+            expect(command2.execute.calledBefore(command3.execute)).to.be.true;
+        });
+        it('Should undo partially executed subcommands in  case of an error', async () => {
+            command3.execute.throwsException();
+
+            await expectToThrowAsync(() => compoundCommand.execute());
+
+            expect(command1.execute.calledOnce).to.be.true;
+            expect(command2.execute.calledOnce).to.be.true;
+            expect(command3.execute.calledOnce).to.be.true;
+            expect(command1.undo.calledOnce).to.be.true;
+            expect(command2.undo.calledOnce).to.be.true;
+        });
+    });
+
+    describe('undo', () => {
+        it('Should undo the subcommands in reverse order', async () => {
+            await compoundCommand.undo();
+            expect(command1.undo.calledOnce).to.be.true;
+            expect(command2.undo.calledOnce).to.be.true;
+            expect(command3.undo.calledOnce).to.be.true;
+            expect(command1.undo.calledAfter(command2.undo)).to.be.true;
+            expect(command2.undo.calledAfter(command3.undo)).to.be.true;
+        });
+
+        it('Should redo partially undone subcommands in  case of an error', async () => {
+            command1.undo.throwsException();
+            await expectToThrowAsync(() => compoundCommand.undo());
+
+            expect(command1.undo.calledOnce).to.be.true;
+            expect(command2.undo.calledOnce).to.be.true;
+            expect(command3.undo.calledOnce).to.be.true;
+            expect(command3.redo.calledOnce).to.be.true;
+            expect(command2.redo.calledOnce).to.be.true;
+        });
+    });
+
+    describe('canUndo', () => {
+        it('should return true if all subcommands can be undone', () => {
+            command1.canUndo?.returns(true);
+            command2.canUndo?.returns(true);
+            command3.canUndo?.returns(true);
+            expect(compoundCommand.canUndo()).to.be.true;
+        });
+        it('should return true if anyof the  subcommands cannot be undone', () => {
+            command1.canUndo?.returns(true);
+            command2.canUndo?.returns(false);
+            command3.canUndo?.returns(true);
+            expect(compoundCommand.canUndo()).to.be.true;
+        });
+    });
+});

package/src/common/command/command.ts

@@ -14,26 +14,115 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 
+import { flatPush, MaybeArray, MaybePromise } from '@eclipse-glsp/protocol';
+
 /**
- * An interface that every command is expected to support.
- * A command can be executed, it can be undone, and can then be redone.
+ * A command implements a specific modification of the source model, which can be applied by invoking `execute()`.
+ * Commands may also provide implementations to `undo()` and `redo()` the effect they had.
+ * To maintain an order in which commands can be undone and redone, they are managed in the context of a {@link CommandStack}.
+ *
+ * Each command is self contained and stores all the information it needs to execute, undo or redo itself.
+ *
+ * In theory commands can be used to execute arbitrary activities and not only modify the source model.
+ * However, it is mostly used to record and manage changes made to the source model via GLSP operations.
  */
 export interface Command {
     /**
-     * Performs the command activity required for the effect.
+     * Performs the command activity required for the effect (e.g. source model change).
      */
-    execute(): void;
+    execute(): MaybePromise<void>;
 
     /**
      * Performs the command activity required to `undo` the effects of a preceding `execute` (or `redo`).
      * The effect, if any, of calling `undo` before `execute` or `redo` have been called, is undefined.
      */
-    undo(): void;
+    undo(): MaybePromise<void>;
 
     /**
      * Performs the command activity required to `redo` the effect after undoing the effect.
      * The effect, if any, of calling `redo` before `undo` is called is undefined.
-     * Note that if you implement `redo` to call `execute` then any derived class will be restricted by that decision also.
      */
-    redo(): void;
+    redo(): MaybePromise<void>;
+
+    /**
+     * Returns whether the command can be undone.
+     * This function is optional. If not implemented, it is assumed that the command can be undone.
+     * @returns whether the command can be undone
+     */
+    canUndo?(): boolean;
+}
+
+export namespace Command {
+    export function canUndo(command: Command): boolean {
+        return command.canUndo?.() ?? true;
+    }
+}
+
+/**
+ * A command that comprises a sequence of subcommands.
+ */
+export class CompoundCommand implements Command {
+    protected readonly commands: Command[];
+
+    constructor(commands: Command[]);
+    constructor(...commands: Command[]);
+    constructor(...commands: MaybeArray<Command>[]) {
+        this.commands = [];
+        flatPush(this.commands, commands);
+    }
+
+    async execute(): Promise<void> {
+        const alreadyExecuted: Command[] = [];
+
+        try {
+            for (const command of this.commands) {
+                await command.execute();
+                alreadyExecuted.unshift(command);
+            }
+        } catch (err) {
+            for (const command of alreadyExecuted) {
+                if (Command.canUndo(command)) {
+                    await command.undo();
+                } else {
+                    break;
+                }
+            }
+            throw err;
+        }
+    }
+
+    async undo(): Promise<void> {
+        const alreadyUndone: Command[] = [];
+        try {
+            for (const command of [...this.commands].reverse()) {
+                await command.undo();
+                alreadyUndone.unshift(command);
+            }
+        } catch (err) {
+            for (const command of alreadyUndone) {
+                await command.redo();
+            }
+            throw err;
+        }
+    }
+
+    async redo(): Promise<void> {
+        const alreadyRedone: Command[] = [];
+
+        try {
+            for (const command of this.commands) {
+                await command.redo();
+                alreadyRedone.unshift(command);
+            }
+        } catch (err) {
+            for (const command of alreadyRedone) {
+                await command.undo();
+            }
+            throw err;
+        }
+    }
+
+    canUndo(): boolean {
+        return this.commands.every(Command.canUndo);
+    }
 }