🌍 Ambient Modules: Declaring External Modules

🎯 Introduction

Welcome to the diplomatic embassy of TypeScript’s type system! 🌍 If TypeScript were a country with its own language and customs, then ambient modules are like diplomatic missions that allow foreign JavaScript libraries to communicate and integrate seamlessly with TypeScript’s strict type system - they provide a bridge between the loosely-typed JavaScript world and TypeScript’s type-safe environment.

Ambient modules allow you to declare types for external JavaScript libraries, Node.js modules, and any code that exists outside your TypeScript compilation but needs type information. They’re essential for working with third-party libraries, creating type definitions for npm packages, and building robust type systems that can encompass entire JavaScript ecosystems.

By the end of this tutorial, you’ll be a master diplomat of ambient modules, capable of creating comprehensive type definitions that make any JavaScript library feel like a first-class TypeScript citizen while maintaining flexibility and compatibility across different environments. Let’s master the art of ambient module diplomacy! 🌟

📚 Understanding Ambient Modules

🤔 What Are Ambient Modules?

Ambient modules are TypeScript declarations that describe the shape and structure of modules that exist at runtime but don’t have TypeScript source code. They use the declare module syntax to define types for external libraries, allowing TypeScript to understand and type-check code that uses these modules.

// 🌟 Basic ambient module declarations

// Declaring a simple external library
declare module 'simple-library' {
  export function greet(name: string): string;
  export function calculate(a: number, b: number): number;
  export const version: string;
}

// Using the declared module
import { greet, calculate, version } from 'simple-library';

const message = greet('TypeScript'); // Type: string
const result = calculate(10, 20); // Type: number
console.log(`Version: ${version}`); // Type: string

// 🎯 Declaring modules with default exports
declare module 'logger-lib' {
  interface LoggerOptions {
    level: 'debug' | 'info' | 'warn' | 'error';
    format: 'json' | 'text';
    output: 'console' | 'file';
  }
  
  interface Logger {
    debug(message: string, meta?: any): void;
    info(message: string, meta?: any): void;
    warn(message: string, meta?: any): void;
    error(message: string, error?: Error): void;
    child(context: Record<string, any>): Logger;
  }
  
  function createLogger(name: string, options?: LoggerOptions): Logger;
  
  export = createLogger; // CommonJS default export
}

// Usage with CommonJS-style import
import createLogger = require('logger-lib');

const logger = createLogger('App', {
  level: 'info',
  format: 'json',
  output: 'console'
});

logger.info('Application started');

// 🔧 Declaring modules with mixed export styles
declare module 'utility-belt' {
  // Named exports
  export function debounce<T extends (...args: any[]) => any>(
    func: T,
    wait: number,
    immediate?: boolean
  ): T;
  
  export function throttle<T extends (...args: any[]) => any>(
    func: T,
    limit: number
  ): T;
  
  export function deepClone<T>(obj: T): T;
  
  // Default export
  interface UtilityBelt {
    string: StringUtils;
    array: ArrayUtils;
    object: ObjectUtils;
    date: DateUtils;
  }
  
  interface StringUtils {
    capitalize(str: string): string;
    kebabCase(str: string): string;
    camelCase(str: string): string;
    truncate(str: string, length: number): string;
  }
  
  interface ArrayUtils {
    chunk<T>(array: T[], size: number): T[][];
    flatten<T>(array: T[][]): T[];
    unique<T>(array: T[]): T[];
    groupBy<T>(array: T[], key: keyof T): Record<string, T[]>;
  }
  
  interface ObjectUtils {
    pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
    omit<T, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
    merge<T, U>(target: T, source: U): T & U;
    isEmpty(obj: any): boolean;
  }
  
  interface DateUtils {
    format(date: Date, pattern: string): string;
    addDays(date: Date, days: number): Date;
    diffInDays(date1: Date, date2: Date): number;
    isWeekend(date: Date): boolean;
  }
  
  const utils: UtilityBelt;
  export default utils;
}

// Usage with mixed imports
import utils, { debounce, throttle, deepClone } from 'utility-belt';

// Use default export
const formattedDate = utils.date.format(new Date(), 'YYYY-MM-DD');
const chunks = utils.array.chunk([1, 2, 3, 4, 5], 2);

// Use named exports
const debouncedHandler = debounce(() => console.log('Debounced'), 300);
const clonedObject = deepClone({ a: 1, b: 2 });

// ✨ Declaring modules with complex types
declare module 'advanced-http-client' {
  interface RequestConfig {
    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
    url: string;
    headers?: Record<string, string>;
    params?: Record<string, any>;
    data?: any;
    timeout?: number;
    retries?: number;
    validateStatus?: (status: number) => boolean;
  }
  
  interface ResponseData<T = any> {
    data: T;
    status: number;
    statusText: string;
    headers: Record<string, string>;
    config: RequestConfig;
  }
  
  interface UploadConfig extends RequestConfig {
    onUploadProgress?: (progressEvent: ProgressEvent) => void;
    maxBodyLength?: number;
    maxContentLength?: number;
  }
  
  interface DownloadConfig extends RequestConfig {
    onDownloadProgress?: (progressEvent: ProgressEvent) => void;
    responseType?: 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream';
  }
  
  interface InterceptorManager<V> {
    use(onFulfilled?: (value: V) => V | Promise<V>, onRejected?: (error: any) => any): number;
    eject(id: number): void;
  }
  
  interface HttpClient {
    request<T = any>(config: RequestConfig): Promise<ResponseData<T>>;
    get<T = any>(url: string, config?: RequestConfig): Promise<ResponseData<T>>;
    post<T = any>(url: string, data?: any, config?: RequestConfig): Promise<ResponseData<T>>;
    put<T = any>(url: string, data?: any, config?: RequestConfig): Promise<ResponseData<T>>;
    delete<T = any>(url: string, config?: RequestConfig): Promise<ResponseData<T>>;
    
    upload<T = any>(url: string, data: FormData, config?: UploadConfig): Promise<ResponseData<T>>;
    download(url: string, config?: DownloadConfig): Promise<ResponseData<ArrayBuffer>>;
    
    interceptors: {
      request: InterceptorManager<RequestConfig>;
      response: InterceptorManager<ResponseData>;
    };
  }
  
  interface ClientFactory {
    create(baseConfig?: RequestConfig): HttpClient;
    defaults: RequestConfig;
  }
  
  const client: HttpClient;
  const factory: ClientFactory;
  
  export { RequestConfig, ResponseData, UploadConfig, DownloadConfig, HttpClient };
  export { client as default, factory };
}

// Advanced usage
import httpClient, { factory, RequestConfig, ResponseData } from 'advanced-http-client';

// Configure default client
httpClient.interceptors.request.use((config) => {
  config.headers = { ...config.headers, 'Authorization': 'Bearer token' };
  return config;
});

// Create custom client
const apiClient = factory.create({
  url: 'https://api.example.com',
  timeout: 30000,
  headers: { 'Content-Type': 'application/json' }
});

interface User {
  id: string;
  name: string;
  email: string;
}

const fetchUser = async (id: string): Promise<User> => {
  const response = await apiClient.get<User>(`/users/${id}`);
  return response.data;
};

🏗️ Advanced Ambient Module Patterns

// 🚀 Conditional module declarations based on environment

// Node.js specific modules
declare module 'node-specific-lib' {
  import { EventEmitter } from 'events';
  import { Readable, Writable } from 'stream';
  
  interface FileSystemWatcher extends EventEmitter {
    close(): void;
    add(path: string): void;
    remove(path: string): void;
  }
  
  interface WatchOptions {
    persistent?: boolean;
    recursive?: boolean;
    encoding?: BufferEncoding;
  }
  
  interface ProcessManager {
    spawn(command: string, args: string[], options?: SpawnOptions): ChildProcess;
    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
    kill(pid: number, signal?: string): boolean;
    list(): ProcessInfo[];
  }
  
  interface SpawnOptions {
    cwd?: string;
    env?: Record<string, string>;
    stdio?: 'pipe' | 'ignore' | 'inherit';
    shell?: boolean;
    timeout?: number;
  }
  
  interface ExecOptions extends SpawnOptions {
    maxBuffer?: number;
  }
  
  interface ExecResult {
    stdout: string;
    stderr: string;
    code: number;
  }
  
  interface ChildProcess extends EventEmitter {
    pid?: number;
    stdin: Writable;
    stdout: Readable;
    stderr: Readable;
    kill(signal?: string): boolean;
  }
  
  interface ProcessInfo {
    pid: number;
    name: string;
    cpu: number;
    memory: number;
    startTime: Date;
  }
  
  export function watch(path: string, options?: WatchOptions): FileSystemWatcher;
  export const processes: ProcessManager;
  export function isNode(): true;
}

// Browser specific modules
declare module 'browser-specific-lib' {
  interface BrowserInfo {
    name: string;
    version: string;
    engine: string;
    os: string;
  }
  
  interface GeolocationService {
    getCurrentPosition(options?: PositionOptions): Promise<GeolocationPosition>;
    watchPosition(
      callback: (position: GeolocationPosition) => void,
      errorCallback?: (error: GeolocationPositionError) => void,
      options?: PositionOptions
    ): number;
    clearWatch(watchId: number): void;
  }
  
  interface StorageManager {
    local: Storage;
    session: Storage;
    cookie: CookieManager;
  }
  
  interface CookieManager {
    get(name: string): string | null;
    set(name: string, value: string, options?: CookieOptions): void;
    remove(name: string): void;
    clear(): void;
  }
  
  interface CookieOptions {
    expires?: Date;
    maxAge?: number;
    domain?: string;
    path?: string;
    secure?: boolean;
    httpOnly?: boolean;
    sameSite?: 'strict' | 'lax' | 'none';
  }
  
  interface NotificationService {
    request(): Promise<NotificationPermission>;
    show(title: string, options?: NotificationOptions): Notification;
    isSupported(): boolean;
  }
  
  export function getBrowserInfo(): BrowserInfo;
  export const geolocation: GeolocationService;
  export const storage: StorageManager;
  export const notifications: NotificationService;
  export function isBrowser(): true;
}

// Universal modules (work in both environments)
declare module 'universal-lib' {
  interface NetworkAdapter {
    fetch(url: string, options?: RequestInit): Promise<Response>;
    isOnline(): boolean;
    getConnectionType(): ConnectionType;
  }
  
  type ConnectionType = 'ethernet' | 'wifi' | 'cellular' | 'bluetooth' | 'unknown';
  
  interface CryptoAdapter {
    randomBytes(size: number): Uint8Array;
    hash(algorithm: string, data: string | Uint8Array): Promise<string>;
    encrypt(data: string, key: string, algorithm?: string): Promise<string>;
    decrypt(data: string, key: string, algorithm?: string): Promise<string>;
  }
  
  interface EventBus {
    on<T = any>(event: string, handler: (data: T) => void): () => void;
    off(event: string, handler: Function): void;
    emit<T = any>(event: string, data?: T): void;
    once<T = any>(event: string, handler: (data: T) => void): () => void;
    clear(event?: string): void;
  }
  
  interface TaskScheduler {
    schedule(task: () => void | Promise<void>, delay: number): TaskHandle;
    scheduleRepeating(task: () => void | Promise<void>, interval: number): TaskHandle;
    immediate(task: () => void | Promise<void>): TaskHandle;
    cancel(handle: TaskHandle): boolean;
    cancelAll(): void;
  }
  
  interface TaskHandle {
    id: string;
    cancel(): boolean;
    isPending(): boolean;
  }
  
  export const network: NetworkAdapter;
  export const crypto: CryptoAdapter;
  export function createEventBus(): EventBus;
  export const scheduler: TaskScheduler;
}

// 🔧 Wildcard module declarations
declare module '*.json' {
  const content: any;
  export default content;
}

declare module '*.css' {
  const classes: { [key: string]: string };
  export default classes;
}

declare module '*.scss' {
  const classes: { [key: string]: string };
  export default classes;
}

declare module '*.svg' {
  const content: string;
  export default content;
}

declare module '*.png' {
  const src: string;
  export default src;
}

declare module '*.jpg' {
  const src: string;
  export default src;
}

// Usage of wildcard declarations
import config from './config.json'; // Type: any
import styles from './component.css'; // Type: { [key: string]: string }
import logo from './logo.svg'; // Type: string
import image from './hero.png'; // Type: string

// 🎨 Plugin-based module declarations
declare module 'plugin-system' {
  interface Plugin<TOptions = any> {
    name: string;
    version: string;
    install(app: Application, options?: TOptions): void | Promise<void>;
    uninstall?(app: Application): void | Promise<void>;
  }
  
  interface PluginManager {
    register<T = any>(plugin: Plugin<T>, options?: T): Promise<void>;
    unregister(pluginName: string): Promise<void>;
    get(pluginName: string): Plugin | undefined;
    list(): Plugin[];
    isRegistered(pluginName: string): boolean;
  }
  
  interface Application {
    plugins: PluginManager;
    use<T = any>(plugin: Plugin<T>, options?: T): Promise<Application>;
    boot(): Promise<void>;
    shutdown(): Promise<void>;
  }
  
  interface MiddlewareContext {
    request: any;
    response: any;
    next(): Promise<void>;
  }
  
  type Middleware = (context: MiddlewareContext) => void | Promise<void>;
  
  interface RouterPlugin extends Plugin {
    get(path: string, ...middleware: Middleware[]): void;
    post(path: string, ...middleware: Middleware[]): void;
    put(path: string, ...middleware: Middleware[]): void;
    delete(path: string, ...middleware: Middleware[]): void;
    use(path: string, ...middleware: Middleware[]): void;
  }
  
  interface DatabasePlugin extends Plugin {
    connect(): Promise<void>;
    disconnect(): Promise<void>;
    query<T = any>(sql: string, params?: any[]): Promise<T[]>;
    transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
  }
  
  interface Transaction {
    query<T = any>(sql: string, params?: any[]): Promise<T[]>;
    commit(): Promise<void>;
    rollback(): Promise<void>;
  }
  
  export function createApp(): Application;
  export { Plugin, PluginManager, Application, Middleware, RouterPlugin, DatabasePlugin };
}

// Plugin usage
import { createApp, Plugin, RouterPlugin, DatabasePlugin } from 'plugin-system';

const routerPlugin: RouterPlugin = {
  name: 'router',
  version: '1.0.0',
  install(app) {
    // Router installation logic
  },
  get(path, ...middleware) {
    // GET route handler
  },
  post(path, ...middleware) {
    // POST route handler
  },
  put(path, ...middleware) {
    // PUT route handler
  },
  delete(path, ...middleware) {
    // DELETE route handler
  },
  use(path, ...middleware) {
    // Middleware registration
  }
};

const dbPlugin: DatabasePlugin = {
  name: 'database',
  version: '2.0.0',
  install(app) {
    // Database installation logic
  },
  async connect() {
    // Connection logic
  },
  async disconnect() {
    // Disconnection logic
  },
  async query<T>(sql: string, params?: any[]): Promise<T[]> {
    // Query implementation
    return [];
  },
  async transaction<T>(callback: (tx: any) => Promise<T>): Promise<T> {
    // Transaction implementation
    return callback({});
  }
};

const app = createApp();
await app.use(routerPlugin);
await app.use(dbPlugin, { connectionString: 'postgresql://...' });
await app.boot();

🛠️ Building an Ambient Module Management System

Let’s create a comprehensive system for managing ambient module declarations:

// 🏗️ Ambient Module Declaration Management System

namespace AmbientModules {
  
  // 📋 Core interfaces for ambient module management
  export interface ModuleRegistry {
    modules: Map<string, ModuleDeclaration>;
    patterns: Map<string, PatternDeclaration>;
    dependencies: Map<string, ModuleDependency[]>;
    versions: Map<string, VersionInfo>;
    metadata: RegistryMetadata;
  }
  
  export interface ModuleDeclaration {
    name: string;
    version: string;
    description: string;
    exports: ExportDeclaration[];
    defaultExport?: DefaultExportDeclaration;
    dependencies: string[];
    peerDependencies: string[];
    environments: Environment[];
    license: string;
    author: string;
    repository?: string;
    tags: string[];
    deprecated?: DeprecationInfo;
    createdAt: Date;
    updatedAt: Date;
  }
  
  export interface ExportDeclaration {
    name: string;
    type: ExportType;
    signature: string;
    description: string;
    examples: string[];
    since?: string;
    deprecated?: DeprecationInfo;
  }
  
  export type ExportType = 
    | 'function' 
    | 'class' 
    | 'interface' 
    | 'type' 
    | 'constant' 
    | 'variable' 
    | 'namespace';
  
  export interface DefaultExportDeclaration {
    type: 'function' | 'class' | 'object' | 'value';
    signature: string;
    description: string;
    examples: string[];
  }
  
  export interface PatternDeclaration {
    pattern: string;
    description: string;
    exampleFiles: string[];
    exportType: string;
    commonUsage: string[];
    relatedPatterns: string[];
  }
  
  export interface ModuleDependency {
    name: string;
    version: string;
    type: 'runtime' | 'peer' | 'dev';
    optional: boolean;
  }
  
  export interface VersionInfo {
    current: string;
    available: string[];
    changelog: ChangelogEntry[];
    compatibility: CompatibilityInfo;
  }
  
  export interface ChangelogEntry {
    version: string;
    date: Date;
    changes: Change[];
  }
  
  export interface Change {
    type: 'added' | 'changed' | 'deprecated' | 'removed' | 'fixed' | 'security';
    description: string;
    breaking: boolean;
    migration?: string;
  }
  
  export interface CompatibilityInfo {
    typescript: string[];
    node: string[];
    browsers: BrowserSupport[];
  }
  
  export interface BrowserSupport {
    name: string;
    version: string;
    supported: boolean;
    notes?: string;
  }
  
  export type Environment = 'node' | 'browser' | 'web-worker' | 'electron' | 'react-native';
  
  export interface DeprecationInfo {
    since: string;
    reason: string;
    replacement?: string;
    removalVersion?: string;
  }
  
  export interface RegistryMetadata {
    totalModules: number;
    totalPatterns: number;
    lastUpdated: Date;
    version: string;
    maintainers: string[];
  }
  
  // 🔧 Module Declaration Generator
  export class DeclarationGenerator {
    private registry: ModuleRegistry;
    private analyzer: ModuleAnalyzer;
    private validator: DeclarationValidator;
    
    constructor() {
      this.registry = this.initializeRegistry();
      this.analyzer = new ModuleAnalyzer();
      this.validator = new DeclarationValidator();
    }
    
    // 📝 Generate ambient module declaration
    generateDeclaration(moduleInfo: ModuleInfo): GenerationResult {
      console.log(`📝 Generating ambient declaration for: ${moduleInfo.name}`);
      
      try {
        // Analyze the module
        const analysis = this.analyzer.analyzeModule(moduleInfo);
        
        // Validate the analysis
        const validation = this.validator.validate(analysis);
        if (!validation.isValid) {
          return {
            success: false,
            errors: validation.errors,
            warnings: validation.warnings
          };
        }
        
        // Generate the declaration
        const declaration = this.createDeclaration(analysis);
        
        // Generate TypeScript code
        const declarationCode = this.generateTypeScriptCode(declaration);
        
        // Register the module
        this.registry.modules.set(moduleInfo.name, declaration);
        
        return {
          success: true,
          declaration,
          code: declarationCode,
          warnings: validation.warnings
        };
        
      } catch (error) {
        return {
          success: false,
          errors: [`Generation failed: ${error.message}`]
        };
      }
    }
    
    // 🔍 Analyze existing module
    analyzeExistingModule(moduleName: string): AnalysisResult {
      console.log(`🔍 Analyzing existing module: ${moduleName}`);
      
      const module = this.registry.modules.get(moduleName);
      if (!module) {
        return {
          found: false,
          error: `Module ${moduleName} not found in registry`
        };
      }
      
      const dependencies = this.analyzeDependencies(module);
      const usage = this.analyzeUsagePatterns(module);
      const compatibility = this.analyzeCompatibility(module);
      
      return {
        found: true,
        module,
        dependencies,
        usage,
        compatibility,
        suggestions: this.generateSuggestions(module, dependencies, usage)
      };
    }
    
    // 🎯 Generate wildcard pattern declaration
    generatePatternDeclaration(pattern: PatternInfo): PatternResult {
      console.log(`🎯 Generating pattern declaration for: ${pattern.pattern}`);
      
      const patternDeclaration: PatternDeclaration = {
        pattern: pattern.pattern,
        description: pattern.description,
        exampleFiles: pattern.exampleFiles,
        exportType: pattern.exportType,
        commonUsage: pattern.commonUsage,
        relatedPatterns: []
      };
      
      const code = this.generatePatternCode(patternDeclaration);
      
      this.registry.patterns.set(pattern.pattern, patternDeclaration);
      
      return {
        success: true,
        declaration: patternDeclaration,
        code
      };
    }
    
    // 🔄 Update module declaration
    updateDeclaration(moduleName: string, updates: Partial<ModuleDeclaration>): UpdateResult {
      console.log(`🔄 Updating declaration for: ${moduleName}`);
      
      const existing = this.registry.modules.get(moduleName);
      if (!existing) {
        return {
          success: false,
          error: `Module ${moduleName} not found`
        };
      }
      
      const updated = { ...existing, ...updates, updatedAt: new Date() };
      
      // Validate the update
      const validation = this.validator.validateUpdate(existing, updated);
      if (!validation.isValid) {
        return {
          success: false,
          error: 'Update validation failed',
          details: validation.errors
        };
      }
      
      this.registry.modules.set(moduleName, updated);
      
      return {
        success: true,
        declaration: updated,
        changes: this.detectChanges(existing, updated)
      };
    }
    
    // 📊 Generate comprehensive report
    generateRegistryReport(): RegistryReport {
      console.log('📊 Generating comprehensive registry report');
      
      const modules = Array.from(this.registry.modules.values());
      const patterns = Array.from(this.registry.patterns.values());
      
      return {
        summary: {
          totalModules: modules.length,
          totalPatterns: patterns.length,
          totalExports: modules.reduce((sum, m) => sum + m.exports.length, 0),
          environmentSupport: this.calculateEnvironmentSupport(modules),
          lastUpdated: this.registry.metadata.lastUpdated
        },
        popularModules: this.findPopularModules(modules),
        deprecatedModules: modules.filter(m => m.deprecated),
        outdatedModules: this.findOutdatedModules(modules),
        dependencyGraph: this.buildDependencyGraph(modules),
        recommendedUpdates: this.generateUpdateRecommendations(modules),
        qualityMetrics: this.calculateQualityMetrics(modules),
        generatedAt: new Date()
      };
    }
    
    // 🔧 Private helper methods
    private initializeRegistry(): ModuleRegistry {
      return {
        modules: new Map(),
        patterns: new Map(),
        dependencies: new Map(),
        versions: new Map(),
        metadata: {
          totalModules: 0,
          totalPatterns: 0,
          lastUpdated: new Date(),
          version: '1.0.0',
          maintainers: ['System']
        }
      };
    }
    
    private createDeclaration(analysis: ModuleAnalysis): ModuleDeclaration {
      return {
        name: analysis.name,
        version: analysis.version,
        description: analysis.description,
        exports: analysis.exports.map(exp => ({
          name: exp.name,
          type: exp.type,
          signature: exp.signature,
          description: exp.description || '',
          examples: exp.examples || [],
          since: analysis.version
        })),
        defaultExport: analysis.defaultExport ? {
          type: analysis.defaultExport.type,
          signature: analysis.defaultExport.signature,
          description: analysis.defaultExport.description || '',
          examples: analysis.defaultExport.examples || []
        } : undefined,
        dependencies: analysis.dependencies,
        peerDependencies: analysis.peerDependencies,
        environments: analysis.environments,
        license: analysis.license || 'Unknown',
        author: analysis.author || 'Unknown',
        repository: analysis.repository,
        tags: analysis.tags || [],
        createdAt: new Date(),
        updatedAt: new Date()
      };
    }
    
    private generateTypeScriptCode(declaration: ModuleDeclaration): string {
      const lines: string[] = [];
      
      lines.push(`// Type definitions for ${declaration.name} ${declaration.version}`);
      lines.push(`// Project: ${declaration.repository || 'Unknown'}`);
      lines.push(`// Definitions by: ${declaration.author}`);
      lines.push('');
      
      lines.push(`declare module '${declaration.name}' {`);
      
      // Generate interfaces for complex types
      const interfaces = this.extractInterfaces(declaration);
      for (const iface of interfaces) {
        lines.push(`  ${iface}`);
      }
      
      // Generate exports
      for (const exp of declaration.exports) {
        lines.push(`  ${this.generateExportCode(exp)}`);
      }
      
      // Generate default export
      if (declaration.defaultExport) {
        lines.push(`  ${this.generateDefaultExportCode(declaration.defaultExport)}`);
      }
      
      lines.push('}');
      
      return lines.join('\n');
    }
    
    private generatePatternCode(pattern: PatternDeclaration): string {
      return `declare module '${pattern.pattern}' {\n  ${pattern.exportType}\n}`;
    }
    
    private generateExportCode(exp: ExportDeclaration): string {
      switch (exp.type) {
        case 'function':
          return `export ${exp.signature};`;
        case 'class':
          return `export ${exp.signature};`;
        case 'interface':
          return `export ${exp.signature};`;
        case 'type':
          return `export ${exp.signature};`;
        case 'constant':
        case 'variable':
          return `export ${exp.signature};`;
        case 'namespace':
          return `export namespace ${exp.name} { ${exp.signature} }`;
        default:
          return `export ${exp.signature};`;
      }
    }
    
    private generateDefaultExportCode(defaultExp: DefaultExportDeclaration): string {
      switch (defaultExp.type) {
        case 'function':
          return `export = ${defaultExp.signature};`;
        case 'class':
          return `export = ${defaultExp.signature};`;
        case 'object':
          return `declare const _default: ${defaultExp.signature}; export = _default;`;
        case 'value':
          return `declare const _default: ${defaultExp.signature}; export = _default;`;
        default:
          return `export = ${defaultExp.signature};`;
      }
    }
    
    private extractInterfaces(declaration: ModuleDeclaration): string[] {
      // Extract interface definitions from signatures
      const interfaces: string[] = [];
      
      for (const exp of declaration.exports) {
        if (exp.type === 'interface') {
          interfaces.push(`interface ${exp.name} ${exp.signature}`);
        }
      }
      
      return interfaces;
    }
    
    private analyzeDependencies(module: ModuleDeclaration): DependencyAnalysis {
      return {
        direct: module.dependencies,
        peer: module.peerDependencies,
        circular: [],
        outdated: [],
        security: []
      };
    }
    
    private analyzeUsagePatterns(module: ModuleDeclaration): UsageAnalysis {
      return {
        mostUsedExports: [],
        commonPatterns: [],
        antiPatterns: [],
        performanceImpact: 'low'
      };
    }
    
    private analyzeCompatibility(module: ModuleDeclaration): CompatibilityAnalysis {
      return {
        typescript: [],
        environments: module.environments,
        breakingChanges: [],
        migrationPaths: []
      };
    }
    
    private generateSuggestions(
      module: ModuleDeclaration,
      dependencies: DependencyAnalysis,
      usage: UsageAnalysis
    ): string[] {
      const suggestions: string[] = [];
      
      if (module.deprecated) {
        suggestions.push(`Consider migrating to ${module.deprecated.replacement || 'an alternative'}`);
      }
      
      if (dependencies.outdated.length > 0) {
        suggestions.push('Update outdated dependencies');
      }
      
      if (module.exports.length > 20) {
        suggestions.push('Consider splitting large module into smaller modules');
      }
      
      return suggestions;
    }
    
    private detectChanges(old: ModuleDeclaration, updated: ModuleDeclaration): Change[] {
      const changes: Change[] = [];
      
      // Detect export changes
      const oldExports = new Set(old.exports.map(e => e.name));
      const newExports = new Set(updated.exports.map(e => e.name));
      
      for (const exp of updated.exports) {
        if (!oldExports.has(exp.name)) {
          changes.push({
            type: 'added',
            description: `Added export: ${exp.name}`,
            breaking: false
          });
        }
      }
      
      for (const exp of old.exports) {
        if (!newExports.has(exp.name)) {
          changes.push({
            type: 'removed',
            description: `Removed export: ${exp.name}`,
            breaking: true
          });
        }
      }
      
      return changes;
    }
    
    private calculateEnvironmentSupport(modules: ModuleDeclaration[]): Record<Environment, number> {
      const support: Record<Environment, number> = {
        'node': 0,
        'browser': 0,
        'web-worker': 0,
        'electron': 0,
        'react-native': 0
      };
      
      for (const module of modules) {
        for (const env of module.environments) {
          support[env]++;
        }
      }
      
      return support;
    }
    
    private findPopularModules(modules: ModuleDeclaration[]): ModuleDeclaration[] {
      // Sort by some popularity metric (e.g., number of exports, tags, etc.)
      return modules.slice(0, 10);
    }
    
    private findOutdatedModules(modules: ModuleDeclaration[]): ModuleDeclaration[] {
      const now = new Date();
      const threeMonthsAgo = new Date(now.getTime() - 90 * 24 * 60 * 60 * 1000);
      
      return modules.filter(m => m.updatedAt < threeMonthsAgo);
    }
    
    private buildDependencyGraph(modules: ModuleDeclaration[]): DependencyGraph {
      return {
        nodes: modules.map(m => ({ id: m.name, label: m.name })),
        edges: modules.flatMap(m => 
          m.dependencies.map(dep => ({ from: m.name, to: dep }))
        )
      };
    }
    
    private generateUpdateRecommendations(modules: ModuleDeclaration[]): UpdateRecommendation[] {
      return modules.map(module => ({
        moduleName: module.name,
        currentVersion: module.version,
        recommendedVersion: 'latest',
        priority: 'medium',
        reason: 'Regular maintenance update'
      }));
    }
    
    private calculateQualityMetrics(modules: ModuleDeclaration[]): QualityMetrics {
      const totalModules = modules.length;
      const documented = modules.filter(m => m.description && m.description.length > 10).length;
      const withExamples = modules.filter(m => 
        m.exports.some(e => e.examples && e.examples.length > 0)
      ).length;
      
      return {
        documentationCoverage: totalModules > 0 ? documented / totalModules : 0,
        exampleCoverage: totalModules > 0 ? withExamples / totalModules : 0,
        averageExports: totalModules > 0 ? 
          modules.reduce((sum, m) => sum + m.exports.length, 0) / totalModules : 0,
        deprecationRate: totalModules > 0 ? 
          modules.filter(m => m.deprecated).length / totalModules : 0
      };
    }
  }
  
  // 🔍 Supporting classes and interfaces
  class ModuleAnalyzer {
    analyzeModule(moduleInfo: ModuleInfo): ModuleAnalysis {
      // Analyze module structure, exports, dependencies, etc.
      return {
        name: moduleInfo.name,
        version: moduleInfo.version || '1.0.0',
        description: moduleInfo.description || '',
        exports: this.extractExports(moduleInfo),
        defaultExport: this.extractDefaultExport(moduleInfo),
        dependencies: moduleInfo.dependencies || [],
        peerDependencies: moduleInfo.peerDependencies || [],
        environments: this.detectEnvironments(moduleInfo),
        license: moduleInfo.license,
        author: moduleInfo.author,
        repository: moduleInfo.repository,
        tags: moduleInfo.tags
      };
    }
    
    private extractExports(moduleInfo: ModuleInfo): ExportInfo[] {
      // Extract export information from module
      return moduleInfo.exports || [];
    }
    
    private extractDefaultExport(moduleInfo: ModuleInfo): DefaultExportInfo | undefined {
      return moduleInfo.defaultExport;
    }
    
    private detectEnvironments(moduleInfo: ModuleInfo): Environment[] {
      // Detect supported environments based on module characteristics
      return moduleInfo.environments || ['node', 'browser'];
    }
  }
  
  class DeclarationValidator {
    validate(analysis: ModuleAnalysis): ValidationResult {
      const errors: string[] = [];
      const warnings: string[] = [];
      
      // Validate module name
      if (!analysis.name || analysis.name.trim() === '') {
        errors.push('Module name cannot be empty');
      }
      
      // Validate exports
      if (!analysis.exports || analysis.exports.length === 0) {
        warnings.push('Module has no exports');
      }
      
      // Validate export signatures
      for (const exp of analysis.exports) {
        if (!exp.signature || exp.signature.trim() === '') {
          errors.push(`Export ${exp.name} has no signature`);
        }
      }
      
      return {
        isValid: errors.length === 0,
        errors,
        warnings
      };
    }
    
    validateUpdate(existing: ModuleDeclaration, updated: ModuleDeclaration): ValidationResult {
      const errors: string[] = [];
      const warnings: string[] = [];
      
      // Check for breaking changes
      const removedExports = existing.exports.filter(oldExp => 
        !updated.exports.find(newExp => newExp.name === oldExp.name)
      );
      
      if (removedExports.length > 0) {
        warnings.push(`Removed exports: ${removedExports.map(e => e.name).join(', ')}`);
      }
      
      return {
        isValid: errors.length === 0,
        errors,
        warnings
      };
    }
  }
  
  // 📊 Supporting interfaces
  interface ModuleInfo {
    name: string;
    version?: string;
    description?: string;
    exports?: ExportInfo[];
    defaultExport?: DefaultExportInfo;
    dependencies?: string[];
    peerDependencies?: string[];
    environments?: Environment[];
    license?: string;
    author?: string;
    repository?: string;
    tags?: string[];
  }
  
  interface ExportInfo {
    name: string;
    type: ExportType;
    signature: string;
    description?: string;
    examples?: string[];
  }
  
  interface DefaultExportInfo {
    type: 'function' | 'class' | 'object' | 'value';
    signature: string;
    description?: string;
    examples?: string[];
  }
  
  interface ModuleAnalysis {
    name: string;
    version: string;
    description: string;
    exports: ExportInfo[];
    defaultExport?: DefaultExportInfo;
    dependencies: string[];
    peerDependencies: string[];
    environments: Environment[];
    license?: string;
    author?: string;
    repository?: string;
    tags?: string[];
  }
  
  interface ValidationResult {
    isValid: boolean;
    errors: string[];
    warnings: string[];
  }
  
  interface GenerationResult {
    success: boolean;
    declaration?: ModuleDeclaration;
    code?: string;
    errors?: string[];
    warnings?: string[];
  }
  
  interface AnalysisResult {
    found: boolean;
    module?: ModuleDeclaration;
    dependencies?: DependencyAnalysis;
    usage?: UsageAnalysis;
    compatibility?: CompatibilityAnalysis;
    suggestions?: string[];
    error?: string;
  }
  
  interface PatternInfo {
    pattern: string;
    description: string;
    exampleFiles: string[];
    exportType: string;
    commonUsage: string[];
  }
  
  interface PatternResult {
    success: boolean;
    declaration?: PatternDeclaration;
    code?: string;
    error?: string;
  }
  
  interface UpdateResult {
    success: boolean;
    declaration?: ModuleDeclaration;
    changes?: Change[];
    error?: string;
    details?: string[];
  }
  
  interface RegistryReport {
    summary: RegistrySummary;
    popularModules: ModuleDeclaration[];
    deprecatedModules: ModuleDeclaration[];
    outdatedModules: ModuleDeclaration[];
    dependencyGraph: DependencyGraph;
    recommendedUpdates: UpdateRecommendation[];
    qualityMetrics: QualityMetrics;
    generatedAt: Date;
  }
  
  interface RegistrySummary {
    totalModules: number;
    totalPatterns: number;
    totalExports: number;
    environmentSupport: Record<Environment, number>;
    lastUpdated: Date;
  }
  
  interface DependencyAnalysis {
    direct: string[];
    peer: string[];
    circular: string[];
    outdated: string[];
    security: string[];
  }
  
  interface UsageAnalysis {
    mostUsedExports: string[];
    commonPatterns: string[];
    antiPatterns: string[];
    performanceImpact: 'low' | 'medium' | 'high';
  }
  
  interface CompatibilityAnalysis {
    typescript: string[];
    environments: Environment[];
    breakingChanges: string[];
    migrationPaths: string[];
  }
  
  interface DependencyGraph {
    nodes: Array<{ id: string; label: string }>;
    edges: Array<{ from: string; to: string }>;
  }
  
  interface UpdateRecommendation {
    moduleName: string;
    currentVersion: string;
    recommendedVersion: string;
    priority: 'low' | 'medium' | 'high';
    reason: string;
  }
  
  interface QualityMetrics {
    documentationCoverage: number;
    exampleCoverage: number;
    averageExports: number;
    deprecationRate: number;
  }
}

// 🚀 Usage examples with the management system
const declarationGenerator = new AmbientModules.DeclarationGenerator();

// Generate declaration for a new module
const moduleInfo: AmbientModules.ModuleInfo = {
  name: 'awesome-utility',
  version: '2.1.0',
  description: 'An awesome utility library with many helpful functions',
  exports: [
    {
      name: 'debounce',
      type: 'function',
      signature: 'function debounce<T extends (...args: any[]) => any>(func: T, wait: number): T',
      description: 'Creates a debounced function that delays invoking func',
      examples: ['const debouncedFn = debounce(myFunction, 300);']
    },
    {
      name: 'throttle',
      type: 'function',
      signature: 'function throttle<T extends (...args: any[]) => any>(func: T, limit: number): T',
      description: 'Creates a throttled function that only invokes func at most once per every limit milliseconds',
      examples: ['const throttledFn = throttle(myFunction, 1000);']
    }
  ],
  environments: ['node', 'browser'],
  license: 'MIT',
  author: 'Utility Team'
};

const result = declarationGenerator.generateDeclaration(moduleInfo);
if (result.success) {
  console.log('Generated declaration:');
  console.log(result.code);
} else {
  console.error('Generation failed:', result.errors);
}

// Generate pattern declaration
const patternInfo: AmbientModules.PatternInfo = {
  pattern: '*.worker.ts',
  description: 'Web Worker TypeScript files',
  exampleFiles: ['main.worker.ts', 'data.worker.ts'],
  exportType: 'const content: string; export default content;',
  commonUsage: ['Web Workers', 'Background processing']
};

const patternResult = declarationGenerator.generatePatternDeclaration(patternInfo);
console.log('Pattern declaration:', patternResult.code);

// Generate comprehensive report
const report = declarationGenerator.generateRegistryReport();
console.log('Registry report:', report);