Clarify when details should go on events vs targets

[jakearchibald]

I'm proposing this following discussions on ProgressEvent in webmachinelearning/translation-api#61.

I wanted to provide reasoning and clarity for this rule, assuming I understand its intent correctly.

---

Preview | Diff

[jakearchibald]

The previous heading seemed… incomplete.

[lukewarlow]

Thanks for this I meant to raise an issue that examples should be added. I think an example that follows the principle is good but an example that doesn't follow it, and what it should have looked like would be useful too.

[jakearchibald]

Unrelated change, but it's something many editors do automatically. I can remove it, but I imagine others will run into the same thing.

[martinthomson]

You are not the only one. We should maybe lint for trailing whitespace.

[annevk]

I'm not sure I agree with this principle. This assumes that tracking this information is free. I don't think it necessarily is. And with the current design only those interested in the information pay for having it tracked.

(This doesn't mean that FetchObserver/FetchMonitor can't expose the information directly, because obtaining such an object could be considered the opt-in.)

[jakearchibald]

That's fair.

[martinthomson]

This is way better than what we had. Thanks for doing this. I've made a few suggestions, but feel free to dismiss them.

[martinthomson]

Does this need to be a note?

[jakearchibald]

I did it to separate the rule from the explanation of the rule, since the explanation is non-normative. But this spec doesn't have such a strict divide between normative and non-normative. But I don't mind either way, happy to go with whatever you think.

[jakearchibald]

I've removed the XHR counter-example based on @annevk's feedback. I couldn't immediately think of another counter-example.

Happy for this to land once others are.

[annevk]

I think the XMLHttpRequest example showed a problem with this principle as a whole. That it doesn't properly consider the engineering trade-offs involved. Whether you expose state on the EventTarget or the Event is really about the purpose of the API, likelihood of the state being needed in all usage scenarios, cost to users, etc.

[jakearchibald]

My assumption was that any rules in this doc can be broken if it can be demonstrated that the alternative is better for users/developers in a given case.

@annevk would it help if I added a note recognising the case where the event listener can be used as an opt-in to internal processing? Although, as we see in the fetch case, there are other ways to handle the opt-in.

[annevk]

Yeah, maybe something that hints at the fact that for potentially costly auxiliary state there is a real trade-off to be made here.

While principles can be broken, generally they point out the one correct way to do something and folks might well take away from that they can never use state on events.

[jakearchibald]

@annevk PTAL

[martinthomson]

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.

[annevk]

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

[jakearchibald]

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.

[jakearchibald]

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