[FEAT] BpmnElementsRegistry API returns shape incoming/outgoing (#2523)

This will facilitate the implementation of "path-related" use cases.

BREAKING CHANGES: the `BpmnSemantic` type includes new properties that
are mandatory.

Author: tbouffard

src/component/registry/bpmn-model-registry.ts

@@ -18,7 +18,7 @@ import type BpmnModel from '../../model/bpmn/internal/BpmnModel';
 import type Shape from '../../model/bpmn/internal/shape/Shape';
 import type { Edge } from '../../model/bpmn/internal/edge/edge';
 import { Flow } from '../../model/bpmn/internal/edge/flows';
-import type { BpmnSemantic, EdgeBpmnSemantic } from './types';
+import type { BaseBpmnSemantic, BpmnSemantic, EdgeBpmnSemantic, ShapeBpmnSemantic } from './types';
 import { ShapeBpmnMarkerKind, ShapeUtil } from '../../model/bpmn/internal';
 import type { ShapeBpmnSubProcess } from '../../model/bpmn/internal/shape/ShapeBpmnElement';
 import ShapeBpmnElement from '../../model/bpmn/internal/shape/ShapeBpmnElement';
@@ -44,19 +44,22 @@ export class BpmnModelRegistry {
     this.onLoadCallback = callback;
   }
 
-  getBpmnSemantic(bpmnElementId: string): BpmnSemantic | EdgeBpmnSemantic | undefined {
+  getBpmnSemantic(bpmnElementId: string): BpmnSemantic | undefined {
     const element = this.searchableModel.elementById(bpmnElementId);
     if (!element) {
       return undefined;
     }
     const bpmnElement = element.bpmnElement;
     const isShape = bpmnElement instanceof ShapeBpmnElement;
-    const semantic: BpmnSemantic = { id: bpmnElementId, name: bpmnElement.name, isShape: isShape, kind: bpmnElement.kind };
+    const semantic: BaseBpmnSemantic = { id: bpmnElementId, name: bpmnElement.name, isShape: isShape, kind: bpmnElement.kind };
     if (bpmnElement instanceof Flow) {
       (<EdgeBpmnSemantic>semantic).sourceRefId = bpmnElement.sourceRefId;
       (<EdgeBpmnSemantic>semantic).targetRefId = bpmnElement.targetRefId;
+    } else {
+      (<ShapeBpmnSemantic>semantic).incomingIds = bpmnElement.incomingIds;
+      (<ShapeBpmnSemantic>semantic).outgoingIds = bpmnElement.outgoingIds;
     }
-    return semantic;
+    return <BpmnSemantic>semantic;
   }
 }
 

src/component/registry/types.ts

@@ -19,7 +19,7 @@ import type { BpmnElementKind } from '../../model/bpmn/internal';
 /**
  * @category Custom Behavior
  */
-export interface BpmnSemantic {
+export interface BaseBpmnSemantic {
   id: string;
   name: string;
   /** `true` when relates to a BPMN Shape, `false` when relates to a BPMN Edge. */
@@ -28,13 +28,28 @@ export interface BpmnSemantic {
 }
 
 /**
- * Extended properties available when {@link BpmnSemantic.isShape} is `false`.
+ * Extended properties available when {@link BaseBpmnSemantic.isShape} is `false`.
+ * @category Custom Behavior
  */
-export interface EdgeBpmnSemantic extends BpmnSemantic {
+export interface EdgeBpmnSemantic extends BaseBpmnSemantic {
   sourceRefId: string;
   targetRefId: string;
 }
 
+/**
+ * Extended properties available when {@link BaseBpmnSemantic.isShape} is `true`.
+ * @category Custom Behavior
+ */
+export interface ShapeBpmnSemantic extends BaseBpmnSemantic {
+  incomingIds: string[];
+  outgoingIds: string[];
+}
+
+/**
+ * @category Custom Behavior
+ */
+export type BpmnSemantic = EdgeBpmnSemantic | ShapeBpmnSemantic;
+
 /**
  * @category Custom Behavior
  */

test/integration/dom.bpmn.elements.test.ts

@@ -48,7 +48,7 @@ describe('Bpmn Elements registry - retrieve BPMN elements', () => {
         const bpmnElements = bpmnVisualization.bpmnElementsRegistry.getElementsByIds(['StartEvent_1', 'Flow_2']);
         expect(bpmnElements).toHaveLength(2);
 
-        expectStartEventBpmnElement(bpmnElements[0], { id: 'StartEvent_1', name: 'Start Event 1' });
+        expectStartEventBpmnElement(bpmnElements[0], { id: 'StartEvent_1', name: 'Start Event 1', outgoing: ['Flow_1'] });
         expectSequenceFlowBpmnElement(bpmnElements[1], { id: 'Flow_2', source: 'Activity_1', target: 'EndEvent_1' });
       });
 
@@ -71,7 +71,7 @@ describe('Bpmn Elements registry - retrieve BPMN elements', () => {
         const bpmnElements = bpmnVisualization.bpmnElementsRegistry.getElementsByKinds(ShapeBpmnElementKind.TASK);
         expect(bpmnElements).toHaveLength(1);
 
-        expectTaskBpmnElement(bpmnElements[0], { id: 'Activity_1', name: 'Task 1' });
+        expectTaskBpmnElement(bpmnElements[0], { id: 'Activity_1', name: 'Task 1', incoming: ['Flow_1'], outgoing: ['Flow_2'] });
       });
 
       it('Pass a single kind related to several existing elements', async () => {

test/integration/helpers/semantic-with-svg-utils.ts

@@ -13,13 +13,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { BpmnElement, EdgeBpmnSemantic } from '../../../src/component/registry';
-import type { ExpectedBaseBpmnElement, ExpectedFlowElement } from '../../unit/helpers/bpmn-semantic-utils';
+import type { BpmnElement, EdgeBpmnSemantic, ShapeBpmnSemantic } from '../../../src/component/registry';
+import type { ExpectedBaseBpmnElement, ExpectedFlowElement, ExpectedFlowNodeElement } from '../../unit/helpers/bpmn-semantic-utils';
 import { expectEndEvent, expectPool, expectSequenceFlow, expectServiceTask, expectStartEvent, expectTask } from '../../unit/helpers/bpmn-semantic-utils';
 import { expectSvgEvent, expectSvgPool, expectSvgSequenceFlow, expectSvgTask } from './html-utils';
 
-export function expectStartEventBpmnElement(bpmnElement: BpmnElement, expected: ExpectedBaseBpmnElement): void {
-  expectStartEvent(bpmnElement.bpmnSemantic, expected);
+export function expectStartEventBpmnElement(bpmnElement: BpmnElement, expected: ExpectedFlowNodeElement): void {
+  expectStartEvent(<ShapeBpmnSemantic>bpmnElement.bpmnSemantic, expected);
   expectSvgEvent(bpmnElement.htmlElement);
 }
 
@@ -33,8 +33,8 @@ export function expectSequenceFlowBpmnElement(bpmnElement: BpmnElement, expected
   expectSvgSequenceFlow(bpmnElement.htmlElement);
 }
 
-export function expectTaskBpmnElement(bpmnElement: BpmnElement, expected: ExpectedBaseBpmnElement): void {
-  expectTask(bpmnElement.bpmnSemantic, expected);
+export function expectTaskBpmnElement(bpmnElement: BpmnElement, expected: ExpectedFlowNodeElement): void {
+  expectTask(<ShapeBpmnSemantic>bpmnElement.bpmnSemantic, expected);
   expectSvgTask(bpmnElement.htmlElement);
 }
 

test/unit/component/registry/bpmn-model-registry.test.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import type { EdgeBpmnSemantic } from '../../../../src/component/registry';
+import type { EdgeBpmnSemantic, ShapeBpmnSemantic } from '../../../../src/component/registry';
 import { BpmnModelRegistry } from '../../../../src/component/registry/bpmn-model-registry';
 import { expectAssociationFlow, expectLane, expectMessageFlow, expectPool, expectSequenceFlow, expectStartEvent } from '../../helpers/bpmn-semantic-utils';
 import { associationFlowInModel, laneInModel, messageFlowInModel, poolInModel, sequenceFlowInModel, startEventInModel } from '../../helpers/bpmn-model-utils';
@@ -47,9 +47,9 @@ describe('Bpmn Model registry', () => {
   });
 
   it('search flowNode', () => {
-    bpmnModelRegistry.load(startEventInModel('start event id', 'start event name'));
-    const bpmnSemantic = bpmnModelRegistry.getBpmnSemantic('start event id');
-    expectStartEvent(bpmnSemantic, { id: 'start event id', name: 'start event name' });
+    bpmnModelRegistry.load(startEventInModel('start event id', 'start event name', { incomingIds: ['incoming_1'], outgoingIds: ['outgoing_1', 'outgoing_2'] }));
+    const bpmnSemantic = <ShapeBpmnSemantic>bpmnModelRegistry.getBpmnSemantic('start event id');
+    expectStartEvent(bpmnSemantic, { id: 'start event id', name: 'start event name', incoming: ['incoming_1'], outgoing: ['outgoing_1', 'outgoing_2'] });
   });
 
   it('search lane', () => {

test/unit/helpers/bpmn-model-utils.ts

@@ -66,9 +66,9 @@ export const associationFlowInModel = (id: string, name: string, source: string,
   return flowInModel(newAssociationFlow, id, name, source, target);
 };
 
-export const startEventInModel = (id: string, name: string): BpmnModel => {
+export const startEventInModel = (id: string, name: string, extras?: ShapeBpmnElementExtraProperties): BpmnModel => {
   const bpmnModel = newBpmnModel();
-  bpmnModel.flowNodes.push(newStartEvent('parentId', id, name));
+  bpmnModel.flowNodes.push(newStartEvent('parentId', id, name, extras));
   return bpmnModel;
 };
 
@@ -84,8 +84,20 @@ export const poolInModel = (id: string, name: string): BpmnModel => {
   return bpmnModel;
 };
 
-const newStartEvent = (parent: string, id: string, name: string): Shape =>
-  new Shape(buildShapeId(id), new ShapeBpmnStartEvent(id, name, ShapeBpmnEventDefinitionKind.TIMER, parent));
+const withExtras = (bpmnElement: ShapeBpmnElement, extras?: ShapeBpmnElementExtraProperties): ShapeBpmnElement => {
+  bpmnElement.incomingIds = extras?.incomingIds ?? [];
+  bpmnElement.outgoingIds = extras?.outgoingIds ?? [];
+  return bpmnElement;
+};
+
+export type ShapeBpmnElementExtraProperties = {
+  incomingIds?: string[];
+  outgoingIds?: string[];
+};
+
+const newStartEvent = (parent: string, id: string, name: string, extras?: ShapeBpmnElementExtraProperties): Shape => {
+  return new Shape(buildShapeId(id), withExtras(new ShapeBpmnStartEvent(id, name, ShapeBpmnEventDefinitionKind.TIMER, parent), extras));
+};
 const newBoundaryEvent = (parent: string, id: string, name: string): Shape =>
   new Shape(buildShapeId(id), new ShapeBpmnBoundaryEvent(id, name, ShapeBpmnEventDefinitionKind.CANCEL, parent));
 

test/unit/helpers/bpmn-semantic-utils.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import type { BpmnSemantic, EdgeBpmnSemantic } from '../../../src/component/registry';
+import type { BpmnSemantic, EdgeBpmnSemantic, ShapeBpmnSemantic } from '../../../src/component/registry';
 import { FlowKind, ShapeBpmnElementKind } from '../../../src/model/bpmn/internal';
 
 export interface ExpectedBaseBpmnElement {
@@ -27,6 +27,11 @@ export interface ExpectedFlowElement extends ExpectedBaseBpmnElement {
   target: string;
 }
 
+export interface ExpectedFlowNodeElement extends ExpectedBaseBpmnElement {
+  incoming?: string[];
+  outgoing?: string[];
+}
+
 const expectFlow = (bpmnSemantic: EdgeBpmnSemantic, expected: ExpectedFlowElement): void => {
   expect(bpmnSemantic.id).toEqual(expected.id);
   expect(bpmnSemantic.name).toEqual(expected.name);
@@ -56,9 +61,15 @@ function expectShape(bpmnSemantic: BpmnSemantic, expected: ExpectedBaseBpmnEleme
   expect(bpmnSemantic.isShape).toBeTruthy();
 }
 
-export function expectStartEvent(bpmnSemantic: BpmnSemantic, expected: ExpectedBaseBpmnElement): void {
+function expectedFlowNode(bpmnSemantic: ShapeBpmnSemantic, expected: ExpectedFlowNodeElement): void {
   expectShape(bpmnSemantic, expected);
+  expect(bpmnSemantic.incomingIds).toEqual(expected.incoming ?? []);
+  expect(bpmnSemantic.outgoingIds).toEqual(expected.outgoing ?? []);
+}
+
+export function expectStartEvent(bpmnSemantic: ShapeBpmnSemantic, expected: ExpectedFlowNodeElement): void {
   expect(bpmnSemantic.kind).toEqual(ShapeBpmnElementKind.EVENT_START);
+  expectedFlowNode(bpmnSemantic, expected);
 }
 
 export function expectEndEvent(bpmnSemantic: BpmnSemantic, expected: ExpectedBaseBpmnElement): void {
@@ -76,9 +87,9 @@ export function expectPool(bpmnSemantic: BpmnSemantic, expected: ExpectedBaseBpm
   expect(bpmnSemantic.kind).toEqual(ShapeBpmnElementKind.POOL);
 }
 
-export function expectTask(bpmnSemantic: BpmnSemantic, expected: ExpectedBaseBpmnElement): void {
-  expectShape(bpmnSemantic, expected);
+export function expectTask(bpmnSemantic: ShapeBpmnSemantic, expected: ExpectedFlowNodeElement): void {
   expect(bpmnSemantic.kind).toEqual(ShapeBpmnElementKind.TASK);
+  expectedFlowNode(bpmnSemantic, expected);
 }
 
 export function expectServiceTask(bpmnSemantic: BpmnSemantic, expected: ExpectedBaseBpmnElement): void {