Thoughts on Error Handling

Note: I am simplifying by considering only callback functions in the topics, but direct returns, promises, and objects also apply.

###Preface

This proposal is to make vows error handling easier to understand. It is completely backwards-compatible with vows 0.7.0. I also have some documentation here.

###Question

Error-handling is a source of frustration for vows users. Can context options set in the topic make this easier?

###Use Cases

This is how I rank use cases in order of importance

1. Node-Style callbacks (error, data); Vows reports errors.
2. Single parameter callbacks (data); Vows reports errors.
3. Node-Style callbacks (error, data); Errors are sent to the vow, not reported.
4. Multiple-parameter callbacks with only data parameters; Vows reports errors.
5. Single parameter callbacks (data); Errors are sent to the vow, not reported.
6. Multiple-parameter callbacks with an error parameter (error, data1, data2, etc.); Vows reports errors.
7. Multiple-parameter callbacks; Errors are sent to the vow, not reported.

Case 1

Node-Style callbacks (error, data); Vows reports errors

• Current: Have the vow accept one parameter (the data).
• Better: None.

Case 2

Single parameter callbacks (data); Vows reports errors

• Current: Wrap the callback, providing an extra null parameter at the front
• Better:

Set this option in the topic:

this.callback.errors = false

Case 3

Node-Style callbacks (error, data); Errors are sent to the vow, not reported

• Current: Set options.error to false in the suite.
• Current: Add a second parameter to the vow.
• Better: None.

Case 4

Multiple-parameter callbacks with only data parameters; Vows reports errors

• Current: Wrap the callback, combining all the data parameters. Separate the parameters again after they're received by the vow.
• Better:

Set this option in the topic:

this.callback.multi = true

Case 5

Single parameter callbacks (data); Errors are sent to the vow, not reported

• Current: Add a second unused parameter to the vow, then check the first parameter to see if it is an error or data.
• Better:

Use a combination of

this.callback.errors = false

and a vow with two parameters (error, data).

Case 6

Multiple-parameter callbacks with an error parameter (error, data1, data2, etc.); Vows reports errors

• Current: Wrap the callback, combining all the data parameters. Separate the parameters again after they're received by the vow.
• Better:

Set these options:

this.callback.multi = true
this.callback.errors = true

Case 7

Multiple-parameter callbacks; Errors are sent to the vow, not reported

• Current: Add an error parameter at the front of the vows parameters
• Better: None. (Worse, actually--see Notes)
• Notes: If case 4 is implemented as above then for case 7 to continue to work as before, the user must not set this.callback.multi to true. The possibility of this option being set by accident is a drawback. The user must remember only to set this.callback.multi to true when vows should report errors.

Conclusion

The above proposal provides equal or better support for six of the seven use cases for error-reporting. It provides slightly worse support only for the least-important case.