Skip to content

Clarify when details should go on events vs targets #585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Clarify when details should go on events vs targets #585

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
0985dde
Clarify when details should go on events vs targets
jakearchibald Sep 17, 2025
9337eb6
Update index.bs
jakearchibald Sep 17, 2025
1193cfa
Provide counter-example
jakearchibald Sep 17, 2025
4c962eb
Tweaks
jakearchibald Sep 17, 2025
209d533
Grammar tweaks
jakearchibald Sep 17, 2025
0d037b5
Tweaks
jakearchibald Sep 17, 2025
0c3916f
Apply suggestions from code review
jakearchibald Sep 18, 2025
726b82f
Remove counter-example
jakearchibald Sep 18, 2025
c3ab2f1
Merge branch 'main' into clarify-event-subclassing
jakearchibald Sep 18, 2025
3459c82
Document exception case
jakearchibald Sep 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2581,6 +2581,13 @@ such as {{InputEvent/inputType}},
describe the nature of an update to the state.
</div>

In some exceptional cases, where maintaining state on an object is expensive,
the state may be placed on the {{Event}} instances,
allowing {{EventTarget/addEventListener}} and {{EventTarget/removeEventListener}} to signal interest/disinterest in this state.
Although, other patterns should be considered,
such as retuning an {{EventTarget}} from a function,
where the function call is a similar signal of interest.
Comment on lines +2587 to +2589
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure that I'm following this sentence. I don't know what "retuning" means in this context.

Do you mean that people might want to consider adding a function to EventTarget to get the state instead? Or are you saying that you might add a function that flips the EventTarget into a mode that tracks the state, so that the cost is only paid when the state is needed?

It would really help if there was a concrete example of this problem. I'm having a little trouble coming up with one.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Calling the function returns the EventTarget, at which point the implementation will have to track the state (if it's exposed on the target instead of the event).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, so instead of something like:

self.pageDataUsage.addEventListener('change', () => {
  console.log(self.pageDataUsage.bytesReceived);
});

…where self.pageDataUsage.bytesReceived will need to be continually updated so it can be synchronously accessed by any code running in the doc/worker, you'd do something like:

self.pageDataUsage.addEventListener('change', (event) => {
  console.log(event.bytesReceived);
});

…where the data is only available to listeners of the change event, so if there are no listeners, the underlying operation to get bytesReceived doesn't need to happen. Or, alternatively, "return an {{EventTarget}} from a function":

const pageDataUsage = await self.monitorDataUsage();

pageDataUsage.addEventListener('change', () => {
  console.log(pageDataUsage.bytesReceived);
});

In this case, it's the call to monitorDataUsage() that signals interest, and GC of pageDataUsage will signal disinterest.

The second model gives you an object representing current state that can be passed around.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

retuning is a typo in the PR. I'll fix that once we figure out the right wording.


<h3 id="events-vs-observers">Use Events and Observers appropriately</h3>

In general, use {{EventTarget}} and notification {{Event}}s,
Expand Down