noMisleadingReturnType (JavaScript)

Language JavaScript (and super languages)

Summary

Rule available since: v2.4.11
Diagnostic Category: lint/nursery/noMisleadingReturnType
This rule doesn’t have a fix.
The default severity of this rule is information.
This rule belongs to the following domains:
- types

How to configure

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

Description

Detect return type annotations that are misleadingly wider than what the implementation actually returns.

Reports when a function’s explicit return type annotation is wider than what TypeScript would infer from the implementation, hiding precise types from callers.

Examples

Invalid

1
function getStatus(b: boolean): string { if (b) return "loading"; return "idle"; }

/invalid.ts:1:31 lint/nursery/noMisleadingReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The return type annotation is wider than what the function actually returns.
  
  > 1 │ function getStatus(b: boolean): string { if (b) return "loading"; return "idle"; }
      │                               ^^^^^^^^
    2 │ 
  
  ℹ A wider return type hides the precise types that callers could rely on.
  
  ℹ Consider using "loading" | "idle" as the return type.
  
  ℹ 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/9810 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
function getCode(ok: boolean): number { if (ok) return 200; return 404; }

/invalid2.ts:1:30 lint/nursery/noMisleadingReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The return type annotation is wider than what the function actually returns.
  
  > 1 │ function getCode(ok: boolean): number { if (ok) return 200; return 404; }
      │                              ^^^^^^^^
    2 │ 
  
  ℹ A wider return type hides the precise types that callers could rely on.
  
  ℹ Consider using 200 | 404 as the return type.
  
  ℹ 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/9810 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 Foo { getStatus(b: boolean): string { if (b) return "loading"; return "idle"; } }

/invalid3.ts:1:34 lint/nursery/noMisleadingReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The return type annotation is wider than what the function actually returns.
  
  > 1 │ class Foo { getStatus(b: boolean): string { if (b) return "loading"; return "idle"; } }
      │                                  ^^^^^^^^
    2 │ 
  
  ℹ A wider return type hides the precise types that callers could rely on.
  
  ℹ Consider using "loading" | "idle" as the return type.
  
  ℹ 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/9810 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
const obj = { getMode(b: boolean): string { if (b) return "dark"; return "light"; } };

/invalid4.ts:1:34 lint/nursery/noMisleadingReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The return type annotation is wider than what the function actually returns.
  
  > 1 │ const obj = { getMode(b: boolean): string { if (b) return "dark"; return "light"; } };
      │                                  ^^^^^^^^
    2 │ 
  
  ℹ A wider return type hides the precise types that callers could rely on.
  
  ℹ Consider using "dark" | "light" as the return type.
  
  ℹ 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/9810 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
function makeData(): object { return { retry: true }; }

/invalid5.ts:1:20 lint/nursery/noMisleadingReturnType ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ℹ The return type annotation is wider than what the function actually returns.
  
  > 1 │ function makeData(): object { return { retry: true }; }
      │                    ^^^^^^^^
    2 │ 
  
  ℹ A wider return type hides the precise types that callers could rely on.
  
  ℹ Narrow the return type to match what the function actually returns.
  
  ℹ 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/9810 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
function getStatus() { return "loading"; }

1
function run(): void { return; }

1
class Foo { greet(): string { return "hello"; } }

Known limitations

Suggested replacement types are only shown when their textual representation is up to 80 characters long. Longer unions fall back to a generic note without the specific suggestion.
When a return uses a type assertion such as as T, the rule does not flag the return unless it can prove that T is narrower than object. Trusted cases include unknown, any, typeof queries, conditional types, generic type parameters, and types the rule cannot resolve. Intersections (A & B) are trusted when every member is or when any member is any; unions (A | B) when at least one is.