Merge pull request #1305 from finos/async-listener-and-PrivateChannel-events

Async listener and private channel events

Author: kriswest

CHANGELOG.md

@@ -10,15 +10,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 * Added clarification that `id` field values SHOULD always be strings to context schema definition (a restriction that can't easily be represented in the generated types). ([#1149](https://github.com/finos/FDC3/pull/1149))
 * Added requirement that Standard versions SHOULD avoid the use unions in context and API definitions wherever possible as these can be hard to replicate and MUST avoid unions of primitive types as these can be impossible to replicate in other languages. ([#120](https://github.com/finos/FDC3/pull/1200))
-* Added reference materials and supported platforms information for FDC3 in .NET via the [finos/fdc3-dotnet](https://github.com/finos/fdc3-dotnet) project. ([#1108](https://github.com/finos/FDC3/pull/1108))
+* Added `addEventListener` to the `DesktopAgent` API to provide support for event listener for non-context and non-intent events, including a `userChannelChanged` event ([#1207](https://github.com/finos/FDC3/pull/1207))
+* Added an `async` `addEventListener` function to the `PrivateChannel` API to replace the deprecated, synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions and to keep consistency with the DesktopAgent API. ([#1305](https://github.com/finos/FDC3/pull/1305))
 
 ### Changed
 
+* `Listener.unsubscribe()` was made async (the return type was changed from `void` to `Promise<void>`) for consistency with the rest of the API. ([#1305](https://github.com/finos/FDC3/pull/1305))
+* Added reference materials and supported platforms information for FDC3 in .NET via the [finos/fdc3-dotnet](https://github.com/finos/fdc3-dotnet) project. ([#1108](https://github.com/finos/FDC3/pull/1108))
 * The supported platforms page in the FDC3 documentation was moved into the API section as the information it provides all relates to FDC3 Desktop Agent API implementations. ([#1108](https://github.com/finos/FDC3/pull/1108))
 
 ### Deprecated
 
 * Made `IntentMetadata.displayName` optional as it is deprecated. ([#1280](https://github.com/finos/FDC3/pull/1280))
+* Deprecated `PrivateChannel`'s synchronous `onAddContextListener`, `onUnsubscribe` and `onDisconnect` functions in favour of an `async` `addEventListener` function consistent with the one added to `DesktopAgent` in #1207. ([#1305](https://github.com/finos/FDC3/pull/1305))
 
 ### Fixed
 

docs/api/ref/DesktopAgent.md

@@ -48,7 +48,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>;
@@ -183,7 +183,7 @@ var contactListener = await _desktopAgent.AddContextListener<Contact>("fdc3.cont
 <TabItem value="ts" label="TypeScript/JavaScript">
 
 ```ts
-addEventListener(type: FDC3EventType  | null, handler: EventHandler): Promise<Listener>;
+addEventListener(type: FDC3EventTypes  | null, handler: EventHandler): Promise<Listener>;
 ```
 
 </TabItem>
@@ -210,12 +210,11 @@ 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("userChannelChanged ", event => { 
   console.log(`Received event ${event.type}\n\tDetails: ${event.details}`);
   //do something else with the event
 });
 ```
-
 </TabItem>
 <TabItem value="dotnet" label=".NET">
 
@@ -226,6 +225,12 @@ Not implemented
 </TabItem>
 </Tabs>
 
+**See also:**
+
+- [`FDC3EventTypes`](./Events#fdc3eventtypes)
+- [`FDC3Event`](./Events#fdc3event)
+- [`EventHandler`](./Events#eventhandler)
+
 ### `addIntentListener`
 
 <Tabs groupId="lang">

docs/api/ref/Events.md

@@ -2,58 +2,152 @@
 title: Events
 ---
 
-In addition to intent and context events, the FDC3 API may be used to listen for other types of events via the `addEventListener()` function.
+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) => void;
+type EventHandler = (event: ApiEvent) => void;
 ```
 
-Describes a callback that handles non-context and non-intent events. Provides the details of the event. 
+Describes a callback that handles non-context and non-intent events. Provides the details of the event.
 
-Used when attaching listeners to events. 
+Used when attaching listeners to events.
 
 **See also:**
-- [`DesktopAgent.addEventListener`](DesktopAgent#addEventListener)
-- [`FDC3Event`](#fdc3event)
 
-## `FDC3EventType`
+- [`DesktopAgent.addEventListener`](DesktopAgent#addeventlistener)
+- [`PrivateChannel.addEventListener`](PrivateChannel#addeventlistener)
+- [`ApiEvent`](#apievent)
+
+## `FDC3EventTypes`
+
 ```ts
-enum FDC3EventType {
-  USER_CHANNEL_CHANGED = "USER_CHANNEL_CHANGED"
-}
+type FDC3EventTypes = "userChannelChanged";
 ```
 
-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;
 }
 ```
 
-Type representing the format of event objects that may be received via the FDC3 API's `addEventListener` function. Will always include both `type` and `details`, which describe type of the event and any additional details respectively.
+Type representing the format of event objects that may be received via the FDC3 API's `addEventListener` function.
+
+Events will always include both `type` and `details` properties, which describe the type of the event and any additional details respectively.
 
 **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: "userChannelChanged";
   readonly details: {
     currentChannelId: string | null
   };
 }
 ```
 
-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.
+Type representing the format of `userChannelChanged`  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.
+
+## `PrivateChannelEventTypes`
+
+```ts
+type PrivateChannelEventTypes = "addContextListener" | "unsubscribe" | "disconnect";
+```
+
+Type defining valid type strings for Private Channel events.
+
+**See also:**
+
+- [`PrivateChannel.addEventListener`](PrivateChannel#addeventlistener)
+
+## `PrivateChannelEvent`
+
+```ts
+interface PrivateChannelEvent extends ApiEvent {
+  readonly type: PrivateChannelEventTypes;
+  readonly details: any;
+}
+```
+
+Type defining the format of event objects that may be received via a PrivateChannel's `addEventListener` function.
+
+**See also:**
+
+- [`PrivateChannel.addEventListener`](PrivateChannel#addeventlistener)
+- [`PrivateChannelEventTypes`](#privatechanneleventtypes)
+
+### `PrivateChannelAddContextListenerEvent`
+
+```ts
+interface PrivateChannelAddContextListenerEvent extends PrivateChannelEvent {
+  readonly type: "addContextListener";
+  readonly details: {
+    contextType: string | null
+  };
+}
+```
+
+Type defining the format of events representing a context listener being added to the channel (`addContextListener`). Desktop Agents MUST fire this event for each invocation of `addContextListener` on the channel, including those that occurred before this handler was registered (to prevent race conditions).
+
+The context type of the listener added is provided as `details.contextType`, which will be `null` if all event types are being listened to.
+
+### `PrivateChannelUnsubscribeEvent`
+
+```ts
+interface PrivateChannelUnsubscribeEvent extends PrivateChannelEvent {
+  readonly type: "unsubscribe";
+  readonly details: {
+    contextType: string | null
+  };
+}
+```
+
+Type defining the format of events representing a context listener removed from the channel (`Listener.unsubscribe()`). Desktop Agents MUST call this when `disconnect()` is called by the other party, for each listener that they had added.
+
+The context type of the  listener removed is provided as `details.contextType`, which will be `null` if all event types were being listened to.
+
+### `PrivateChannelDisconnectEvent`
+
+```ts
+export interface PrivateChannelDisconnectEvent extends PrivateChannelEvent {
+  readonly type: "disconnect";
+  readonly details: null | undefined;
+}
+```
+
+Type defining the format of events representing a remote app being terminated or is otherwise disconnecting from the PrivateChannel. This event is fired in addition to unsubscribe events that will also be fired for any context listeners the disconnecting app had added.
+
+No details are provided.