Merge pull request #1004 from finos/1003-clarify-getresult-on-resolve-to-void

Clarify intended behavior on void intent results

Author: kriswest

docs/api/ref/DesktopAgent.md

@@ -95,7 +95,7 @@ const contactListener = await fdc3.addContextListener('fdc3.contact', (contact,
 addIntentListener(intent: string, handler: IntentHandler): Promise<Listener>;
 ```
 
-Adds a listener for incoming intents from the Desktop Agent. The handler function may return void or a promise that resolves to a [`IntentResult`](Types#intentresult), which is either a [`Context`](Types#context) object, representing any data that should be returned to the app that raised the intent, or a [`Channel`](Channel) or [`PrivateChannel`](PrivateChannel) over which data responses will be sent. The `IntentResult` will be returned to the app that raised the intent via the [`IntentResolution`](Metadata#intentresolution) and retrieved from it using the `getResult()` function.
+Adds a listener for incoming intents from the Desktop Agent. The handler function may return void or a promise that resolves to a [`IntentResult`](Types#intentresult), which is either a [`Context`](Types#context) object (representing any data that should be returned to the app that raised the intent),  a [`Channel`](Channel), a [`PrivateChannel`](PrivateChannel) over which data responses will be sent, or `void`. The `IntentResult` will be returned to the app that raised the intent via the [`IntentResolution`](Metadata#intentresolution) and retrieved from it using the `getResult()` function.
 
 The Desktop Agent MUST reject the promise returned by the `getResult()` function of `IntentResolution` if any of the following is true: 
 1. The intent handling function's returned promise rejects.
@@ -642,7 +642,7 @@ If you wish to raise an intent without a context, use the `fdc3.nothing` context
 
 Returns an [`IntentResolution`](Metadata#intentresolution) object with details of the app instance that was selected (or started) to respond to the intent.
 
-Issuing apps may optionally wait on the promise that is returned by the `getResult()` member of the IntentResolution. This promise will resolve when the _receiving app's_ intent handler function returns and resolves a promise. The Desktop Agent resolves the issuing app's promise with the Context object or Channel that is provided as resolution by the receiving app. The Desktop Agent MUST reject the issuing app's promise, with a string from the [`ResultError`](Errors#resulterror) enumeration, if: (1) the intent handling function's returned promise rejects, (2) the intent handling function doesn't return a promise, or (3) the returned promise resolves to an invalid type.
+Issuing apps may optionally wait on the promise that is returned by the `getResult()` member of the `IntentResolution`. This promise will resolve when the _receiving app's_ intent handler function returns and resolves a promise. The Desktop Agent resolves the issuing app's promise with the Context object, Channel object or void that is provided as resolution within the receiving app. The Desktop Agent MUST reject the issuing app's promise, with a string from the [`ResultError`](Errors#resulterror) enumeration, if: (1) the intent handling function's returned promise rejects, (2) the intent handling function doesn't return a valid response (a promise or void), or (3) the returned promise resolves to an invalid type.
 
 #### Example
 

docs/api/ref/Errors.md

@@ -139,8 +139,8 @@ Contains constants representing the errors that can be encountered when calling
 
 ```typescript
 enum ResultError {
-  /** Returned if the `IntentHandler` exited without returning a Promise or that
-   *  Promise was not resolved with a Context or Channel object. 
+  /** Returned if the intent handler exited without returning a valid result 
+   * (a promise resolving to a Context, Channel object or void).
    */
   NoResultReturned = 'NoResultReturned',
 

docs/api/ref/Metadata.md

@@ -335,18 +335,18 @@ interface IntentResolution {
    */
   readonly version?: string;
 
-  /** Retrieves a promise that will resolve to either `Context` data returned 
-   *  by the application that resolves the raised intent or a `Channel` 
-   *  established and returned by the app resolving the intent. 
+  /** Retrieves a promise that will resolve to `Context` data returned 
+   *  by the application that resolves the raised intent, a `Channel` 
+   *  established and returned by the app resolving the intent or void. 
    * 
    *  A `Channel` returned MAY be of the `PrivateChannel` type. The 
    *  client can then `addContextListener()` on that channel to, for example, 
    *  receive a stream of data.
    * 
    *  If an error occurs (i.e. an error is thrown by the handler function,
-   *  the promise it returns is rejected, or a promise is not returned by the
-   *  handler function) then the Desktop Agent MUST reject the promise returned
-   *  by the `getResult()` function of the `IntentResolution` with a string from
+   *  the promise it returns is rejected, or the promise resolved to an invalid 
+   *  type) then the Desktop Agent MUST reject the promise returned by the 
+   *  `getResult()` function of the `IntentResolution` with a string from
    *  the `ResultError` enumeration.
    */
    getResult(): Promise<IntentResult>;

docs/api/ref/Types.md

@@ -86,7 +86,7 @@ Optional metadata about the context message, including the app that originated t
 type IntentHandler = (context: Context, metadata?: ContextMetadata) => Promise<IntentResult> | void;
 ```
 
-Describes a callback that handles a context event and may return a promise of a Context or Channel object to be returned to the application that raised the intent.
+Describes a callback that handles a context event and may return a promise of a Context, Channel object or `void` to be returned to the application that raised the intent.
 
 Used when attaching listeners for raised intents.
 
@@ -103,10 +103,10 @@ Optional metadata about the intent & context message, including the app that ori
 ## `IntentResult`
 
 ```typescript
-type IntentResult = Context | Channel;
+type IntentResult = Context | Channel | void;
 ```
 
-Describes results that an Intent handler may optionally return that should be communicated back to the app that raised the intent, via the [`IntentResolution`](Metadata#intentresolution).
+Describes results that an Intent handler may return that should be communicated back to the app that raised the intent, via the [`IntentResolution`](Metadata#intentresolution).
 
 Represented as a union type in TypeScript, however, this type may be rendered as an interface in other languages that both the `Context` and `Channel` types implement, allowing either to be returned by an `IntentHandler`.
 

src/api/DesktopAgent.ts

@@ -236,7 +236,7 @@ export interface DesktopAgent {
    *
    * Returns an `IntentResolution` object with details of the app instance that was selected (or started) to respond to the intent. 
    *
-   * Issuing apps may optionally wait on the promise that is returned by the `getResult()` member of the `IntentResolution`. This promise will resolve when the _receiving app's_ intent handler function returns and resolves a promise. The Desktop Agent resolves the issuing app's promise with the Context object or Channel that is provided as resolution within the receiving app. The Desktop Agent MUST reject the issuing app's promise, with a string from the `ResultError` enumeration, if: (1) the intent handling function's returned promise rejects, (2) the intent handling function doesn't return a promise, or (3) the returned promise resolves to an invalid type.
+   * Issuing apps may optionally wait on the promise that is returned by the `getResult()` member of the `IntentResolution`. This promise will resolve when the _receiving app's_ intent handler function returns and resolves a promise. The Desktop Agent resolves the issuing app's promise with the Context object, Channel object or void that is provided as resolution within the receiving app. The Desktop Agent MUST reject the issuing app's promise, with a string from the `ResultError` enumeration, if: (1) the intent handling function's returned promise rejects, (2) the intent handling function doesn't return a valid response (a promise or void), or (3) the returned promise resolves to an invalid type.
    *
    * ```javascript
    * // raise an intent for resolution by the desktop agent
@@ -293,11 +293,11 @@ export interface DesktopAgent {
   raiseIntentForContext(context: Context, app?: AppIdentifier): Promise<IntentResolution>;
 
   /**
-   * Adds a listener for incoming Intents from the Agent. The handler function may return void or a promise that should resolve to an `IntentResult`, which is either a `Context` object, representing any data that should be returned, or a `Channel` over which data responses will be sent. The IntentResult will be returned to app that raised the intent via the `IntentResolution` and retrieved from it using the `getResult()` function.
+   * Adds a listener for incoming intents from the Desktop Agent. The handler function may return void or a promise that resolves to an `IntentResult`, which is either a `Context` object, representing any data that should be returned to the app that raised the intent, a `Channel` Object, a `PrivateChannel` over which data responses will be sent, or `void`. The `IntentResult` will be returned to the app that raised the intent via the `IntentResolution` and retrieved from it using the `getResult()` function.
    *
    * The Desktop Agent MUST reject the promise returned by the `getResult()` function of `IntentResolution` if: (1) the intent handling function's returned promise rejects, (2) the intent handling function doesn't return a promise, or (3) the returned promise resolves to an invalid type.
    *
-   * The `PrivateChannel` type is provided to support synchronisation of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via raising an intent.
+   * The `PrivateChannel` type is provided to support synchronization of data transmitted over returned channels, by allowing both parties to listen for events denoting subscription and unsubscription from the returned channel. `PrivateChannels` are only retrievable via raising an intent.
    *
    * Optional metadata about the raised intent, including the app that originated the message, SHOULD be provided by the desktop agent implementation.
    *

src/api/Errors.ts

@@ -38,7 +38,7 @@ export enum ResolveError {
 }
 
 export enum ResultError {
-  /** Returned if the intent handler exited without returning a Promise or that Promise was not resolved with a Context or Channel object. */
+  /** Returned if the intent handler exited without returning a valid result (a promise resolving to a Context, Channel object or void). */
   NoResultReturned = 'NoResultReturned',
   /** Returned if the Intent handler function processing the raised intent throws an error or rejects the Promise it returned. */
   IntentHandlerRejected = 'IntentHandlerRejected',

src/api/IntentResolution.ts

@@ -49,18 +49,19 @@ export interface IntentResolution {
    */
   readonly version?: string;
   /**
-   * Retrieves a promise that will resolve to either `Context` data returned
-   * by the application that resolves the raised intent or a `Channel`
-   * established and returned by the app resolving the intent.
+   * Retrieves a promise that will resolve to `Context` data returned
+   * by the application that resolves the raised intent, a `Channel`
+   * established and returned by the app resolving the intent or void.
    *
-   * A `Channel` returned will often be of the `PrivateChannel` type. The
+   * A `Channel` returned MAY be of the `PrivateChannel` type. The
    * client can then `addContextListener()` on that channel to, for example,
    * receive a stream of data.
    *
-   * The promise MUST reject with a string from the `ResultError` enumeration
-   * if an error is thrown by the intent handler, it rejects the returned
-   * promise, it does not return a promise or the promise resolves to an
-   * object of an invalid type.
+   * If an error occurs (i.e. an error is thrown by the handler function,
+   * the promise it returns is rejected, or the promise resolved to an invalid
+   * type) then the Desktop Agent MUST reject the promise returned by the
+   * `getResult()` function of the `IntentResolution` with a string from
+   * the `ResultError` enumeration.
    */
   getResult(): Promise<IntentResult>;
 }

src/api/Types.ts

@@ -18,10 +18,10 @@ export type ContextHandler = (context: Context, metadata?: ContextMetadata) => v
  * Intents can return results that are either context data objects
  * or a reference to a Channel.
  */
-export type IntentResult = Context | Channel;
+export type IntentResult = Context | Channel | void;
 /**
  * Describes a callback that handles a context event and may return a
- * promise of a Context or Channel object to be returned to the
+ * promise of a Context, Channel object or void to be returned to the
  * application that raised the intent.
  * Used when attaching listeners for raised intents.
  *