WIP :GENERATE TYPES

lib/BaseViewer.js

@@ -31,6 +31,12 @@ import {
   importBpmnDiagram
 } from './import/Importer';
 
+/**
+ * @template T
+ *
+ * @typedef { import('diagram-js/lib/core/EventBus').default<T> } EventBus
+ */
+
 /**
  * @template T
  *
@@ -116,9 +122,19 @@ import {
  * } } SaveSVGDoneEvent
  */
 
+/**
+ * @template Type
+ *
+ * @typedef { Type extends { eventBus: EventBus<infer X> } ? X : never } EventMap
+ */
+
 /**
  * A base viewer for BPMN 2.0 diagrams.
  *
+ * @template [ServiceMap=null]
+ *
+ * @extends Diagram<ServiceMap>
+ *
  * Have a look at {@link Viewer}, {@link NavigatedViewer} or {@link Modeler} for
  * bundles that include actual features.
  *
@@ -542,9 +558,18 @@ BaseViewer.prototype.destroy = function() {
 };
 
 /**
- * Register an event listener.
+ * @overlord
  *
- * Remove an event listener via {@link BaseViewer#off}.
+ * Register an event listener for events with the given name.
+ *
+ * The callback will be invoked with `event, ...additionalArguments`
+ * that have been passed to {@link EventBus#fire}.
+ *
+ * Returning false from a listener will prevent the events default action
+ * (if any is specified). To stop an event from being processed further in
+ * other listeners execute {@link Event#stopPropagation}.
+ *
+ * Returning anything but `undefined` from a listener will stop the listener propagation.
  *
  * @template T
  *
@@ -553,6 +578,25 @@ BaseViewer.prototype.destroy = function() {
  * @param {EventBusEventCallback<T>} callback The callback.
  * @param {any} [that] Value of `this` the callback will be called with.
  */
+/**
+ * Register an event listener for events with the given name.
+ *
+ * The callback will be invoked with `event, ...additionalArguments`
+ * that have been passed to {@link EventBus#fire}.
+ *
+ * Returning false from a listener will prevent the events default action
+ * (if any is specified). To stop an event from being processed further in
+ * other listeners execute {@link Event#stopPropagation}.
+ *
+ * Returning anything but `undefined` from a listener will stop the listener propagation.
+ *
+ * @template {keyof EventMap<ServiceMap>} EventName
+ *
+ * @param {EventName} events to subscribe to
+ * @param {number} [priority=1000] listen priority
+ * @param {EventBusEventCallback<(EventMap<ServiceMap>)[EventName]>} callback
+ * @param {any} [that] callback context
+ */
 BaseViewer.prototype.on = function(events, priority, callback, that) {
   return this.get('eventBus').on(events, priority, callback, that);
 };

lib/BaseViewer.spec.ts

@@ -1,6 +1,6 @@
 import CommandStack from 'diagram-js/lib/command/CommandStack';
 
-import { Event } from 'diagram-js/lib/core/EventBus';
+import EventBus, { Event } from 'diagram-js/lib/core/EventBus';
 
 import BaseViewer, {
   ImportDoneEvent,
@@ -11,6 +11,7 @@ import BaseViewer, {
 } from './BaseViewer';
 
 import OverlaysModule from 'diagram-js/lib/features/overlays';
+import Canvas from 'diagram-js/lib/core/Canvas';
 
 const viewer = new BaseViewer();
 
@@ -170,4 +171,31 @@ export function testViewer(viewer: BaseViewer) {
   });
 
   viewer.on<Event>('detach', () => {});
-}
+}
+
+// typed API usage
+
+type FooEvent = {
+  foo: string;
+};
+
+type EventMap = {
+  foo: FooEvent
+};
+
+type TypeMap = {
+  canvas: Canvas,
+  eventBus: EventBus<EventMap>
+};
+
+const typedViewer = new BaseViewer<TypeMap>();
+
+const bus = typedViewer.get('eventBus');
+
+const canvas = typedViewer.get('canvas');
+
+canvas.zoom('fit-viewport');
+
+typedViewer.on('foo', event => {
+  console.log(event.foo);
+});