eslint/docs/rules/no-unsafe-finally.md

   1 # disallow control flow statements in `finally` blocks (no-unsafe-finally)
   2
   3 JavaScript suspends the control flow statements of `try` and `catch` blocks until the execution of `finally` block finishes. So, when `return`, `throw`, `break`, or `continue` is used in `finally`, control flow statements inside `try` and `catch` are overwritten, which is considered as unexpected behavior. Such as:
   4
   5 ```js
   6 // We expect this function to return 1;
   7 (() => {
   8     try {
   9         return 1; // 1 is returned but suspended until finally block ends
  10     } catch(err) {
  11         return 2;
  12     } finally {
  13         return 3; // 3 is returned before 1, which we did not expect
  14     }
  15 })();
  16
  17 // > 3
  18 ```
  19
  20 ```js
  21 // We expect this function to throw an error, then return
  22 (() => {
  23     try {
  24         throw new Error("Try"); // error is thrown but suspended until finally block ends
  25     } finally {
  26         return 3; // 3 is returned before the error is thrown, which we did not expect
  27     }
  28 })();
  29
  30 // > 3
  31 ```
  32
  33 ```js
  34 // We expect this function to throw Try(...) error from the catch block
  35 (() => {
  36     try {
  37         throw new Error("Try")
  38     } catch(err) {
  39         throw err; // The error thrown from try block is caught and rethrown
  40     } finally {
  41         throw new Error("Finally"); // Finally(...) is thrown, which we did not expect
  42     }
  43 })();
  44
  45 // > Uncaught Error: Finally(...)
  46 ```
  47
  48 ```js
  49 // We expect this function to return 0 from try block.
  50 (() => {
  51   label: try {
  52     return 0; // 0 is returned but suspended until finally block ends
  53   } finally {
  54     break label; // It breaks out the try-finally block, before 0 is returned.
  55   }
  56   return 1;
  57 })();
  58
  59 // > 1
  60 ```
  61
  62 ## Rule Details
  63
  64 This rule disallows `return`, `throw`, `break`, and `continue` statements inside `finally` blocks. It allows indirect usages, such as in `function` or `class` definitions.
  65
  66 Examples of **incorrect** code for this rule:
  67
  68 ```js
  69 /*eslint no-unsafe-finally: "error"*/
  70 let foo = function() {
  71     try {
  72         return 1;
  73     } catch(err) {
  74         return 2;
  75     } finally {
  76         return 3;
  77     }
  78 };
  79 ```
  80
  81 ```js
  82 /*eslint no-unsafe-finally: "error"*/
  83 let foo = function() {
  84     try {
  85         return 1;
  86     } catch(err) {
  87         return 2;
  88     } finally {
  89         throw new Error;
  90     }
  91 };
  92 ```
  93
  94 Examples of **correct** code for this rule:
  95
  96 ```js
  97 /*eslint no-unsafe-finally: "error"*/
  98 let foo = function() {
  99     try {
 100         return 1;
 101     } catch(err) {
 102         return 2;
 103     } finally {
 104         console.log("hola!");
 105     }
 106 };
 107 ```
 108
 109 ```js
 110 /*eslint no-unsafe-finally: "error"*/
 111 let foo = function() {
 112     try {
 113         return 1;
 114     } catch(err) {
 115         return 2;
 116     } finally {
 117         let a = function() {
 118             return "hola!";
 119         }
 120     }
 121 };
 122 ```
 123
 124 ```js
 125 /*eslint no-unsafe-finally: "error"*/
 126 let foo = function(a) {
 127     try {
 128         return 1;
 129     } catch(err) {
 130         return 2;
 131     } finally {
 132         switch(a) {
 133             case 1: {
 134                 console.log("hola!")
 135                 break;
 136             }
 137         }
 138     }
 139 };
 140 ```
 141
 142 ## When Not To Use It
 143
 144 If you want to allow control flow operations in `finally` blocks, you can turn this rule off.