Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Keywords and Declarations

TypeScript return statements and return types

Reference for return in TypeScript: how return types are inferred, explicit annotations, void and never, missing returns, type predicates and returning unions.

return ends a function and optionally supplies a value. TypeScript infers the function's return type as the union of the types of all its return expressions, plus undefined if the end of the function can be reached without returning.

You can also state the return type yourself with : Type after the parameter list. An annotation turns every return into a checked assignment and makes the contract explicit.

TypeScript
function parse(s: string) {
  if (s === "") return null;
  return Number(s);
}
// inferred: number | null

Try it

TypeScript Inferred unions and annotations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript A missing return is an error

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Type predicates as return types

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
return;                     // returns undefined
return expression;          // returns a value
function f(): Type { ... }  // annotated return type
function f(x: unknown): x is Type { ... }          // type predicate
function f(x: unknown): asserts x is Type { ... }  // assertion function
Part Description
expression Must be assignable to the annotated return type.
: Type The declared result type.
x is Type A boolean-returning function that narrows its argument in the true branch.
asserts x is Type A function that throws unless x is Type; narrows after the call.

Errors and edge cases:

  • A path that ends without a value in a function whose return type excludes undefined is error TS2366 ("Function lacks ending return statement and return type does not include 'undefined'"). With noImplicitReturns, inconsistent paths are TS7030 ("Not all code paths return a value").
  • Returning the wrong type is TS2322 ("Type 'string' is not assignable to type 'number'").
  • Code after return is unreachable; allowUnreachableCode: false turns the warning into an error (TS7027).

Usage notes

  • Inference widens. return "a" in an unannotated function gives string, not "a", unless the expression is as const or a context asks for the literal.
  • Annotate public APIs. Exported functions and class methods should have explicit return types so a body change cannot silently change the public type.
  • void versus undefined. A function typed () => void may return any value when assigned from another function, but a function declared with : void itself can only return undefined. See void.
  • never. A function that always throws or loops forever has return type never. See never.
  • Async functions wrap the type in Promise: async function f(): Promise<number> { return 1; }.
  • Generators use Generator<Y, R, N>; return supplies the R.
  • return in finally overrides earlier returns and thrown errors, which is almost never wanted.
  • Contextual return typing. In const f: () => "a" | "b" = () => "a", the literal stays narrow because the context asks for it.