Add `document.ready` promise

[tabatkins]

It's annoying to deal with window.onload, since your async code might not know whether it's run before or after the load event has fired. jQuery makes this easy with its $.ready() function, which functions in a promise-like manner.

So anyway, let's add a .ready promise to Document.

[annevk]

So what would the equivalent be for DOMContentLoaded?

[foolip]

Is there any implementor interest, and have you done a search in existing content to see if many scripts already use document.ready in a way that could break?

[annevk]

There is definitely interest for this. Using promises for state transitions is much more developer friendly.

[jakearchibald]

Here's a discussion on this from last year https://lists.w3.org/Archives/Public/public-whatwg-archive/2014Mar/0091.html

Completely agree. Anything with an onload/error event should get a .ready promise property. Document, images, script, link etc.

[jakearchibald]

(But I do think .ready should be dom ready)

[foolip]

(But I do think .ready should be dom ready)

Do you mean that document.ready should correspond to DOMContentLoaded? It looks like that's the jQuery defintion, so I agree, making document.ready mean anything else seems likely to create confusion.

[jakearchibald]

Yep, agree for the same reasons.

We might want .loaded for full load, but we should think about what that could mean for .ready on other APIs.

[foolip]

Yeah, it would bad if we ended up with some incomprehensible mix of .loaded and .ready, and it looks like at least FontFaceSet.ready already means "ready to use" which is the same I guess we'd want for HTMLImageElement.ready... I guess .ready everywhere except for the document (and window?) load event?

[fvsch]

A suggestion:

• window.ready -> Promise for window.onload
• document.ready -> Promise for DOMContentLoaded

Because the window is ready when everything is loaded, but the document is ready when the initial tree was fully built or something?

One possible downside is that there are a lot of jQuery exemples out there with $(window).ready() and $(document).ready() used indiscriminately. So this precedent could create confusion. (Though technically one can do jQuery().ready() to get the same prototype method.)

[domenic]

In general I feel that .loaded is what we would use most of the time, with a special jQuery-inspired case of .ready for the DOMContentLoaded counterpart.

[jakearchibald]

That fits with onload. Makes sense.

[foolip]

We already have FontFaceSet.ready, so it's a bit late to make .ready the special case.

[jakearchibald]

There's also navigator.serviceWorker.ready - but that doesn't just mean loaded, so it's a special case already

[zcorpan]

Images are also special.

https://html.spec.whatwg.org/multipage/embedded-content.html#img-available

Images can also have two requests going at the same time. The "pending" request is basically hidden currently, but there is some interest in exposing it. See ResponsiveImagesCG/picture-element#269

strawman proposal:

var currentURL = img.currentURL;
var currentPromise = img.ready;
var pendingURL = img.pending.currentURL;
var pendingPromise = img.pending.ready;