Reworking addEventListener to avoid union types in .NET, events now inherit from a common ancestor ApiEvent

Author: kriswest

docs/api/ref/DesktopAgent.md

@@ -41,7 +41,7 @@ interface DesktopAgent {
   leaveCurrentChannel() : Promise<void>;
 
   // non-context events 
-  addEventListener(type: FDC3EventType  | null, handler: EventHandler): Promise<Listener>;
+  addEventListener(type: FDC3EventTypes  | null, handler: EventHandler): Promise<Listener>;
 
   //implementation info
   getInfo(): Promise<ImplementationMetadata>;
@@ -96,7 +96,7 @@ const contactListener = await fdc3.addContextListener('fdc3.contact', (contact,
 
 ### `addEventListener`
 ```ts
-addEventListener(type: FDC3EventType  | null, handler: EventHandler): Promise<Listener>;
+addEventListener(type: FDC3EventTypes  | null, handler: EventHandler): Promise<Listener>;
 ```
 
 Registers a handler for non-context and non-intent events from the Desktop Agent. If the consumer is only interested in an event of a particular type, they can specify that type. If the consumer is able to receive events of any type or will inspect types received, then they can pass `null` as the `type` parameter to receive all event types.
@@ -110,13 +110,17 @@ Whenever the handler function is called it will be passed an event object with d
 const listener = await fdc3.addEventListener(null, event => { ... });
 
 // listener for a specific event type that logs its details
-const userChannelChangedListener = await fdc3.addEventListener(FDC3EventType.USER_CHANNEL_CHANGED, event => { 
+const userChannelChangedListener = await fdc3.addEventListener("USER_CHANNEL_CHANGED", event => { 
   console.log(`Received event ${event.type}\n\tDetails: ${event.details}`);
   //do something else with the event
 });
-````
+```
 
+**See also:**
 
+- [`FDC3EventTypes`](./Events#fdc3eventtypes)
+- [`FDC3Event`](./Events#fdc3event)
+- [`EventHandler`](./Events#eventhandler)
 
 ### `addIntentListener`
 

docs/api/ref/Events.md

@@ -4,10 +4,26 @@ title: Events
 
 In addition to intent and context events, the FDC3 API and PrivateChannel API may be used to listen for other types of events via their `addEventListener()` functions.
 
+## `ApiEvent`
+
+Type defining a basic event object that may be emitted by an FDC3 API interface such as DesktopAgent or PrivateChannel. There are more specific event types defined for each interface.
+
+```ts
+interface ApiEvent {
+  readonly type: string;
+  readonly details: any;
+}
+```
+
+**See also:**
+
+- [`FDC3Event`](#fdc3event)
+- [`PrivateChannelEvent`](#privatechannelevent)
+
 ## `EventHandler`
 
 ```ts
-type EventHandler = (event: FDC3Event | PrivateChannelEvent) => void;
+type EventHandler = (event: ApiEvent) => void;
 ```
 
 Describes a callback that handles non-context and non-intent events. Provides the details of the event.
@@ -16,28 +32,27 @@ Used when attaching listeners to events.
 
 **See also:**
 
-- [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener)
-- [`FDC3Event`](#fdc3event)
+- [`DesktopAgent.addEventListener`](DesktopAgent#addeventlistener)
+- [`PrivateChannel.addEventListener`](PrivateChannel#addeventlistener)
+- [`ApiEvent`](#apievent)
 
-## `FDC3EventType`
+## `FDC3EventTypes`
 
 ```ts
-enum FDC3EventType {
-  USER_CHANNEL_CHANGED = "USER_CHANNEL_CHANGED"
-}
+type FDC3EventTypes = "USER_CHANNEL_CHANGED";
 ```
 
-Enumeration defining the types of (non-context and non-intent) events that may be received via the FDC3 API's `addEventListener` function.
+Type defining valid type strings for DesktopAgent interface events.
 
 **See also:**
 
-- [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener)
+- [`DesktopAgent.addEventListener`](DesktopAgent#addeventlistener)
 
 ## `FDC3Event`
 
 ```ts
-interface FDC3Event {
-  readonly type: FDC3EventType;
+interface FDC3Event extends ApiEvent{
+  readonly type: FDC3EventTypes;
   readonly details: any;
 }
 ```
@@ -48,14 +63,14 @@ Events will always include both `type` and `details` properties, which describe
 
 **See also:**
 
-- [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener)
-- [`FDC3EventType`](#fdc3eventtype)
+- [`DesktopAgent.addEventListener`](DesktopAgent#addeventlistener)
+- [`FDC3EventTypes`](#fdc3eventtypes)
 
 ### `FDC3ChannelChangedEvent`
 
 ```ts
 interface FDC3ChannelChangedEvent extends FDC3Event {
-  readonly type: FDC3EventType.USER_CHANNEL_CHANGED;
+  readonly type: "USER_CHANNEL_CHANGED";
   readonly details: {
     currentChannelId: string | null
   };
@@ -66,27 +81,23 @@ Type representing the format of USER_CHANNEL_CHANGED events.
 
 The identity of the channel joined is provided as `details.currentChannelId`, which will be `null` if the app is no longer joined to any channel.
 
-## `PrivateChannelEventType`
+## `PrivateChannelEventTypes`
 
 ```ts
-enum PrivateChannelEventType {
-  ADD_CONTEXT_LISTENER = "addContextListener",
-  UNSUBSCRIBE = "unsubscribe",
-  DISCONNECT = "disconnect"
-}
+type PrivateChannelEventTypes = "addContextListener" | "unsubscribe" | "disconnect";
 ```
 
-Enumeration defining the types of (non-context and non-intent) events that may be received via a PrivateChannel's `addEventListener` function.
+Type defining valid type strings for Private Channel events.
 
 **See also:**
 
-- [`PrivateChannel.addEventListener`](PrivateChannel#addEventListener)
+- [`PrivateChannel.addEventListener`](PrivateChannel#addeventlistener)
 
 ## `PrivateChannelEvent`
 
 ```ts
-interface PrivateChannelEvent {
-  readonly type: PrivateChannelEventType;
+interface PrivateChannelEvent extends ApiEvent {
+  readonly type: PrivateChannelEventTypes;
   readonly details: any;
 }
 ```
@@ -95,14 +106,14 @@ Type defining the format of event objects that may be received via a PrivateChan
 
 **See also:**
 
-- [`PrivateChannel.addEventListener`](PrivateChannel#addEventListener)
-- [`PrivateChannelEventType`](#privatechanneleventtype)
+- [`PrivateChannel.addEventListener`](PrivateChannel#addeventlistener)
+- [`PrivateChannelEventTypes`](#privatechanneleventtypes)
 
 ### `PrivateChannelAddContextListenerEvent`
 
 ```ts
 interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent {
-  readonly type: PrivateChannelEventType.ADD_CONTEXT_LISTENER;
+  readonly type: "addContextListener";
   readonly details: {
     contextType: string | null
   };
@@ -117,7 +128,7 @@ The context type of the listener added is provided as `details.contextType`, whi
 
 ```ts
 interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent {
-  readonly type: PrivateChannelEventType.UNSUBSCRIBE;
+  readonly type: "unsubscribe";
   readonly details: {
     contextType: string | null
   };
@@ -132,7 +143,7 @@ The context type of the  listener removed is provided as `details.contextType`,
 
 ```ts
 export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent {
-  readonly type: PrivateChannelEventType.DISCONNECT;
+  readonly type: "disconnect";
   readonly details: null | undefined;
 }
 ```

docs/api/ref/PrivateChannel.md

@@ -17,7 +17,7 @@ It is intended that Desktop Agent implementations:
 ```ts
 interface  PrivateChannel extends Channel {
   // functions
-  addEventListener(type: PrivateChannelEventType  | null, handler: EventHandler): Promise<Listener>;
+  addEventListener(type: PrivateChannelEventTypes  | null, handler: EventHandler): Promise<Listener>;
   disconnect(): Promise<void>;
 
   //deprecated functions
@@ -120,7 +120,7 @@ try {
 ### `addEventListener`
 
 ```ts
-addEventListener(type: PrivateChannelEventType  | null, handler: EventHandler): Promise<Listener>;
+addEventListener(type: PrivateChannelEventTypes  | null, handler: EventHandler): Promise<Listener>;
 ```
 
 Register a handler for events from the PrivateChannel. Whenever the handler function is called it will be passed an event object with details related to the event.
@@ -142,7 +142,8 @@ const channelChangedListener: Listener = await myPrivateChannel.addEventListener
 
 **See also:**
 
-- [`PrivateChannelEventType`](./Events#privatechanneleventtype)
+- [`PrivateChannelEventTypes`](./Events#privatechanneleventtypes)
+- [`PrivateChannelEvent`](./Events#privatechannelevent)
 - [`EventHandler`](./Events#eventhandler)
 
 ### `disconnect`

src/api/DesktopAgent.ts

@@ -15,7 +15,7 @@ import { AppIdentifier } from './AppIdentifier';
 import { AppMetadata } from './AppMetadata';
 import { Intent } from '../intents/Intents';
 import { ContextType } from '../context/ContextType';
-import { EventHandler, FDC3EventType } from './Events';
+import { EventHandler, FDC3EventTypes } from './Events';
 
 /**
  * A Desktop Agent is a desktop component (or aggregate of components) that serves as a
@@ -395,7 +395,7 @@ export interface DesktopAgent {
    * @param {EventHandler} handler A function that events received will be passed to. 
    * 
    */ 
-  addEventListener(type: FDC3EventType  | null, handler: EventHandler): Promise<Listener>;
+  addEventListener(type: FDC3EventTypes  | null, handler: EventHandler): Promise<Listener>;
 
   /**
    * Retrieves a list of the User channels available for the app to join.

src/api/Events.ts

@@ -3,59 +3,61 @@
  * Copyright FINOS FDC3 contributors - see NOTICE file
  */
 
+/**
+ * Type defining a basic event object that may be emitted by an FDC3 API interface
+ * such as DesktopAgent or PrivateChannel. There are more specific event types
+ * defined for each interface. 
+ */
+export interface ApiEvent {
+  readonly type: string;
+  readonly details: any;
+}
+
 /** Type representing a handler function for events from the Desktop Agent
  * or a PrivateChannel. 
- * @param event The handler function will be passed an `FDC3Event` or
- * `PrivateChannelEvent` Object providing details of the event (such as a
- * change of channel membership for the app, or type of context listener added)
+ * @param event The handler function will be passed an `ApiEvent` (or more specifically
+ *  an `FDC3Event` or `PrivateChannelEvent`) Object providing details of the event (such 
+ * as a change of channel membership for the app, or type of context listener added)
  * as the only parameter.
  */
-export type EventHandler = (event: FDC3Event | PrivateChannelEvent ) => void;
+export type EventHandler = (event: ApiEvent ) => void;
 
 /**
- * Enumeration defining the types of (non-context and non-intent) events that may be received
-   via the FDC3 API's `addEventListener` function. 
+ * Type defining valid type strings for DesktopAgent interface events.
  */
-export enum FDC3EventType {
-  USER_CHANNEL_CHANGED = "USER_CHANNEL_CHANGED"
-}
+export type FDC3EventTypes = "USER_CHANNEL_CHANGED";
+
 
 /**
  * Type defining the format of event objects that may be received
-   via the FDC3 API's `addEventListener` function.
+ * via the FDC3 API's `addEventListener` function.
  */
-export interface FDC3Event {
-  readonly type: FDC3EventType;
+export interface FDC3Event extends ApiEvent {
+  readonly string: FDC3EventTypes;
   readonly details: any;
 }
 
 /**
  * Type defining the format of event USER_CHANNEL_CHANGED objects
  */
 export interface FDC3ChannelChangedEvent extends FDC3Event {
-  readonly type: FDC3EventType.USER_CHANNEL_CHANGED;
+  readonly type: "USER_CHANNEL_CHANGED";
   readonly details: {
     currentChannelId: string | null
   };
 }
 
 /**
- * Enumeration defining the types of events that may be received
-   via a PrivateChannel's `addEventListener` function.
+ * Type defining valid type strings for Private Channel events.
  */
-  export enum PrivateChannelEventType {
-  ADD_CONTEXT_LISTENER = "addContextListener",
-  UNSUBSCRIBE = "unsubscribe",
-  DISCONNECT = "disconnect"
-}
-  
-  
+export type PrivateChannelEventTypes = "addContextListener" | "unsubscribe" | "disconnect";
+
 /**
  * Type defining the format of event objects that may be received
  * via a PrivateChannel's `addEventListener` function.
  */
 export interface PrivateChannelEvent {
-  readonly type: PrivateChannelEventType;
+  readonly type: PrivateChannelEventTypes;
   readonly details: any;
 }
 
@@ -69,7 +71,7 @@ export interface PrivateChannelEvent {
  * which will be `null` if all event types are being listened to.
  */
 export interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent {
-  readonly type: PrivateChannelEventType.ADD_CONTEXT_LISTENER;
+  readonly type: "addContextListener";
   readonly details: {
     contextType: string | null
   };
@@ -84,7 +86,7 @@ export interface PrivateChannelAddContextListenerEvent extends PrivateChannelEve
  * which will be `null` if all event types were being listened to.
  */
 export interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent {
-  readonly type: PrivateChannelEventType.UNSUBSCRIBE;
+  readonly type: "unsubscribe";
   readonly details: {
     contextType: string | null
   };
@@ -97,6 +99,6 @@ export interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent {
  * No details are provided.
  */
 export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent {
-  readonly type: PrivateChannelEventType.DISCONNECT;
+  readonly type: "disconnect";
   readonly details: null | undefined;
 }

src/api/PrivateChannel.ts

@@ -5,7 +5,7 @@
 
 import { Listener } from './Listener';
 import { Channel } from './Channel';
-import { EventHandler, PrivateChannelEventType } from './Events';
+import { EventHandler, PrivateChannelEventTypes } from './Events';
 
 /**
  * Object representing a private context channel, which is intended to support
@@ -43,7 +43,7 @@ export interface PrivateChannel extends Channel {
    * @param {EventHandler} handler A function that events received will be passed to. 
    * 
    */ 
-  addEventListener(type: PrivateChannelEventType  | null, handler: EventHandler): Promise<Listener>;
+  addEventListener(type: PrivateChannelEventTypes  | null, handler: EventHandler): Promise<Listener>;
 
   /**
    * May be called to indicate that a participant will no longer interact with this channel.