@ ampproject/ 重新绘图

通过变换重映射顺序源图以指向原始源代码

重映射允许您使用通过转换代码和“再映射”生成的源图 他们到原始来源位置。 想想"我的精密代码, 改变与bail和捆绑 使用webpack),所有指向您原始源代码中的正确位置.

在重映射下,你的任何源代码转换 不需要意识到输入的源图, 它们只需要生成输出源图。 这大大简化了建筑习惯 转换(认为是找到和替换).

安装

npm install @ampproject/remapping

使用量

function remapping(
  map: SourceMap | SourceMap[],
  loader: (file: string, ctx: LoaderContext) => (SourceMap | null | undefined),
  options?: { excludeContent: boolean, decodedMappings: boolean }
): SourceMap;

// LoaderContext gives the loader the importing sourcemap, tree depth, the ability to override the
// "source" location (where child sources are resolved relative to, or the location of original
// source), and the ability to override the "content" of an original source for inclusion in the
// output sourcemap.
type LoaderContext = {
 readonly importer: string;
 readonly depth: number;
 source: string;
 content: string | null | undefined;
}

remapping 取最后输出源图,并 a loader 函数。 每个源文件指针 在源图中 loader 将用一条坚定的道路召唤。 如果路径本身代表 转换文件(它有一个与它相关的酸液图),然后是 loader 应该还回去 源图. 如果没有,该路径将被视为原始的,未转换的源代码.

// Babel transformed "helloworld.js" into "transformed.js"
const transformedMap = JSON.stringify({
  file: 'transformed.js',
  // 1st column of 2nd line of output file translates into the 1st source
  // file, line 3, column 2
  mappings: ';CAEE',
  sources: ['helloworld.js'],
  version: 3,
});

// Uglify minified "transformed.js" into "transformed.min.js"
const minifiedTransformedMap = JSON.stringify({
  file: 'transformed.min.js',
  // 0th column of 1st line of output file translates into the 1st source
  // file, line 2, column 1.
  mappings: 'AACC',
  names: [],
  sources: ['transformed.js'],
  version: 3,
});

const remapped = remapping(
  minifiedTransformedMap,
  (file, ctx) => {

    // The "transformed.js" file is an transformed file.
    if (file === 'transformed.js') {
      // The root importer is empty.
      console.assert(ctx.importer === '');
      // The depth in the sourcemap tree we're currently loading.
      // The root `minifiedTransformedMap` is depth 0, and its source children are depth 1, etc.
      console.assert(ctx.depth === 1);

      return transformedMap;
    }

    // Loader will be called to load transformedMap's source file pointers as well.
    console.assert(file === 'helloworld.js');
    // `transformed.js`'s sourcemap points into `helloworld.js`.
    console.assert(ctx.importer === 'transformed.js');
    // This is a source child of `transformed`, which is a source child of `minifiedTransformedMap`.
    console.assert(ctx.depth === 2);
    return null;
  }
);

console.log(remapped);
// {
//   file: 'transpiled.min.js',
//   mappings: 'AAEE',
//   sources: ['helloworld.js'],
//   version: 3,
// };

在这个例子中, loader 将两次呼叫:

1. "transformed.js"中的第一个源文件指针 minifiedTransformedMap我们返回 与之相关的源图( 毕竟是一个已转换的文件) , 这样源图位置就可以 被追踪到它所代表的源文件.
2. "helloworld.js"我们的原始,未修改的源代码。 此文件没有源代码图, 所以 我们回来了 null。 。 。 .

这个 remapped 源图现在从 transformed.min.js 进入 helloworld.js如果 你要读 mappings,它表示"一行输出行的第0栏指向一行 栏 helloworld.js" ..

文件的多重转换

作为方便,如果你对一个文件有多个单源转换,你可以通过一个 数组源图文件,顺序为最近期的转换源图。 注意这一点: 更改 importer 财务报告和审定财务报表 depth 每一个呼叫我们装载器。 所以我们上面的例子可能是 写为:

const remapped = remapping(
  [minifiedTransformedMap, transformedMap],
  () => null
);

console.log(remapped);
// {
//   file: 'transpiled.min.js',
//   mappings: 'AAEE',
//   sources: ['helloworld.js'],
//   version: 3,
// };

对加载图的高级控制

source

这个 source 属性可以覆盖到任何值来改变当前负载的位置。 比如说, 对于原始源文件,它允许我们将位置更改为原始源,无论 来源地图条目所言。 对于转换的文件, 它允许我们改变 相对解析加载源图的儿童源位置.

const remapped = remapping(
  minifiedTransformedMap,
  (file, ctx) => {

    if (file === 'transformed.js') {
      // We pretend the transformed.js file actually exists in the 'src/' directory. When the nested
      // source files are loaded, they will now be relative to `src/`.
      ctx.source = 'src/transformed.js';
      return transformedMap;
    }

    console.assert(file === 'src/helloworld.js');
    // We could futher change the source of this original file, eg, to be inside a nested directory
    // itself. This will be reflected in the remapped sourcemap.
    ctx.source = 'src/nested/transformed.js';
    return null;
  }
);

console.log(remapped);
// {
//   …,
//   sources: ['src/nested/helloworld.js'],
// };

content

这个 content 当我们遇到原始源文件时,属性会被覆盖。 Eg 允许 以手动方式提供原始文件的出处内容,无论 sourcesContent 字段存在于父源图中。 也可以设定为 null 删除 源内容.

const remapped = remapping(
  minifiedTransformedMap,
  (file, ctx) => {

    if (file === 'transformed.js') {
      // transformedMap does not include a `sourcesContent` field, so usually the remapped sourcemap
      // would not include any `sourcesContent` values.
      return transformedMap;
    }

    console.assert(file === 'helloworld.js');
    // We can read the file to provide the source content.
    ctx.content = fs.readFileSync(file, 'utf8');
    return null;
  }
);

console.log(remapped);
// {
//   …,
//   sourcesContent: [
//     'console.log("Hello world!")',
//   ],
// };

选项

不适用

默认, excludeContent 实值 false。通过 { excludeContent: true } 将排除 sourcesContent 字段从返回的源图。 这主要在您想要减少时有用 大小从源图.

解码绘图

默认, decodedMappings 实值 false。通过 { decodedMappings: true } 将离开 mappings 字段内 解码状态 改为 编码为 VLQ 字符串 .