mdn / sprints

Archived: MDN Web Docs issues are tracked in the content repository.
https://github.com/mdn/content
Creative Commons Zero v1.0 Universal
151 stars 144 forks source link

Correction/improving section of Incumbent settings object tracking to the good version. #4027

Closed dSalieri closed 7 months ago

dSalieri commented 2 years ago

URL(s)

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

Request type

Details

Well, I noticed how ecma262 transformated since 11 version in relation to promises. When I was checking out ecma262 draft, I saw that there appeared definition of HostMakeJobCallback (there is the same definition, only more precise in whatwg). Looking through the Host definitions tied with promises, I noticed interesting conception that was named as Incumbent. I got started to investigate it, that was moderately hard. I saw that Incumbent conception should not use if it possible, but there is perhaps the only justifiable use of the incumbent concept on the web platform (that's very pitty, that we have no example of it).

After all I saw interesting section on the mdn in Promise, that was about incumbent settings object and why this is very important. Unfortunately this section about incumbent settings object in Promise was written bad.

Initial part (introducing of the incumbent settings object) was written good enough. But when you encouter with examples, troubles of understanding get you. Before examples, you will be warned that all web-API knows about the incumbent settings object - this knowledge mess you in the future.

So examples.

First:

<!DOCTYPE html>
<iframe></iframe> <!-- we have a realm here -->
<script> // we have a realm here as well
  const bound = frames[0].postMessage.bind(
    frames[0], "some data", "*");
    // bound is a built-in function -- there is no user
    // code on the stack, so which realm do we use?
  window.setTimeout(bound);
  // this still works, because we use the youngest
  // realm (the incumbent) on the stack
</script>

This example will work in all browsers - so says on the mdn. Well I think that if you're reading article about Promises you need to see full example for understanding. What do we see here? Part of code, that doesn't say anything about his correct work. Don't you?

Going next.

Second:

<!DOCTYPE html>
<iframe></iframe> <!-- we have a realm here -->
<script> // we have a realm here as well
  const bound = frames[0].postMessage.bind(
    frames[0], "some data", "*");
    // bound is a built in function -- there is no user
    // code on the stack -- which realm do we use?
  Promise.resolve(undefined).then(bound);
  // this still works, because we use the youngest
  // realm (the incumbent) on the stack
</script>

This example is almost copy of the first one. Mdn says that to the promises applies same conception like in the top example. Check out this example is too impossible, because there is no part of code that shows you correct behaviour.

Finally, last example:

<!-- y.html -->
<!DOCTYPE html>
<iframe src="x.html"></iframe>
<script>
  const bound = frames[0].postMessage.bind(frames[0], "some data", "*");
  Promise.resolve(undefined).then(bound);
</script>
<!-- x.html -->
<!DOCTYPE html>
<script>
window.addEventListener("message", (event) => {
  document.querySelector("#text").textContent = "hello";
  // this code will only run in browsers that track the incumbent settings object
  console.log(event);
}, false);
</script>

First thing what you notice is document.querySelector("#text").textContent = "hello"; - there is no place in the code that has id text. My first thought after commiting my reading this section: "There is defenitely something missing here". But ok, ok if we omit this silly error - this example better than previous two past.

After reading I had (still have) questions: 1) How are the first two examples different from the last? Article doesn't say anything about it. 2) However article says that the first two examples will work everywhere but the last. Why? 3) At the end article says:

In the above example, the inner text of the