path: root/SPECS/module-system/interop.js

/**
 * Module Interoperability and Compatibility Layer
 *
 * Provides seamless interoperability between different module systems:
 * - CommonJS <-> ES Modules
 * - AMD compatibility
 * - UMD pattern support
 * - Webpack-style bundling
 * - Dynamic import() polyfill
 */

/**
 * Module interoperability utilities
 */
class ModuleInterop {
  /**
   * Create interop getter for ES module default export
   * @param {Object} module - Module object
   * @returns {Object} Interoped module
   */
  static createInteropRequireDefault(module) {
    return module && module.__esModule ? module : { default: module };
  }

  /**
   * Create interop getter for wildcard imports
   * @param {Object} module - Module object
   * @returns {Object} Interoped module
   */
  static createInteropRequireWildcard(module) {
    if (module && module.__esModule) {
      return module;
    }

    const result = {};
    if (module != null) {
      for (const key of Object.getOwnPropertyNames(module)) {
        if (
          key !== "default" &&
          Object.prototype.hasOwnProperty.call(module, key)
        ) {
          this.defineProperty(result, key, {
            get: () => module[key],
            enumerable: true,
          });
        }
      }
    }

    this.defineProperty(result, "default", {
      value: module,
      enumerable: true,
    });

    return result;
  }

  /**
   * Safe property definition with fallback
   * @param {Object} obj - Target object
   * @param {string} key - Property key
   * @param {Object} descriptor - Property descriptor
   */
  static defineProperty(obj, key, descriptor) {
    try {
      Object.defineProperty(obj, key, descriptor);
    } catch (e) {
      obj[key] = descriptor.value || descriptor.get?.();
    }
  }

  /**
   * Check if module has ES module marker
   * @param {any} module - Module to check
   * @returns {boolean} True if ES module
   */
  static isESModule(module) {
    return module && module.__esModule === true;
  }

  /**
   * Get default export from module
   * @param {any} module - Module object
   * @returns {any} Default export
   */
  static getDefaultExport(module) {
    if (!module) return module;

    if (this.isESModule(module)) {
      return module.default !== undefined ? module.default : module;
    }

    return module;
  }

  /**
   * Get named export from module
   * @param {any} module - Module object
   * @param {string} name - Export name
   * @returns {any} Named export
   */
  static getNamedExport(module, name) {
    if (!module) return undefined;

    if (this.isESModule(module) || typeof module === "object") {
      return module[name];
    }

    return undefined;
  }
}

/**
 * CommonJS to ES Module converter
 */
class CommonJSToESM {
  /**
   * Convert CommonJS module to ES module format
   * @param {Function} moduleFactory - CommonJS module factory
   * @param {Object} context - Module context
   * @returns {Object} ES module exports
   */
  static convert(moduleFactory, context = {}) {
    const module = { exports: {} };
    const exports = module.exports;

    // Execute CommonJS module
    const result = moduleFactory.call(
      exports,
      exports,
      context.require || (() => {}),
      module,
      context.__filename || "",
      context.__dirname || "",
    );

    // Handle different export patterns
    let esmodule = {};

    // If exports is a function or primitive, make it the default export
    if (
      typeof module.exports === "function" ||
      typeof module.exports !== "object" ||
      module.exports === null
    ) {
      esmodule.default = module.exports;
    } else {
      // Copy all properties as named exports
      for (const key in module.exports) {
        if (Object.prototype.hasOwnProperty.call(module.exports, key)) {
          esmodule[key] = module.exports[key];
        }
      }

      // Also provide as default if no explicit default
      if (!("default" in esmodule)) {
        esmodule.default = module.exports;
      }
    }

    // Mark as ES module
    Object.defineProperty(esmodule, "__esModule", {
      value: true,
      enumerable: false,
      configurable: false,
    });

    return esmodule;
  }
}

/**
 * ES Module to CommonJS converter
 */
class ESMToCommonJS {
  /**
   * Convert ES module to CommonJS format
   * @param {Object} esModule - ES module exports
   * @returns {any} CommonJS exports
   */
  static convert(esModule) {
    if (!esModule || typeof esModule !== "object") {
      return esModule;
    }

    // If it has a default export and no other exports, return the default
    const keys = Object.keys(esModule).filter((k) => k !== "__esModule");
    if (keys.length === 1 && keys[0] === "default") {
      return esModule.default;
    }

    // Otherwise, return the module as-is (named exports)
    return esModule;
  }
}

/**
 * AMD (Asynchronous Module Definition) compatibility
 */
class AMDCompat {
  constructor() {
    this.modules = new Map();
    this.factories = new Map();
    this.loading = new Map();
  }

  /**
   * Define an AMD module
   * @param {string} id - Module ID
   * @param {Array} deps - Dependencies
   * @param {Function} factory - Module factory
   */
  define(id, deps = [], factory) {
    if (typeof id !== "string") {
      // Anonymous module
      factory = deps;
      deps = id;
      id = this.generateId();
    }

    if (typeof deps === "function") {
      // No dependencies
      factory = deps;
      deps = [];
    }

    this.factories.set(id, { deps, factory });

    // Try to resolve immediately if dependencies are available
    this.tryResolve(id);
  }

  /**
   * Require an AMD module
   * @param {Array|string} deps - Dependencies
   * @param {Function} callback - Success callback
   * @param {Function} errorCallback - Error callback
   */
  require(deps, callback, errorCallback) {
    if (typeof deps === "string") {
      deps = [deps];
    }

    this.loadDependencies(deps)
      .then((modules) => {
        if (callback) {
          callback(...modules);
        }
      })
      .catch((error) => {
        if (errorCallback) {
          errorCallback(error);
        } else {
          console.error("AMD require error:", error);
        }
      });
  }

  /**
   * Try to resolve a module if all dependencies are available
   * @param {string} id - Module ID
   */
  tryResolve(id) {
    const moduleInfo = this.factories.get(id);
    if (!moduleInfo || this.modules.has(id)) {
      return;
    }

    const { deps, factory } = moduleInfo;

    // Check if all dependencies are available
    const depModules = [];
    for (const dep of deps) {
      if (this.modules.has(dep)) {
        depModules.push(this.modules.get(dep));
      } else {
        // Not all dependencies available yet
        return;
      }
    }

    // Execute factory
    let module;
    try {
      module = factory(...depModules);
    } catch (error) {
      console.error(`Error executing AMD module ${id}:`, error);
      return;
    }

    this.modules.set(id, module);

    // Try to resolve other modules that might depend on this one
    for (const [otherId] of this.factories) {
      if (otherId !== id) {
        this.tryResolve(otherId);
      }
    }
  }

  /**
   * Load dependencies asynchronously
   * @param {Array<string>} deps - Dependency IDs
   * @returns {Promise<Array>} Promise resolving to dependency modules
   */
  async loadDependencies(deps) {
    const promises = deps.map((dep) => this.loadDependency(dep));
    return Promise.all(promises);
  }

  /**
   * Load single dependency
   * @param {string} id - Dependency ID
   * @returns {Promise} Promise resolving to module
   */
  loadDependency(id) {
    if (this.modules.has(id)) {
      return Promise.resolve(this.modules.get(id));
    }

    if (this.loading.has(id)) {
      return this.loading.get(id);
    }

    const promise = new Promise((resolve, reject) => {
      const checkInterval = setInterval(() => {
        if (this.modules.has(id)) {
          clearInterval(checkInterval);
          resolve(this.modules.get(id));
        }
      }, 10);

      // Timeout after 5 seconds
      setTimeout(() => {
        clearInterval(checkInterval);
        reject(new Error(`AMD module timeout: ${id}`));
      }, 5000);
    });

    this.loading.set(id, promise);
    return promise;
  }

  /**
   * Generate anonymous module ID
   * @returns {string} Generated ID
   */
  generateId() {
    return `anonymous_${Date.now()}_${Math.random().toString(36).substring(7)}`;
  }
}

/**
 * UMD (Universal Module Definition) pattern support
 */
class UMDPattern {
  /**
   * Create UMD wrapper for module
   * @param {Function} factory - Module factory
   * @param {string} name - Global name
   * @param {Array<string>} deps - Dependencies
   * @returns {string} UMD wrapped code
   */
  static wrap(factory, name, deps = []) {
    const factoryStr = factory.toString();
    const depsStr = JSON.stringify(deps);

    return `
      (function (root, factory) {
        if (typeof exports === 'object' && typeof module !== 'undefined') {
          // CommonJS
          module.exports = factory(${deps.map((dep) => `require('${dep}')`).join(", ")});
        } else if (typeof define === 'function' && define.amd) {
          // AMD
          define(${depsStr}, factory);
        } else {
          // Global
          root.${name} = factory(${deps.map((dep) => `root.${dep}`).join(", ")});
        }
      })(typeof globalThis !== 'undefined' ? globalThis :
         typeof window !== 'undefined' ? window :
         typeof global !== 'undefined' ? global :
         typeof self !== 'undefined' ? self : this, ${factoryStr});
    `;
  }

  /**
   * Detect UMD pattern in code
   * @param {string} code - Code to analyze
   * @returns {boolean} True if UMD pattern detected
   */
  static isUMD(code) {
    const umdPatterns = [
      /typeof exports === 'object' && typeof module !== 'undefined'/,
      /typeof define === 'function' && define\.amd/,
      /\(function \(root, factory\)/,
      /\(typeof window !== 'undefined' \? window/,
    ];

    return umdPatterns.some((pattern) => pattern.test(code));
  }
}

/**
 * Dynamic import() polyfill
 */
class DynamicImportPolyfill {
  constructor(moduleLoader) {
    this.moduleLoader = moduleLoader;
  }

  /**
   * Polyfill for dynamic import()
   * @param {string} specifier - Module specifier
   * @returns {Promise<Object>} Promise resolving to module
   */
  async import(specifier) {
    try {
      const module = await this.moduleLoader.load(specifier);

      // Ensure it looks like an ES module
      if (module && typeof module === "object" && !module.__esModule) {
        return ModuleInterop.createInteropRequireWildcard(module);
      }

      return module;
    } catch (error) {
      throw new Error(
        `Failed to import module '${specifier}': ${error.message}`,
      );
    }
  }

  /**
   * Install polyfill globally
   * @param {Object} global - Global object
   */
  install(global = globalThis) {
    if (typeof global.import !== "function") {
      global.import = this.import.bind(this);
    }
  }
}

/**
 * Webpack-style module bundling compatibility
 */
class WebpackCompat {
  /**
   * Create webpack-style require function
   * @param {Object} modules - Module map
   * @returns {Function} Require function
   */
  static createRequire(modules) {
    const installedModules = {};

    function __webpack_require__(moduleId) {
      // Check if module is in cache
      if (installedModules[moduleId]) {
        return installedModules[moduleId].exports;
      }

      // Create a new module (and put it into the cache)
      const module = (installedModules[moduleId] = {
        i: moduleId,
        l: false,
        exports: {},
      });

      // Execute the module function
      modules[moduleId].call(
        module.exports,
        module,
        module.exports,
        __webpack_require__,
      );

      // Flag the module as loaded
      module.l = true;

      // Return the exports of the module
      return module.exports;
    }

    // Expose the modules object
    __webpack_require__.m = modules;

    // Expose the module cache
    __webpack_require__.c = installedModules;

    // Define getter function for harmony exports
    __webpack_require__.d = function (exports, name, getter) {
      if (!__webpack_require__.o(exports, name)) {
        Object.defineProperty(exports, name, { enumerable: true, get: getter });
      }
    };

    // Define __esModule on exports
    __webpack_require__.r = function (exports) {
      if (typeof Symbol !== "undefined" && Symbol.toStringTag) {
        Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
      }
      Object.defineProperty(exports, "__esModule", { value: true });
    };

    // Object.prototype.hasOwnProperty.call
    __webpack_require__.o = function (object, property) {
      return Object.prototype.hasOwnProperty.call(object, property);
    };

    return __webpack_require__;
  }
}

// Create global instances
const amdCompat = new AMDCompat();

module.exports = {
  ModuleInterop,
  CommonJSToESM,
  ESMToCommonJS,
  AMDCompat,
  UMDPattern,
  DynamicImportPolyfill,
  WebpackCompat,

  // Global instances
  amdCompat,

  // Convenience functions
  interopDefault: ModuleInterop.createInteropRequireDefault,
  interopWildcard: ModuleInterop.createInteropRequireWildcard,
  isESModule: ModuleInterop.isESModule,
  getDefaultExport: ModuleInterop.getDefaultExport,
  cjsToESM: CommonJSToESM.convert,
  esmToCJS: ESMToCommonJS.convert,
  createUMD: UMDPattern.wrap,
  isUMD: UMDPattern.isUMD,
  createWebpackRequire: WebpackCompat.createRequire,
};