Be able to type diagram and events

lib/Diagram.js

@@ -12,6 +12,16 @@ import CoreModule from './core';
  * } & Record<string, any> } DiagramOptions
  */
 
+/**
+ * @template T
+ * @typedef {import('didi').FactoryFunction<T>} FactoryFunction
+ */
+
+/**
+ * @template T
+ * @typedef {import('didi').ArrayFunc<T>} ArrayFunc
+ */
+
 /**
  * Bootstrap an injector from a list of modules, instantiating a number of default components
  *
@@ -30,9 +40,10 @@ function bootstrap(modules) {
 /**
  * Creates an injector from passed options.
  *
+ * @template ServiceMap
  * @param {DiagramOptions} [options]
  *
- * @return {Injector}
+ * @return {Injector<ServiceMap>}
  */
 function createInjector(options) {
 
@@ -59,6 +70,7 @@ function createInjector(options) {
  *
  * @class
  * @constructor
+ * @template [ServiceMap=null]
  *
  * @example Creating a plug-in that logs whenever a shape is added to the canvas.
  *
@@ -97,44 +109,17 @@ function createInjector(options) {
  * ```
  *
  * @param {DiagramOptions} [options]
- * @param {Injector} [injector] An (optional) injector to bootstrap the diagram with.
+ * @param {Injector<ServiceMap>} [injector] An (optional) injector to bootstrap the diagram with.
  */
 export default function Diagram(options, injector) {
 
-  this._injector = injector = injector || createInjector(options);
-
-  // API
-
-  /**
-   * Resolves a diagram service.
-   *
-   * @template T
-   *
-   * @param {string} name The name of the service to get.
-   * @param {boolean} [strict=true] If false, resolve missing services to null.
-   *
-   * @return {T|null}
-   */
-  this.get = injector.get;
-
   /**
-   * Executes a function with its dependencies injected.
-   *
-   * @template T
-   *
-   * @param {Function} func function to be invoked
-   * @param {InjectionContext} [context] context of the invocation
-   * @param {LocalsMap} [locals] locals provided
-   *
-   * @return {T|null}
+   * @type {Injector<ServiceMap>}
    */
-  this.invoke = injector.invoke;
+  this._injector = injector || createInjector(options);
 
   // init
 
-  // indicate via event
-
-
   /**
    * An event indicating that all plug-ins are loaded.
    *
@@ -157,6 +142,82 @@ export default function Diagram(options, injector) {
   this.get('eventBus').fire('diagram.init');
 }
 
+/**
+ * @overlord
+ *
+ * Resolves a diagram service.
+ *
+ * @template T
+ *
+ * @param {string} name The name of the service to get.
+ *
+ * @return {T}
+ */
+/**
+ * @overlord
+ *
+ * Resolves a diagram service.
+ *
+ * @template T
+ *
+ * @param {string} name The name of the service to get.
+ * @param {true} strict If false, resolve missing services to null.
+ *
+ * @return {T}
+ */
+/**
+ * @overlord
+ *
+ * Resolves a diagram service.
+ *
+ * @template T
+ *
+ * @param {string} name The name of the service to get.
+ * @param {boolean} strict If false, resolve missing services to null.
+ *
+ * @return {T|null}
+ */
+/**
+ * Resolves a diagram service.
+ *
+ * @template {keyof ServiceMap} Name
+ *
+ * @param {Name} name The name of the service to get.
+ *
+ * @return {ServiceMap[Name]}
+ */
+Diagram.prototype.get = function(name, strict) {
+  return this._injector.get(name, strict);
+};
+
+/**
+ * @overlord
+ *
+ * Invoke the given function, injecting dependencies. Return the result.
+ *
+ * @template T
+ *
+ * @param {FactoryFunction<T>} func
+ * @param {InjectionContext} [context]
+ * @param {LocalsMap} [locals]
+ *
+ * @return {T}
+ */
+/**
+ * Invoke the given function, injecting dependencies provided in
+ * array notation. Return the result.
+ *
+ * @template T
+ *
+ * @param {ArrayFunc<T>} func function to be invoked
+ * @param {InjectionContext} [context] context of the invocation
+ * @param {LocalsMap} [locals] locals provided
+ *
+ * @return {T}
+ */
+Diagram.prototype.invoke = function(func, context, locals) {
+  return this._injector.invoke(func, context, locals);
+};
 
 /**
  * Destroys the diagram

lib/Diagram.spec.ts

@@ -33,4 +33,23 @@ const foo = diagram.invoke((modeling: Modeling, eventBus: EventBus) => {
   };
 });
 
-foo.bar = false;
+foo.bar = false;
+
+type NoneEvent = {};
+
+type EventMap = {
+  'diagram.init': NoneEvent
+};
+
+type ServiceMap = {
+  'eventBus': EventBus<EventMap>
+};
+
+const typedDiagram = new Diagram<ServiceMap>();
+
+const eventBus = typedDiagram.get('eventBus');
+
+eventBus.on('diagram.init', (event) => {
+
+  // go forth and react to init (!)
+});

lib/core/EventBus.js

@@ -118,6 +118,8 @@ var slice = Array.prototype.slice;
  * var sum = eventBus.fire('sum', 1, 2);
  * console.log(sum); // 3
  * ```
+ *
+ * @template [EventMap=null]
  */
 export default function EventBus() {
 
@@ -131,8 +133,9 @@ export default function EventBus() {
   this.on('diagram.destroy', 1, this._destroy, this);
 }
 
-
 /**
+ * @overlord
+ *
  * Register an event listener for events with the given name.
  *
  * The callback will be invoked with `event, ...additionalArguments`
@@ -151,6 +154,25 @@ export default function EventBus() {
  * @param {EventBusEventCallback<T>} callback
  * @param {any} [that] callback context
  */
+/**
+ * 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} EventName
+ *
+ * @param {EventName} events to subscribe to
+ * @param {number} [priority=1000] listen priority
+ * @param {EventBusEventCallback<EventMap[EventName]>} callback
+ * @param {any} [that] callback context
+ */
 EventBus.prototype.on = function(events, priority, callback, that) {
 
   events = isArray(events) ? events : [ events ];
@@ -188,6 +210,8 @@ EventBus.prototype.on = function(events, priority, callback, that) {
 };
 
 /**
+ * @overlord
+ *
  * Register an event listener that is called only once.
  *
  * @template T
@@ -197,6 +221,16 @@ EventBus.prototype.on = function(events, priority, callback, that) {
  * @param {EventBusEventCallback<T>} callback
  * @param {any} [that] callback context
  */
+/**
+ * Register an event listener that is called only once.
+ *
+ * @template {keyof EventMap} EventName
+ *
+ * @param {EventName} events to subscribe to
+ * @param {number} [priority=1000] listen priority
+ * @param {EventBusEventCallback<EventMap[EventName]>} callback
+ * @param {any} [that] callback context
+ */
 EventBus.prototype.once = function(events, priority, callback, that) {
   var self = this;
 

lib/core/EventBus.spec.ts

@@ -59,3 +59,22 @@ eventBus.once('foo', callback, this);
 eventBus.once('foo', (event, additional1, additional2) => {
   console.log('foo', event, additional1, additional2);
 });
+
+
+type EventMap = {
+  foo: FooEvent
+};
+
+const typedEventBus = new EventBus<EventMap>();
+
+typedEventBus.on('foo', (event: FooEvent) => {
+  const { foo } = event;
+
+  console.log(foo);
+});
+
+typedEventBus.on('foo', (event) => {
+  const { foo } = event;
+
+  console.log(foo);
+});