useExplicitReturnType

TypeScript and TSX

Summary

Rule available since: v2.4.11
Diagnostic Category: lint/nursery/useExplicitReturnType
This rule doesn’t have a fix.
The default severity of this rule is warning.
Sources:
- Inspired from @typescript-eslint/explicit-function-return-type

How to configure

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useExplicitReturnType": "error"
6
      }
7
    }
8
  }
9
}

Description

Require explicit return types on functions and class methods.

Functions in TypeScript often don’t need to be given an explicit return type annotation. Leaving off the return type is less code to read or write and allows the compiler to infer it from the contents of the function.

However, explicit return types are required when using TypeScript’s isolatedModules and similar single-file transpilation tools, because the compiler cannot perform cross-file type inference. Without explicit return types, exported functions may produce incomplete or incorrect .d.ts declarations.

This rule enforces that functions do have an explicit return type annotation.

Examples

Invalid

1
// Should indicate that no value is returned (void)
2
function test() {
3
  return;
4
}

code-block.ts:2:1 lint/nursery/useExplicitReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Missing return type on function.
  
    1 │ // Should indicate that no value is returned (void)
  > 2 │ function test() {
      │ ^^^^^^^^^^^^^
    3 │   return;
    4 │ }
  
  ℹ Declaring the return type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/2017 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

1
// Should indicate that a number is returned
2
var fn = function () {
3
   return 1;
4
};

code-block.ts:2:10 lint/nursery/useExplicitReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Missing return type on function.
  
    1 │ // Should indicate that a number is returned
  > 2 │ var fn = function () {
      │          ^^^^^^^^^^^^^
  > 3 │    return 1;
  > 4 │ };
      │ ^
    5 │ 
  
  ℹ Declaring the return type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/2017 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

1
// Should indicate that a string is returned
2
var arrowFn = () => 'test';

code-block.ts:2:15 lint/nursery/useExplicitReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Missing return type on function.
  
    1 │ // Should indicate that a string is returned
  > 2 │ var arrowFn = () => ‘test’;
      │               ^^^^^^^^^^^^
    3 │ 
  
  ℹ Declaring the return type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/2017 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

1
class Test {
2
  // Should indicate that no value is returned (void)
3
  method() {
4
    return;
5
  }
6
}

code-block.ts:3:3 lint/nursery/useExplicitReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Missing return type on function.
  
    1 │ class Test {
    2 │   // Should indicate that no value is returned (void)
  > 3 │   method() {
      │   ^^^^^^^^^^
  > 4 │     return;
  > 5 │   }
      │   ^
    6 │ }
    7 │ 
  
  ℹ Declaring the return type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/2017 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

The following example is considered incorrect for a higher-order function, as the returned function does not specify a return type:

1
var arrowFn = () => () => {};

code-block.ts:1:21 lint/nursery/useExplicitReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Missing return type on function.
  
  > 1 │ var arrowFn = () => () => {};
      │                     ^^^^^^^^
    2 │ 
  
  ℹ Declaring the return type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/2017 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

1
var arrowFn = () => {
2
  return () => { };
3
}

code-block.ts:2:10 lint/nursery/useExplicitReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Missing return type on function.
  
    1 │ var arrowFn = () => {
  > 2 │   return () => { };
      │          ^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Declaring the return type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/2017 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

The following example is considered incorrect because not all return statements return a function. A higher-order function is only valid when every return statement returns a function expression:

1
function f() {
2
  if (x) {
3
    return 0;
4
  }
5
  return (): void => {}
6
}

code-block.ts:1:1 lint/nursery/useExplicitReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Missing return type on function.
  
  > 1 │ function f() {
      │ ^^^^^^^^^^
    2 │   if (x) {
    3 │     return 0;
  
  ℹ Declaring the return type makes the code self-documented and can speed up TypeScript type checking.
  
  ℹ Add a return type to the function.
  
  ℹ This rule is still being actively worked on, so it may be missing features or have rough edges. Visit https://github.com/biomejs/biome/issues/2017 for more information or to report possible bugs.
  
  ℹ This rule belongs to the nursery group, which means it is not yet stable and may change in the future. Visit https://biomejs.dev/linter/#nursery for more information.

Valid

1
// No return value should be expected (void)
2
function test(): void {
3
  return;
4
}

1
// A return value of type number
2
var fn = function (): number {
3
  return 1;
4
}

1
// A return value of type string
2
var arrowFn = (): string => 'test';

1
class Test {
2
  // No return value should be expected (void)
3
  method(): void {
4
    return;
5
  }
6
}

The following example is considered correct code for a function immediately returning a value with as const:

1
var func = (value: number) => ({ foo: 'bar', value }) as const;

The following examples are considered correct code for a function passed as an argument:

1
// Callbacks without return types
2
setTimeout(function() { console.log("Hello!"); }, 1000);

The following example is considered correct code for a higher-order function, where the returned function explicitly specifies a return type and the function body contains only one statement:

1
// the outer function returns an inner function that has a `void` return type
2
var arrowFn = () => (): void => {};

1
// the outer function returns an inner function that has a `void` return type
2
var arrowFn = () => {
3
  return (): void => { };
4
}

The following examples are considered correct for type annotations on variables in function expressions:

1
// A function with a type assertion using `as`
2
var asTyped = (() => '') as () => string;

1
// A function with a type assertion using `<>`
2
var castTyped = <() => string>(() => '');

1
// A variable declarator with a type annotation.
2
type FuncType = () => string;
3
var arrowFn: FuncType = () => 'test';

1
// A function is a default parameter with a type annotation
2
type CallBack = () => void;
3
var f = (gotcha: CallBack = () => { }): void => { };

1
// A class property with a type annotation
2
type MethodType = () => void;
3
class App {
4
    private method: MethodType = () => { };
5
}

Options

`allowExpressions`

When set to true, only function declarations and class methods are checked. Function expressions (assigned to variables, passed as arguments, etc.) are allowed without return types.

Default: false

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useExplicitReturnType": {
6
          "options": {
7
            "allowExpressions": true
8
          }
9
        }
10
      }
11
    }
12
  }
13
}

1
// Callbacks and standalone expressions are allowed
2
setTimeout(function() { console.log("Hello!"); }, 1000);
3
foo(() => 1);

`allowIifes`

When set to true, IIFEs (Immediately Invoked Function Expressions) are allowed without explicit return types.

Default: false

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useExplicitReturnType": {
6
          "options": {
7
            "allowIifes": true
8
          }
9
        }
10
      }
11
    }
12
  }
13
}

1
// IIFEs are allowed
2
(function () {
3
  return 1;
4
})();
5
(() => {
6
  return 1;
7
})();

`allowedNames`

An array of function/method names that are allowed to not have explicit return types.

Default: []

1
{
2
  "linter": {
3
    "rules": {
4
      "nursery": {
5
        "useExplicitReturnType": {
6
          "options": {
7
            "allowedNames": [
8
              "myFunction"
9
            ]
10
          }
11
        }
12
      }
13
    }
14
  }
15
}

1
// Functions with allowed names don't need return types
2
function myFunction() {
3
  return 42;
4
}