Parcel的source-map库

这是一个专门为Parcel打包器定制的source-map库，专注于快速组合和操作source-maps。

要了解更多关于sourcemaps的格式和工作原理，您可以查看SourceMap 规范。

如何使用此库？

如果您想在项目中使用此库或希望编写支持sourcemap的Parcel插件，以下说明应能帮助您入门。

为了提供更多信息，我们在SourceMap类的每个函数中添加了doctypes，您可以深入了解每个功能的作用。

创建SourceMap实例

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

从现有sourcemap创建

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

之后，您可以调用addVLQMap(map, lineOffset, columnOffset)函数，此函数接受参数map、lineOffset和columnOffset。map参数对应于sourcemap对象。行和列偏移是可选参数，用于偏移生成的行和列。（这可以在后处理或包装与sourcemap链接的代码时使用，在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();

一次创建一个映射

如果您想使用此库从头开始创建sourcemap，您可以调用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>