eslint/docs/src/rules/callback-return.md

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