Parcel 的源映射库

这是一个专门为 Parcel 打包器构建的源映射库，专注于快速合并和操作源映射。

要了解有关源映射的格式和它们是如何工作的更多信息，您可以查看源映射规范。

如何使用此库？

如果您想在项目中使用此库或想编写一个带有源映射支持的 Parcel 插件，此部分将解释您如何开始。

为了获取更多信息，我们为 SourceMap 类的每个函数都添加了文档类型，以便您可以深入了解每个功能的作用。

创建 SourceMap 实例

您可以从另一个源映射创建源映射，或者一次创建一个映射。

从现有源映射创建

要从现有源映射创建源映射，您必须确保它首先是一个 JS 对象，可以通过询问您正在运行的编译器的对象版本或使用 JSON.parse 或任何其他 JSON 解析器解析序列化的映射来实现。

之后，您可以调用函数 addVLQMap(map, lineOffset, columnOffset)，这个函数接受参数 map、lineOffset 和 columnOffset。映射参数对应于源映射对象。行和列偏移是可选参数，用于偏移生成的行和列。（这可以在后期处理或包装与源映射链接的代码时使用，在 Parcel 中，这用于合并映射。）

示例

import SourceMap from '@parcel/source-map';

const RAW_SOURCEMAP = {
  version: 3,
  file: "helloworld.js",
  sources: ["helloworld.coffee"],
  names: [],
  mappings: "AAAA;AAAA,EAAA,OAAO,CAAC,GAAR,CAAY,aAAZ,CAAA,CAAA;AAAA",
};

let sourcemap = new SourceMap();
sourcemap.addVLQMap(RAW_SOURCEMAP);

// This function removes the underlying references in the native code
sourcemap.delete();

一次创建一个映射

如果您想使用此库从头开始创建源映射，您可以调用 addIndexedMapping(mapping, lineOffset, columnOffset) 函数。

示例

import SourceMap from '@parcel/source-map';

let sourcemap = new SourceMap();

// Add a single mapping
sourcemap.addIndexedMapping({
  generated: {
    // line index starts at 1
    line: 1,
    // column index starts at 0
    column: 4
  },
  original: {
    // line index starts at 1
    line: 1,
    // column index starts at 0
    column: 4
  },
  source: 'index.js',
  // Name is optional
  name: 'A'
});

// This function removes the underlying references in the native code
sourcemap.delete();

缓存

为了缓存源映射，我们有一个 toBuffer() 函数，该函数返回一个可以保存到磁盘以供以后使用并快速合并源映射的缓冲区。

您可以使用 addBuffer(buffer, lineOffset) 函数将缓存的映射添加到 SourceMap 实例中，您也可以偏移生成的行和列。

灵感和目的

我们为什么要写这个库

Parcel 是一个性能优先的打包器，因此我们喜欢尽可能优化 Parcel 的性能。

我们的原始源映射实现使用了 mozilla 的 source-map 以及一些 JavaScript，存在内存使用和序列化时间的问题（我们使用 JavaScript 对象在内存中保留所有映射，并使用 JSON 进行缓存）。

这个实现是从头开始用 Rust 编写的，通过利用源和名称的索引来最小化内存使用，并通过使用缓冲区而不是 JSON 来优化缓存时的序列化时间。

先前的工作和灵感

没有这些库，这个库今天就不会这么好了。我们使用了这些库中的想法和模式来启发和优化我们的代码，并使用它来确定如何正确处理源映射。

• Mozilla 的 source-map
• Nick Fitzgerald 的 source-map-mappings
• Rich Harris 的 sourcemap-codec

为这个库做出贡献

欢迎对这个库做出贡献，就像对 Parcel 系统中庞大的库和工具集合中的任何部分一样。

先决条件

要能够构建和开发这个项目，您需要安装以下工具

• node.js
• Rust

构建项目

出于开发目的，您可能需要构建或重新构建项目，为此您需要构建 N-API 模块和 JS 代码。

要这样做，请运行以下命令：（有关更多信息，您可以查看 ./package.json 和 ./Makefile）

yarn transpile && yarn build:node

标记一个发布版

在您能够标记发布版之前，请确保已安装 cargo-release cargo install cargo-release，我们使用它来标记 cargo 文件中的发布标签。

yarn tag-release <version>