@eclipse-glsp/server 1.1.0-RC05

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

@@ -0,0 +1,93 @@
+/********************************************************************************
+ * 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 { 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', () => {
+            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', () => {
+            command3.execute.throwsException();
+
+            expect(() => compoundCommand.execute()).to.throw();
+
+            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', () => {
+            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', () => {
+            command1.undo.throwsException();
+
+            expect(() => compoundCommand.undo()).to.throw();
+
+            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

@@ -0,0 +1,124 @@
+/********************************************************************************
+ * Copyright (c) 2022-2023 STMicroelectronics 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 { flatPush, MaybeArray } from '@eclipse-glsp/protocol';
+
+/**
+ * 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 (e.g. source model change).
+     */
+    execute(): 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;
+
+    /**
+     * 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.
+     */
+    redo(): 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);
+    }
+
+    execute(): void {
+        const alreadyExecuted: Command[] = [];
+
+        try {
+            this.commands.forEach(command => {
+                command.execute();
+                alreadyExecuted.unshift(command);
+            });
+        } catch (err) {
+            for (const command of alreadyExecuted) {
+                if (Command.canUndo(command)) {
+                    command.undo();
+                } else {
+                    break;
+                }
+            }
+            throw err;
+        }
+    }
+
+    undo(): void {
+        const alreadyUndone: Command[] = [];
+        try {
+            [...this.commands].reverse().forEach(command => {
+                command.undo();
+                alreadyUndone.unshift(command);
+            });
+        } catch (err) {
+            alreadyUndone.forEach(command => command.redo());
+            throw err;
+        }
+    }
+
+    redo(): void {
+        const alreadyRedone: Command[] = [];
+
+        try {
+            this.commands.forEach(command => {
+                command.redo();
+                alreadyRedone.unshift(command);
+            });
+        } catch (err) {
+            alreadyRedone.forEach(command => command.undo());
+            throw err;
+        }
+    }
+
+    canUndo(): boolean {
+        return this.commands.every(Command.canUndo);
+    }
+}

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

@@ -0,0 +1,74 @@
+/********************************************************************************
+ * 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 { AnyObject } from '@eclipse-glsp/protocol';
+import { expect } from 'chai';
+import { RecordingCommand } from './recording-command';
+
+interface TestModel {
+    string: string;
+    number: number;
+    flag: boolean;
+    maybe?: AnyObject;
+}
+
+let jsonObject: TestModel;
+
+describe('RecordingCommand', () => {
+    let beforeState: TestModel;
+
+    beforeEach(() => {
+        jsonObject = {
+            string: 'foo',
+            number: 0,
+            flag: true
+        };
+        beforeState = JSON.parse(JSON.stringify(jsonObject));
+    });
+
+    it('should be undoable after execution', () => {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        const command = new RecordingCommand(jsonObject, () => {});
+        expect(command.canUndo()).to.be.false;
+        command.execute();
+        expect(command.canUndo()).to.be.true;
+    });
+
+    it('should restore the pre execution state when undo is called', () => {
+        const command = new RecordingCommand(jsonObject, () => {
+            jsonObject.string = 'bar';
+            jsonObject.flag = false;
+            jsonObject.maybe = { hello: 'world' };
+        });
+        command.execute();
+        expect(jsonObject).to.not.be.deep.equals(beforeState);
+        command.undo();
+        expect(jsonObject).to.be.deep.equals(beforeState);
+    });
+
+    it('should restore the post execution state when redo is called', () => {
+        const command = new RecordingCommand(jsonObject, () => {
+            jsonObject.string = 'bar';
+            jsonObject.flag = false;
+            jsonObject.maybe = { hello: 'world' };
+        });
+        command.execute();
+        const afterState = JSON.parse(JSON.stringify(jsonObject));
+        jsonObject = JSON.parse(JSON.stringify(afterState));
+        command.redo();
+        expect(jsonObject).to.be.deep.equals(afterState);
+    });
+});

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

@@ -0,0 +1,119 @@
+/********************************************************************************
+ * 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 { GModelRootSchema } from '@eclipse-glsp/graph';
+import { AnyObject } from '@eclipse-glsp/protocol';
+import * as jsonPatch from 'fast-json-patch';
+import { GModelSerializer } from '../features/model/gmodel-serializer';
+import { ModelState } from '../features/model/model-state';
+import { Command } from './command';
+/**
+ * An abstract implementation for {@link Command} that should records changes made to a JSON object during execution.
+ * These changes are recorded in the form of json patches.
+ */
+export abstract class AbstractRecordingCommand<JsonObject extends AnyObject> implements Command {
+    protected undoPatch?: jsonPatch.Operation[];
+    protected redoPatch?: jsonPatch.Operation[];
+
+    execute(): void {
+        const beforeState = this.deepClone(this.getJsonObject());
+        this.doExecute();
+        const afterState = this.getJsonObject();
+        this.undoPatch = jsonPatch.compare(afterState, beforeState);
+        this.redoPatch = jsonPatch.compare(beforeState, afterState);
+    }
+
+    /**
+     * Retrieves the current state of the JSON object. Is called right before and
+     * right after {@link AbstractRecordingCommand.doExecute} to derive the undo & redo patches.
+     * @returns The current state of the JSON object
+     */
+    protected abstract getJsonObject(): JsonObject;
+
+    /**
+     * The actual execution i.e. series of changes applied to the JSOn object that should be captured.
+     */
+    protected abstract doExecute(): void;
+
+    protected applyPatch(object: JsonObject, patch: jsonPatch.Operation[]): void {
+        jsonPatch.applyPatch(object, patch, false, true);
+    }
+
+    /**
+     * Captures the original state of the JSON object before executing the command routine.
+     * This implementation cannot clone circular structures as it relies on `JSON.stringify`.
+     * @param object The object that should be cloned
+     * @returns A deep clone of the given object
+     */
+    protected deepClone(object: JsonObject): JsonObject {
+        return jsonPatch.deepClone(object);
+    }
+
+    undo(): void {
+        if (this.undoPatch) {
+            this.applyPatch(this.getJsonObject(), this.undoPatch);
+        }
+    }
+
+    redo(): void {
+        if (this.redoPatch) {
+            this.applyPatch(this.getJsonObject(), this.redoPatch);
+        }
+    }
+
+    canUndo(): boolean {
+        return !!this.undoPatch && !!this.redoPatch;
+    }
+}
+
+/**
+ * Simple base implementation of {@link AbstractRecordingCommand} that records the changes made to the given JSON object during
+ * the the given `doExecute` function.
+ */
+export class RecordingCommand<JsonObject extends AnyObject = AnyObject> extends AbstractRecordingCommand<JsonObject> {
+    constructor(protected jsonObject: JsonObject, protected doExecute: () => void) {
+        super();
+    }
+
+    protected getJsonObject(): JsonObject {
+        return this.jsonObject;
+    }
+}
+
+/**
+ * Simple base implementation of {@link AbstractRecordingCommand} that allows recording of changes made
+ * to the `GModelRoot` ({@link ModelState.root}) during the given `doExecute` function
+ */
+export class GModelRecordingCommand extends AbstractRecordingCommand<GModelRootSchema> {
+    constructor(protected modelState: ModelState, protected serializer: GModelSerializer, protected doExecute: () => void) {
+        super();
+    }
+
+    override execute(): void {
+        super.execute();
+        this.modelState.index.indexRoot(this.modelState.root);
+    }
+
+    protected getJsonObject(): GModelRootSchema {
+        return this.serializer.createSchema(this.modelState.root);
+    }
+
+    protected override applyPatch(rootSchema: GModelRootSchema, patch: jsonPatch.Operation[]): void {
+        super.applyPatch(rootSchema, patch);
+        const newRoot = this.serializer.createRoot(rootSchema);
+        this.modelState.updateRoot(newRoot);
+    }
+}

package/src/common/command/undo-redo-action-handler.ts

@@ -0,0 +1,57 @@
+/********************************************************************************
+ * 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 { Action, MaybePromise, RedoAction, UndoAction } from '@eclipse-glsp/protocol';
+import { inject, injectable } from 'inversify';
+import { ActionHandler } from '../actions/action-handler';
+import { ModelSubmissionHandler } from '../features/model/model-submission-handler';
+import { CommandStack } from './command-stack';
+
+@injectable()
+export class UndoRedoActionHandler implements ActionHandler {
+    @inject(CommandStack)
+    protected commandStack: CommandStack;
+
+    @inject(ModelSubmissionHandler)
+    protected modelSubmissionHandler: ModelSubmissionHandler;
+
+    readonly actionKinds = [UndoAction.KIND, RedoAction.KIND];
+
+    execute(action: Action): MaybePromise<Action[]> {
+        if (UndoAction.is(action)) {
+            return this.undo();
+        } else if (RedoAction.is(action)) {
+            return this.redo();
+        }
+        return [];
+    }
+
+    protected undo(): MaybePromise<Action[]> {
+        if (this.commandStack.canUndo()) {
+            this.commandStack.undo();
+            return this.modelSubmissionHandler.submitModel('undo');
+        }
+        return [];
+    }
+
+    protected redo(): MaybePromise<Action[]> {
+        if (this.commandStack.canRedo()) {
+            this.commandStack.redo();
+            return this.modelSubmissionHandler.submitModel('redo');
+        }
+        return [];
+    }
+}

package/src/common/di/binding-target.spec.ts

@@ -0,0 +1,147 @@
+/********************************************************************************
+ * Copyright (c) 2022-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, interfaces } from 'inversify';
+import * as sinon from 'sinon';
+import { applyBindingTarget } from './binding-target';
+// Simple no op classes to construct inversify binding syntaxes.
+class Target {}
+
+class SubTarget extends Target {}
+
+describe('BindingTarget', () => {
+    describe('bindTarget()', () => {
+        // Setup nested spies for the fluent inversify binding API
+        let context: {
+            bind: sinon.SinonStub<[serviceIdentifier: interfaces.ServiceIdentifier<any>], interfaces.BindingToSyntax<any>>;
+            isBound: sinon.SinonStub<[serviceIdentifier: interfaces.ServiceIdentifier<any>], boolean>;
+        };
+        let toSyntax: sinon.SinonStubbedInstance<interfaces.BindingToSyntax<any>>;
+        let whenOnSyntax: sinon.SinonStubbedInstance<interfaces.BindingWhenOnSyntax<any>>;
+
+        const setupStubs = (): {
+            context: {
+                bind: sinon.SinonStub<[serviceIdentifier: interfaces.ServiceIdentifier<any>], interfaces.BindingToSyntax<any>>;
+                isBound: sinon.SinonStub<[serviceIdentifier: interfaces.ServiceIdentifier<any>], boolean>;
+            };
+            toSyntax: sinon.SinonStubbedInstance<interfaces.BindingToSyntax<any>>;
+            inWhenOnSyntax: sinon.SinonStubbedInstance<interfaces.BindingInWhenOnSyntax<any>>;
+            whenOnSyntax: sinon.SinonStubbedInstance<interfaces.BindingWhenOnSyntax<any>>;
+        } => {
+            const container = new Container();
+            const bind = sinon.stub<[serviceIdentifier: interfaces.ServiceIdentifier<any>], interfaces.BindingToSyntax<any>>();
+            const isBound = sinon.stub<[serviceIdentifier: interfaces.ServiceIdentifier<any>], boolean>();
+
+            let toSyntax: sinon.SinonStubbedInstance<interfaces.BindingToSyntax<any>> = {} as any;
+            let inWhenOnSyntax: sinon.SinonStubbedInstance<interfaces.BindingInWhenOnSyntax<any>> = {} as any;
+            container.load(
+                new ContainerModule(_bind => {
+                    const toStub = _bind('StubMe');
+                    inWhenOnSyntax = sinon.stub(toStub.to(Target));
+                    whenOnSyntax = sinon.stub(toStub.toConstantValue(''));
+                    toSyntax = sinon.stub(toStub);
+
+                    bind.returns(toSyntax);
+                    toSyntax.to.returns(inWhenOnSyntax);
+                    toSyntax.toSelf.returns(inWhenOnSyntax);
+                    toSyntax.toDynamicValue.returns(inWhenOnSyntax);
+                    toSyntax.toService.returns();
+                })
+            );
+
+            return {
+                context: { bind, isBound },
+                toSyntax,
+                inWhenOnSyntax,
+                whenOnSyntax
+            };
+        };
+
+        beforeEach(() => {
+            const stubs = setupStubs();
+            context = stubs.context;
+            toSyntax = stubs.toSyntax;
+            whenOnSyntax = stubs.whenOnSyntax;
+        });
+
+        describe('Bind to constructor', () => {
+            it('Should bind the service identifier `to` the given target with no scope', () => {
+                applyBindingTarget(context, Target, SubTarget);
+                expect(toSyntax.to.calledOnceWith(SubTarget)).to.be.true;
+            });
+
+            it('Should bind the service identifier `toSelf` with no scope', () => {
+                applyBindingTarget(context, Target, Target);
+                expect(toSyntax.toSelf.calledOnce).to.be.true;
+            });
+        });
+
+        describe('Bind to service', () => {
+            it('Should bind the service identifier `service` using the given target service with no scope', () => {
+                context.isBound.returns(true);
+                applyBindingTarget(context, Target, { service: SubTarget });
+                expect(toSyntax.toService.calledOnceWith(SubTarget)).to.be.true;
+            });
+            it('Should throw an error because the given target service is not bound', () => {
+                context.isBound.returns(false);
+                expect(() => applyBindingTarget(context, Target, { service: SubTarget, autoBind: false })).to.throw();
+            });
+            it('Should bind the unbound target service to itself before applying the toService binding', () => {
+                context.isBound.returns(false);
+                applyBindingTarget(context, Target, { service: SubTarget });
+                expect(context.bind.calledWith(Target)).to.be.true;
+            });
+            it('The return syntax should be no op and invocation of a syntax function should throw an error', () => {
+                context.isBound.returns(true);
+                const syntax = applyBindingTarget(context, Target, { service: SubTarget });
+                expect(() => {
+                    syntax.inRequestScope();
+                }).to.throw(
+                    `${Target.toString()} has been bound to 'service'.` +
+                        "Using 'in','when' or 'on' bindings after" +
+                        "a 'toService' binding is not possible."
+                );
+            });
+        });
+
+        describe('Bind to constant value', () => {
+            it('Should bind the service identifier `toConstantValue` using the given target with no scope', () => {
+                const subTarget = new SubTarget();
+                applyBindingTarget(context, Target, { constantValue: subTarget });
+                expect(toSyntax.toConstantValue.calledOnceWith(subTarget)).to.be.true;
+            });
+            it("The return syntax's in functions should be no op and invocation should log a warning", () => {
+                const spy = sinon.spy(console, 'warn');
+                const subTarget = new SubTarget();
+                const syntax = applyBindingTarget(context, Target, { constantValue: subTarget });
+                syntax.inSingletonScope();
+                expect(
+                    spy.calledWith(
+                        `${Target.toString()} has been bound to 'constantValue'. Binding in Singleton scope has no effect.` +
+                            'Constant value bindings are effectively Singleton bindings.'
+                    )
+                ).to.be.true;
+            });
+        });
+
+        describe('Bind to dynamic value', () => {
+            it('Should bind the service identifier `toDynamicValue` using the given factory function with no scope', () => {
+                applyBindingTarget(context, Target, { dynamicValue: context => new SubTarget() });
+                expect(toSyntax.toDynamicValue.calledOnce);
+            });
+        });
+    });
+});