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.
function parse(s: string) { if (s === "") return null; return Number(s); } // inferred: number | null
Try it
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.
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.
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
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
undefinedis error TS2366 ("Function lacks ending return statement and return type does not include 'undefined'"). WithnoImplicitReturns, 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
returnis unreachable;allowUnreachableCode: falseturns the warning into an error (TS7027).
Usage notes
- Inference widens.
return "a"in an unannotated function givesstring, not"a", unless the expression isas constor 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.
voidversusundefined. A function typed() => voidmay return any value when assigned from another function, but a function declared with: voiditself can only returnundefined. See void.never. A function that always throws or loops forever has return typenever. See never.- Async functions wrap the type in
Promise:async function f(): Promise<number> { return 1; }. - Generators use
Generator<Y, R, N>;returnsupplies theR. returninfinallyoverrides 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.
Related
- function, Arrow functions, throw, if and else
- Lessons: Functions, Type inference, Custom type guards