The Awaited<T> Utility

What structurally occurs if you possess an incredibly deep chain mapping of Promises natively imported explicitly from a third-party un-typed library package cleanly?

In TypeScript v4.5+, the developers securely released the globally mapped globally accessible Awaited<T> Utility uniquely targeting unwrapping asynchronous wrappers recursively.

Unwrapping Nested Promises

It operates by functionally digging down repeatedly stripping away Promise<> layers gracefully until it perfectly isolates the raw return data natively!

// A deeply chaotic Promise wrapper
type NestedData = Promise<Promise<Promise<string>>>;

// Without Awaited: You would have to manually strip each layer!
// With Awaited: It aggressively unwraps recursively cleanly.
type UnpackedString = Awaited<NestedData>; // Safely resolves directly to 'string'

Practical Usage with Returns

It's most classically implemented paired actively alongside ReturnType<T>.

// A highly complex async function
async function deeplyFetchDashboardAnalytics() {
    return { views: 500, clicks: 12 };
}

// Extracting the final return shape securely without invoking!
type AnalyticsShape = Awaited<ReturnType<typeof deeplyFetchDashboardAnalytics>>;

// AnalyticsShape rigidly evaluates securely into:
// { views: number, clicks: number }