Skip to content

Commit

Permalink
Merge pull request #1127 from finos/1107-fix-intent-result-type-in-2.0
Browse files Browse the repository at this point in the history
Correcting IntentResult error in FDC3 2.0 and adding a very minor clarification to 2.1/next
  • Loading branch information
kriswest authored Jan 25, 2024
2 parents 29c90c7 + cc68903 commit f4a46c0
Show file tree
Hide file tree
Showing 7 changed files with 16 additions and 10 deletions.
2 changes: 1 addition & 1 deletion docs/api/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ As an alternative to raising a specific intent, you may also raise an unspecifie

### Intent Results

An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results maybe either a single `Context` object, or a `Channel` that may be used to send a stream of responses. The [`PrivateChannel`](ref/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](ref/DesktopAgent#raiseintent).
An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results may be a single `Context` object, a `Channel` that may be used to send a stream of responses, or `void` (no result). The [`PrivateChannel`](ref/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](ref/DesktopAgent#raiseintent).

For example, an application handling a `CreateOrder` intent might return a context representing the order and including an ID, allowing the application that raised the intent to make further calls using that ID.

Expand Down
2 changes: 1 addition & 1 deletion website/versioned_docs/version-2.0/api/ref/DesktopAgent.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions website/versioned_docs/version-2.0/api/ref/Errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,8 +122,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',

Expand Down
6 changes: 3 additions & 3 deletions website/versioned_docs/version-2.0/api/ref/Metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -345,9 +345,9 @@ interface IntentResolution {
* 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>;
Expand Down
8 changes: 7 additions & 1 deletion website/versioned_docs/version-2.0/api/ref/Types.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,13 +104,19 @@ 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).

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`.

:::info

The original release of FDC3 2.0 contained an error in the `IntentResult` type, which omitted `void` as a valid return type. It was intended that an `IntentHandler` be able to return either `void` or a Promise that resolves to `void` and, as these are valid results, no error should be thrown by `IntentResolution.getResult()`. This was corrected in FDC3 2.1 and retrospectively corrected in FDC3 2.0.

:::

#### See also

* [`Context`](#context)
Expand Down
2 changes: 1 addition & 1 deletion website/versioned_docs/version-2.0/api/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ As an alternative to raising a specific intent, you may also raise an unspecifie

### Intent Results

An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results maybe either a single `Context` object, or a `Channel` that may be used to send a stream of responses. The [`PrivateChannel`](ref/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](ref/DesktopAgent#raiseintent).
An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results may be a single `Context` object, a `Channel` that may be used to send a stream of responses, or `void` (no result). The [`PrivateChannel`](ref/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](ref/DesktopAgent#raiseintent).

For example, an application handling a `CreateOrder` intent might return a context representing the order and including an ID, allowing the application that raised the intent to make further calls using that ID.

Expand Down
2 changes: 1 addition & 1 deletion website/versioned_docs/version-2.1/api/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ As an alternative to raising a specific intent, you may also raise an unspecifie

### Intent Results

An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results maybe either a single `Context` object, or a `Channel` that may be used to send a stream of responses. The [`PrivateChannel`](ref/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](ref/DesktopAgent#raiseintent).
An optional [`IntentResult`](ref/Types#intentresult) may also be returned as output by an application handling an intent. Results may be a single `Context` object, a `Channel` that may be used to send a stream of responses, or `void` (no result). The [`PrivateChannel`](ref/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](ref/DesktopAgent#raiseintent).

For example, an application handling a `CreateOrder` intent might return a context representing the order and including an ID, allowing the application that raised the intent to make further calls using that ID.

Expand Down

0 comments on commit f4a46c0

Please sign in to comment.