why does iced coffeescript give warning: overused deferral when an exception is thrown

Question

what does the "overused deferral" warning mean in iced coffeescript? It seems to happen when I throw an uncaught error in the code. How can I let the error bubble up as I need it be an uncaught error for unit testing. For instance, if my getByName method throws an error it bubbles up that iced coffeescript warning rather than bubbling up the exception.

await Profile.getByName p.uname, defer(err, existingUser)
return done new errors.DuplicateUserName(), 409 if existingUser isnt null
return done new Error("error in looking up user name " + err), 500 if err

Answer 1

This error is generated when a callback generated by defer is called more than once. In your case, it could be that Profile.getByName is calling its callback twice (or more). This warning almost always indicates an error in my experience.

You can disable this warning if you create a callback from a Rendezvous and explicitly make it a "multi" callback. Otherwise, it only makes sense to have the return from defer give you a one-shot callback.

More info here: https://github.com/maxtaco/coffee-script/blob/iced/iced.md#icedrendezvousidimultidefer-slots

A small note on terminology: in IcedCoffeeScript, a callback generated by defer is known as a "deferral" in error messages and the documentation.

Answer 2

On top of Max's answer, the appropriate usage of the continuation style programming should be to replace the one-off callbacks, not the repetitive callbacks. All await does is to wait for all its deferrals to complete so it can move on. The following example using node.js's fs module to read a large file would reproduce this error:

toread = process.argv[2]
fs = require 'fs'
rs = fs.createReadStream toread
await rs.on 'data', defer content
console.log "content: #{content}"

Now run this script with a huge text file. Since the data event will fire more than once as the large file content doesn't fit the buffer, it fires multiple times to the generated defer callback, thus giving the same error.

<partial file contents...>
ICED warning: overused deferral at <anonymous> (C:\Users\kk\3.coffee:4)
ICED warning: overused deferral at <anonymous> (C:\Users\kk\3.coffee:4)
ICED warning: overused deferral at <anonymous> (C:\Users\kk\3.coffee:4)
...

In this case, it is wrong to use await/defer since the content won't be complete. This is exactly why Max mentioned the presence of this error would usually indicate a code bug. In fact IMO it should throw an error rather than a warning that can be silenced.