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

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