素晴らしいコミュニティモジュール
  1. 表紙
  2. コミュニティモジュール
  3. ソースマップ

ソースマップ

ビルドステータス

故宮

これは、ここで説明するソース マップ形式を生成および使用するためのライブラリです 。

ノードで使用する

1
$ npm install source-map

ウェブ上で使用する

1
2
3
4
5
6
<script src="https://unpkg.com/source-map@0.7.2/dist/source-map.js"></script>
<script>
    sourceMap.SourceMapConsumer.initialize({
        "lib/mappings.wasm": "https://unpkg.com/source-map@0.7.2/lib/mappings.wasm"
    });
</script>

目次

例

Consuming a source map

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
const rawSourceMap = {
  version: 3,
  file: 'min.js',
  names: ['bar', 'baz', 'n'],
  sources: ['one.js', 'two.js'],
  sourceRoot: 'http://example.com/www/js/',
  mappings: 'CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUE,GAClB,OAAOA'
};

const whatever = await SourceMapConsumer.with(rawSourceMap, null, consumer => {

  console.log(consumer.sources);
  // [ 'http://example.com/www/js/one.js',
  //   'http://example.com/www/js/two.js' ]

  console.log(consumer.originalPositionFor({
    line: 2,
    column: 28
  }));
  // { source: 'http://example.com/www/js/two.js',
  //   line: 2,
  //   column: 10,
  //   name: 'n' }

  console.log(consumer.generatedPositionFor({
    source: 'http://example.com/www/js/two.js',
    line: 2,
    column: 10
  }));
  // { line: 2, column: 28 }

  consumer.eachMapping(function (m) {
    // ...
  });

  return computeWhatever();
});

Generating a source map

詳細ガイド: JavaScript へのコンパイルとソース マップを使用したデバッグ

SourceNode (高レベル API) を使用する場合

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
function compile(ast) {
  switch (ast.type) {
  case 'BinaryExpression':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      [compile(ast.left), " + ", compile(ast.right)]
    );
  case 'Literal':
    return new SourceNode(
      ast.location.line,
      ast.location.column,
      ast.location.source,
      String(ast.value)
    );
  // ...
  default:
    throw new Error("Bad AST");
  }
}

var ast = parse("40 + 2", "add.js");
console.log(compile(ast).toStringWithSourceMap({
  file: 'add.js'
}));
// { code: '40 + 2',
//   map: [object SourceMapGenerator] }

SourceMapGenerator (低レベル API) を使用する場合

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
var map = new SourceMapGenerator({
  file: "source-mapped.js"
});

map.addMapping({
  generated: {
    line: 10,
    column: 35
  },
  source: "foo.js",
  original: {
    line: 33,
    column: 2
  },
  name: "christopher"
});

console.log(map.toString());
// '{"version":3,"file":"source-mapped.js","sources":["foo.js"],"names":["christopher"],"mappings":";;;;;;;;;mCAgCEA"}'

API

モジュールへの参照を取得します。

1
2
3
4
5
6
7
8
// Node.js
var sourceMap = require('source-map');

// Browser builds
var sourceMap = window.sourceMap;

// Inside Firefox
const sourceMap = require("devtools/toolkit/sourcemap/source-map.js");

SourceMapConsumer

インスタンスSourceMapConsumerは解析されたソース マップを表し、生成されたソース内のファイル位置を指定することで、元のファイルの位置に関する情報をクエリできます。

SourceMapConsumer.initialize(オプション)

SourceMapConsumerWeb など、node.js の外部で使用する場合は、どの URL からロードするかを知る必要があり、 を構築する前にlib/mappings.wasm呼び出して通知する必要があります。initializeSourceMapConsumer

オプション オブジェクトには次のプロパティがあります。

  • "lib/mappings.wasm":ファイルStringの URL を含む A。lib/mappings.wasm
1
2
3
sourceMap.SourceMapConsumer.initialize({
  "lib/mappings.wasm": "https://example.com/source-map/lib/mappings.wasm"
});

新しい SourceMapConsumer(rawSourceMap)

唯一のパラメータは生のソース マップです ('d 可能な文字列 JSON.parseまたはオブジェクトとして)。仕様によれば、ソース マップには次の属性があります。

  • version: このマップが準拠しているソース マップ仕様のバージョン。

  • sources: 元のソース ファイルへの URL の配列。

  • names: 個々のマッピングで参照できる識別子の配列。

  • sourceRoot: オプション。すべてのソースが相対的な URL ルートです。

  • sourcesContent: オプション。元のソース ファイルの内容の配列。

  • mappings: 実際のマッピングを含む Base64 VLQ の文字列。

  • file: オプション。このソース マップが関連付けられている生成されたファイル名。

構築されたソース マップ コンシューマの Promise が返されます。

がSourceMapConsumer使用されなくなった場合は、その destroyメソッドを呼び出す必要があります。

1
2
3
const consumer = await new sourceMap.SourceMapConsumer(rawSourceMapJsonData);
doStuffWith(consumer);
consumer.destroy();

あるいは、 を使用するSourceMapConsumer.withと、 を呼び出すことを忘れずに済みますdestroy。

SourceMapConsumer.with

新しいSourceMapConsumerfrom rawSourceMapandを構築しますsourceMapUrl (SourceMapConsumer詳細についてはコンストラクターを参照してください。次に、async function f(SourceMapConsumer) -> T新しく構築されたコンシューマで を呼び出し、f完了するまで待機し、destroyコンシューマを呼び出して、fの戻り値を返します。

完了後にコンシューマーを使用しないでくださいf。

を使用すると、コンシューマーをwith手動で呼び出すことを覚えておく必要はありません。完了すると自動的に呼び出されるからです。destroyf

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const xSquared = await SourceMapConsumer.with(
  myRawSourceMap,
  null,
  async function (consumer) {
    // Use `consumer` inside here and don't worry about remembering
    // to call `destroy`.

    const x = await whatever(consumer);
    return x * x;
  }
);

// You may not use that `consumer` anymore out here; it has
// been destroyed. But you can use `xSquared`.
console.log(xSquared);

SourceMapConsumer.prototype.destroy()

手動で管理されているこのソース マップ コンシューマに関連する wasm データを解放します。

1
consumer.destroy();

あるいは、 を使用するSourceMapConsumer.withと、 を呼び出すことを忘れずに済みますdestroy。

SourceMapConsumer.prototype.computeColumnSpans()

生成されたマッピングごとに最後の列を計算します。最後の列は包括的です。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Before:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]

consumer.computeColumnSpans();

// After:
consumer.allGeneratedPositionsFor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1,
//     lastColumn: 9 },
//   { line: 2,
//     column: 10,
//     lastColumn: 19 },
//   { line: 2,
//     column: 20,
//     lastColumn: Infinity } ]

SourceMapConsumer.prototype.originalPositionFor(generatedPosition)

指定された、生成されたソースの行と列の位置に関する元のソース、行、および列の情報を返します。唯一の引数は、次のプロパティを持つオブジェクトです。

  • line: 生成されたソースの行番号。このライブラリの行番号は 1 から始まります (基礎となるソース マップ仕様では 0 から始まる行番号が使用されていることに注意してください。このライブラリは変換を処理します)。

  • column: 生成されたソースの列番号。このライブラリの列番号は 0 から始まります。

  • bias: または のいずれSourceMapConsumer.GREATEST_LOWER_BOUNDか SourceMapConsumer.LEAST_UPPER_BOUND。正確な要素が見つからない場合に、検索している要素より小さいか大きい、最も近い要素を返すかどうかを指定します。デフォルトは です SourceMapConsumer.GREATEST_LOWER_BOUND。

次のプロパティを持つオブジェクトが返されます。

  • source: 元のソース ファイル、またはこの情報が利用できない場合は null。

  • line: 元のソースの行番号、またはこの情報が利用できない場合は null 行番号は 1 から始まります。

  • column: 元のソースの列番号、またはこの情報が利用できない場合は null。列番号は 0 から始まります。

  • name: 元の識別子、またはこの情報が利用できない場合は null。

1
2
3
4
5
6
7
8
9
10
11
consumer.originalPositionFor({ line: 2, column: 10 })
// { source: 'foo.coffee',
//   line: 2,
//   column: 2,
//   name: null }

consumer.originalPositionFor({ line: 99999999999999999, column: 999999999999999 })
// { source: null,
//   line: null,
//   column: null,
//   name: null }

SourceMapConsumer.prototype.generatedPositionFor(originalPosition)

指定された元のソース、行、列の位置について生成された行と列の情報を返します。唯一の引数は、次のプロパティを持つオブジェクトです。

  • source: 元のソースのファイル名。

  • line: 元のソースの行番号。行番号は 1 から始まります。

  • column: 元のソースの列番号。列番号は 0 から始まります。

次のプロパティを持つオブジェクトが返されます。

  • line: 生成されたソースの行番号、または null 行番号は 1 から始まります。

  • column: 生成されたソース内の列番号、または null。列番号は 0 から始まります。

1
2
3
consumer.generatedPositionFor({ source: "example.js", line: 2, column: 10 })
// { line: 1,
//   column: 56 }

SourceMapConsumer.prototype.allGeneratedPositionsFor(originalPosition)

指定された元のソース、行、および列について生成されたすべての行および列の情報を返します。列が指定されていない場合は、検索している行、またはマッピングがある次に近い行に対応するすべてのマッピングを返します。それ以外の場合は、を返します。指定された行と、検索している列、またはオフセットを持つ次に近い列のいずれかに対応するすべてのマッピング。

唯一の引数は、次のプロパティを持つオブジェクトです。

  • source: 元のソースのファイル名。

  • line: 元のソースの行番号。行番号は 1 から始まります。

  • column: オプション。元のソースの列番号。列番号は 0 から始まります。

そして、それぞれ次のプロパティを持つオブジェクトの配列が返されます。

  • line: 生成されたソースの行番号、または null 行番号は 1 から始まります。

  • column: 生成されたソース内の列番号、または null。列番号は 0 から始まります。

1
2
3
4
5
6
7
consumer.allGeneratedpositionsfor({ line: 2, source: "foo.coffee" })
// [ { line: 2,
//     column: 1 },
//   { line: 2,
//     column: 10 },
//   { line: 2,
//     column: 20 } ]

SourceMapConsumer.prototype.hasContentsOfAllSources()

ソース マップにリストされているすべてのソースの埋め込みソース コンテンツがある場合は true を返し、そうでない場合は false を返します。

つまり、このメソッドが を返す場合true、 内の consumer.sourceContentFor(s)すべてのソースに対して成功します。sconsumer.sources

1
2
3
4
5
6
7
// ...
if (consumer.hasContentsOfAllSources()) {
  consumerReadyCallback(consumer);
} else {
  fetchSources(consumer, consumerReadyCallback);
}
// ...

SourceMapConsumer.prototype.sourceContentFor(source[, returnNullOnMissing])

指定されたソースの元のソース コンテンツを返します。唯一の引数は、元のソース ファイルの URL です。

指定されたソースのソース コンテンツが見つからない場合は、エラーがスローされます。オプションで、代わりに返されるtrue2 番目のパラメータとして渡しますnull。

1
2
3
4
5
6
7
8
9
10
11
consumer.sources
// [ "my-cool-lib.clj" ]

consumer.sourceContentFor("my-cool-lib.clj")
// "..."

consumer.sourceContentFor("this is not in the source map");
// Error: "this is not in the source map" is not in the source map

consumer.sourceContentFor("this is not in the source map", true);
// null

SourceMapConsumer.prototype.eachMapping(コールバック、コンテキスト、順序)

元のソース/行/列と、このソース マップ内の生成された行/列の間の各マッピングを繰り返します。

  • callback: 各マッピングで呼び出される関数。マッピングの形式は次のとおりです。{ source, generatedLine, generatedColumn, originalLine, originalColumn, name }

  • contextthis : オプション。指定した場合、このオブジェクトは呼び出されるたびに値になりますcallback。

  • order: または のいずれかSourceMapConsumer.GENERATED_ORDER。 SourceMapConsumer.ORIGINAL_ORDER生成されたファイルの行/列順序または元のソース/行/列順序でソートされたマッピングをそれぞれ反復処理するかどうかを指定します。デフォルトは です SourceMapConsumer.GENERATED_ORDER。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
consumer.eachMapping(function (m) { console.log(m); })
// ...
// { source: 'illmatic.js',
//   generatedLine: 1,
//   generatedColumn: 0,
//   originalLine: 1,
//   originalColumn: 0,
//   name: null }
// { source: 'illmatic.js',
//   generatedLine: 2,
//   generatedColumn: 0,
//   originalLine: 2,
//   originalColumn: 0,
//   name: null }
// ...

SourceMapGenerator

SourceMapGenerator のインスタンスは、増分的に構築されるソース マップを表します。

new SourceMapGenerator([startOfSourceMap])

次のプロパティを持つオブジェクトを渡すことができます。

  • file: このソース マップが関連付けられている生成されたソースのファイル名。

  • sourceRoot: このソース マップ内のすべての相対 URL のルート。

  • skipValidation: オプション。 の場合true、追加時のマッピングの検証が無効になります。これによりパフォーマンスが向上しますが、最後の手段として慎重に使用する必要があります。その場合でも、テストを実行するときは、可能であればこのフラグの使用を避ける必要があります。

1
2
3
4
var generator = new sourceMap.SourceMapGenerator({
  file: "my-generated-javascript-file.js",
  sourceRoot: "http://example.com/app/js/"
});

SourceMapGenerator.fromSourceMap(sourceMapConsumer)

SourceMapGenerator既存のインスタンスから新しいインスタンスを作成しますSourceMapConsumer。

  • sourceMapConsumerソースマップ。
1
var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer);

SourceMapGenerator.prototype.addMapping(マッピング)

元のソースの行と列から、作成中のこのソース マップの生成されたソースの行と列に 1 つのマッピングを追加します。マッピング オブジェクトには次のプロパティが必要です。

  • generated: 生成された行と列の位置を含むオブジェクト。

  • original: 元の行と列の位置を持つオブジェクト。

  • source: 元のソース ファイル (sourceRoot に相対)。

  • name: このマッピングのオプションの元のトークン名。

1
2
3
4
5
generator.addMapping({
  source: "module-one.scm",
  original: { line: 128, column: 0 },
  generated: { line: 3, column: 456 }
})

SourceMapGenerator.prototype.setSourceContent(sourceFile, sourceContent)

オリジナルソースファイルのソース内容を設定します。

  • sourceFile元のソース ファイルの URL。

  • sourceContentソースファイルの内容。

1
2
generator.setSourceContent("module-one.scm",
                           fs.readFileSync("path/to/module-one.scm"))

SourceMapGenerator.prototype.applySourceMap(sourceMapConsumer[,sourceFile[,sourceMapPath]])

ソース ファイルの SourceMap を SourceMap に適用します。提供されたソース ファイルへの各マッピングは、提供された SourceMap を使用して書き換えられます。注: 結果のマッピングの解像度は、このマップと提供されたマップの最小値になります。

  • sourceMapConsumer: 適用される SourceMap。

  • sourceFile: オプション。ソース ファイルのファイル名。省略した場合、sourceMapConsumer.file が存在する場合はそれが使用されます。それ以外の場合は、エラーがスローされます。

  • sourceMapPath: オプション。適用される SourceMap へのパスのディレクトリ名。相対的な場合は、SourceMap に対する相対パスです。

    このパラメータは、2 つの SourceMap が同じディレクトリになく、適用される SourceMap に相対ソース パスが含まれている場合に必要です。その場合、それらの相対ソース パスは SourceMap を基準にして書き換える必要があります。

    省略した場合、両方の SourceMap が同じディレクトリにあるものとみなされ、書き換えの必要はありません (供給しても'.'同じ効果があります)。

SourceMapGenerator.prototype.toString()

生成されるソース マップを文字列にレンダリングします。

1
2
generator.toString()
// '{"version":3,"sources":["module-one.scm"],"names":[],"mappings":"...snip...","file":"my-generated-javascript-file.js","sourceRoot":"http://example.com/app/js/"}'

SourceNode

SourceNodes は、生成された JavaScript ソース コードのスニペットを補間および/または連結して抽象化する方法を提供しますが、その一方で、これらのスニペットと元のソース コードの間に関連付けられた行と列の情報は維持されます。これは、コンパイラが出力する前に使用する最終的な中間表現として役立ちます。生成されたJSとソースマップ。

new SourceNode([行, 列, ソース[, チャンク[, 名前]]])

  • line: このソース ノードに関連付けられた元の行番号、または元の行に関連付けられていない場合は null。行番号は 1 から始まります。

  • column: このソース ノードに関連付けられた元の列番号、または元の列に関連付けられていない場合は null。列番号は 0 から始まります。

  • source: 元のソースのファイル名。ファイル名が指定されていない場合は null。

  • chunk: オプション。すぐに に渡されますSourceNode.prototype.add。以下を参照してください。

  • name: オプション、元の識別子。

1
2
3
4
5
var node = new SourceNode(1, 2, "a.cpp", [
  new SourceNode(3, 4, "b.cpp", "extern int status;\n"),
  new SourceNode(5, 6, "c.cpp", "std::string* make_string(size_t n);\n"),
  new SourceNode(7, 8, "d.cpp", "int main(int argc, char** argv) {}\n"),
]);

SourceNode.fromStringWithSourceMap(コード、sourceMapConsumer[、相対パス])

生成されたコードと SourceMapConsumer から SourceNode を作成します。

  • code:生成されたコード

  • sourceMapConsumer生成されたコードのソースマップ

  • relativePath相対ソースの相対パスである必要があるオプションのパスsourceMapConsumer 。

1
2
const consumer = await new SourceMapConsumer(fs.readFileSync("path/to/my-file.js.map", "utf8"));
const node = SourceNode.fromStringWithSourceMap(fs.readFileSync("path/to/my-file.js"), consumer);

SourceNode.prototype.add(チャンク)

生成された JS のチャンクをこのソース ノードに追加します。

  • chunk: 生成された JS コードの文字列スニペット、 の別のインスタンス SourceNode、または各メンバーがそれらのいずれかである配列。
1
2
3
node.add(" + ");
node.add(otherNode);
node.add([leftHandOperandNode, " + ", rightHandOperandNode]);

SourceNode.prototype.prepend(チャンク)

生成された JS のチャンクをこのソース ノードの先頭に追加します。

  • chunk: 生成された JS コードの文字列スニペット、 の別のインスタンス SourceNode、または各メンバーがそれらのいずれかである配列。
1
node.prepend("/** Build Id: f783haef86324gf **/\n\n");

SourceNode.prototype.setSourceContent(sourceFile, sourceContent)

ソース ファイルのソース コンテンツを設定します。これはフィールドに追加され SourceMapますsourcesContent。

  • sourceFile: ソースファイルのファイル名

  • sourceContent：ソースファイルの内容

1
2
node.setSourceContent("module-one.scm",
                      fs.readFileSync("path/to/module-one.scm"))

SourceNode.prototype.walk(fn)

このノードとその子の JS スニペットのツリー上を歩きます。ウォーキング関数は JS の各スニペットに対して 1 回呼び出され、そのスニペットとそのスニペットに関連付けられた元のソースの行/列の位置が渡されます。

  • fn: トラバーサル機能。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.walk(function (code, loc) { console.log("WALK:", code, loc); })
// WALK: uno { source: 'b.js', line: 3, column: 4, name: null }
// WALK: dos { source: 'a.js', line: 1, column: 2, name: null }
// WALK: tres { source: 'a.js', line: 1, column: 2, name: null }
// WALK: quatro { source: 'c.js', line: 5, column: 6, name: null }

SourceNode.prototype.walkSourceContents(fn)

SourceNodes のツリー上を歩きます。ウォーキング関数は各ソース ファイル コンテンツに対して呼び出され、ファイル名とソース コンテンツが渡されます。

  • fn: トラバーサル機能。
1
2
3
4
5
6
7
8
9
10
11
12
var a = new SourceNode(1, 2, "a.js", "generated from a");
a.setSourceContent("a.js", "original a");
var b = new SourceNode(1, 2, "b.js", "generated from b");
b.setSourceContent("b.js", "original b");
var c = new SourceNode(1, 2, "c.js", "generated from c");
c.setSourceContent("c.js", "original c");

var node = new SourceNode(null, null, null, [a, b, c]);
node.walkSourceContents(function (source, contents) { console.log("WALK:", source, ":", contents); })
// WALK: a.js : original a
// WALK: b.js : original b
// WALK: c.js : original c

SourceNode.prototype.join(sep)

SourceNodes を除く同様Array.prototype.join。このソース ノードの各子の間にセパレータを挿入します。

  • sep: セパレータ。
1
2
3
4
5
6
var lhs = new SourceNode(1, 2, "a.rs", "my_copy");
var operand = new SourceNode(3, 4, "a.rs", "=");
var rhs = new SourceNode(5, 6, "a.rs", "orig.clone()");

var node = new SourceNode(null, null, null, [ lhs, operand, rhs ]);
var joinedNode = node.join(" ");

SourceNode.prototype.replaceRight(パターン、置換)

String.prototype.replace一番右のソース スニペットを呼び出します。ソース ノードの末尾から空白をトリミングする場合などに便利です。

  • pattern: 置換するパターン。

  • replacement: パターンを置き換えるもの。

1
2
// Trim trailing white space.
node.replaceRight(/\s*$/, "");

SourceNode.prototype.toString()

このソース ノードの文字列表現を返します。ツリー上を移動し、さまざまなスニペットをすべて 1 つの文字列に連結します。

1
2
3
4
5
6
7
8
9
10
11
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toString()
// 'unodostresquatro'

SourceNode.prototype.toStringWithSourceMap([startOfSourceMap])

このソース ノードのツリーの文字列表現に加えて、生成されたソースと元のソースの間のすべてのマッピングを含む SourceMapGenerator を返します。

引数は と同じですnew SourceMapGenerator。

1
2
3
4
5
6
7
8
9
10
11
12
var node = new SourceNode(1, 2, "a.js", [
  new SourceNode(3, 4, "b.js", "uno"),
  "dos",
  [
    "tres",
    new SourceNode(5, 6, "c.js", "quatro")
  ]
]);

node.toStringWithSourceMap({ file: "my-output-file.js" })
// { code: 'unodostresquatro',
//   map: [object SourceMapGenerator] }
© Copyright 2012-2024 fibjs.org |サポートしてください