Sandboxed Module 技术文档

1. 安装指南

要安装 sandboxed-module，请在终端中运行以下命令：

npm install sandboxed-module

2. 项目的使用说明

sandboxed-module 是一个用于依赖注入的 Node.js 模块加载器。它允许你在模块中注入依赖项，主要用于单元测试。以下是一个简单的使用示例：

var SandboxedModule = require('sandboxed-module');
var user = SandboxedModule.require('./user', {
  requires: {'mysql': {fake: 'mysql module'}},
  globals: {myGlobal: 'variable'},
  locals: {myLocal: 'other variable'},
});

在这个示例中，sandboxed-module 加载了 ./user 模块，并注入了 mysql 模块的假实现，以及一些全局和局部变量。

3. 项目API使用文档

SandboxedModule.load(moduleId, [options])

返回一个新的 SandboxedModule，其中 moduleId 是通常传递给 require() 的模块路径或 ID。该模块将在其自己的 v8 上下文中加载，但可以访问正常的 Node.js 环境。

options 是一个可选对象，用于注入以下内容：

• requires: 一个对象，包含 moduleId 和要注入的值，当沙盒模块需要它们时。
• globals: 一个对象，包含要注入到沙盒模块中的全局变量。
• locals: 一个对象，包含要注入到沙盒模块中的局部变量。
• sourceTransformers: 一个对象，包含命名的函数，用于转换沙盒模块的源代码。
• singleOnly: 如果为 false，沙盒模块所需的模块将不会被沙盒化。默认情况下，所有沙盒模块所需的模块都将使用相同的选项进行沙盒化。
• sourceTransformersSingleOnly: 如果为 false，源转换器将不会对沙盒模块所需的模块运行。默认情况下，它将采用与 singleOnly 相同的值。

SandboxedModule.require(moduleId, [options])

与 SandboxedModule.load() 相同，但直接返回 sandboxedModule.exports。

SandboxedModule.configure(options)

在所有 SandboxedModule.load() 和 SandboxedModule.require() 使用中全局设置选项。

SandboxedModule.registerBuiltInSourceTransformer(name)

启用内置的源转换器。目前，SandboxedModule 有两个内置源转换器：

• "coffee" - 使用 CoffeeScript 编译源代码。
• "istanbul" - 当 istanbul 代码覆盖运行时，通过 istanbul 进行源代码插桩。

sandboxedModule.filename

模块的完整路径。

sandboxedModule.module

底层的 Node.js Module 实例。

sandboxedModule.exports

返回 sandboxedModule.module.exports 对象的 getter。

sandboxedModule.globals

该模块加载的 v8 上下文的全局对象。对该对象的修改将反映在沙盒模块中。

sandboxedModule.locals

使用闭包注入到沙盒模块中的局部变量。修改此对象不会影响沙盒的状态。

sandboxedModule.required

一个对象，包含沙盒模块本身所需的所有模块的列表。键是用于 require 调用的 moduleId。

sandboxedModule.sourceTransformers

一个命名的函数对象，用于转换通过 SandboxedModule.require 所需的源代码。

4. 项目安装方式

sandboxed-module 可以通过 npm 安装，安装命令如下：

npm install sandboxed-module

安装完成后，你可以在项目中通过 require('sandboxed-module') 来使用它。