> ## 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 Promise A `Promise` in TypeScript is a strongly-typed proxy object representing the eventual completion, or failure, of an asynchronous operation. It encapsulates a value that may not be available yet, enforcing compile-time type safety on the resolved value through generics (`Promise`). ## Type Signature and Generics TypeScript defines a Promise using a generic type parameter `T`, which dictates the exact compile-time type of the value the Promise will yield upon successful execution. ```typescript theme={"dark"} const numericPromise: Promise = new Promise((resolve, reject) => { resolve(42); // Valid // resolve("42"); // Type Error: Argument of type 'string' is not assignable to parameter of type 'number' }); ``` ## The Executor Function The `Promise` constructor accepts an executor callback. TypeScript strictly types the arguments of this executor: `resolve` and `reject`. * `resolve`: A function that accepts a value of type `T` or a `PromiseLike`. * `reject`: A function that accepts a reason, typically typed as `any` or `unknown`. The constructor signature is defined within the TypeScript standard library as follows: ```typescript theme={"dark"} interface PromiseConstructor { new (executor: ( resolve: (value: T | PromiseLike) => void, reject: (reason?: any) => void ) => void): Promise; } ``` ## State Machine A Promise exists in one of three mutually exclusive runtime states. While these state transitions occur entirely at runtime, TypeScript's compile-time type system tracks the *type* of the value yielded upon fulfillment via the generic parameter `T`: 1. **Pending**: The initial state. No value is available. 2. **Fulfilled**: The operation completed successfully. The Promise yields a value of type `T`. 3. **Rejected**: The operation failed. The Promise yields a rejection reason (typically `Error` or `unknown`). ## Instance Methods and Type Propagation When chaining Promises, TypeScript infers the return type of the subsequent Promise based on the return value of the callback provided to `.then()` or `.catch()`. ```typescript theme={"dark"} declare const initialPromise: Promise; // Type propagation: Promise -> Promise -> Promise const chainedPromise: Promise = initialPromise .then((val: number) => val.toString()) .then((str: string) => str.length > 0) .catch((err: unknown) => false); ``` If a `.then()` callback returns a non-Promise value of type `U`, TypeScript automatically wraps the return type as `Promise`. If it returns a `Promise`, the resulting type is flattened to `Promise`, preventing nested types like `Promise>`. ## Static Methods and Tuple Inference TypeScript provides advanced type inference for `Promise` static methods, particularly when handling arrays or iterables of Promises. **`Promise.all`** When passed a tuple of Promises, `Promise.all` infers a Promise resolving to a tuple of the exact corresponding types. ```typescript theme={"dark"} const p1 = Promise.resolve(100); // Promise const p2 = Promise.resolve("Active"); // Promise // Inferred type: Promise<[number, string]> const combined = Promise.all([p1, p2]); ``` **`Promise.race`** Returns a Promise that resolves or rejects as soon as the first Promise in the iterable settles. The return type is a union of the generic types of the input Promises. ```typescript theme={"dark"} // Inferred type: Promise const raced = Promise.race([p1, p2]); ``` ## Async/Await Return Types The `async` modifier in TypeScript acts as a syntactic guarantee that a function will return a `Promise`. If the function's body returns a raw value of type `T`, the TypeScript compiler enforces the function signature as `Promise`. ```typescript theme={"dark"} // The return type MUST be Promise, even though a raw string is returned. async function getStatus(): Promise { return "OK"; } // Awaiting unwraps the Promise back to T async function evaluateStatus(): Promise { const status: string = await getStatus(); } ``` ## The `PromiseLike` Interface TypeScript utilizes structural typing (duck typing) for asynchronous objects via the `PromiseLike` interface. An object is considered `PromiseLike` (often called a "Thenable") if it implements a `.then()` method, even if it is not an instance of the native `Promise` class. TypeScript allows `await` to be used on any `PromiseLike` object, safely unwrapping it to type `T`. ```typescript theme={"dark"} interface PromiseLike { then( onfulfilled?: ((value: T) => TResult1 | PromiseLike) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike) | undefined | null ): PromiseLike; } ```

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