Some background:
#247 added mappingHint to wrapCallback. At the time, we thought that the default behavior should wrap multiple arguments to the callback in an array, but this was not backwards compatible, so we decided to delay until 3.0 and added a note in the docs warning of the impending change.
I'm not so sure this default behavior is a good thing anymore. See petkaantonov/bluebird#307 for the issues bluebird (and Q) have had with this default behavior breaking promisified functions. Basically, the following cases can happen
- Library writer adds an extra argument to the callback. From their standpoint, this is not a breaking change, but it causes
wrapCallback to push an array instead.
- Library writer normally fires the callback with two arguments, but adds a code path that only does it with one (e.g.,
cb(null, value) instead of cb(null, value, null)). The intention is that the second value should be null. This is a common Javascript pattern, but it causes wrapCallback to switch between pushing an array and not practically willy-nilly. This is very bad.
I suggest we take out the wording in the mappingHint docs and just ask people to specify a mappingHint when they need to.
Some background:
#247 added
mappingHinttowrapCallback. At the time, we thought that the default behavior should wrap multiple arguments to the callback in an array, but this was not backwards compatible, so we decided to delay until 3.0 and added a note in the docs warning of the impending change.I'm not so sure this default behavior is a good thing anymore. See petkaantonov/bluebird#307 for the issues bluebird (and Q) have had with this default behavior breaking promisified functions. Basically, the following cases can happen
wrapCallbackto push an array instead.cb(null, value)instead ofcb(null, value, null)). The intention is that the second value should benull. This is a common Javascript pattern, but it causeswrapCallbackto switch between pushing an array and not practically willy-nilly. This is very bad.I suggest we take out the wording in the
mappingHintdocs and just ask people to specify amappingHintwhen they need to.