Strengthen the types for `Bridge` events #3838

esanzgar · 2021-10-15T09:51:40Z

I have created type definitions for all the event names that are sent
across the different frames using various Bridges. It is based on the
previous bridge-events.js. I broke down the events in four sections
based on the direction of the messages:

guest -> sidebar events
host -> sidebar events
sidebar -> guest/s events
sidebar -> host events

For those events that didn't have a description I added one.

This is more stringent and less verbose than the previous lookup system.

codecov · 2021-10-15T09:55:13Z

Codecov Report

Merging #3838 (b36b8e6) into master (910b3da) will decrease coverage by 0.00%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master    #3838      +/-   ##
==========================================
- Coverage   99.02%   99.02%   -0.01%     
==========================================
  Files         211      211              
  Lines        7797     7796       -1     
  Branches     1757     1757              
==========================================
- Hits         7721     7720       -1     
  Misses         76       76

Impacted Files	Coverage Δ
src/annotator/guest.js	`99.16% <ø> (ø)`
src/annotator/sidebar.js	`98.13% <ø> (ø)`
src/shared/bridge.js	`100.00% <ø> (ø)`
src/annotator/annotation-counts.js	`100.00% <100.00%> (ø)`
src/annotator/annotation-sync.js	`100.00% <100.00%> (ø)`
src/annotator/features.js	`100.00% <100.00%> (ø)`
src/sidebar/components/HypothesisApp.js	`100.00% <100.00%> (ø)`
src/sidebar/components/TopBar.js	`100.00% <100.00%> (ø)`
src/sidebar/components/UserMenu.js	`100.00% <100.00%> (ø)`
src/sidebar/services/features.js	`100.00% <100.00%> (ø)`
... and 1 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 910b3da...b36b8e6. Read the comment docs.

I have created type definitions for all the event names that are sent across the different frames using various `Bridge`s. It is based on the previous `bridge-events.js`. I broke down the events in four sections based on the direction of the messages: * guest -> sidebar events * host -> sidebar events * sidebar -> guest/s events * sidebar -> host events For those events that didn't have a description I added one. This is more stringent and less verbose than the previous lookup system.

robertknight

The functional code changes look good. I found a few minor typos of event names in test descriptions.

The main feedback I have is regarding the comments in the bridge-events.d.ts file. There are a few that are incorrect, some in obvious ways and others in more subtle ones, and others that reference implementation details of how the event is currently handled rather what the event means. For example when the guest sends "closeSidebar" to the sidebar app it is requesting that the sidebar be closed. How exactly the sidebar makes this happen is an implementation detail that might change in future. The most common issue I see though is where a comment restates the event and type name with the same words. Unless a comment is adding value (eg. by clarifying something about when the event is emitted, or why, or otherwise providing useful additional information), I would prefer to remove it.

robertknight · 2021-10-18T07:19:21Z

src/shared/bridge.js


 /**
 * The Bridge service sets up a channel between frames and provides an events
 * API on top of it.
 *
+ * @template {BridgeEvent} CallMethods - Names of methods that can be called (via {@link call})
+ * @template {BridgeEvent} OnMethods - Names of methods that can be handled (via {@link on})


Per a Slack thread from last week, this is where defaults for template arguments might be useful. You could use [CallMethods=BridgeEvent] and any use of Bridge without arguments would use that. As it is, there are several places where no template arguments are specified and so it will default to any.

I probably would have been inclined to just use string as the base type here, to avoid coupling Bridge to the specific events that it is used with in the client.

The advantage of using BridgeEvent instead of string is that it autocompletes the possible event types:

The above works if the Bridge is not redefined with a typedef.

Ah. That seems useful, although presumably this would also work if the Bridge instance has an annotation to specify the specific events that it uses?

src/sidebar/components/test/HypothesisApp-test.js

robertknight · 2021-10-18T07:23:44Z

src/types/bridge-events.d.ts

@@ -0,0 +1,161 @@
+/**
+ * This module defines the set of global events that are dispatched across the
+ * the bridge(s) between the sidebar-host and sidebar-guest(s).


I would change this to be a little more general. Something like: "This module defines the events that are sent between frames with different roles in the client (guest, host, sidebar)".

I expect that we will want to add additional channels in future, eg. guest <-> host or notebook <-> host and this change would avoid needing to update this comment each time.

src/types/bridge-events.d.ts

robertknight · 2021-10-18T08:06:25Z

src/annotator/annotation-sync.js

+/**
+ * @template {GuestToSidebarEvent} T
+ * @template {SidebarToGuestEvent} U
+ * @typedef {import('../shared/bridge').Bridge<T,U>} Bridge


Since we only ever use Bridge with one pair of type arguments in this file, you could just make the type arguments part of this typedef. eg.

/** * @typedef {import('../shared/bridge').Bridge<GuestToSidebarEvent, SidebarToGuestEvent>} SidebarBridge */

src/annotator/test/sidebar-test.js

robertknight · 2021-10-18T08:19:15Z

src/sidebar/services/frame-sync.js

+ * @typedef {import('../../types/bridge-events').SidebarToHostEvent} SidebarToHostEvent
+ * @typedef {import('../../types/bridge-events').HostToSidebarEvent} HostToSidebarEvent
+ * @typedef {import('../../types/bridge-events').SidebarToGuestEvent} SidebarToGuestEvent
+ * @typedef {import('../../types/bridge-events').GuestToSidebarEvent} GuestToSidebarEvent


It's unfortunate how verbose this gets. There have been some discussions about better options in microsoft/TypeScript#22160 but I don't see a solution yet.

robertknight · 2021-10-18T08:24:49Z

src/types/bridge-events.d.ts

+  | 'profileRequested'
+
+  /**
+   * The sidebar inform the host to update the number of annotations in the partner site.


I think there is ambiguity here about what "number of annotations" means. There is already a clearer explanation in https://h.readthedocs.io/projects/client/en/latest/publishers/host-page-integration/#cmdoption-arg-data-hypothesis-annotation-count which we could link to.

esanzgar · 2021-10-18T13:49:29Z

src/annotator/annotation-counts.js

@@ -11,8 +9,9 @@ const ANNOTATION_COUNT_ATTR = 'data-hypothesis-annotation-count';
 *   display annotation count.
 * @param {import('../shared/bridge').Bridge} bridge - Channel for host-sidebar communication


The issue about any type doesn't seem to happen in version 4.5:
https://www.staging-typescript.org/play?ts=4.5.0-dev.20211015&filetype=js#code/PQKhCgAIUgBAXApgWwA4BsCGTIG8DkAFouugPb4A++ARgJ6L4C+kAKlDLKpgE6bJ5WLTB2DgAxlgDOUyMjoBhabNxRI60BHXrO3PgNxDII7dDGnxmUgApMASlWmLZAHZSy6RADpyAc1t2ANxq6kzgYeDgmnDwdKiIePJKmDIAPEQk5PgAfCwgYuKuUvCQAJZu8Jgu4ogAjJAAvJAuiADucorK1kHg5cVVNbVeljYZpBQ9UWAxcQm4Scrp9Iy5ZhJFJX2V1YgATI3NbR3JMt3BWwN7w1bo1rQM+JOFFWUVlwDMBy3tCylSZ703jt3tdRsRxo9zkCaiCRrd7owekA

esanzgar · 2021-10-18T13:51:48Z

src/annotator/annotation-counts.js

@@ -11,8 +9,9 @@ const ANNOTATION_COUNT_ATTR = 'data-hypothesis-annotation-count';
 *   display annotation count.
 * @param {import('../shared/bridge').Bridge} bridge - Channel for host-sidebar communication


Passing in the bridge here is not really the best separation of responsibilities. What I would suggest we do in future is make the sidebar responsible for listening for the message and instead put only the logic for updating the page elements (the contents of updateAnnotationCountElems here) in a function in a separate module.

I agree.

esanzgar · 2021-10-18T13:54:40Z

src/annotator/annotation-sync.js

+/**
+ * @template {GuestToSidebarEvent} T
+ * @template {SidebarToGuestEvent} U
+ * @typedef {import('../shared/bridge').Bridge<T,U>} Bridge


esanzgar · 2021-10-18T14:07:57Z

src/types/bridge-events.d.ts

@@ -0,0 +1,161 @@
+/**
+ * This module defines the set of global events that are dispatched across the
+ * the bridge(s) between the sidebar-host and sidebar-guest(s).


esanzgar · 2021-10-18T15:24:02Z

src/shared/bridge.js


 /**
 * The Bridge service sets up a channel between frames and provides an events
 * API on top of it.
 *
+ * @template {BridgeEvent} CallMethods - Names of methods that can be called (via {@link call})
+ * @template {BridgeEvent} OnMethods - Names of methods that can be handled (via {@link on})


The advantage of using BridgeEvent instead of string is that it autocompletes the possible event types:

The above works if the Bridge is not redefined with a typedef.

esanzgar · 2021-10-18T15:30:44Z

src/annotator/guest.js

+    /**
+     * Channel for sidebar-guest communication.
+     *
+     * @type {Bridge<GuestToSidebarEvent,SidebarToGuestEvent>}


Try to remove the type here and you will see that the it has a default template argument:

esanzgar · 2021-10-18T15:46:40Z

I have accepted your changes regarding the descriptions of the events. Most of the descriptions were created previously.

Some of the messages brings clarity to how the events flow. For example, I found it useful to know that the closeSidebar flows from guest -> sidebar -> host.

Some other events are difficult to explain even with the description: toggleAnnotationSelection vs. focusAnnotations

esanzgar · 2021-10-18T15:50:05Z

src/types/bridge-events.d.ts

+  /**
+   * The host informs the sidebar that a guest frame has been destroyed
+   */
+  | 'destroyFrame'


Do you think frameDestroyed would be clearer? (It sounds symmetric to sidebarOpened)

Probably. Some of the RPC calls defined in this module represent events that happened, without the caller necessarily expecting a specific response from the other frame. Other calls are commands that ask the receiving frame to do something specific (eg. openSidebar). destroyFrame does seem more of an event than a command.

robertknight · 2021-10-19T11:47:05Z

src/types/bridge-events.d.ts

@@ -76,7 +76,7 @@ export type SidebarToGuestEvent =
  | 'focusAnnotations'

  /**
-   * The sidebar is asking the guest(s) to get the document metadata.
+   * The sidebar is asking the guest(s) the URL and other metadata about the document.


"the URL" => "for the URL"

Co-authored-by: Robert Knight <robertknight@gmail.com>

robertknight

LGTM. Thanks for your patience with this.

robertknight · 2021-10-19T12:50:20Z

src/annotator/annotation-sync.js

 * @typedef {import('../types/annotator').AnnotationData} AnnotationData
 * @typedef {import('../types/annotator').Destroyable} Destroyable
+ * @typedef {import('../types/bridge-events').GuestToSidebarEvent} GuestToSidebarEvent
+ * @typedef {import('../types/bridge-events').SidebarToGuestEvent} SidebarToGuestEvent


Are these typedefs still needed given the change to the Bridge typedef above?

robertknight · 2021-10-19T12:52:47Z

src/shared/bridge.js


 /**
 * The Bridge service sets up a channel between frames and provides an events
 * API on top of it.
 *
+ * @template {BridgeEvent} CallMethods - Names of methods that can be called (via {@link call})
+ * @template {BridgeEvent} OnMethods - Names of methods that can be handled (via {@link on})


Ah. That seems useful, although presumably this would also work if the Bridge instance has an annotation to specify the specific events that it uses?

esanzgar mentioned this pull request Oct 15, 2021

Re-enforce the use of enums for Bridge events #3833

Closed

esanzgar force-pushed the bridge-event-types branch 3 times, most recently from 545ce16 to e6b39e5 Compare October 15, 2021 13:04

esanzgar force-pushed the bridge-event-types branch from e6b39e5 to 1748ca4 Compare October 16, 2021 06:27

robertknight requested changes Oct 18, 2021

View reviewed changes

esanzgar mentioned this pull request Oct 18, 2021

Make highlight visibility state work in a multi-guest world #3830

Merged

esanzgar force-pushed the bridge-event-types branch from 03fb10e to 38cc9d7 Compare October 18, 2021 15:16

esanzgar commented Oct 18, 2021

View reviewed changes

esanzgar force-pushed the bridge-event-types branch from 38cc9d7 to eb4470d Compare October 18, 2021 15:42

esanzgar commented Oct 18, 2021

View reviewed changes

esanzgar force-pushed the bridge-event-types branch from eb4470d to 0327737 Compare October 18, 2021 16:08

robertknight reviewed Oct 19, 2021

View reviewed changes

Apply suggestions from code review

b36b8e6

Co-authored-by: Robert Knight <robertknight@gmail.com>

esanzgar force-pushed the bridge-event-types branch from 0327737 to b36b8e6 Compare October 19, 2021 12:29

robertknight approved these changes Oct 19, 2021

View reviewed changes

esanzgar merged commit 0b757c6 into master Oct 19, 2021

esanzgar deleted the bridge-event-types branch October 19, 2021 13:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Strengthen the types for `Bridge` events #3838

Strengthen the types for `Bridge` events #3838

esanzgar commented Oct 15, 2021

codecov bot commented Oct 15, 2021 •

edited

Loading

robertknight left a comment

robertknight Oct 18, 2021

esanzgar Oct 18, 2021

robertknight Oct 19, 2021

robertknight Oct 18, 2021

esanzgar Oct 18, 2021

robertknight Oct 18, 2021

esanzgar Oct 18, 2021

robertknight Oct 18, 2021

robertknight Oct 18, 2021

esanzgar Oct 18, 2021

esanzgar Oct 18, 2021

esanzgar Oct 18, 2021

esanzgar Oct 18, 2021

esanzgar Oct 18, 2021

esanzgar Oct 18, 2021

esanzgar commented Oct 18, 2021

esanzgar Oct 18, 2021

robertknight Oct 19, 2021

robertknight Oct 19, 2021

robertknight left a comment

robertknight Oct 19, 2021

robertknight Oct 19, 2021

		@@ -11,8 +9,9 @@ const ANNOTATION_COUNT_ATTR = 'data-hypothesis-annotation-count';
		* display annotation count.
		* @param {import('../shared/bridge').Bridge} bridge - Channel for host-sidebar communication

Strengthen the types for Bridge events #3838

Strengthen the types for Bridge events #3838

Conversation

esanzgar commented Oct 15, 2021

codecov bot commented Oct 15, 2021 • edited Loading

Codecov Report

robertknight left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

esanzgar commented Oct 18, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

robertknight left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Strengthen the types for `Bridge` events #3838

Strengthen the types for `Bridge` events #3838

codecov bot commented Oct 15, 2021 •

edited

Loading