> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt > Use this file to discover all available pages before exploring further. # TypeScript Async Function An asynchronous function in TypeScript is a function declared with the `async` modifier that implicitly and strictly returns a `Promise`. It enables the use of the `await` operator to pause execution until a Promise settles, allowing asynchronous, non-blocking operations to be written in a synchronous, procedural style. ## Return Type Mechanics In TypeScript, the return type of an `async` function must always be a `Promise`, where `T` is the type of the value ultimately returned. If the function returns a raw value, the JavaScript runtime automatically wraps it in a resolved Promise, and TypeScript enforces the corresponding `Promise` signature. If the function returns nothing, the type is `Promise`. ```typescript theme={"dark"} // Standard function declaration async function getUserId(username: string): Promise { return 42; // Implicitly wrapped in Promise.resolve(42) } // Arrow function expression const getUserName = async (id: number): Promise => { return "admin"; }; // Void return type async function logEvent(event: string): Promise { console.log(event); } ``` ## Type Inference TypeScript's compiler automatically infers the `Promise` return type based on the returned value if an explicit return type is omitted. However, explicitly defining the return type is a best practice to prevent accidental leakage of internal types or unhandled Promise chains. ```typescript theme={"dark"} // Inferred as Promise async function isAuthenticated() { return true; } ``` ## The `await` Operator and Recursive Type Unwrapping The `await` keyword can only be used inside an `async` function (or at the top level of a module). From a typing perspective, `await` acts as a recursive type un-wrapper. When applied to an expression of type `Promise`, TypeScript does not just unwrap a single layer; it recursively unwraps nested Promises until it reaches a non-Promise type. For example, if the expression is typed as `Promise>`, `await` evaluates to `string`, not `Promise`. Under the hood, TypeScript models this recursive unwrapping mechanism using the `Awaited` utility type. Because native JavaScript Promises automatically flatten at runtime, a true `Promise>` cannot be instantiated using standard APIs like `Promise.resolve()`. However, the type system must still account for nested Promise types that might be declared or inferred. ```typescript theme={"dark"} // Declared to demonstrate type unwrapping without runtime flattening errors declare const nestedPromise: Promise>; async function processData(): Promise { // TypeScript recursively unwraps Promise> to string[] const data: string[] = await nestedPromise; } // The underlying utility type modeling this behavior: type Wrapped = Promise>; type Unwrapped = Awaited; // Evaluates to number ``` If `await` is used on a non-Promise value, TypeScript resolves it to the exact type of that value, though this is syntactically redundant. ## Error Handling and `unknown` Types When a Promise is rejected inside an `async` function, it throws an exception that halts execution unless caught. In TypeScript, the `catch` clause variable is typed as `unknown` by default (when `useUnknownInCatchVariables` is enabled in `tsconfig.json`). Strict type narrowing is required to safely interact with the caught rejection reason. ```typescript theme={"dark"} declare function unstableAsyncOperation(): Promise; async function fetchSafely(): Promise { try { const response: string = await unstableAsyncOperation(); return response; } catch (error: unknown) { // Type narrowing required before accessing error properties if (error instanceof Error) { console.error(`Operation failed: ${error.message}`); } else if (typeof error === "string") { console.error(`String error: ${error}`); } return null; } } ``` ## Async Generators TypeScript also supports asynchronous generator functions using `async function*`. These return an `AsyncGenerator` instead of a standard `Promise`, yielding Promises that resolve sequentially. ```typescript theme={"dark"} async function* generateSequence(): AsyncGenerator { yield await Promise.resolve(1); yield await Promise.resolve(2); } ```

Tired of Poor TypeScript Skills? Fix That With Deep Grasping! Learn More