Promise API - Errors returned in resolve instead of reject

[ryanswanson]

I believe there is a discrepancy between FDC3 DesktopAgent TypeScript typings and the @finos/fdc3-desktop-agent implementation with regards to Promise typing and associated error handling.

I hope the resolution of this issue will make the two consistent as well as clarify the responsibility for FDC3 DesktopAgent implementations in general. I apologize if the answer is already documented somewhere that I missed.

The core question is: Should FDC3 Promise-based API implementations respond with associated errors (ChannelError, OpenError, ResolveError) using resolve or reject?

Current Typings

Current DesktopAgent typings in @finos/fdc3-desktop-agent and @finos/fdc3 include references to Error typings as tsdoc comments rather than being included in the parameterized Promise types, Promise<T>.

Example:

    /**
     * ...
     * If opening errors, it returns an `Error` with a string from the `OpenError` enumeration.
     * ...
     */
    open(name: string, context?: Context): Promise<void>;
  

To clarify, the type parameter (T) in Promise<T> refers only to the resolve method's parameter type. The type for reject is and should remain any by design (exception typing).

These typings suggest that errors would not be passed to resolve, but instead be passed to reject, where the any type can be refined using appropriate type guards.

Current fdc3-desktop-agent

From my use of the fdc3-desktop-agent Chrome plugin, it appears that errors are only passed to resolve and that reject may not currently be called at all.

Option: Adapt Typings

To build our initial prototype with the plugin, I created my own types for DesktopAgent that incorporates error types into the Promise type parameter T as applies to resolve method function parameters, as shown by the following excerpt:

import {OpenError, ...} from '@finos/fdc3';

export interface DesktopAgent {
  open(name: string, context?: Context): Promise<undefined | Error<OpenError>>;
  ...
}

export interface Error<T> {
  error: T;
}

If the intended use for errors is to use resolve, should the published typings be updated?

I would also suggest that the Error object typing should be included as part of the public FDC3 interface. The Error<T> interface above is just one way this can be accomplished. I could imagine this interface evolving over time - for instance, if multiple errors could apply to a single reject response or if additional metadata should be included.

Option: Adjust fdc3-desktop-agent

If the intended use for errors is to use reject as suggested by current typings, should the fdc3-desktop-agent be adjusted/fixed?

Thank you in advance.
Ryan