⚖ ️ Classic vs Node Resolution: Resolution Strategies

🎯 Introduction

Welcome to the strategic battleground of module resolution! ⚖️ If TypeScript’s resolution strategies were chess players, Classic would be the traditionalist who follows time-tested patterns, while Node.js would be the modern grandmaster who adapts to the contemporary ecosystem. Understanding these two approaches is crucial for mastering TypeScript’s module system!

TypeScript offers two main module resolution strategies: Classic (the original approach) and Node.js (the modern standard). Each has its own algorithm, use cases, and trade-offs. While Node.js resolution is the default and most commonly used today, understanding both strategies will help you make informed decisions about your project configuration and troubleshoot resolution issues effectively.

By the end of this tutorial, you’ll be a master of both resolution strategies, capable of choosing the right approach for your projects and understanding exactly how TypeScript resolves modules in different scenarios. Let’s dive into the strategic world of module resolution! 🌟

📚 Understanding Resolution Strategies

🤔 What Are Resolution Strategies?

Resolution strategies determine the algorithm TypeScript uses to locate modules when processing import statements. The strategy affects the order of locations searched, the file extensions considered, and how package.json files are interpreted.

// 🌟 The same import can resolve differently based on strategy
import { UserService } from './services/UserService';
import { lodash } from 'lodash';
import { Component } from '@angular/core';

// ⚖️ Classic Resolution Strategy
// - Simpler algorithm
// - Walks up directory tree for non-relative imports
// - No package.json awareness
// - Limited file extension support

// 📦 Node.js Resolution Strategy  
// - Mimics Node.js module resolution
// - Complex algorithm with package.json support
// - Full npm ecosystem compatibility
// - Extensive file extension and index file support

// 🎯 Let's demonstrate the differences with a comprehensive example

// 📁 Project structure for demonstration:
// /project/
//   ├── src/
//   │   ├── app/
//   │   │   ├── components/
//   │   │   │   ├── UserProfile.ts
//   │   │   │   └── Button.ts
//   │   │   ├── services/
//   │   │   │   ├── UserService.ts
//   │   │   │   ├── ApiService.ts
//   │   │   │   └── index.ts
//   │   │   └── utils/
//   │   │       ├── validation.ts
//   │   │       ├── formatting.ts
//   │   │       └── index.ts
//   │   ├── shared/
//   │   │   ├── types.ts
//   │   │   └── constants.ts
//   │   └── main.ts
//   ├── node_modules/
//   │   ├── lodash/
//   │   │   ├── package.json
//   │   │   ├── index.js
//   │   │   └── lib/
//   │   └── moment/
//   │       ├── package.json
//   │       └── moment.js
//   ├── types/
//   │   ├── custom.d.ts
//   │   └── api.d.ts
//   ├── package.json
//   └── tsconfig.json

// 🔧 Resolution strategy comparison class
class ResolutionStrategyComparison {
  // 📊 Track resolution attempts
  private resolutionAttempts: {
    classic: Array<{ import: string; steps: string[]; result: string | null }>;
    node: Array<{ import: string; steps: string[]; result: string | null }>;
  } = { classic: [], node: [] };

  // ⚖️ Compare resolution strategies for the same import
  async compareResolution(
    importSpecifier: string,
    fromFile: string,
    compilerOptions: any
  ): Promise<{
    classic: { result: string | null; steps: string[] };
    node: { result: string | null; steps: string[] };
    differences: string[];
  }> {
    console.log(`⚖️ Comparing resolution strategies for: "${importSpecifier}"`);
    console.log(`📁 From file: ${fromFile}`);

    // 🎯 Classic resolution
    const classicResult = await this.resolveWithClassic(importSpecifier, fromFile, compilerOptions);
    
    // 📦 Node.js resolution
    const nodeResult = await this.resolveWithNode(importSpecifier, fromFile, compilerOptions);

    // 🔍 Analyze differences
    const differences = this.analyzeDifferences(classicResult, nodeResult);

    console.log('📊 Resolution Comparison Results:');
    console.log('   Classic:', classicResult.result || 'Not found');
    console.log('   Node.js:', nodeResult.result || 'Not found');

    return {
      classic: classicResult,
      node: nodeResult,
      differences
    };
  }

  // 🎯 Classic resolution implementation
  private async resolveWithClassic(
    importSpecifier: string,
    fromFile: string,
    compilerOptions: any
  ): Promise<{ result: string | null; steps: string[] }> {
    const steps: string[] = [];
    steps.push(`🎯 Starting Classic resolution for: ${importSpecifier}`);

    // 📁 Check if it's a relative import
    if (this.isRelativeImport(importSpecifier)) {
      steps.push('📁 Detected relative import - using relative resolution');
      return await this.classicRelativeResolution(importSpecifier, fromFile, steps);
    } else {
      steps.push('📦 Detected non-relative import - using classic non-relative resolution');
      return await this.classicNonRelativeResolution(importSpecifier, fromFile, steps);
    }
  }

  // 📦 Node.js resolution implementation
  private async resolveWithNode(
    importSpecifier: string,
    fromFile: string,
    compilerOptions: any
  ): Promise<{ result: string | null; steps: string[] }> {
    const steps: string[] = [];
    steps.push(`📦 Starting Node.js resolution for: ${importSpecifier}`);

    // 📁 Check if it's a relative import
    if (this.isRelativeImport(importSpecifier)) {
      steps.push('📁 Detected relative import - using Node.js relative resolution');
      return await this.nodeRelativeResolution(importSpecifier, fromFile, compilerOptions, steps);
    } else {
      steps.push('📦 Detected non-relative import - using Node.js non-relative resolution');
      return await this.nodeNonRelativeResolution(importSpecifier, fromFile, compilerOptions, steps);
    }
  }

  // 🎯 Classic relative resolution
  private async classicRelativeResolution(
    importSpecifier: string,
    fromFile: string,
    steps: string[]
  ): Promise<{ result: string | null; steps: string[] }> {
    const containingDir = this.getDirectoryPath(fromFile);
    const resolvedPath = this.resolvePath(containingDir, importSpecifier);

    steps.push(`📍 Resolved base path: ${resolvedPath}`);

    // 🔍 Classic only tries .ts and .d.ts extensions
    const extensions = ['.ts', '.d.ts'];
    
    for (const ext of extensions) {
      const candidate = `${resolvedPath}${ext}`;
      steps.push(`🔍 Trying: ${candidate}`);
      
      if (await this.fileExists(candidate)) {
        steps.push(`✅ Found: ${candidate}`);
        return { result: candidate, steps };
      }
    }

    steps.push(`❌ Classic resolution failed for: ${importSpecifier}`);
    return { result: null, steps };
  }

  // 🎯 Classic non-relative resolution
  private async classicNonRelativeResolution(
    importSpecifier: string,
    fromFile: string,
    steps: string[]
  ): Promise<{ result: string | null; steps: string[] }> {
    let currentDir = this.getDirectoryPath(fromFile);

    // 🔄 Walk up directory tree
    while (currentDir !== '/') {
      steps.push(`📁 Searching in directory: ${currentDir}`);

      // 🔍 Try extensions in current directory
      const extensions = ['.ts', '.d.ts'];
      
      for (const ext of extensions) {
        const candidate = `${currentDir}/${importSpecifier}${ext}`;
        steps.push(`🔍 Trying: ${candidate}`);
        
        if (await this.fileExists(candidate)) {
          steps.push(`✅ Found: ${candidate}`);
          return { result: candidate, steps };
        }
      }

      // 📁 Move up one directory
      currentDir = this.getParentDirectory(currentDir);
      steps.push(`⬆️ Moving up to: ${currentDir}`);
    }

    steps.push(`❌ Classic non-relative resolution failed for: ${importSpecifier}`);
    return { result: null, steps };
  }

  // 📦 Node.js relative resolution
  private async nodeRelativeResolution(
    importSpecifier: string,
    fromFile: string,
    compilerOptions: any,
    steps: string[]
  ): Promise<{ result: string | null; steps: string[] }> {
    const containingDir = this.getDirectoryPath(fromFile);
    const resolvedPath = this.resolvePath(containingDir, importSpecifier);

    steps.push(`📍 Resolved base path: ${resolvedPath}`);

    // 🔍 Node.js tries multiple extensions
    const extensions = ['.ts', '.tsx', '.d.ts', '.js', '.jsx'];
    
    // 📄 Try as file
    for (const ext of extensions) {
      const candidate = `${resolvedPath}${ext}`;
      steps.push(`🔍 Trying as file: ${candidate}`);
      
      if (await this.fileExists(candidate)) {
        steps.push(`✅ Found file: ${candidate}`);
        return { result: candidate, steps };
      }
    }

    // 📁 Try as directory
    steps.push(`📁 Trying as directory: ${resolvedPath}`);
    
    // 📄 Check for package.json
    const packageJsonPath = `${resolvedPath}/package.json`;
    if (await this.fileExists(packageJsonPath)) {
      steps.push(`📄 Found package.json: ${packageJsonPath}`);
      
      const packageJson = await this.readJsonFile(packageJsonPath);
      const mainField = packageJson.main || packageJson.types || packageJson.typings;
      
      if (mainField) {
        const mainPath = `${resolvedPath}/${mainField}`;
        steps.push(`📦 Trying main field: ${mainPath}`);
        
        if (await this.fileExists(mainPath)) {
          steps.push(`✅ Found via package.json main: ${mainPath}`);
          return { result: mainPath, steps };
        }
      }
    }

    // 🗂️ Try index files
    const indexCandidates = extensions.map(ext => `${resolvedPath}/index${ext}`);
    
    for (const candidate of indexCandidates) {
      steps.push(`🔍 Trying index file: ${candidate}`);
      
      if (await this.fileExists(candidate)) {
        steps.push(`✅ Found index file: ${candidate}`);
        return { result: candidate, steps };
      }
    }

    steps.push(`❌ Node.js relative resolution failed for: ${importSpecifier}`);
    return { result: null, steps };
  }

  // 📦 Node.js non-relative resolution
  private async nodeNonRelativeResolution(
    importSpecifier: string,
    fromFile: string,
    compilerOptions: any,
    steps: string[]
  ): Promise<{ result: string | null; steps: string[] }> {
    // 🗺️ Try path mapping first (Node.js strategy with TypeScript extensions)
    if (compilerOptions.baseUrl && compilerOptions.paths) {
      steps.push('🗺️ Checking path mappings...');
      
      const pathResult = await this.tryPathMapping(importSpecifier, compilerOptions, steps);
      if (pathResult) {
        return { result: pathResult, steps };
      }
    }

    // 📦 Try node_modules resolution
    steps.push('📦 Searching in node_modules...');
    
    let currentDir = this.getDirectoryPath(fromFile);

    while (currentDir !== '/') {
      const nodeModulesPath = `${currentDir}/node_modules`;
      steps.push(`📁 Checking: ${nodeModulesPath}`);

      if (await this.directoryExists(nodeModulesPath)) {
        const moduleResult = await this.resolveFromNodeModules(
          nodeModulesPath,
          importSpecifier,
          steps
        );
        
        if (moduleResult) {
          return { result: moduleResult, steps };
        }
      }

      currentDir = this.getParentDirectory(currentDir);
    }

    // 🔍 Try global @types
    steps.push('🌍 Checking global @types...');
    const globalTypesResult = await this.resolveGlobalTypes(importSpecifier, steps);
    if (globalTypesResult) {
      return { result: globalTypesResult, steps };
    }

    steps.push(`❌ Node.js non-relative resolution failed for: ${importSpecifier}`);
    return { result: null, steps };
  }

  // 🗺️ Path mapping resolution
  private async tryPathMapping(
    importSpecifier: string,
    compilerOptions: any,
    steps: string[]
  ): Promise<string | null> {
    const { baseUrl, paths } = compilerOptions;
    
    for (const [pattern, substitutions] of Object.entries(paths)) {
      const match = this.matchPattern(pattern, importSpecifier);
      
      if (match) {
        steps.push(`🎯 Matched pattern: ${pattern}`);
        
        for (const substitution of substitutions as string[]) {
          const resolvedPath = this.substitutePattern(substitution, match.groups, baseUrl);
          steps.push(`🔄 Trying substitution: ${resolvedPath}`);
          
          const extensions = ['.ts', '.tsx', '.d.ts', '.js', '.jsx'];
          
          for (const ext of extensions) {
            const candidate = `${resolvedPath}${ext}`;
            
            if (await this.fileExists(candidate)) {
              steps.push(`✅ Found via path mapping: ${candidate}`);
              return candidate;
            }
          }
          
          // Try index files
          for (const ext of extensions) {
            const candidate = `${resolvedPath}/index${ext}`;
            
            if (await this.fileExists(candidate)) {
              steps.push(`✅ Found index via path mapping: ${candidate}`);
              return candidate;
            }
          }
        }
      }
    }
    
    return null;
  }

  // 📦 Resolve from node_modules
  private async resolveFromNodeModules(
    nodeModulesPath: string,
    importSpecifier: string,
    steps: string[]
  ): Promise<string | null> {
    const [scopeOrName, ...rest] = importSpecifier.split('/');
    let packageName: string;
    let subPath: string;
    
    if (scopeOrName.startsWith('@')) {
      packageName = `${scopeOrName}/${rest[0]}`;
      subPath = rest.slice(1).join('/');
    } else {
      packageName = scopeOrName;
      subPath = rest.join('/');
    }
    
    const packageDir = `${nodeModulesPath}/${packageName}`;
    steps.push(`📦 Checking package: ${packageDir}`);
    
    if (!(await this.directoryExists(packageDir))) {
      return null;
    }
    
    if (subPath) {
      // Resolving subpath
      const subPathResolved = `${packageDir}/${subPath}`;
      return await this.resolveFileWithExtensions(subPathResolved, steps);
    } else {
      // Resolving main entry
      return await this.resolvePackageMain(packageDir, steps);
    }
  }

  // 📄 Resolve package main entry
  private async resolvePackageMain(packageDir: string, steps: string[]): Promise<string | null> {
    const packageJsonPath = `${packageDir}/package.json`;
    
    if (await this.fileExists(packageJsonPath)) {
      const packageJson = await this.readJsonFile(packageJsonPath);
      steps.push(`📄 Read package.json for: ${packageJson.name}`);
      
      // Try different entry fields
      const entryFields = ['types', 'typings', 'main', 'module'];
      
      for (const field of entryFields) {
        if (packageJson[field]) {
          const entryPath = `${packageDir}/${packageJson[field]}`;
          steps.push(`🔍 Trying ${field} field: ${entryPath}`);
          
          if (await this.fileExists(entryPath)) {
            steps.push(`✅ Found via ${field}: ${entryPath}`);
            return entryPath;
          }
        }
      }
    }
    
    // Try default index files
    return await this.resolveFileWithExtensions(`${packageDir}/index`, steps);
  }

  // 🌍 Resolve global types
  private async resolveGlobalTypes(importSpecifier: string, steps: string[]): Promise<string | null> {
    const globalTypesPath = `/usr/local/lib/node_modules/@types/${importSpecifier}`;
    steps.push(`🌍 Checking global types: ${globalTypesPath}`);
    
    if (await this.directoryExists(globalTypesPath)) {
      return await this.resolvePackageMain(globalTypesPath, steps);
    }
    
    return null;
  }

  // 📄 Resolve file with extensions
  private async resolveFileWithExtensions(basePath: string, steps: string[]): Promise<string | null> {
    const extensions = ['.ts', '.tsx', '.d.ts', '.js', '.jsx', ''];
    
    for (const ext of extensions) {
      const candidate = basePath + ext;
      
      if (await this.fileExists(candidate)) {
        steps.push(`✅ Found: ${candidate}`);
        return candidate;
      }
    }
    
    return null;
  }

  // 🔍 Analyze differences between resolution strategies
  private analyzeDifferences(
    classicResult: { result: string | null; steps: string[] },
    nodeResult: { result: string | null; steps: string[] }
  ): string[] {
    const differences: string[] = [];

    // Compare results
    if (classicResult.result !== nodeResult.result) {
      differences.push(`Different resolution results: Classic=${classicResult.result}, Node=${nodeResult.result}`);
    }

    // Compare step counts
    if (classicResult.steps.length !== nodeResult.steps.length) {
      differences.push(`Different number of resolution steps: Classic=${classicResult.steps.length}, Node=${nodeResult.steps.length}`);
    }

    // Check for Node.js-specific features
    const nodeSpecificFeatures = [
      'package.json',
      'index file',
      'node_modules',
      'path mapping',
      '@types'
    ];

    const nodeUsesFeatures = nodeSpecificFeatures.some(feature =>
      nodeResult.steps.some(step => step.toLowerCase().includes(feature))
    );

    const classicUsesFeatures = nodeSpecificFeatures.some(feature =>
      classicResult.steps.some(step => step.toLowerCase().includes(feature))
    );

    if (nodeUsesFeatures && !classicUsesFeatures) {
      differences.push('Node.js resolution uses advanced features not available in Classic');
    }

    return differences;
  }

  // 🔧 Utility methods
  private isRelativeImport(importSpecifier: string): boolean {
    return importSpecifier.startsWith('./') || 
           importSpecifier.startsWith('../') || 
           importSpecifier.startsWith('/');
  }

  private getDirectoryPath(filePath: string): string {
    return filePath.substring(0, filePath.lastIndexOf('/')) || '/';
  }

  private getParentDirectory(dirPath: string): string {
    const parent = dirPath.substring(0, dirPath.lastIndexOf('/')) || '/';
    return parent === dirPath ? '/' : parent;
  }

  private resolvePath(basePath: string, relativePath: string): string {
    if (relativePath.startsWith('./')) {
      return `${basePath}/${relativePath.substring(2)}`;
    } else if (relativePath.startsWith('../')) {
      const parentDir = this.getParentDirectory(basePath);
      return this.resolvePath(parentDir, relativePath.substring(3));
    } else {
      return `${basePath}/${relativePath}`;
    }
  }

  private matchPattern(pattern: string, input: string): { groups: string[] } | null {
    const regexPattern = pattern.replace(/\*/g, '(.*)');
    const regex = new RegExp(`^${regexPattern}$`);
    const match = input.match(regex);
    
    return match ? { groups: match.slice(1) } : null;
  }

  private substitutePattern(substitution: string, groups: string[], baseUrl: string): string {
    let result = substitution;
    groups.forEach((group) => {
      result = result.replace(/\*/g, group);
    });
    return `${baseUrl}/${result}`;
  }

  // 🔧 File system simulation
  private async fileExists(path: string): Promise<boolean> {
    const simulatedFiles = [
      '/project/src/app/services/UserService.ts',
      '/project/src/app/utils/validation.ts',
      '/project/src/shared/types.ts',
      '/project/node_modules/lodash/package.json',
      '/project/node_modules/lodash/index.js',
      '/project/node_modules/moment/package.json',
      '/project/node_modules/moment/moment.js',
      '/project/types/custom.d.ts'
    ];
    
    return simulatedFiles.includes(path);
  }

  private async directoryExists(path: string): Promise<boolean> {
    const simulatedDirs = [
      '/project/src',
      '/project/src/app',
      '/project/src/app/services',
      '/project/node_modules',
      '/project/node_modules/lodash',
      '/project/node_modules/moment'
    ];
    
    return simulatedDirs.includes(path);
  }

  private async readJsonFile(path: string): Promise<any> {
    const simulatedPackageJsons: Record<string, any> = {
      '/project/node_modules/lodash/package.json': {
        name: 'lodash',
        version: '4.17.21',
        main: 'lodash.js',
        types: 'index.d.ts'
      },
      '/project/node_modules/moment/package.json': {
        name: 'moment',
        version: '2.29.4',
        main: 'moment.js',
        types: 'moment.d.ts'
      }
    };
    
    return simulatedPackageJsons[path] || {};
  }

  // 📊 Get resolution statistics
  getStatistics() {
    const classicStats = this.resolutionAttempts.classic;
    const nodeStats = this.resolutionAttempts.node;
    
    return {
      classic: {
        totalAttempts: classicStats.length,
        successful: classicStats.filter(a => a.result).length,
        averageSteps: classicStats.reduce((sum, a) => sum + a.steps.length, 0) / classicStats.length || 0
      },
      node: {
        totalAttempts: nodeStats.length,
        successful: nodeStats.filter(a => a.result).length,
        averageSteps: nodeStats.reduce((sum, a) => sum + a.steps.length, 0) / nodeStats.length || 0
      }
    };
  }
}

// 🎮 Usage example
const resolutionStrategyDemo = async (): Promise<void> => {
  const comparison = new ResolutionStrategyComparison();
  
  const compilerOptions = {
    moduleResolution: 'node',
    baseUrl: '/project/src',
    paths: {
      '@/*': ['*'],
      '@services/*': ['app/services/*'],
      '@utils/*': ['app/utils/*']
    }
  };
  
  // 📁 Test relative import
  await comparison.compareResolution(
    './UserService',
    '/project/src/app/components/UserProfile.ts',
    compilerOptions
  );
  
  // 📦 Test npm package import
  await comparison.compareResolution(
    'lodash',
    '/project/src/app/main.ts',
    compilerOptions
  );
  
  // 🗺️ Test path-mapped import
  await comparison.compareResolution(
    '@services/UserService',
    '/project/src/app/components/UserProfile.ts',
    compilerOptions
  );
  
  // 📊 Show statistics
  console.log('📊 Resolution Statistics:', comparison.getStatistics());
};

💡 Detailed Strategy Comparison

Let’s dive deep into the specific differences between Classic and Node.js resolution:

// 🌟 Comprehensive strategy comparison
interface ResolutionStrategy {
  name: 'classic' | 'node';
  algorithm: string;
  fileExtensions: string[];
  supportsPackageJson: boolean;
  supportsIndexFiles: boolean;
  supportsNodeModules: boolean;
  supportsPathMapping: boolean;
  performance: 'fast' | 'moderate' | 'slow';
  useCases: string[];
}

// ⚖️ Strategy definitions
const resolutionStrategies: Record<string, ResolutionStrategy> = {
  classic: {
    name: 'classic',
    algorithm: 'Simple directory traversal',
    fileExtensions: ['.ts', '.d.ts'],
    supportsPackageJson: false,
    supportsIndexFiles: false,
    supportsNodeModules: false,
    supportsPathMapping: true, // Limited support
    performance: 'fast',
    useCases: [
      'Legacy TypeScript projects',
      'Simple module structures',
      'Projects without npm dependencies',
      'Quick prototyping'
    ]
  },
  
  node: {
    name: 'node',
    algorithm: 'Node.js-compatible resolution',
    fileExtensions: ['.ts', '.tsx', '.js', '.jsx', '.d.ts'],
    supportsPackageJson: true,
    supportsIndexFiles: true,
    supportsNodeModules: true,
    supportsPathMapping: true,
    performance: 'moderate',
    useCases: [
      'Modern TypeScript applications',
      'Projects using npm packages',
      'React/Angular/Vue applications',
      'Full-stack development',
      'Library development',
      'Monorepo setups'
    ]
  }
};

// 🔧 Strategy selector and analyzer
class ResolutionStrategyAnalyzer {
  // 🎯 Recommend strategy based on project characteristics
  static recommendStrategy(projectProfile: {
    hasNodeModules: boolean;
    usesNpmPackages: boolean;
    hasReactComponents: boolean;
    isLibrary: boolean;
    isLegacy: boolean;
    requiresPathMapping: boolean;
    performanceCritical: boolean;
  }): {
    recommended: 'classic' | 'node';
    reasons: string[];
    warnings: string[];
  } {
    const reasons: string[] = [];
    const warnings: string[] = [];
    let recommended: 'classic' | 'node' = 'node'; // Default to node
    
    // 📦 Check for npm dependencies
    if (projectProfile.usesNpmPackages || projectProfile.hasNodeModules) {
      reasons.push('Project uses npm packages - Node.js resolution required');
      recommended = 'node';
    }
    
    // ⚛️ Check for React/JSX
    if (projectProfile.hasReactComponents) {
      reasons.push('React components require .tsx/.jsx support - Node.js resolution recommended');
      recommended = 'node';
    }
    
    // 📚 Check for library development
    if (projectProfile.isLibrary) {
      reasons.push('Library development benefits from Node.js resolution for package.json support');
      recommended = 'node';
    }
    
    // 🗺️ Check for complex path mapping
    if (projectProfile.requiresPathMapping) {
      reasons.push('Complex path mapping works better with Node.js resolution');
      recommended = 'node';
    }
    
    // ⚡ Check for performance requirements
    if (projectProfile.performanceCritical && !projectProfile.usesNpmPackages) {
      reasons.push('Performance-critical and simple structure - Classic might be faster');
      warnings.push('Classic resolution has limited features');
      // Don't change recommendation, just note the option
    }
    
    // 🕰️ Check for legacy projects
    if (projectProfile.isLegacy && !projectProfile.usesNpmPackages) {
      reasons.push('Legacy project without npm dependencies - Classic might be suitable');
      warnings.push('Consider migrating to Node.js resolution for future compatibility');
    }
    
    // 🚨 Add warnings for Classic
    if (recommended === 'classic') {
      warnings.push('Classic resolution is deprecated and may be removed in future TypeScript versions');
      warnings.push('Limited ecosystem compatibility');
      warnings.push('No package.json support');
    }
    
    return { recommended, reasons, warnings };
  }

  // 📊 Compare performance characteristics
  static comparePerformance(
    projectSize: 'small' | 'medium' | 'large',
    dependencyCount: number,
    pathMappingComplexity: 'simple' | 'moderate' | 'complex'
  ): {
    classic: { speed: number; memoryUsage: number; reliability: number };
    node: { speed: number; memoryUsage: number; reliability: number };
    recommendation: string;
  } {
    // Performance metrics (1-10 scale)
    const classic = {
      speed: projectSize === 'small' ? 9 : (projectSize === 'medium' ? 7 : 5),
      memoryUsage: 8, // Generally lower
      reliability: dependencyCount > 0 ? 3 : 8 // Poor with dependencies
    };
    
    const node = {
      speed: pathMappingComplexity === 'simple' ? 8 : (pathMappingComplexity === 'moderate' ? 6 : 4),
      memoryUsage: 6, // Higher due to more features
      reliability: 9 // Consistently good
    };
    
    const recommendation = classic.speed > node.speed && dependencyCount === 0
      ? 'Classic for simple projects without dependencies'
      : 'Node.js for robust, feature-complete resolution';
    
    return { classic, node, recommendation };
  }

  // 🔧 Generate optimal tsconfig.json
  static generateOptimalConfig(
    strategy: 'classic' | 'node',
    projectType: 'app' | 'library' | 'monorepo',
    features: {
      pathMapping: boolean;
      strict: boolean;
      jsx: boolean;
      decorators: boolean;
    }
  ): any {
    const baseConfig = {
      compilerOptions: {
        moduleResolution: strategy,
        target: 'ES2020',
        module: strategy === 'node' ? 'ES2020' : 'AMD',
        lib: ['ES2020', 'DOM'],
        strict: features.strict,
        esModuleInterop: strategy === 'node',
        allowSyntheticDefaultImports: strategy === 'node',
        skipLibCheck: true,
        forceConsistentCasingInFileNames: true
      }
    };

    // 🎯 Strategy-specific optimizations
    if (strategy === 'node') {
      Object.assign(baseConfig.compilerOptions, {
        resolveJsonModule: true,
        isolatedModules: true,
        allowJs: true,
        declaration: projectType === 'library',
        declarationMap: projectType === 'library',
        sourceMap: true
      });
      
      // 🗺️ Path mapping for Node.js
      if (features.pathMapping) {
        Object.assign(baseConfig.compilerOptions, {
          baseUrl: './src',
          paths: {
            '@/*': ['*'],
            '@components/*': ['components/*'],
            '@services/*': ['services/*'],
            '@utils/*': ['utils/*'],
            '@types/*': ['../types/*']
          }
        });
      }
      
      // ⚛️ JSX support
      if (features.jsx) {
        Object.assign(baseConfig.compilerOptions, {
          jsx: 'react-jsx',
          allowJs: true
        });
      }
      
      // 🎨 Decorator support
      if (features.decorators) {
        Object.assign(baseConfig.compilerOptions, {
          experimentalDecorators: true,
          emitDecoratorMetadata: true
        });
      }
      
    } else {
      // Classic strategy optimizations
      Object.assign(baseConfig.compilerOptions, {
        noResolve: false,
        typeRoots: ['./types']
      });
      
      // Limited path mapping for Classic
      if (features.pathMapping) {
        Object.assign(baseConfig.compilerOptions, {
          baseUrl: '.',
          paths: {
            '*': ['./src/*', './types/*']
          }
        });
      }
    }

    // 📁 Project-specific includes/excludes
    const includeExclude = {
      include: projectType === 'monorepo' 
        ? ['packages/*/src/**/*', 'shared/**/*']
        : ['src/**/*'],
      exclude: ['node_modules', 'dist', '**/*.test.ts', '**/*.spec.ts']
    };

    return { ...baseConfig, ...includeExclude };
  }

  // 🐛 Debug resolution strategy issues
  static debugResolutionIssues(
    strategy: 'classic' | 'node',
    error: string,
    context: {
      importSpecifier: string;
      fromFile: string;
      tsConfigPath: string;
    }
  ): {
    possibleCauses: string[];
    solutions: string[];
    alternativeStrategy: string;
  } {
    const possibleCauses: string[] = [];
    const solutions: string[] = [];
    let alternativeStrategy = '';

    if (strategy === 'classic') {
      if (error.includes('Cannot find module')) {
        possibleCauses.push(
          'Classic resolution only supports .ts and .d.ts extensions',
          'No support for package.json main field',
          'No support for index files',
          'Limited path mapping support'
        );
        
        solutions.push(
          'Switch to Node.js resolution strategy',
          'Ensure imported files have .ts or .d.ts extensions',
          'Use full relative paths without relying on index files',
          'Check if the module exists in the directory tree'
        );
        
        alternativeStrategy = 'Switch to "moduleResolution": "node" for better compatibility';
      }
      
      if (context.importSpecifier.includes('node_modules')) {
        possibleCauses.push('Classic resolution does not support node_modules');
        solutions.push('Must use Node.js resolution for npm packages');
        alternativeStrategy = 'Node.js resolution is required for npm dependencies';
      }
      
    } else {
      // Node.js resolution issues
      if (error.includes('Cannot find module')) {
        possibleCauses.push(
          'Incorrect path mapping configuration',
          'Missing package.json or incorrect main field',
          'File does not exist at resolved location',
          'Incorrect baseUrl setting'
        );
        
        solutions.push(
          'Check tsconfig.json paths configuration',
          'Verify package.json main/types fields',
          'Use --traceResolution for detailed debugging',
          'Ensure baseUrl is set correctly'
        );
        
        alternativeStrategy = 'Classic resolution might work for simple relative imports';
      }
      
      if (error.includes('path mapping')) {
        possibleCauses.push(
          'baseUrl not set when using paths',
          'Incorrect glob patterns in paths',
          'IDE not recognizing path mappings'
        );
        
        solutions.push(
          'Set baseUrl when using paths',
          'Restart TypeScript service',
          'Check path pattern syntax'
        );
      }
    }

    return { possibleCauses, solutions, alternativeStrategy };
  }
}

// 🎮 Usage examples
const strategyComparisonDemo = async (): Promise<void> => {
  // 🎯 Analyze project for strategy recommendation
  const projectProfile = {
    hasNodeModules: true,
    usesNpmPackages: true,
    hasReactComponents: true,
    isLibrary: false,
    isLegacy: false,
    requiresPathMapping: true,
    performanceCritical: false
  };
  
  const recommendation = ResolutionStrategyAnalyzer.recommendStrategy(projectProfile);
  console.log('📊 Strategy Recommendation:', recommendation);
  
  // 📊 Compare performance
  const performance = ResolutionStrategyAnalyzer.comparePerformance('medium', 25, 'moderate');
  console.log('⚡ Performance Comparison:', performance);
  
  // 🔧 Generate optimal configuration
  const optimalConfig = ResolutionStrategyAnalyzer.generateOptimalConfig(
    'node',
    'app',
    {
      pathMapping: true,
      strict: true,
      jsx: true,
      decorators: false
    }
  );
  console.log('⚙️ Optimal Configuration:', optimalConfig);
  
  // 🐛 Debug common issues
  const debugInfo = ResolutionStrategyAnalyzer.debugResolutionIssues(
    'classic',
    'Cannot find module \'react\'',
    {
      importSpecifier: 'react',
      fromFile: '/project/src/App.tsx',
      tsConfigPath: '/project/tsconfig.json'
    }
  );
  console.log('🐛 Debug Information:', debugInfo);
};

🎉 Conclusion

Congratulations! You’ve mastered the strategic differences between Classic and Node.js module resolution! ⚖️

🎯 What You’ve Learned

• ⚖️ Strategy Differences: Deep understanding of Classic vs Node.js resolution
• 📦 Algorithm Details: How each strategy locates and resolves modules
• 🎯 Use Case Analysis: When to choose each resolution strategy
• 🔧 Configuration Optimization: Tailoring tsconfig.json for each strategy
• 🐛 Debugging Techniques: Troubleshooting strategy-specific issues

🚀 Key Benefits

• 🎯 Strategic Decision Making: Choose the right resolution strategy for your project
• ⚡ Performance Optimization: Understand performance implications of each strategy
• 🔧 Configuration Mastery: Optimize module resolution for your specific needs
• 🐛 Effective Debugging: Quickly identify and resolve strategy-related issues
• 📚 Future-Proofing: Prepare for TypeScript evolution and best practices

🔥 Best Practices Recap

1. 📦 Use Node.js Resolution: Default choice for modern TypeScript projects
2. ⚖️ Consider Classic: Only for simple, legacy projects without npm dependencies
3. 🔧 Optimize Configuration: Tailor tsconfig.json to your resolution strategy
4. 🐛 Enable Tracing: Use —traceResolution for debugging complex issues
5. 📊 Monitor Performance: Track resolution performance in large projects

You’re now equipped to make informed decisions about module resolution strategies and optimize your TypeScript projects for the best development experience! 🌟

Happy coding, and may your modules always resolve strategically! ⚖️✨