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

   1 ---
   2 title: consistent-return
   3 layout: doc
   4 rule_type: suggestion
   5 ---
   6
   7
   8 Unlike statically-typed languages which enforce that a function returns a specified type of value, JavaScript allows different code paths in a function to return different types of values.
   9
  10 A confusing aspect of JavaScript is that a function returns `undefined` if any of the following are true:
  11
  12 * it does not execute a `return` statement before it exits
  13 * it executes `return` which does not specify a value explicitly
  14 * it executes `return undefined`
  15 * it executes `return void` followed by an expression (for example, a function call)
  16 * it executes `return` followed by any other expression which evaluates to `undefined`
  17
  18 If any code paths in a function return a value explicitly but some code path do not return a value explicitly, it might be a typing mistake, especially in a large function. In the following example:
  19
  20 * a code path through the function returns a Boolean value `true`
  21 * another code path does not return a value explicitly, therefore returns `undefined` implicitly
  22
  23 ```js
  24 function doSomething(condition) {
  25     if (condition) {
  26         return true;
  27     } else {
  28         return;
  29     }
  30 }
  31 ```
  32
  33 ## Rule Details
  34
  35 This rule requires `return` statements to either always or never specify values. This rule ignores function definitions where the name begins with an uppercase letter, because constructors (when invoked with the `new` operator) return the instantiated object implicitly if they do not return another object explicitly.
  36
  37 Examples of **incorrect** code for this rule:
  38
  39 ::: incorrect
  40
  41 ```js
  42 /*eslint consistent-return: "error"*/
  43
  44 function doSomething(condition) {
  45     if (condition) {
  46         return true;
  47     } else {
  48         return;
  49     }
  50 }
  51
  52 function doSomething(condition) {
  53     if (condition) {
  54         return true;
  55     }
  56 }
  57 ```
  58
  59 :::
  60
  61 Examples of **correct** code for this rule:
  62
  63 ::: correct
  64
  65 ```js
  66 /*eslint consistent-return: "error"*/
  67
  68 function doSomething(condition) {
  69     if (condition) {
  70         return true;
  71     } else {
  72         return false;
  73     }
  74 }
  75
  76 function Foo() {
  77     if (!(this instanceof Foo)) {
  78         return new Foo();
  79     }
  80
  81     this.a = 0;
  82 }
  83 ```
  84
  85 :::
  86
  87 ## Options
  88
  89 This rule has an object option:
  90
  91 * `"treatUndefinedAsUnspecified": false` (default) always either specify values or return `undefined` implicitly only.
  92 * `"treatUndefinedAsUnspecified": true` always either specify values or return `undefined` explicitly or implicitly.
  93
  94 ### treatUndefinedAsUnspecified
  95
  96 Examples of **incorrect** code for this rule with the default `{ "treatUndefinedAsUnspecified": false }` option:
  97
  98 ::: incorrect
  99
 100 ```js
 101 /*eslint consistent-return: ["error", { "treatUndefinedAsUnspecified": false }]*/
 102
 103 function foo(callback) {
 104     if (callback) {
 105         return void callback();
 106     }
 107     // no return statement
 108 }
 109
 110 function bar(condition) {
 111     if (condition) {
 112         return undefined;
 113     }
 114     // no return statement
 115 }
 116 ```
 117
 118 :::
 119
 120 Examples of **incorrect** code for this rule with the `{ "treatUndefinedAsUnspecified": true }` option:
 121
 122 ::: incorrect
 123
 124 ```js
 125 /*eslint consistent-return: ["error", { "treatUndefinedAsUnspecified": true }]*/
 126
 127 function foo(callback) {
 128     if (callback) {
 129         return void callback();
 130     }
 131     return true;
 132 }
 133
 134 function bar(condition) {
 135     if (condition) {
 136         return undefined;
 137     }
 138     return true;
 139 }
 140 ```
 141
 142 :::
 143
 144 Examples of **correct** code for this rule with the `{ "treatUndefinedAsUnspecified": true }` option:
 145
 146 ::: correct
 147
 148 ```js
 149 /*eslint consistent-return: ["error", { "treatUndefinedAsUnspecified": true }]*/
 150
 151 function foo(callback) {
 152     if (callback) {
 153         return void callback();
 154     }
 155     // no return statement
 156 }
 157
 158 function bar(condition) {
 159     if (condition) {
 160         return undefined;
 161     }
 162     // no return statement
 163 }
 164 ```
 165
 166 :::
 167
 168 ## When Not To Use It
 169
 170 If you want to allow functions to have different `return` behavior depending on code branching, then it is safe to disable this rule.