fix: bind this in API-returned objects & update docs for JS implementers

[jaybhanushali3166]

Related Issue

resolves #1638

Contributor License Agreement

• I acknowledge that a contributor license agreement is required and that I have one in place or will seek to put one in place ASAP.

Review Checklist

• Issue: If a change was made to the FDC3 Standard, was an issue linked above?
• CHANGELOG: Is a CHANGELOG.md entry included?
• API changes: Does this PR include changes to any of the FDC3 APIs (DesktopAgent, Channel, PrivateChannel, Listener, Bridging)?
  • Docs & Sources: If yes, were both documentation (/docs) and sources updated?
    
    JSDoc comments on interfaces and types should be matched to the main documentation in /docs
  • Conformance tests: If yes, are conformance test definitions (/toolbox/fdc3-conformance) still correct and complete?
    
    Conformance test definitions should cover all required aspects of an FDC3 Desktop Agent implementation, which are usually marked with a MUST keyword, and optional features (SHOULD or MAY) where the format of those features is defined
  • Schemas: If yes, were changes applied to the Bridging and FDC3 for Web protocol schemas?
    
    The Web Connection protocol and Desktop Agent Communication Protocol schemas must be able to support all necessary aspects of the Desktop Agent API, while Bridging must support those aspects necessary for Desktop Agents to communicate with each other
    • If yes, was code generation (npm run build) run and the results checked in?
      
      Generated code will be found at /src/api/BrowserTypes.ts and/or /src/bridging/BridgingTypes.ts
• Context types: Were new Context type schemas created or modified in this PR?
  • Were the field type conventions adhered to?
  • Was the BaseContext schema applied via allOf (as it is in existing types)?
  • Was a title and description provided for all properties defined in the schema?
  • Was at least one example provided?
  • Was code generation (npm run build) run and the results checked in?
    
    Generated code will be found at /src/context/ContextTypes.ts
• Intents: Were new Intents created in this PR?
  • Were the intent name prefixes and other naming conventions & characteristics adhered to?
  • Was the new intent added to the list in the Intents Overview?

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: jaybhanushali3166 / name: Jay Bhanushali (c6841af, 453573e, 9ef42a5, cae9ce9)
• ✅ login: kriswest / name: Kris West (a718c75)

[netlify]

✅ Deploy Preview for fdc3 ready!

Name	Link
🔨 Latest commit	a718c75
🔍 Latest deploy log	https://app.netlify.com/projects/fdc3/deploys/68c182263c53cb00077f4820
😎 Deploy Preview	https://deploy-preview-1645.preview-fdc3.finos.org
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[kriswest]

This is looking good so far, although you still need to bind the functions of IntentResolution at: https://github.com/jaybhanushali3166/FDC3/blob/fix/bind-this-in-api-objects-and-docs-update/packages/fdc3-agent-proxy/src/intents/DefaultIntentResolution.ts

I think it would also be worth defining some tests - try repeating an existing test but with a destructured function instead of the DesktopAgent reference itself. As the destructuring is a MUST, we need both conformance tests and unit tests for the code:

• Text description of a tests to go in:
  • App Channel tests: https://github.com/jaybhanushali3166/FDC3/blob/fix/bind-this-in-api-objects-and-docs-update/website/docs/api/conformance/App-Channel-Tests.md
  • Intent tests: https://github.com/jaybhanushali3166/FDC3/blob/fix/bind-this-in-api-objects-and-docs-update/website/docs/api/conformance/Intents-Tests.md
  • Destructuring the desktop functions should probably be testing on a few key functions (repeat existing tests but destructure broadcast, open, raiseIntent?)
• Unit tests for code:
  • App Channels: https://github.com/jaybhanushali3166/FDC3/blob/fix/bind-this-in-api-objects-and-docs-update/packages/fdc3-agent-proxy/test/features/app-channels.feature
  • Intent Results (binding of getResult function): https://github.com/jaybhanushali3166/FDC3/blob/fix/bind-this-in-api-objects-and-docs-update/packages/fdc3-agent-proxy/test/features/intent-results.feature
  • Destructuing desktop agents functions distributed amongst other tests?

[kriswest]

Please also add a CHANGELOG.md entry in the unreleased section: https://github.com/jaybhanushali3166/FDC3/blob/fix/bind-this-in-api-objects-and-docs-update/CHANGELOG.md#unreleased

[kriswest]

@jaybhanushali3166 will you be able to make the requested additions to this PR, or would you like someone else to take this on to complete?

[jaybhanushali3166]

@kriswest, I am working on it. Finishing up the test cases.

[kriswest]

@jaybhanushali3166 Awesome, let us know how you get on - and ignore the failing Report coverage task, we need to fix that.

[jaybhanushali3166]

Hi @kriswest , for the test cases as we are using existing tests with destructed methods, are we also expecting new step definitions too? Something like this:

When('I destructure method {string} from {string}', function (this: CustomWorld, methodName: string, objectField: string) {
  const object = handleResolve(objectField, this);
  const destructuredMethod = object[methodName].bind(object);
  this.props[`destructured_${methodName}`] = destructuredMethod;
`});

[kriswest]

Hi @kriswest , for the test cases as we are using existing tests with destructed methods, are we also expecting new step definitions too? Something like this:

When('I destructure method {string} from {string}', function (this: CustomWorld, methodName: string, objectField: string) {
  const object = handleResolve(objectField, this);
  const destructuredMethod = object[methodName].bind(object);
  this.props[`destructured_${methodName}`] = destructuredMethod;
`});

Hi @jaybhanushali3166, yes I'd add a new step to do the destructuring - however don't include the bind, as you are trying to test that implementation did it already. Hence:

When('I destructure method {string} from {string}', function (this: CustomWorld, methodName: string, objectField: string) {
  const object = handleResolve(objectField, this);
  const destructuredMethod = object[methodName];
  this.props[`destructured_${methodName}`] = destructuredMethod;
});

[jaybhanushali3166]

Hi @kriswest, I have pushed the updates. let me know if there are any other changes needed. Thanks!

[kriswest]

@jaybhanushali3166 this is looking really good. I need a small adjustment to the changelog and conflicts resolved (both look easy, just another test being added).

Your test cases and conformance cases all look really good - although we could do with the same for user channels (fdc3.broadcast and fdc3.addContextListener). These weren't added when the DesktopAgentProxy's functions were bound. If you're willing to add that in that would be awesome, if not we can drop another issue and PR.

[kriswest]

LGTM, next step is a review by @finos/fdc3-editors (@novavi or @hughtroeger) - and we'll bring it to the next Standards Working Group meeting for final approval (as it introduced an new conformance requirement on the web).

[kriswest]

@jaybhanushali3166 many thanks for your contribution on this!

[jaybhanushali3166]

Welcome, @kriswest! Thank you for your patience and support as we worked through these changes, it’s well appreciated.