向模块注入配置的最优方案：兼顾编辑器智能提示

你的需求很明确：让something.js模块接收外部传入的配置、自身不主动加载配置，同时要让编辑器能正确识别模块类型，提供代码补全和分析能力。你原来的写法确实会让编辑器困惑——因为模块导出的类型在第一次调用后发生了突变：从初始化函数变成了Something实例，下面提供两种简洁且编辑器友好的实现方式：

方案一：带JSDoc类型标注的单例模式 #

这种方式通过明确的类型注释告诉编辑器模块的最终导出类型，同时保持单例逻辑的简洁性：

/**
 * @typedef {Object} SomethingOptions
 * @property {string} apiUrl - 接口地址配置
 * @property {number} timeout - 请求超时配置
 */

class Something {
  /**
   * @param {SomethingOptions} options
   */
  constructor(options) {
    this.config = options;
  }

  fetchData() {
    console.log(`请求地址：${this.config.apiUrl}，超时时间：${this.config.timeout}`);
  }
}

// 存储单例实例
let instance = null;

/**
 * @param {SomethingOptions} [options]
 * @returns {Something}
 */
module.exports = function(options) {
  // 已初始化直接返回实例
  if (instance) return instance;
  // 首次调用必须传配置
  if (!options) throw new Error('首次调用必须传入配置参数');
  
  instance = new Something(options);
  // 替换导出，后续直接返回实例
  module.exports = instance;
  return instance;
};

使用示例 #

// 第一次调用传入配置
const something1 = require('./something')({ apiUrl: 'https://example.com', timeout: 5000 });
something1.fetchData(); // 编辑器能自动提示fetchData方法和config属性

// 后续调用直接返回已初始化的实例
const something2 = require('./something');
console.log(something1 === something2); // true

这种写法的优势：

• JSDoc注释清晰定义了导出函数的参数和返回值类型，编辑器能精准识别第一次调用后返回的Something实例
• 后续替换导出为实例的逻辑不影响编辑器的类型分析，因为注释已经明确了最终导出类型
• 逻辑直观，不会出现类型来回切换导致的编辑器混乱

方案二：分离初始化与实例获取逻辑 #

如果觉得单例替换导出的写法还是不够直观，可以把初始化和实例获取拆分为两个独立方法，完全适配编辑器的类型识别习惯：

/**
 * @typedef {Object} SomethingOptions
 * @property {string} apiUrl - 接口地址配置
 * @property {number} timeout - 请求超时配置
 */

class Something {
  /**
   * @param {SomethingOptions} options
   */
  constructor(options) {
    this.config = options;
  }

  fetchData() {
    console.log(`请求地址：${this.config.apiUrl}，超时时间：${this.config.timeout}`);
  }
}

let instance = null;

module.exports = {
  /**
   * 初始化模块配置
   * @param {SomethingOptions} options
   */
  init(options) {
    if (instance) {
      console.warn('Something模块已完成初始化，重复调用无效');
      return;
    }
    instance = new Something(options);
  },

  /**
   * 获取模块实例
   * @returns {Something}
   */
  getInstance() {
    if (!instance) throw new Error('Something模块未初始化，请先调用init方法');
    return instance;
  }
};

使用示例 #

// 初始化配置（建议在项目入口处调用）
require('./something').init({ apiUrl: 'https://example.com', timeout: 5000 });

// 项目任意位置获取实例
const something = require('./something').getInstance();
something.fetchData(); // 编辑器能完美提示实例方法和属性

这种方式虽然多了一步init调用，但逻辑完全清晰，编辑器能精准识别导出对象的init和getInstance方法，以及getInstance返回的Something实例类型，彻底避免识别混乱问题。

内容的提问来源于stack exchange，提问作者Danyal Aytekin