Record.whenReady() has inconsistent behavior

[Vortex375]

Record.whenReady() sometimes invokes the callback synchronously (i.e. "immediately) and sometimes asynchronously by using this.once('ready', ...).

This is known as "releasing Zalgo" (http://blog.izs.me/post/59142742143/designing-apis-for-asynchrony)

whenReady() should always invoke the callback asynchronously (e.g. using setTimeout()).

[WolframHempel]

Hi @Vortex375

a record's ready event fires when the record is first loaded(asynchronous). If its data is already loaded however it is available immediately (synchronously) - as can be determined by checking the record's isReady flag.

whenReady() was introduced solely for the purpose of normalising these two behaviors and intentionally fires straight away when the data is already available and with a delay if it is still being loaded.

[Vortex375]

However, having this inconsistent behavior complicates the usage of this "convenience" method, because you have to check the isReady flag anyway, or always wrap the call to whenReady() in a process.nextTick() or setTimeout().

It also prevents the method from being used conveniently with async.waterfall() and the like.

Most importantly, it is common design practice to have a method either always invoke its callback synchronously or asynchronously - not both. Though the behavior is somewhat documented (it states the callback can be invoked "immediately") it is not what a user would expect the method to do.

Would there be any drawback to always invoking the callback asynchronously?

[WolframHempel]

You wouldn't actually need to wrap the method into setTimeout and async.waterfall works perfectly fine with a mix of synchronous and asynchronous methods.

As mentioned, whenReady purely exists to fire WHEN the record is ready - which might be the case already or once it received data from the server. Could you provide a concrete example that can't be solved without making the method aynchronous?