better-module-loader

这是一个支持 ESM 和 CommonJS 模块的 Node.js 模块加载工具。

English version: README.md

特性

• 递归加载目录中的模块
• 支持 ESM（.mjs、.js）和 CommonJS（.cjs）模块
• 支持工厂函数模块 - 自动调用函数导出
• 支持类模块 - 自动实例化类导出
• 自动根据文件名或模块的 name 属性命名模块
• 支持自定义递归深度限制
• 支持文件扩展名过滤

安装

npm install better-module-loader

使用说明

ESM 用法

import { loadDir, loadDirTo, traverseDir, loadModule, isModule } from 'better-module-loader';

// 从目录中加载所有模块
const modules = await loadDir('./path/to/modules');

// 使用选项加载
const options = {
  depth: 2,          // 递归加载最多 2 层目录
  exts: ['.js'],     // 只加载 .js 文件
  args: [{ config: {} }], // 传递给工厂函数或构造函数的参数
  singleObject: true  // 处理模块并返回最终对象，而不是原始模块对象
};
const modules = await loadDir('./path/to/modules', options);

// 将模块加载到现有目标对象中
const target = {};
await loadDirTo(target, './path/to/modules', options);

CommonJS 用法

const { loadDir, loadDirTo } = require('better-module-loader');

// 从目录中加载所有模块
loadDir('./path/to/modules').then((modules) => {
  console.log(modules);
});

// 使用选项加载
const options = { args: [{ config: {} }] };
loadDir('./path/to/modules', options).then((modules) => {
  console.log(modules);
});

API

loadDir(path, options?)

从指定目录加载模块，并返回一个包含加载结果的新对象。

参数：

• path - 要加载的目录路径
• options（可选）- 配置选项：
  • depth - 递归加载的最大深度（默认：0，表示不限深度）
  • exts - 要包含的文件扩展名数组（默认：所有）
  • args - 传递给工厂函数或类构造函数的参数
  • singleObject - 如果为 true，则提取默认导出（或唯一命名导出）并调用函数/类；如果为 false，返回原始模块对象
    • loadDir / loadDirTo 默认值：false

返回： Promise<Record<string, any>>

注意：loadDir / loadDirTo 默认 singleObject: false，因此默认返回原始模块对象，除非显式开启处理。

loadDirTo(target, path, options?)

从指定目录加载模块到现有目标对象中。

参数：

• target - 要填充模块的目标对象
• path - 要加载的目录路径
• options（可选）- 与 loadDir 相同

返回： Promise<Record<string, any>> - 返回目标对象

traverseDir(dir, depth, callback)

递归遍历目录，并对每个文件调用回调函数。

参数：

• dir - 要遍历的目录路径
• depth - 最大递归深度
• callback - 查找到文件时调用的函数（支持 async）

返回： Promise<void>

loadModule(fp, options?)

加载单个模块文件。

参数：

• fp - 模块文件路径
• options（可选）- 配置选项：
  • args - 传递给工厂函数或类构造函数的参数
  • singleObject - 如果为 true，则提取默认导出（或唯一命名导出）并调用函数/类；如果为 false（默认），返回原始模块对象
    • loadModule 默认值：false

返回： Promise<any>

示例：

• await loadModule('./module.js') 返回原始模块对象
• await loadModule('./module.js', { singleObject: true }) 返回处理后的导出对象（如果是函数/类则会调用）

isModule(obj)

检查一个对象是否为 ES 模块对象。

参数：

• obj - 要检查的对象

返回： boolean

模块类型

对象模块

export default {
  name: 'myModule',
  doSomething() { /* ... */ }
};

工厂函数

export default function(context) {
  return {
    doSomething() { /* ... */ }
  };
}

类

export default class MyClass {
  constructor(context) {
    this.context = context;
  }
  doSomething() { /* ... */ }
}

示例

import { loadDir } from 'better-module-loader';

// 使用上下文加载服务模块
const context = {
  config: { port: 3000 },
  logger: console
};

const services = await loadDir('./services', {
  args: [context],
  depth: 2,
  singleObject: true
});

// 使用加载的服务
services.userService.createUser({ name: 'John' });
services.orderService.processOrder({ id: '123' });

许可证

MIT