Document using promise-returning methods for state transitions

[domenic]

Streams uses them this way, and @sicking was proposing something similar for Service Worker.

• It should be a third major use of promises, as a generalization of one-and-done events.
• Such cases should always be expressed as methods, never as getters.
• We can use the example of image.loaded(), pointing out that image.loaded doesn't work because you can "reload" an image by setting its src.
• We should caution against overuse of this pattern, as it steps on the toes of recurring events a bit.
• The major difference between this and recurring events is the recurring part: adding listeners to promise-vending state transition methods only gives you notification of the next state transition, whereas adding an event listener gives you notification each time the event is triggered. The former is often what you want for state machine code.
• We should note that it's particularly useful because it allows post-facto registration of interest.

[domenic]

I wonder if we should give naming guidelines. On public-webapps I suggested whenRegistrationNeeded() or waitForRegistrationNeeded() for service worker. But then again, I propose loaded() above for images. In streams, I use wait().

To some extent it comes down to verb vs. adjective... loaded() could become waitForLoaded() or whenLoaded(). wait() could become whenReadable() or waitForReadable(). Or, whenRegistrationNeeded() could become registrationNeeded(), and wait() could become readable().

Hmm.

[domenic]

After some IRC discussion with @Hixie and @jakearchibald and @TabAtkins, I have been convinced that trying to use methods vs. properties as a distinction here is a bad idea. They should be properties. And any prefixes or naming guidelines are not a good idea either.

http://krijnhoetmer.nl/irc-logs/whatwg/20140520#l-987

So it should be image.loaded (despite the fact that images can be reused) and serviceWorker.registrationNeeded. stream.wait() remains a method because it actually performs an action, of signaling to the stream that there are consumers waiting for data.

[tabatkins]

So it sounds like the distinction you're arguing for is that informational promises should just be exposed as properties, while methods that take some action and then also return a promise should be, well, methods. Right?

This separation means that Font Loading is almost right, with the exception of FontFaceSet#ready(), which has no side-effect and just hands you an informational promise. Correct? Does it matter that a FontFaceSet can flip back and forth between "ready" and "not ready" many times over the course of a document, thus meaning we'd end up generating fresh promises several times for the property form?

[domenic]

Right?

Yup!

Does it matter that a FontFaceSet can flip back and forth between "ready" and "not ready" many times over the course of a document, thus meaning we'd end up generating fresh promises several times for the property form?

At first I thought it did, as you can see from the original post, but conversations with @Hixie in IRC convinced me that it doesn't matter, and I was trying to use the method-vs.-property signal for something it wasn't really meant for. So yeah, as long as it's not a fresh promise each time you get the property, but instead changes only in reaction to well-defined events (like re-loading), a property is fine.