Configuration System

/**
 * Configure RequireJS runtime behavior
 * @param config - Configuration object
 */
function require.config(config: RequireConfig): void;

interface RequireConfig {
  /** Base URL for all module lookups */
  baseUrl?: string;
  
  /** Path mappings for module names */
  paths?: { [key: string]: string };
  
  /** Package configurations */
  packages?: PackageConfig[];
  
  /** Module mapping for different contexts */
  map?: { [key: string]: { [key: string]: string } };
  
  /** Configuration passed to modules */
  config?: { [key: string]: any };
  
  /** Shim configuration for non-AMD libraries */
  shim?: { [key: string]: ShimConfig };
  
  /** Timeout for module loading (seconds) */
  waitSeconds?: number;
  
  /** Context name for multiple RequireJS instances */
  context?: string;
  
  /** Dependencies to load immediately */
  deps?: string[];
  
  /** Callback after deps are loaded */
  callback?: Function;
  
  /** Enforce define() calls */
  enforceDefine?: boolean;
  
  /** Script loading attributes */
  scriptType?: string;
  
  /** Use XHTML-compatible script tags */
  xhtml?: boolean;
  
  /** Query string args for cache busting */
  urlArgs?: string | ((id: string, url: string) => string);
  
  /** jQuery version specification for compatibility */
  jQuery?: string;
  
  /** Skip data-main attribute processing */
  skipDataMain?: boolean;
  
  /** Node.js-specific enhanced compatibility */
  nodeIdCompat?: boolean;
}

// Basic path configuration
require.config({
  baseUrl: 'scripts',
  paths: {
    'jquery': 'lib/jquery-1.8.2.min',
    'underscore': 'lib/underscore-min',
    'backbone': 'lib/backbone-min',
    'templates': '../templates'
  }
});

// Complex application configuration
require.config({
  baseUrl: 'js',
  
  paths: {
    // Libraries
    'jquery': 'vendor/jquery/jquery.min',
    'bootstrap': 'vendor/bootstrap/js/bootstrap.bundle.min',
    'moment': 'vendor/moment/moment.min',
    
    // Application modules
    'app': 'app',
    'models': 'app/models',
    'views': 'app/views',
    'collections': 'app/collections',
    
    // Plugins
    'text': 'vendor/requirejs-text/text',
    'domready': 'vendor/requirejs-domready/domReady'
  },
  
  // Handle non-AMD libraries
  shim: {
    'bootstrap': {
      deps: ['jquery']
    }
  },
  
  // Module-specific configuration
  config: {
    'app/config': {
      apiUrl: '/api/v1',
      version: '2.1.0'
    }
  },
  
  // Load core dependencies
  deps: ['domready', 'app/main'],
  
  // Increase timeout for slow connections
  waitSeconds: 30
});

/**
 * Path mapping configuration
 */
interface PathConfig {
  /** Direct path mappings */
  paths: { [moduleName: string]: string };
  
  /** Base URL for relative paths */
  baseUrl: string;
  
  /** URL calculation function */
  urlArgs?: string | ((id: string, url: string) => string);
}

/**
 * Path resolution rules
 */
interface PathResolution {
  /** Relative paths resolved from baseUrl */
  relative: string;  // './module' -> baseUrl + 'module'
  
  /** Absolute URLs used directly */
  absolute: string;  // 'http://cdn.com/lib.js'
  
  /** Path mappings take precedence */
  mapped: string;    // 'jquery' -> paths.jquery value
  
  /** Fallback to baseUrl + moduleName */
  default: string;   // 'utils' -> baseUrl + 'utils.js'
}

// Path mapping scenarios
require.config({
  baseUrl: 'scripts',
  
  paths: {
    // Map to different filename
    'jquery': 'lib/jquery-1.8.2.min',
    
    // Map to subdirectory
    'admin': 'modules/admin/main',
    
    // Map to CDN (with fallback)
    'backbone': [
      '//cdnjs.cloudflare.com/ajax/libs/backbone.js/1.1.2/backbone-min',
      'lib/backbone-min'
    ],
    
    // Map entire directory
    'templates': '../templates'
  },
  
  // Add cache busting
  urlArgs: "bust=" + (new Date()).getTime()
});

// Advanced path configuration
require.config({
  baseUrl: '/app/js',
  
  paths: {
    // Version management
    'jquery': 'vendor/jquery/2.1.4/jquery.min',
    'underscore': 'vendor/underscore/1.8.3/underscore-min',
    
    // Environment-specific paths
    'config': window.location.hostname === 'localhost' ? 
      'config/development' : 'config/production',
    
    // Conditional paths
    'analytics': window.ANALYTICS_ENABLED ? 
      'vendor/analytics/analytics' : 'utils/analytics-stub'
  }
});

/**
 * Package configuration
 */
interface PackageConfig {
  /** Package name */
  name: string;
  
  /** Package location (directory) */
  location?: string;
  
  /** Main module within package */
  main?: string;
  
  /** Package-specific configuration */
  config?: any;
}

/**
 * Package resolution behavior
 */
interface PackageResolution {
  /** 'myPackage' resolves to location + '/' + main */
  nameOnly: string;
  
  /** 'myPackage/module' resolves to location + '/module' */
  withModule: string;
  
  /** 'myPackage/main' resolves to main module */
  explicitMain: string;
}

// Basic package configuration
require.config({
  packages: [
    {
      name: 'dojo',
      location: 'vendor/dojo',
      main: 'main'
    },
    {
      name: 'dijit', 
      location: 'vendor/dijit',
      main: 'main'
    }
  ]
});

// Complex package setup
require.config({
  baseUrl: 'js',
  
  packages: [
    // Full package specification
    {
      name: 'mylib',
      location: 'vendor/mylib-2.0',
      main: 'index',
      config: {
        locale: 'en-US',
        theme: 'default'
      }
    },
    
    // Simple package (uses defaults)
    {
      name: 'utils',
      location: 'app/utils'
      // main defaults to 'main'
    },
    
    // Package with custom main
    {
      name: 'widgets',
      location: 'app/widgets',
      main: 'widget-core'
    }
  ]
});

// Using packages
require(['mylib', 'mylib/advanced', 'utils'], function(mylib, advanced, utils) {
  // mylib -> vendor/mylib-2.0/index.js
  // mylib/advanced -> vendor/mylib-2.0/advanced.js  
  // utils -> app/utils/main.js
});

/**
 * Shim configuration for non-AMD libraries
 */
interface ShimConfig {
  /** Dependencies that must load before this library */
  deps?: string[];
  
  /** Global variable name this library exports */
  exports?: string;
  
  /** Initialization function returning the export value */
  init?: Function;
}

/**
 * Common shim patterns
 */
interface CommonShims {
  /** jQuery plugins */
  jqueryPlugin: {
    deps: ["jquery"];
    exports?: string;
  };
  
  /** Global libraries */
  globalLibrary: {
    exports: string;
    init?: () => any;
  };
  
  /** Legacy scripts */
  legacyScript: {
    deps?: string[];
    init: () => any;
  };
}

// Common library shims
require.config({
  paths: {
    'jquery': 'lib/jquery-1.8.2.min',
    'underscore': 'lib/underscore-min', 
    'backbone': 'lib/backbone-min',
    'bootstrap': 'lib/bootstrap.min',
    'modernizr': 'lib/modernizr.custom'
  },
  
  shim: {
    // Underscore exports '_'
    'underscore': {
      exports: '_'
    },
    
    // Backbone depends on underscore and jQuery, exports 'Backbone'
    'backbone': {
      deps: ['underscore', 'jquery'],
      exports: 'Backbone'
    },
    
    // Bootstrap depends on jQuery, no export needed
    'bootstrap': {
      deps: ['jquery']
    },
    
    // Modernizr exports 'Modernizr' 
    'modernizr': {
      exports: 'Modernizr'
    }
  }
});

// Advanced shim configurations
require.config({
  shim: {
    // Custom initialization
    'legacy-lib': {
      deps: ['jquery'],
      init: function($) {
        // Custom setup before export
        window.LegacyLib.setJQuery($);
        return window.LegacyLib;
      }
    },
    
    // jQuery plugin (no export)
    'jquery.plugin': {
      deps: ['jquery']
    },
    
    // Library with complex dependencies
    'complex-lib': {
      deps: ['jquery', 'underscore', 'moment'],
      exports: 'ComplexLib',
      init: function($, _, moment) {
        // Configure the library
        window.ComplexLib.configure({
          jquery: $,
          utilities: _,
          dateLib: moment
        });
        return window.ComplexLib;
      }
    }
  }
});

/**
 * Module mapping configuration
 */
interface MapConfig {
  /** Module mappings */
  map: {
    [contextModule: string]: {
      [originalModule: string]: string;
    };
  };
}

/**
 * Mapping resolution patterns
 */
interface MappingPatterns {
  /** Global mapping (applies to all modules) */
  "*": { [module: string]: string };
  
  /** Context-specific mapping */
  contextSpecific: { [module: string]: string };
  
  /** Hierarchical mapping resolution */
  resolution: "most-specific-wins";
}

// Version mapping
require.config({
  map: {
    // All modules use jQuery 1.8.2 by default
    '*': {
      'jquery': 'jquery-1.8.2'
    },
    
    // Except legacy module which needs older version
    'legacy/old-component': {
      'jquery': 'jquery-1.4.4'
    }
  },
  
  paths: {
    'jquery-1.8.2': 'lib/jquery-1.8.2.min',
    'jquery-1.4.4': 'lib/jquery-1.4.4.min'
  }
});

// Feature mapping
require.config({
  map: {
    '*': {
      'storage': 'storage/localStorage'
    },
    
    // Mobile context uses different storage
    'mobile/*': {
      'storage': 'storage/mobileStorage'
    },
    
    // Admin context has enhanced storage
    'admin/*': {
      'storage': 'storage/adminStorage'
    }
  }
});

// Library abstraction mapping
require.config({
  map: {
    '*': {
      // Abstract interface
      'http': 'http/jquery',
      'promise': 'promise/native'
    },
    
    // Legacy browsers use different implementations
    'legacy-support': {
      'http': 'http/xhr',
      'promise': 'promise/when'
    }
  }
});

/**
 * Module configuration
 */
interface ModuleConfigData {
  config: {
    [moduleName: string]: any;
  };
}

/**
 * Accessing module configuration within modules
 */
interface ModuleConfigAccess {
  /** Access via module.config() */
  moduleConfig: () => any;
  
  /** Access via require('module').config() */
  requireConfig: any;
}

// Global configuration
require.config({
  config: {
    'app/config': {
      apiUrl: 'https://api.example.com',
      version: '1.2.3',
      features: {
        advancedSearch: true,
        beta: false
      }
    },
    
    'analytics/tracker': {
      trackingId: 'UA-12345-1',
      sampleRate: 100,
      anonymizeIp: true
    },
    
    'i18n': {
      locale: 'en-US',
      fallback: 'en',
      loadPath: 'locales/{{lng}}/{{ns}}.json'
    }
  }
});

// Using configuration in modules
define(['module'], function(module) {
  var config = module.config();
  
  return {
    init: function() {
      console.log('API URL:', config.apiUrl);
      console.log('Version:', config.version);
      
      if (config.features.advancedSearch) {
        this.enableAdvancedSearch();
      }
    },
    
    enableAdvancedSearch: function() {
      // Implementation
    }
  };
});

// Environment-specific configuration
var config = {
  baseUrl: 'js',
  config: {}
};

// Set environment-specific values
if (window.location.hostname === 'localhost') {
  config.config['app/config'] = {
    apiUrl: 'http://localhost:3000/api',
    debug: true,
    logLevel: 'verbose'
  };
} else {
  config.config['app/config'] = {
    apiUrl: 'https://production-api.example.com',
    debug: false,
    logLevel: 'error'
  };
}

require.config(config);

/**
 * Context configuration
 */
interface ContextConfig extends RequireConfig {
  /** Unique context identifier */
  context: string;
}

/**
 * Context management functions
 */
interface ContextManagement {
  /** Create new context */
  requirejs.config(config: ContextConfig): RequireJS;
  
  /** Access existing context */
  requirejs.s.contexts[contextName]: Context;
  
  /** Default context */
  requirejs.s.contexts._: Context;
}

// Create application contexts
var mainApp = requirejs.config({
  context: 'main-app',
  baseUrl: 'js/main',
  paths: {
    'jquery': '../lib/jquery',
    'utils': 'app/utils'
  }
});

var adminApp = requirejs.config({
  context: 'admin-app', 
  baseUrl: 'js/admin',
  paths: {
    'jquery': '../lib/jquery',
    'utils': 'admin/utils'
  }
});

// Use different contexts
mainApp(['app'], function(app) {
  app.start();
});

adminApp(['admin'], function(admin) {
  admin.initialize();
});

// Widget isolation
function createWidget(name, config) {
  var widgetContext = requirejs.config({
    context: 'widget-' + name,
    baseUrl: 'widgets/' + name,
    config: {
      'widget/main': config
    }
  });
  
  return {
    load: function(callback) {
      widgetContext(['widget/main'], callback);
    },
    
    unload: function() {
      // Clean up context
      delete requirejs.s.contexts['widget-' + name];
    }
  };
}

// Usage
var myWidget = createWidget('calendar', {
  theme: 'blue',
  startDate: new Date()
});

myWidget.load(function(calendar) {
  calendar.render();
});

/**
 * Build-specific configuration (extends RequireConfig)
 */
interface BuildSpecificConfig {
  /** Preserve certain modules from optimization */
  stubModules?: string[];
  
  /** Wrap built modules */
  wrap?: {
    start: string;
    end: string;
  } | boolean;
  
  /** Override require.js loading */
  insertRequire?: string[];
  
  /** Name anonymous modules */
  namespace?: string;
  
  /** Include require.js in build */
  include?: string[];
  
  /** Main build file path */
  mainConfigFile?: string;
}

// Build configuration file
({
  // Runtime configuration
  baseUrl: 'src/js',
  paths: {
    'jquery': 'lib/jquery-1.8.2.min',
    'text': 'lib/text'
  },
  
  // Build-specific options
  name: 'main',
  out: 'dist/main-built.js',
  
  // Preserve text plugin from bundling
  stubModules: ['text'],
  
  // Wrap entire build
  wrap: {
    start: '(function() {',
    end: '})();'
  },
  
  // Insert require calls
  insertRequire: ['main'],
  
  // Use namespace
  namespace: 'MyApp',
  
  // Include require.js
  include: ['requireLib']
})

// Configuration type definitions
interface ConfigurationError extends Error {
  configType: "path" | "package" | "shim" | "map";
  moduleName?: string;
  configKey?: string;
}

interface ConfigValidation {
  /** Validate configuration object */
  validate(config: RequireConfig): ConfigValidation.Result;
  
  /** Merge multiple configurations */
  merge(...configs: RequireConfig[]): RequireConfig;
  
  /** Normalize paths and URLs */
  normalize(config: RequireConfig): RequireConfig;
}

namespace ConfigValidation {
  interface Result {
    valid: boolean;
    errors: ConfigurationError[];
    warnings: string[];
    normalized: RequireConfig;
  }
}

// Runtime configuration state
interface ConfigurationState {
  /** Current configuration */
  current: RequireConfig;
  
  /** Configuration history */
  history: RequireConfig[];
  
  /** Context-specific configurations */
  contexts: { [context: string]: RequireConfig };
}