useExplicitType

Diagnostic Category: lint/nursery/useExplicitType

TypeScript and TSX

Since: v1.9.3

Caution

This rule is part of the nursery group.

Sources:

• Same as: @typescript-eslint/explicit-function-return-type

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 do make it visually more clear what type is returned by a function. They can also speed up TypeScript type checking performance in large codebases with many large functions. Explicit return types also reduce the chance of bugs by asserting the return type, and it avoids surprising “action at a distance,” where changing the body of one function may cause failures inside another function.

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

Examples

Section titled Examples

Invalid

Section titled Invalid

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

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

  ⚠ 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-documenting and can speed up TypeScript type checking.
  
  ℹ Add a return type annotation.
  

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

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

  ⚠ 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-documenting and can speed up TypeScript type checking.
  
  ℹ Add a return type annotation.
  

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

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

  ⚠ 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-documenting and can speed up TypeScript type checking.
  
  ℹ Add a return type annotation.
  

class Test {
  // Should indicate that no value is returned (void)
  method() {
    return;
  }
}

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

  ⚠ 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-documenting and can speed up TypeScript type checking.
  
  ℹ Add a return type annotation.
  

// Should indicate that no value is returned (void)
function test(a: number) {
  a += 1;
}

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

  ⚠ Missing return type on function.
  
  > 1 │ // Should indicate that no value is returned (void)
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  > 2 │ function test(a: number) {
      │ ^^^^^^^^^^^^^
    3 │   a += 1;
    4 │ }
  
  ℹ Declaring the return type makes the code self-documenting and can speed up TypeScript type checking.
  
  ℹ Add a return type annotation.
  

// Should use const assertions
const func = (value: number) => ({ type: 'X', value }) as any;

code-block.ts:2:14 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Missing return type on function.
  
    1 │ // Should use const assertions
  > 2 │ const func = (value: number) => ({ type: ‘X’, value }) as any;
      │              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    3 │ 
  
  ℹ Declaring the return type makes the code self-documenting and can speed up TypeScript type checking.
  
  ℹ Add a return type annotation.
  

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

const arrowFn = () => () => {};

code-block.ts:1:23 lint/nursery/useExplicitType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ Missing return type on function.
  
  > 1 │ const arrowFn = () => () => {};
      │                       ^^^^^^^^
    2 │ 
  
  ℹ Declaring the return type makes the code self-documenting and can speed up TypeScript type checking.
  
  ℹ Add a return type annotation.
  

const arrowFn = () => {
  return () => { };
}

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

  ⚠ Missing return type on function.
  
    1 │ const arrowFn = () => {
  > 2 │   return () => { };
      │          ^^^^^^^^^
    3 │ }
    4 │ 
  
  ℹ Declaring the return type makes the code self-documenting and can speed up TypeScript type checking.
  
  ℹ Add a return type annotation.
  

The following pattern is considered incorrect code for a higher-order function because the function body contains multiple statements. We only check whether the first statement is a function return.

// A function has multiple statements in the body
function f() {
  if (x) {
    return 0;
  }
  return (): void => {}
}

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

  ⚠ Missing return type on function.
  
  > 1 │ // A function has multiple statements in the body
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  > 2 │ function f() {
      │ ^^^^^^^^^^
    3 │   if (x) {
    4 │     return 0;
  
  ℹ Declaring the return type makes the code self-documenting and can speed up TypeScript type checking.
  
  ℹ Add a return type annotation.
  

// A function has multiple statements in the body
function f() {
  let str = "test";
  return (): string => {
    str;
  }
}

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

  ⚠ Missing return type on function.
  
  > 1 │ // A function has multiple statements in the body
      │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  > 2 │ function f() {
      │ ^^^^^^^^^^
    3 │   let str = “test”;
    4 │   return (): string => {
  
  ℹ Declaring the return type makes the code self-documenting and can speed up TypeScript type checking.
  
  ℹ Add a return type annotation.
  

Valid

Section titled Valid

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

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

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

class Test {
  // No return value should be expected (void)
  method(): void {
    return;
  }
}

The following patterns are considered correct code for a function immediately returning a value with as const:

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

The following patterns are considered correct code for a function allowed within specific expression contexts, such as an IIFE, a function passed as an argument, or a function inside an array:

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

// IIFE
(() => {})();

// a function inside an array
[function () {}, () => {}];

The following pattern 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:

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

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

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

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

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

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

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

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

Related links

Section titled Related links

• Disable a rule
• Configure the rule fix
• Rule options