⚡ Promises in TypeScript: Type-Safe Asynchronous Code

🎯 Introduction

Welcome to the exciting world of type-safe asynchronous programming! 🎉 In this guide, we’ll explore how TypeScript transforms JavaScript Promises from potential sources of runtime errors into bulletproof, type-safe async operations.

You’ll discover how to harness TypeScript’s powerful type system to catch async errors at compile time, create robust data flows, and build applications that handle uncertainty with confidence. Whether you’re fetching data from APIs 🌐, processing files 📁, or orchestrating complex async workflows 🔄, mastering typed Promises is essential for modern TypeScript development.

By the end of this tutorial, you’ll be writing async code that’s not just functional, but elegantly typed and impossible to break! 🚀 Let’s dive in! 🏊‍♂️

📚 Understanding TypeScript Promises

🤔 What are Typed Promises?

Think of a TypeScript Promise as a type-safe container for future values 📦. It’s like placing an order at a restaurant 🍕 - you get a receipt (the Promise) that guarantees you’ll eventually receive your specific meal (the typed result), or you’ll be told what went wrong (the typed error).

In TypeScript terms, Promise<T> provides:

• ✨ Type-safe results - know exactly what you’ll get when the promise resolves
• 🚀 Compile-time error checking - catch async mistakes before runtime
• 🛡️ Intelligent autocomplete - IDE support for async return values
• 📦 Generic constraints - ensure promises return the right types

💡 Why Use Typed Promises?

Here’s why typed promises are game-changers:

1. Predictable Async Code 🔮: Know what your async functions return
2. Early Error Detection 🚨: Catch type mismatches before deployment
3. Safer API Calls 🌐: Ensure responses match expected interfaces
4. Better Team Collaboration 👥: Self-documenting async interfaces
5. Refactoring Confidence 🔧: Change async code without fear

Real-world example: When fetching user data from an API 👤, typed promises ensure you can’t accidentally treat a User object as a string!

🔧 Basic Promise Types and Patterns

📝 Promise<T> Fundamentals

Let’s start with the core Promise types:

// 🎯 Basic Promise types
// Promise that resolves to a string
const fetchMessage = (): Promise<string> => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve("Hello, TypeScript! 👋");
    }, 1000);
  });
};

// Promise that resolves to a number
const calculateAsync = (a: number, b: number): Promise<number> => {
  return new Promise((resolve, reject) => {
    if (a < 0 || b < 0) {
      reject(new Error("Negative numbers not allowed! 🚫"));
      return;
    }
    
    // 🧮 Simulate async calculation
    setTimeout(() => {
      const result = a * b + Math.random() * 100;
      resolve(Math.round(result));
    }, 500);
  });
};

// Promise that resolves to a custom interface
interface UserProfile {
  id: string;
  name: string;
  email: string;
  avatar?: string;
  lastLogin: Date;
}

const fetchUserProfile = (userId: string): Promise<UserProfile> => {
  return new Promise((resolve, reject) => {
    // 🔍 Simulate API call validation
    if (!userId || userId.trim() === '') {
      reject(new Error("User ID is required! 📝"));
      return;
    }
    
    // 📊 Mock successful response
    setTimeout(() => {
      const user: UserProfile = {
        id: userId,
        name: `User ${userId}`,
        email: `user${userId}@example.com`,
        avatar: `https://api.adorable.io/avatars/100/${userId}.png`,
        lastLogin: new Date()
      };
      
      resolve(user);
      console.log(`✅ Fetched profile for user: ${user.name}`);
    }, 800);
  });
};

💡 Explanation: Notice how each Promise is typed with Promise<T> where T is the exact type of data it will resolve to!

🎯 Error Handling with Types

TypeScript provides excellent support for typed error handling:

// 🚨 Custom error types for better error handling
class NetworkError extends Error {
  constructor(
    message: string,
    public statusCode: number,
    public endpoint: string
  ) {
    super(message);
    this.name = 'NetworkError';
  }
}

class ValidationError extends Error {
  constructor(
    message: string,
    public field: string,
    public value: any
  ) {
    super(message);
    this.name = 'ValidationError';
  }
}

// 🎯 Type-safe promise with specific error types
const fetchDataWithTypedErrors = async (url: string): Promise<any> => {
  try {
    if (!url.startsWith('http')) {
      throw new ValidationError(
        'Invalid URL format 🔗', 
        'url', 
        url
      );
    }
    
    // 📡 Simulate HTTP request
    const response = await fetch(url);
    
    if (!response.ok) {
      throw new NetworkError(
        `HTTP ${response.status}: ${response.statusText} 📡`,
        response.status,
        url
      );
    }
    
    const data = await response.json();
    console.log(`✅ Successfully fetched data from: ${url}`);
    return data;
    
  } catch (error) {
    // 🎯 TypeScript helps us handle different error types
    if (error instanceof NetworkError) {
      console.error(`🌐 Network error (${error.statusCode}): ${error.message}`);
      throw error;
    } else if (error instanceof ValidationError) {
      console.error(`⚠️ Validation error for ${error.field}: ${error.message}`);
      throw error;
    } else {
      console.error(`💥 Unexpected error: ${error}`);
      throw new Error(`Unexpected error: ${error}`);
    }
  }
};

// 🛡️ Result type for safer error handling
type Result<T, E = Error> = {
  success: true;
  data: T;
} | {
  success: false;
  error: E;
};

// 🎯 Safe promise wrapper that never throws
const safePromise = async <T>(
  promise: Promise<T>
): Promise<Result<T>> => {
  try {
    const data = await promise;
    return { success: true, data };
  } catch (error) {
    return { 
      success: false, 
      error: error instanceof Error ? error : new Error(String(error))
    };
  }
};

🔄 Promise Composition and Chaining

Advanced patterns for combining promises:

// 🔗 Promise chaining with type safety
interface ApiUser {
  id: string;
  username: string;
  email: string;
}

interface UserPosts {
  userId: string;
  posts: Array<{
    id: string;
    title: string;
    content: string;
    createdAt: Date;
  }>;
}

interface UserStats {
  userId: string;
  totalPosts: number;
  averageWordsPerPost: number;
  lastPostDate: Date | null;
}

// 🎯 Chained API calls with type preservation
const getUserWithPostsAndStats = async (userId: string): Promise<{
  user: ApiUser;
  posts: UserPosts;
  stats: UserStats;
}> => {
  // 👤 First, get the user
  const user = await fetchApiUser(userId);
  console.log(`📋 Fetched user: ${user.username}`);
  
  // 📝 Then get their posts
  const posts = await fetchUserPosts(user.id);
  console.log(`📚 Fetched ${posts.posts.length} posts`);
  
  // 📊 Finally calculate stats
  const stats = await calculateUserStats(posts);
  console.log(`📈 Calculated stats: ${stats.totalPosts} posts`);
  
  return { user, posts, stats };
};

// 🎭 Mock API functions with proper typing
const fetchApiUser = (userId: string): Promise<ApiUser> => {
  return new Promise((resolve, reject) => {
    if (!userId) {
      reject(new Error("User ID required! 📝"));
      return;
    }
    
    setTimeout(() => {
      resolve({
        id: userId,
        username: `user_${userId}`,
        email: `${userId}@example.com`
      });
    }, 300);
  });
};

const fetchUserPosts = (userId: string): Promise<UserPosts> => {
  return new Promise((resolve) => {
    setTimeout(() => {
      const posts = Array.from({ length: 5 }, (_, i) => ({
        id: `post_${i + 1}`,
        title: `Post ${i + 1} by user ${userId}`,
        content: `This is the content of post ${i + 1}. Lorem ipsum dolor sit amet.`,
        createdAt: new Date(Date.now() - (i * 24 * 60 * 60 * 1000))
      }));
      
      resolve({ userId, posts });
    }, 500);
  });
};

const calculateUserStats = (userPosts: UserPosts): Promise<UserStats> => {
  return new Promise((resolve) => {
    setTimeout(() => {
      const { posts } = userPosts;
      const totalPosts = posts.length;
      
      const totalWords = posts.reduce((sum, post) => {
        return sum + post.content.split(' ').length;
      }, 0);
      
      const averageWordsPerPost = totalPosts > 0 ? totalWords / totalPosts : 0;
      const lastPostDate = posts.length > 0 ? posts[0].createdAt : null;
      
      resolve({
        userId: userPosts.userId,
        totalPosts,
        averageWordsPerPost: Math.round(averageWordsPerPost),
        lastPostDate
      });
    }, 200);
  });
};

💡 Practical Examples

🌐 Example 1: Type-Safe API Client

Let’s build a comprehensive, type-safe API client:

// 📡 Generic API response types
interface ApiResponse<T> {
  success: boolean;
  data: T;
  message: string;
  timestamp: Date;
}

interface ApiError {
  success: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, any>;
  };
  timestamp: Date;
}

// 🎯 HTTP methods enum
enum HttpMethod {
  GET = 'GET',
  POST = 'POST',
  PUT = 'PUT',
  DELETE = 'DELETE',
  PATCH = 'PATCH'
}

// 🔧 Request configuration interface
interface RequestConfig {
  method: HttpMethod;
  headers?: Record<string, string>;
  body?: any;
  timeout?: number;
  retries?: number;
}

// 🚀 Type-safe API client class
class TypeSafeApiClient {
  private baseUrl: string;
  private defaultHeaders: Record<string, string>;
  private defaultTimeout: number = 5000;
  
  constructor(baseUrl: string, defaultHeaders: Record<string, string> = {}) {
    this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
    this.defaultHeaders = {
      'Content-Type': 'application/json',
      ...defaultHeaders
    };
  }
  
  // 🎯 Generic request method with full type safety
  private async request<T>(
    endpoint: string, 
    config: RequestConfig
  ): Promise<ApiResponse<T>> {
    const url = `${this.baseUrl}${endpoint}`;
    const timeout = config.timeout || this.defaultTimeout;
    
    console.log(`📡 ${config.method} ${url}`);
    
    try {
      // 🔧 Prepare request options
      const requestOptions: RequestInit = {
        method: config.method,
        headers: {
          ...this.defaultHeaders,
          ...config.headers
        }
      };
      
      // 📦 Add body for non-GET requests
      if (config.body && config.method !== HttpMethod.GET) {
        requestOptions.body = JSON.stringify(config.body);
      }
      
      // ⏰ Create timeout promise
      const timeoutPromise = new Promise<never>((_, reject) => {
        setTimeout(() => {
          reject(new Error(`Request timeout after ${timeout}ms ⏰`));
        }, timeout);
      });
      
      // 🏃‍♂️ Race between fetch and timeout
      const response = await Promise.race([
        fetch(url, requestOptions),
        timeoutPromise
      ]);
      
      if (!response.ok) {
        throw new Error(`HTTP ${response.status}: ${response.statusText} 📡`);
      }
      
      const data = await response.json();
      
      const apiResponse: ApiResponse<T> = {
        success: true,
        data,
        message: 'Request successful',
        timestamp: new Date()
      };
      
      console.log(`✅ ${config.method} ${url} - Success`);
      return apiResponse;
      
    } catch (error) {
      console.error(`❌ ${config.method} ${url} - Failed:`, error);
      throw error;
    }
  }
  
  // 🔍 GET request with type safety
  async get<T>(endpoint: string, headers?: Record<string, string>): Promise<ApiResponse<T>> {
    return this.request<T>(endpoint, {
      method: HttpMethod.GET,
      headers
    });
  }
  
  // ➕ POST request with typed body and response
  async post<TRequest, TResponse>(
    endpoint: string, 
    body: TRequest, 
    headers?: Record<string, string>
  ): Promise<ApiResponse<TResponse>> {
    return this.request<TResponse>(endpoint, {
      method: HttpMethod.POST,
      body,
      headers
    });
  }
  
  // 🔄 PUT request with full typing
  async put<TRequest, TResponse>(
    endpoint: string, 
    body: TRequest, 
    headers?: Record<string, string>
  ): Promise<ApiResponse<TResponse>> {
    return this.request<TResponse>(endpoint, {
      method: HttpMethod.PUT,
      body,
      headers
    });
  }
  
  // 🗑️ DELETE request
  async delete<T>(endpoint: string, headers?: Record<string, string>): Promise<ApiResponse<T>> {
    return this.request<T>(endpoint, {
      method: HttpMethod.DELETE,
      headers
    });
  }
  
  // 🛡️ Safe request wrapper that doesn't throw
  async safeRequest<T>(
    method: 'get' | 'post' | 'put' | 'delete',
    endpoint: string,
    body?: any
  ): Promise<Result<ApiResponse<T>, ApiError>> {
    try {
      let result: ApiResponse<T>;
      
      switch (method) {
        case 'get':
          result = await this.get<T>(endpoint);
          break;
        case 'post':
          result = await this.post<any, T>(endpoint, body);
          break;
        case 'put':
          result = await this.put<any, T>(endpoint, body);
          break;
        case 'delete':
          result = await this.delete<T>(endpoint);
          break;
      }
      
      return { success: true, data: result };
      
    } catch (error) {
      const apiError: ApiError = {
        success: false,
        error: {
          code: 'REQUEST_FAILED',
          message: error instanceof Error ? error.message : 'Unknown error',
          details: { method, endpoint, body }
        },
        timestamp: new Date()
      };
      
      return { success: false, error: apiError };
    }
  }
}

// 🎮 Usage example with specific types
interface BlogPost {
  id: string;
  title: string;
  content: string;
  author: string;
  publishedAt: Date;
  tags: string[];
}

interface CreatePostRequest {
  title: string;
  content: string;
  author: string;
  tags: string[];
}

// 📚 Blog API service using the typed client
class BlogApiService {
  private client: TypeSafeApiClient;
  
  constructor(apiUrl: string, authToken?: string) {
    const headers = authToken ? { 'Authorization': `Bearer ${authToken}` } : {};
    this.client = new TypeSafeApiClient(apiUrl, headers);
  }
  
  // 📋 Get all posts with type safety
  async getAllPosts(): Promise<BlogPost[]> {
    const response = await this.client.get<BlogPost[]>('/posts');
    return response.data;
  }
  
  // 👁️ Get single post by ID
  async getPost(id: string): Promise<BlogPost> {
    const response = await this.client.get<BlogPost>(`/posts/${id}`);
    return response.data;
  }
  
  // ➕ Create new post
  async createPost(postData: CreatePostRequest): Promise<BlogPost> {
    const response = await this.client.post<CreatePostRequest, BlogPost>(
      '/posts', 
      postData
    );
    return response.data;
  }
  
  // 🔄 Update existing post
  async updatePost(id: string, postData: Partial<CreatePostRequest>): Promise<BlogPost> {
    const response = await this.client.put<Partial<CreatePostRequest>, BlogPost>(
      `/posts/${id}`, 
      postData
    );
    return response.data;
  }
  
  // 🗑️ Delete post
  async deletePost(id: string): Promise<{ deleted: boolean }> {
    const response = await this.client.delete<{ deleted: boolean }>(`/posts/${id}`);
    return response.data;
  }
}

🎯 Try it yourself: Add caching, request deduplication, and retry logic to the API client!

📁 Example 2: File Processing Pipeline

Let’s create a type-safe file processing system:

// 📄 File processing types
interface FileMetadata {
  name: string;
  size: number;
  type: string;
  lastModified: Date;
  path: string;
}

interface ProcessingResult<T> {
  file: FileMetadata;
  result: T;
  processingTime: number;
  success: boolean;
}

interface ImageProcessingOptions {
  width?: number;
  height?: number;
  quality?: number;
  format?: 'jpeg' | 'png' | 'webp';
}

interface ProcessedImage {
  originalSize: number;
  processedSize: number;
  dimensions: {
    width: number;
    height: number;
  };
  format: string;
  outputPath: string;
}

// 🏭 Type-safe file processing pipeline
class FileProcessingPipeline {
  private processingQueue: Map<string, Promise<any>> = new Map();
  
  // 📊 Process multiple files with type safety
  async processFiles<T>(
    files: FileMetadata[],
    processor: (file: FileMetadata) => Promise<T>,
    options: {
      concurrency?: number;
      onProgress?: (completed: number, total: number) => void;
      onError?: (file: FileMetadata, error: Error) => void;
    } = {}
  ): Promise<ProcessingResult<T>[]> {
    const { concurrency = 3, onProgress, onError } = options;
    const results: ProcessingResult<T>[] = [];
    
    console.log(`🏭 Starting processing pipeline for ${files.length} files`);
    
    // 🔄 Process files in batches to control concurrency
    for (let i = 0; i < files.length; i += concurrency) {
      const batch = files.slice(i, i + concurrency);
      
      const batchPromises = batch.map(async (file): Promise<ProcessingResult<T>> => {
        const startTime = Date.now();
        
        try {
          console.log(`⚙️ Processing: ${file.name}`);
          const result = await processor(file);
          const processingTime = Date.now() - startTime;
          
          console.log(`✅ Completed: ${file.name} (${processingTime}ms)`);
          
          return {
            file,
            result,
            processingTime,
            success: true
          };
          
        } catch (error) {
          const processingTime = Date.now() - startTime;
          console.error(`❌ Failed: ${file.name}`, error);
          
          if (onError) {
            onError(file, error instanceof Error ? error : new Error(String(error)));
          }
          
          return {
            file,
            result: null as any, // This will be filtered out
            processingTime,
            success: false
          };
        }
      });
      
      const batchResults = await Promise.allSettled(batchPromises);
      
      // 📊 Extract successful results
      for (const result of batchResults) {
        if (result.status === 'fulfilled' && result.value.success) {
          results.push(result.value);
        }
      }
      
      // 📈 Report progress
      if (onProgress) {
        onProgress(results.length, files.length);
      }
    }
    
    console.log(`🎉 Pipeline completed: ${results.length}/${files.length} files processed`);
    return results;
  }
  
  // 🖼️ Image-specific processing
  async processImages(
    imageFiles: FileMetadata[],
    options: ImageProcessingOptions = {}
  ): Promise<ProcessingResult<ProcessedImage>[]> {
    return this.processFiles(
      imageFiles.filter(file => file.type.startsWith('image/')),
      (file) => this.processImage(file, options),
      {
        concurrency: 2, // Images are resource-intensive
        onProgress: (completed, total) => {
          console.log(`🖼️ Image processing: ${completed}/${total}`);
        },
        onError: (file, error) => {
          console.error(`❌ Image processing failed for ${file.name}:`, error.message);
        }
      }
    );
  }
  
  // 🎨 Single image processor
  private async processImage(
    file: FileMetadata, 
    options: ImageProcessingOptions
  ): Promise<ProcessedImage> {
    // 🎭 Simulate image processing
    return new Promise((resolve, reject) => {
      if (file.size > 50 * 1024 * 1024) { // 50MB limit
        reject(new Error(`File too large: ${file.size} bytes 📏`));
        return;
      }
      
      setTimeout(() => {
        const processed: ProcessedImage = {
          originalSize: file.size,
          processedSize: Math.round(file.size * 0.7), // 30% compression
          dimensions: {
            width: options.width || 1920,
            height: options.height || 1080
          },
          format: options.format || 'jpeg',
          outputPath: `/processed/${file.name.replace(/\.[^.]+$/, `.${options.format || 'jpg'}`)}`
        };
        
        resolve(processed);
      }, Math.random() * 2000 + 500); // 0.5-2.5s processing time
    });
  }
  
  // 📊 Get processing statistics
  async getProcessingStats(results: ProcessingResult<any>[]): Promise<{
    totalFiles: number;
    successfulFiles: number;
    failedFiles: number;
    averageProcessingTime: number;
    totalProcessingTime: number;
  }> {
    return new Promise((resolve) => {
      const successful = results.filter(r => r.success);
      const totalTime = results.reduce((sum, r) => sum + r.processingTime, 0);
      
      resolve({
        totalFiles: results.length,
        successfulFiles: successful.length,
        failedFiles: results.length - successful.length,
        averageProcessingTime: results.length > 0 ? Math.round(totalTime / results.length) : 0,
        totalProcessingTime: totalTime
      });
    });
  }
}

// 🎮 Usage example
const pipeline = new FileProcessingPipeline();

// 📁 Mock file metadata
const sampleFiles: FileMetadata[] = [
  {
    name: 'vacation-photo.jpg',
    size: 2.5 * 1024 * 1024, // 2.5MB
    type: 'image/jpeg',
    lastModified: new Date(),
    path: '/uploads/vacation-photo.jpg'
  },
  {
    name: 'profile-picture.png',
    size: 1.2 * 1024 * 1024, // 1.2MB
    type: 'image/png',
    lastModified: new Date(),
    path: '/uploads/profile-picture.png'
  },
  {
    name: 'presentation.pptx',
    size: 15 * 1024 * 1024, // 15MB
    type: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
    lastModified: new Date(),
    path: '/uploads/presentation.pptx'
  }
];

// 🚀 Process images with type safety
async function runImageProcessing(): Promise<void> {
  try {
    const results = await pipeline.processImages(sampleFiles, {
      width: 1200,
      height: 800,
      quality: 85,
      format: 'jpeg'
    });
    
    console.log(`🎯 Processed ${results.length} images successfully`);
    
    const stats = await pipeline.getProcessingStats(results);
    console.log('📊 Processing Statistics:', stats);
    
  } catch (error) {
    console.error('❌ Pipeline failed:', error);
  }
}

🚀 Advanced Promise Patterns

🧙‍♂️ Promise Utilities and Helpers

Advanced utilities for promise composition:

// 🎯 Advanced Promise utility class
class PromiseUtils {
  // ⏰ Timeout wrapper for any promise
  static withTimeout<T>(
    promise: Promise<T>, 
    timeoutMs: number, 
    timeoutMessage?: string
  ): Promise<T> {
    const timeoutPromise = new Promise<never>((_, reject) => {
      setTimeout(() => {
        reject(new Error(timeoutMessage || `Operation timed out after ${timeoutMs}ms ⏰`));
      }, timeoutMs);
    });
    
    return Promise.race([promise, timeoutPromise]);
  }
  
  // 🔄 Retry failed promises with exponential backoff
  static async retry<T>(
    promiseFactory: () => Promise<T>,
    options: {
      maxAttempts?: number;
      baseDelay?: number;
      maxDelay?: number;
      backoffFactor?: number;
      shouldRetry?: (error: Error) => boolean;
    } = {}
  ): Promise<T> {
    const {
      maxAttempts = 3,
      baseDelay = 1000,
      maxDelay = 10000,
      backoffFactor = 2,
      shouldRetry = () => true
    } = options;
    
    let lastError: Error;
    
    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
      try {
        console.log(`🔄 Attempt ${attempt}/${maxAttempts}`);
        return await promiseFactory();
      } catch (error) {
        lastError = error instanceof Error ? error : new Error(String(error));
        
        if (attempt === maxAttempts || !shouldRetry(lastError)) {
          break;
        }
        
        // 📈 Calculate delay with exponential backoff
        const delay = Math.min(
          baseDelay * Math.pow(backoffFactor, attempt - 1),
          maxDelay
        );
        
        console.log(`⏳ Waiting ${delay}ms before retry...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
    
    throw lastError!;
  }
  
  // 🏎️ Parallel promise execution with concurrency limit
  static async parallel<T>(
    tasks: (() => Promise<T>)[],
    concurrency: number = 5
  ): Promise<T[]> {
    const results: T[] = [];
    const executing: Promise<void>[] = [];
    
    for (const task of tasks) {
      const promise = task().then(result => {
        results.push(result);
      });
      
      executing.push(promise);
      
      if (executing.length >= concurrency) {
        await Promise.race(executing);
        // Remove completed promises
        executing.splice(0, executing.length);
      }
    }
    
    // Wait for remaining promises
    await Promise.all(executing);
    return results;
  }
  
  // 🔄 Chain promises in sequence
  static async sequence<T>(
    tasks: (() => Promise<T>)[]
  ): Promise<T[]> {
    const results: T[] = [];
    
    for (const task of tasks) {
      const result = await task();
      results.push(result);
    }
    
    return results;
  }
  
  // 🎰 Promise with random delay (useful for testing)
  static delay<T>(value: T, minMs: number = 0, maxMs?: number): Promise<T> {
    const delay = maxMs ? Math.random() * (maxMs - minMs) + minMs : minMs;
    
    return new Promise(resolve => {
      setTimeout(() => resolve(value), delay);
    });
  }
  
  // 🎯 Create a cancellable promise
  static cancellable<T>(promise: Promise<T>): {
    promise: Promise<T>;
    cancel: () => void;
  } {
    let isCancelled = false;
    let rejectFn: (reason?: any) => void;
    
    const cancellablePromise = new Promise<T>((resolve, reject) => {
      rejectFn = reject;
      
      promise
        .then(value => {
          if (!isCancelled) {
            resolve(value);
          }
        })
        .catch(error => {
          if (!isCancelled) {
            reject(error);
          }
        });
    });
    
    return {
      promise: cancellablePromise,
      cancel: () => {
        isCancelled = true;
        rejectFn(new Error('Promise was cancelled 🚫'));
      }
    };
  }
}

// 🎮 Example usage of advanced utilities
async function demonstrateAdvancedPatterns(): Promise<void> {
  try {
    // ⏰ Timeout example
    const quickData = await PromiseUtils.withTimeout(
      fetchDataWithDelay(500),
      1000,
      "Data fetch took too long! ⏰"
    );
    console.log('⚡ Quick data:', quickData);
    
    // 🔄 Retry example
    const retryData = await PromiseUtils.retry(
      () => unreliableApiCall(),
      {
        maxAttempts: 3,
        baseDelay: 500,
        shouldRetry: (error) => !error.message.includes('validation')
      }
    );
    console.log('🔄 Retry data:', retryData);
    
    // 🏎️ Parallel execution
    const parallelTasks = Array.from({ length: 10 }, (_, i) => 
      () => PromiseUtils.delay(`Task ${i + 1}`, 100, 1000)
    );
    
    const parallelResults = await PromiseUtils.parallel(parallelTasks, 3);
    console.log('🏎️ Parallel results:', parallelResults);
    
  } catch (error) {
    console.error('❌ Advanced patterns demo failed:', error);
  }
}

// 🎭 Mock functions for demonstration
async function fetchDataWithDelay(delayMs: number): Promise<string> {
  await new Promise(resolve => setTimeout(resolve, delayMs));
  return `Data fetched after ${delayMs}ms delay 📊`;
}

async function unreliableApiCall(): Promise<string> {
  if (Math.random() < 0.7) {
    throw new Error('Network error 🌐');
  }
  return 'API call successful! ✅';
}

🏗️ Promise-Based State Management

Creating a type-safe state management system with promises:

// 📊 State management types
interface StateChange<T> {
  previous: T;
  current: T;
  timestamp: Date;
  action: string;
}

interface StateSubscription<T> {
  id: string;
  callback: (change: StateChange<T>) => void;
  filter?: (change: StateChange<T>) => boolean;
}

// 🎯 Type-safe promise-based state manager
class PromiseStateManager<T> {
  private state: T;
  private subscriptions: Map<string, StateSubscription<T>> = new Map();
  private pendingUpdates: Map<string, Promise<T>> = new Map();
  private history: StateChange<T>[] = [];
  private maxHistorySize: number = 100;
  
  constructor(initialState: T) {
    this.state = initialState;
    console.log('🎯 State manager initialized');
  }
  
  // 📖 Get current state
  getState(): T {
    return { ...this.state } as T; // Return a copy to prevent mutations
  }
  
  // 🔄 Update state with a promise-based updater
  async updateState(
    updater: (currentState: T) => Promise<T> | T,
    actionName: string = 'UPDATE'
  ): Promise<T> {
    const updateId = `${actionName}_${Date.now()}_${Math.random()}`;
    
    // 🔒 Prevent concurrent updates of the same action
    if (this.pendingUpdates.has(actionName)) {
      console.log(`⏳ Waiting for pending ${actionName} to complete...`);
      await this.pendingUpdates.get(actionName);
    }
    
    try {
      console.log(`🔄 Starting state update: ${actionName}`);
      
      const updatePromise = this.performUpdate(updater, actionName);
      this.pendingUpdates.set(actionName, updatePromise);
      
      const newState = await updatePromise;
      return newState;
      
    } finally {
      this.pendingUpdates.delete(actionName);
    }
  }
  
  // 🎭 Perform the actual state update
  private async performUpdate(
    updater: (currentState: T) => Promise<T> | T,
    actionName: string
  ): Promise<T> {
    const previousState = this.getState();
    
    try {
      // 🚀 Apply the updater function
      const result = updater(previousState);
      const newState = await Promise.resolve(result);
      
      // 📝 Record the state change
      const change: StateChange<T> = {
        previous: previousState,
        current: newState,
        timestamp: new Date(),
        action: actionName
      };
      
      // 💾 Update internal state
      this.state = newState;
      this.addToHistory(change);
      
      // 📢 Notify subscribers
      await this.notifySubscribers(change);
      
      console.log(`✅ State updated: ${actionName}`);
      return newState;
      
    } catch (error) {
      console.error(`❌ State update failed: ${actionName}`, error);
      throw error;
    }
  }
  
  // 📝 Add change to history
  private addToHistory(change: StateChange<T>): void {
    this.history.push(change);
    
    // 🧹 Keep history size manageable
    if (this.history.length > this.maxHistorySize) {
      this.history = this.history.slice(-this.maxHistorySize);
    }
  }
  
  // 📢 Notify all subscribers about state changes
  private async notifySubscribers(change: StateChange<T>): Promise<void> {
    const notifications = Array.from(this.subscriptions.values())
      .filter(sub => !sub.filter || sub.filter(change))
      .map(async (sub) => {
        try {
          await Promise.resolve(sub.callback(change));
        } catch (error) {
          console.error(`❌ Subscriber ${sub.id} error:`, error);
        }
      });
    
    await Promise.all(notifications);
  }
  
  // 👂 Subscribe to state changes
  subscribe(
    callback: (change: StateChange<T>) => void,
    filter?: (change: StateChange<T>) => boolean
  ): string {
    const id = `sub_${Date.now()}_${Math.random()}`;
    
    this.subscriptions.set(id, {
      id,
      callback,
      filter
    });
    
    console.log(`👂 Subscriber ${id} added`);
    return id;
  }
  
  // 👋 Unsubscribe from state changes
  unsubscribe(subscriptionId: string): boolean {
    const removed = this.subscriptions.delete(subscriptionId);
    if (removed) {
      console.log(`👋 Subscriber ${subscriptionId} removed`);
    }
    return removed;
  }
  
  // 📜 Get state history
  getHistory(limit?: number): StateChange<T>[] {
    return limit ? this.history.slice(-limit) : [...this.history];
  }
  
  // ⏪ Rollback to a previous state
  async rollback(steps: number = 1): Promise<T> {
    if (this.history.length < steps) {
      throw new Error(`Cannot rollback ${steps} steps, only ${this.history.length} changes in history`);
    }
    
    const targetState = this.history[this.history.length - steps - 1]?.current || this.history[0]?.previous;
    
    if (!targetState) {
      throw new Error('No target state found for rollback');
    }
    
    return this.updateState(() => targetState, `ROLLBACK_${steps}`);
  }
}

// 🎮 Example usage with a shopping cart
interface CartItem {
  id: string;
  name: string;
  price: number;
  quantity: number;
}

interface ShoppingCartState {
  items: CartItem[];
  total: number;
  discountCode?: string;
  discountAmount: number;
}

// 🛒 Shopping cart with promise-based state management
class ShoppingCart {
  private stateManager: PromiseStateManager<ShoppingCartState>;
  
  constructor() {
    const initialState: ShoppingCartState = {
      items: [],
      total: 0,
      discountAmount: 0
    };
    
    this.stateManager = new PromiseStateManager(initialState);
    
    // 👂 Subscribe to total changes
    this.stateManager.subscribe(
      (change) => {
        console.log(`💰 Cart total: $${change.current.total.toFixed(2)}`);
      },
      (change) => change.previous.total !== change.current.total
    );
  }
  
  // ➕ Add item to cart with async validation
  async addItem(item: Omit<CartItem, 'id'>): Promise<ShoppingCartState> {
    return this.stateManager.updateState(async (state) => {
      // 🔍 Simulate async inventory check
      await this.checkInventory(item.name);
      
      const newItem: CartItem = {
        ...item,
        id: `item_${Date.now()}_${Math.random()}`
      };
      
      const existingItemIndex = state.items.findIndex(i => i.name === item.name);
      
      let newItems: CartItem[];
      if (existingItemIndex >= 0) {
        // 🔄 Update quantity of existing item
        newItems = [...state.items];
        newItems[existingItemIndex] = {
          ...newItems[existingItemIndex],
          quantity: newItems[existingItemIndex].quantity + item.quantity
        };
      } else {
        // ➕ Add new item
        newItems = [...state.items, newItem];
      }
      
      const newTotal = this.calculateTotal(newItems, state.discountAmount);
      
      return {
        ...state,
        items: newItems,
        total: newTotal
      };
    }, 'ADD_ITEM');
  }
  
  // 🏷️ Apply discount code with async validation
  async applyDiscountCode(code: string): Promise<ShoppingCartState> {
    return this.stateManager.updateState(async (state) => {
      // 🔍 Simulate async discount validation
      const discount = await this.validateDiscountCode(code);
      
      const discountAmount = state.total * discount.percentage;
      const newTotal = this.calculateTotal(state.items, discountAmount);
      
      return {
        ...state,
        discountCode: code,
        discountAmount,
        total: newTotal
      };
    }, 'APPLY_DISCOUNT');
  }
  
  // 🧮 Calculate total
  private calculateTotal(items: CartItem[], discountAmount: number = 0): number {
    const subtotal = items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
    return Math.max(0, subtotal - discountAmount);
  }
  
  // 🔍 Mock inventory check
  private async checkInventory(itemName: string): Promise<void> {
    await new Promise(resolve => setTimeout(resolve, 200));
    
    if (itemName.toLowerCase().includes('outofstock')) {
      throw new Error(`${itemName} is out of stock! 📦`);
    }
  }
  
  // 🏷️ Mock discount validation
  private async validateDiscountCode(code: string): Promise<{ percentage: number }> {
    await new Promise(resolve => setTimeout(resolve, 300));
    
    const validCodes: Record<string, number> = {
      'SAVE10': 0.10,
      'SAVE20': 0.20,
      'WELCOME': 0.15
    };
    
    if (!validCodes[code]) {
      throw new Error(`Invalid discount code: ${code} 🏷️`);
    }
    
    return { percentage: validCodes[code] };
  }
  
  // 📊 Get current cart state
  getState(): ShoppingCartState {
    return this.stateManager.getState();
  }
  
  // 👂 Subscribe to cart changes
  onCartChange(callback: (change: StateChange<ShoppingCartState>) => void): string {
    return this.stateManager.subscribe(callback);
  }
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Losing Type Information in Promise Chains

// ❌ Wrong way - losing types in complex chains
async function fetchUserDataBad(): Promise<any> {
  const response = await fetch('/api/user');
  const data = await response.json(); // 💥 Returns 'any'
  const processed = await processData(data); // 💥 Still 'any'
  return processed; // 💥 No type safety!
}

// Using the result loses all type information
const userData = await fetchUserDataBad();
// userData. <-- No autocomplete, no type safety

// ✅ Correct way - maintain types throughout the chain
interface UserApiResponse {
  user: {
    id: string;
    name: string;
    email: string;
  };
  metadata: {
    lastLogin: string;
    preferences: Record<string, any>;
  };
}

interface ProcessedUserData {
  id: string;
  name: string;
  email: string;
  lastLogin: Date;
  preferences: Record<string, any>;
}

async function fetchUserDataGood(): Promise<ProcessedUserData> {
  // 🎯 Type the response explicitly
  const response = await fetch('/api/user');
  const data: UserApiResponse = await response.json();
  
  // 🔄 Type-safe processing
  const processed: ProcessedUserData = await processUserData(data);
  return processed;
}

async function processUserData(data: UserApiResponse): Promise<ProcessedUserData> {
  return {
    id: data.user.id,
    name: data.user.name,
    email: data.user.email,
    lastLogin: new Date(data.metadata.lastLogin),
    preferences: data.metadata.preferences
  };
}

// ✅ Now we have full type safety!
const userData = await fetchUserDataGood();
console.log(userData.name); // 🎯 Full autocomplete and type checking

🤯 Pitfall 2: Not Handling Promise Rejection Types

// ❌ Wrong way - not typing errors properly
async function riskyOperation(): Promise<string> {
  try {
    const result = await someAsyncOperation();
    return result;
  } catch (error) {
    // 💥 'error' is unknown type - no type safety!
    console.log(error.message); // 🚫 TypeScript error
    throw error;
  }
}

// ✅ Correct way - proper error typing
interface ApiError {
  code: string;
  message: string;
  statusCode: number;
}

class NetworkError extends Error {
  constructor(public statusCode: number, message: string) {
    super(message);
    this.name = 'NetworkError';
  }
}

async function safeOperation(): Promise<string> {
  try {
    const result = await someAsyncOperation();
    return result;
  } catch (error) {
    // 🎯 Type-safe error handling
    if (error instanceof NetworkError) {
      console.log(`Network error ${error.statusCode}: ${error.message}`);
      throw error;
    } else if (error && typeof error === 'object' && 'code' in error) {
      const apiError = error as ApiError;
      console.log(`API error ${apiError.code}: ${apiError.message}`);
      throw new Error(`API Error: ${apiError.message}`);
    } else {
      console.log(`Unknown error: ${String(error)}`);
      throw new Error(`Unknown error: ${String(error)}`);
    }
  }
}

// 🛡️ Even better - use Result types for safer error handling
type OperationResult<T> = 
  | { success: true; data: T }
  | { success: false; error: string; errorType: 'network' | 'api' | 'unknown' };

async function safestOperation(): Promise<OperationResult<string>> {
  try {
    const result = await someAsyncOperation();
    return { success: true, data: result };
  } catch (error) {
    if (error instanceof NetworkError) {
      return { 
        success: false, 
        error: error.message, 
        errorType: 'network' 
      };
    } else {
      return { 
        success: false, 
        error: String(error), 
        errorType: 'unknown' 
      };
    }
  }
}

🔥 Pitfall 3: Promise Constructor Anti-patterns

// ❌ Wrong way - unnecessary Promise constructor
async function unnecessaryPromiseConstructor(): Promise<string> {
  return new Promise(async (resolve, reject) => {
    try {
      const data = await fetch('/api/data');
      const result = await data.json();
      resolve(result); // 💥 This is redundant!
    } catch (error) {
      reject(error); // 💥 This is also redundant!
    }
  });
}

// ❌ Also wrong - mixing callbacks with async/await
function mixedPatterns(): Promise<string> {
  return new Promise((resolve, reject) => {
    fetch('/api/data')
      .then(async response => {
        const data = await response.json(); // 💥 Mixing patterns
        resolve(data);
      })
      .catch(reject);
  });
}