Improved diagram server API

Author: spoenemann

.gitignore

@@ -3,3 +3,4 @@
 node_modules/
 npm-debug.log
 yarn-error.log
+.DS_Store

examples/random-graph/src/di.config.ts

@@ -21,8 +21,7 @@ import {
     loadDefaultModules, LocalModelSource, SNode, SEdge, SLabel, configureModelElement,
     SGraph, RectangularNodeView, PolylineEdgeView
 } from 'sprotty';
-import { ElkFactory, ElkLayoutEngine } from 'sprotty-elk';
-import elkLayoutModule from 'sprotty-elk/lib/di.config';
+import { ElkFactory, ElkLayoutEngine, elkLayoutModule } from 'sprotty-elk/lib/inversify';
 
 export default (containerId: string) => {
     require('sprotty/css/sprotty.css');

packages/sprotty-elk/CHANGELOG.md

@@ -6,13 +6,15 @@ This change log covers only the `elkjs` layout of Sprotty. See also the change l
 
 The `sprotty-elk` package was moved to the main repository of Sprotty, which is now a monorepo. Furthermore, the dependency to the `sprotty` package was removed in favor of the new `sprotty-protocol` package.
 
-This package can now be used on the backend side with Node.js as well as on the frontend side.
+This package can now be used on the backend side with Node.js as well as on the frontend side:
+ * In the backend, import from `'sprotty-elk/lib/elk-layout'`. These are the plain definitions without a dependency to InversifyJS.
+ * In the frontend, import from `'sprotty-elk'` (the default export) or `'sprotty-elk/lib/inversify'`. These definitions are adapted to be used with InversifyJS.
+
+Of course you can use the InversifyJS-specific definitions in the backend as well if you plan to use that DI framework there.
 
 Breaking API changes:
- * The `elkLayoutModule` is no longer exported by the package index. Imports need to be changed to this:
-```typescript
-import elkLayoutModule from 'sprotty-elk/lib/di.config';
-```
+ * The module `di.config` was removed in favor of `inversify`, which contains all InversifyJS-specific definitions.
+ * The plain definitions in the module `elk-layout` no longer include InversifyJS annotations.
  * The `elkLayoutModule` no longer includes a binding for `TYPES.IModelLayoutEngine`. Add it like this:
 ```typescript
 bind(TYPES.IModelLayoutEngine).toService(ElkLayoutEngine);

packages/sprotty-elk/src/elk-layout.spec.ts

@@ -20,8 +20,7 @@ import { expect } from 'chai';
 import { Container } from 'inversify';
 import ElkConstructor from 'elkjs/lib/elk.bundled';
 import { SEdge, SGraph, SNode, SPort } from 'sprotty-protocol/lib/model';
-import { ElkFactory, ElkLayoutEngine } from './elk-layout';
-import elkLayoutModule from './di.config';
+import { ElkFactory, ElkLayoutEngine, elkLayoutModule } from './inversify';
 
 describe('ElkLayoutEngine', () => {
     const container = new Container();

packages/sprotty-elk/src/elk-layout.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2018 TypeFox and others.
+ * Copyright (c) 2018-2021 TypeFox 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
@@ -14,31 +14,25 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 
-import { injectable, inject } from 'inversify';
 import {
     ELK, ElkNode, ElkGraphElement, ElkEdge, ElkLabel, ElkPort, ElkShape, ElkPrimitiveEdge,
     ElkExtendedEdge, LayoutOptions
 } from 'elkjs/lib/elk-api';
-import { IModelLayoutEngine } from 'sprotty-protocol/lib/diagram-server';
+import { IModelLayoutEngine } from 'sprotty-protocol/lib/diagram-services';
 import { SEdge, SGraph, SLabel, SModelElement, SNode, SPort, SShapeElement } from 'sprotty-protocol/lib/model';
 import { Point } from 'sprotty-protocol/lib/utils/geometry';
 import { getBasicType, SModelIndex } from 'sprotty-protocol/lib/utils/model-utils';
 
-export const ElkFactory = Symbol('ElkFactory');
-export const IElementFilter = Symbol('IElementFilter');
-export const ILayoutConfigurator = Symbol('ILayoutConfigurator');
-
 /**
  * Layout engine that delegates to ELK by transforming the Sprotty graph into an ELK graph.
  */
-@injectable()
 export class ElkLayoutEngine implements IModelLayoutEngine {
 
     protected readonly elk: ELK;
 
-    constructor(@inject(ElkFactory) elkFactory: ElkFactory,
-                @inject(IElementFilter) protected readonly filter: IElementFilter,
-                @inject(ILayoutConfigurator) protected readonly configurator: ILayoutConfigurator) {
+    constructor(elkFactory: ElkFactory,
+                protected readonly filter: IElementFilter,
+                protected readonly configurator: ILayoutConfigurator) {
         this.elk = elkFactory();
     }
 
@@ -272,7 +266,6 @@ export interface IElementFilter {
     apply(element: SModelElement, index: SModelIndex): boolean
 }
 
-@injectable()
 export class DefaultElementFilter implements IElementFilter {
 
     apply(element: SModelElement, index: SModelIndex): boolean {
@@ -329,7 +322,6 @@ export interface ILayoutConfigurator {
     apply(element: SModelElement, index: SModelIndex): LayoutOptions | undefined
 }
 
-@injectable()
 export class DefaultLayoutConfigurator implements ILayoutConfigurator {
 
     apply(element: SModelElement, index: SModelIndex): LayoutOptions | undefined {

packages/sprotty-elk/src/index.ts

@@ -14,4 +14,6 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 
-export * from './elk-layout';
+// By default we export the Inversify-ready version. If you want to use the plain
+// version, import from `sprotty-elk/lib/elk-layout`.
+export * from './inversify';

packages/sprotty-elk/src/di.config.ts renamed to packages/sprotty-elk/src/inversify.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2018 TypeFox and others.
+ * Copyright (c) 2018-2021 TypeFox 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
@@ -14,11 +14,26 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 
-import { ContainerModule } from 'inversify';
+import { ContainerModule, injectable } from 'inversify';
 import {
-    ElkLayoutEngine, DefaultElementFilter, IElementFilter, DefaultLayoutConfigurator, ILayoutConfigurator
+    ElkLayoutEngine as ElkLayoutEnginePlain, DefaultElementFilter as DefaultElementFilterPlain,
+    DefaultLayoutConfigurator as DefaultLayoutConfiguratorPlain, ElkFactory as ElkFactoryPlain,
+    IElementFilter as IElementFilterPlain, ILayoutConfigurator as ILayoutConfiguratorPlain
 } from './elk-layout';
 
+export const ElkLayoutEngine: typeof ElkLayoutEnginePlain = injectable()(ElkLayoutEnginePlain);
+
+export type ElkFactory = ElkFactoryPlain;
+export const ElkFactory = Symbol('ElkFactory');
+
+export type IElementFilter = IElementFilterPlain;
+export const IElementFilter = Symbol('IElementFilter');
+export const DefaultElementFilter: typeof DefaultElementFilterPlain = injectable()(DefaultElementFilterPlain);
+
+export type ILayoutConfigurator = ILayoutConfiguratorPlain;
+export const ILayoutConfigurator = Symbol('ILayoutConfigurator');
+export const DefaultLayoutConfigurator: typeof DefaultLayoutConfiguratorPlain = injectable()(DefaultLayoutConfiguratorPlain);
+
 /**
  * This dependency injection module adds the default bindings for the frontend integration of ELK.
  * **Note:** Since this package has no direct dependency to the `sprotty` frontend package,
@@ -35,10 +50,13 @@ import {
  * You can import `ElkConstructor` from `'elkjs/lib/elk.bundled'` for the bundled variant or
  * `'elkjs/lib/elk-api'` for the webworker variant.
  */
-const elkLayoutModule = new ContainerModule(bind => {
-    bind(ElkLayoutEngine).toSelf().inSingletonScope();
+export const elkLayoutModule = new ContainerModule(bind => {
+    bind(ElkLayoutEngine).toDynamicValue(context => {
+        const elkFactory = context.container.get<ElkFactory>(ElkFactory);
+        const elementFilter = context.container.get<IElementFilter>(IElementFilter);
+        const layoutConfigurator = context.container.get<ILayoutConfigurator>(ILayoutConfigurator);
+        return new ElkLayoutEngine(elkFactory, elementFilter, layoutConfigurator);
+    }).inSingletonScope();
     bind(IElementFilter).to(DefaultElementFilter);
     bind(ILayoutConfigurator).to(DefaultLayoutConfigurator);
 });
-
-export default elkLayoutModule;

packages/sprotty-protocol/src/diagram-server.spec.ts

@@ -45,15 +45,15 @@ describe('DiagramServer', () => {
             async a => {
                 dispatched.push(a)
             }, {
-            diagramGenerator: {
+            DiagramGenerator: {
                 generate: () => {
                     return {
                         type: 'root',
                         id: 'root',
                     };
                 }
             },
-            layoutEngine: {
+            ModelLayoutEngine: {
                 layout: model => {
                     (model as SModelRoot & BoundsAware).position = { x: 10, y: 10 };
                     return model;

packages/sprotty-protocol/src/diagram-server.ts

@@ -18,18 +18,18 @@ import {
     Action, isResponseAction, ResponseAction, RequestModelAction, ComputedBoundsAction, LayoutAction, RequestBoundsAction,
     RequestAction, generateRequestId, SetModelAction, UpdateModelAction, RejectAction, isRequestAction
 } from './actions';
+import { DiagramServices, DiagramState, IDiagramGenerator, IModelLayoutEngine } from './diagram-services';
 import { SModelRoot } from './model';
 import { Deferred } from './utils/async';
-import { JsonMap } from './utils/json';
-import { applyBounds, cloneModel, SModelIndex } from './utils/model-utils';
+import { applyBounds, cloneModel } from './utils/model-utils';
 
 /**
  * An instance of this class is responsible for handling a single diagram client. It holds the current
  * state of the diagram and manages communication with the client via actions.
  */
 export class DiagramServer {
 
-    protected readonly state: DiagramState & {
+    readonly state: DiagramState & {
         lastSubmittedModelType?: string
     } = {
         currentRoot: {
@@ -38,15 +38,18 @@ export class DiagramServer {
         },
         revision: 0
     };
+    readonly dispatch: <A extends Action>(action: A) => Promise<void>;
+
+    protected readonly diagramGenerator: IDiagramGenerator;
+    protected readonly layoutEngine?: IModelLayoutEngine;
     protected readonly requests = new Map<string, Deferred<ResponseAction>>();
     protected readonly handlers = new Map<string, ServerActionHandler[]>();
-    readonly dispatch: <A extends Action>(action: A) => Promise<void>;
-    readonly services: DiagramServices;
 
     constructor(dispatch: <A extends Action>(action: A) => Promise<void>,
                 services: DiagramServices) {
         this.dispatch = dispatch;
-        this.services = services;
+        this.diagramGenerator = services.DiagramGenerator;
+        this.layoutEngine = services.ModelLayoutEngine;
     }
 
     /**
@@ -201,7 +204,7 @@ export class DiagramServer {
     protected async handleRequestModel(action: RequestModelAction): Promise<void> {
         this.state.options = action.options;
         try {
-            const newRoot = await this.services.diagramGenerator.generate({
+            const newRoot = await this.diagramGenerator.generate({
                 options: this.state.options ?? {},
                 state: this.state
             });
@@ -242,8 +245,8 @@ export class DiagramServer {
         if (newRoot.revision !== this.state.revision) {
             return;
         }
-        if (this.needsServerLayout) {
-            newRoot = await this.services.layoutEngine.layout(newRoot);
+        if (this.needsServerLayout && this.layoutEngine) {
+            newRoot = await this.layoutEngine.layout(newRoot);
         }
         const modelType = newRoot.type;
         if (cause && cause.kind === RequestModelAction.KIND) {
@@ -266,37 +269,19 @@ export class DiagramServer {
         return Promise.resolve();
     }
 
-    protected handleLayout(action: LayoutAction): Promise<void> {
+    protected async handleLayout(action: LayoutAction): Promise<void> {
+        if (!this.layoutEngine) {
+            return;
+        }
         if (!this.needsServerLayout) {
-            return Promise.resolve();
+            let newRoot = cloneModel(this.state.currentRoot);
+            newRoot = await this.layoutEngine.layout(newRoot);
+            newRoot.revision = ++this.state.revision;
+            this.state.currentRoot = newRoot;
         }
-        const newRoot = cloneModel(this.state.currentRoot);
-        newRoot.revision = ++this.state.revision;
-        this.state.currentRoot = newRoot;
-        return this.doSubmitModel(newRoot, true, action);
+        await this.doSubmitModel(this.state.currentRoot, true, action);
     }
 
 }
 
-export type DiagramOptions = JsonMap;
-
-export interface IModelLayoutEngine {
-    layout(model: SModelRoot, index?: SModelIndex): SModelRoot | Promise<SModelRoot>;
-}
-
-export interface IDiagramGenerator {
-    generate(args: { options: DiagramOptions, state: DiagramState }): SModelRoot | Promise<SModelRoot>
-}
-
-export interface DiagramServices {
-    readonly diagramGenerator: IDiagramGenerator
-    readonly layoutEngine: IModelLayoutEngine;
-}
-
-export interface DiagramState {
-    options?: DiagramOptions;
-    currentRoot: SModelRoot;
-    revision: number;
-}
-
 export type ServerActionHandler<A extends Action = Action> = (action: A, state: DiagramState, server: DiagramServer) => Promise<void>;

packages/sprotty-protocol/src/diagram-services.ts

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * Copyright (c) 2021 TypeFox 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 { SModelRoot } from './model';
+import { JsonMap } from './utils/json';
+import { SModelIndex } from './utils/model-utils';
+
+export type DiagramOptions = JsonMap;
+
+/**
+ * The current state captured by a `DiagramServer`.
+ */
+export interface DiagramState {
+    options?: DiagramOptions;
+    currentRoot: SModelRoot;
+    revision: number;
+}
+
+/**
+ * The set of services required by a `DiagramServer`.
+ */
+export interface DiagramServices {
+    readonly DiagramGenerator: IDiagramGenerator
+    readonly ModelLayoutEngine?: IModelLayoutEngine
+}
+
+/**
+ * A diagram generator is responsible for creating a diagram model from some source.
+ * This process is controlled by the `DiagramOptions`, which for example may contain
+ * a URI to the source document from which the diagram shall be created.
+ */
+export interface IDiagramGenerator {
+    generate(args: GeneratorArguments): SModelRoot | Promise<SModelRoot>
+}
+
+export interface GeneratorArguments {
+    options: DiagramOptions
+    state: DiagramState
+}
+
+/**
+ * This service is responsible for the "macro layout" of a model, that is the positioning
+ * and sizing of the main structural elements of a model. In a graph, macro layout affects
+ * positions of nodes and routings of edges, but not necessarily the layout of labels and
+ * compartments inside a node, which are often arranged on the client side ("micro layout").
+ */
+export interface IModelLayoutEngine {
+    layout(model: SModelRoot, index?: SModelIndex): SModelRoot | Promise<SModelRoot>;
+}