素晴らしいコミュニティモジュール

ソースマップ

ビルドステータス

NPM

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

ノードで使用

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(オプション)

使用している場合SourceMapConsumerのNode.jsの外側を、Web上で例えば、それはどのようなURLから負荷に知っておく必要がありますlib/mappings.wasm。あなたが呼び出すことによって、それを通知しなければならないinitialize任意の構築前にSourceMapConsumer秒。

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

  • "lib/mappings.wasm":ファイルStringの URL を含む 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

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

f完了後にコンシューマーを使用してはなりません

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

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)すべてのソースのために成功しますsの中で consumer.sources

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

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

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

指定されたソースのソース コンテンツが見つからない場合は、エラーがスローされます。オプションで、代わりに返さtrueれるように 2 番目のパラメータとして渡し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 }

  • context: オプション. 指定された場合、このオブジェクトは呼び出されるthis たびに値になります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 のインスタンスは、増分的に構築されているソース マップを表します。

新しい 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(mapping)

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

  • 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 が存在する場合は、sourceMapConsumer.file が使用されます。そうでない場合は、エラーがスローされます。

  • sourceMapPath: オプション. 適用される SourceMap へのパスの dirname. 相対の場合は、SourceMap からの相対パスです。

    このパラメーターは、2 つの 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 生成されたコードの SourceMap

  • 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 つである配列。
1 2 3
node.add(" + "); node.add(otherNode); node.add([leftHandOperandNode, " + ", rightHandOperandNode]);

SourceNode.prototype.prepend(チャンク)

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

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

SourceNode.prototype.setSourceContent(sourceFile, sourceContent)

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

  • 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)

SourceNode のツリーをウォークオーバーします。ウォーキング関数はソース ファイルのコンテンツごとに呼び出され、ファイル名とソース コンテンツが渡されます。

  • 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)

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

  • 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] }