eslint/docs/rules/callback-return.md

   1 # Enforce Return After Callback (callback-return)
   2
   3 This rule was **deprecated** in ESLint v7.0.0. Please use the corresponding rule in [`eslint-plugin-node`](https://github.com/mysticatea/eslint-plugin-node).
   4
   5 The callback pattern is at the heart of most I/O and event-driven programming
   6  in JavaScript.
   7
   8 ```js
   9 function doSomething(err, callback) {
  10     if (err) {
  11         return callback(err);
  12     }
  13     callback();
  14 }
  15 ```
  16
  17 To prevent calling the callback multiple times it is important to `return` anytime the callback is triggered outside
  18  of the main function body. Neglecting this technique often leads to issues where you do something more than once.
  19  For example, in the case of an HTTP request, you may try to send HTTP headers more than once leading Node.js to `throw`
  20  a `Can't render headers after they are sent to the client.` error.
  21
  22 ## Rule Details
  23
  24 This rule is aimed at ensuring that callbacks used outside of the main function block are always part-of or immediately
  25 preceding a `return` statement. This rule decides what is a callback based on the name of the function being called.
  26
  27 ## Options
  28
  29 The rule takes a single option - an array of possible callback names - which may include object methods. The default callback names are `callback`, `cb`, `next`.
  30
  31 ### Default callback names
  32
  33 Examples of **incorrect** code for this rule with the default `["callback", "cb", "next"]` option:
  34
  35 ```js
  36 /*eslint callback-return: "error"*/
  37
  38 function foo(err, callback) {
  39     if (err) {
  40         callback(err);
  41     }
  42     callback();
  43 }
  44 ```
  45
  46 Examples of **correct** code for this rule with the default `["callback", "cb", "next"]` option:
  47
  48 ```js
  49 /*eslint callback-return: "error"*/
  50
  51 function foo(err, callback) {
  52     if (err) {
  53         return callback(err);
  54     }
  55     callback();
  56 }
  57 ```
  58
  59 ### Supplied callback names
  60
  61 Examples of **incorrect** code for this rule with the option `["done", "send.error", "send.success"]`:
  62
  63 ```js
  64 /*eslint callback-return: ["error", ["done", "send.error", "send.success"]]*/
  65
  66 function foo(err, done) {
  67     if (err) {
  68         done(err);
  69     }
  70     done();
  71 }
  72
  73 function bar(err, send) {
  74     if (err) {
  75         send.error(err);
  76     }
  77     send.success();
  78 }
  79 ```
  80
  81 Examples of **correct** code for this rule with the option `["done", "send.error", "send.success"]`:
  82
  83 ```js
  84 /*eslint callback-return: ["error", ["done", "send.error", "send.success"]]*/
  85
  86 function foo(err, done) {
  87     if (err) {
  88         return done(err);
  89     }
  90     done();
  91 }
  92
  93 function bar(err, send) {
  94     if (err) {
  95         return send.error(err);
  96     }
  97     send.success();
  98 }
  99 ```
 100
 101 ## Known Limitations
 102
 103 Because it is difficult to understand the meaning of a program through static analysis, this rule has limitations:
 104
 105 * *false negatives* when this rule reports correct code, but the program calls the callback more than one time (which is incorrect behavior)
 106 * *false positives* when this rule reports incorrect code, but the program calls the callback only one time (which is correct behavior)
 107
 108 ### Passing the callback by reference
 109
 110 The static analysis of this rule does not detect that the program calls the callback if it is an argument of a function (for example,  `setTimeout`).
 111
 112 Example of a *false negative* when this rule reports correct code:
 113
 114 ```js
 115 /*eslint callback-return: "error"*/
 116
 117 function foo(err, callback) {
 118     if (err) {
 119         setTimeout(callback, 0); // this is bad, but WILL NOT warn
 120     }
 121     callback();
 122 }
 123 ```
 124
 125 ### Triggering the callback within a nested function
 126
 127 The static analysis of this rule does not detect that the program calls the callback from within a nested function or an immediately-invoked function expression (IIFE).
 128
 129 Example of a *false negative* when this rule reports correct code:
 130
 131 ```js
 132 /*eslint callback-return: "error"*/
 133
 134 function foo(err, callback) {
 135     if (err) {
 136         process.nextTick(function() {
 137             return callback(); // this is bad, but WILL NOT warn
 138         });
 139     }
 140     callback();
 141 }
 142 ```
 143
 144 ### If/else statements
 145
 146 The static analysis of this rule does not detect that the program calls the callback only one time in each branch of an `if` statement.
 147
 148 Example of a *false positive* when this rule reports incorrect code:
 149
 150 ```js
 151 /*eslint callback-return: "error"*/
 152
 153 function foo(err, callback) {
 154     if (err) {
 155         callback(err); // this is fine, but WILL warn
 156     } else {
 157         callback();    // this is fine, but WILL warn
 158     }
 159 }
 160 ```
 161
 162 ## When Not To Use It
 163
 164 There are some cases where you might want to call a callback function more than once. In those cases this rule
 165  may lead to incorrect behavior. In those cases you may want to reserve a special name for those callbacks and
 166  not include that in the list of callbacks that trigger warnings.
 167
 168 ## Further Reading
 169
 170 * [The Art Of Node: Callbacks](https://github.com/maxogden/art-of-node#callbacks)
 171 * [Nodejitsu: What are the error conventions?](https://docs.nodejitsu.com/articles/errors/what-are-the-error-conventions/)
 172
 173 ## Related Rules
 174
 175 * [handle-callback-err](handle-callback-err.md)