Fantastico modulo della community

Mappa di origine

Stato build

NPM

Questa è una libreria per generare e utilizzare il formato della mappa sorgente descritto qui .

Utilizzare con Node

1
$ npm install source-map

Utilizzare sul Web

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>

Sommario

Esempi

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

Guida approfondita:compilazione in JavaScript e debug con mappe di origine

Con SourceNode (API di alto livello)

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

Con SourceMapGenerator (API di basso livello)

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

Ottieni un riferimento al modulo:

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

Un'istanza SourceMapConsumer rappresenta una mappa di origine analizzata che possiamo interrogare per informazioni sulle posizioni del file originale dandogli una posizione del file nell'origine generata.

SourceMapConsumer.initialize (opzioni)

Quando si utilizza SourceMapConsumer al di fuori di node.js, ad esempio sul Web, è necessario sapere da quale URL caricare lib/mappings.wasm . È necessario informarlo chiamando initialize prima di costruire qualsiasi SourceMapConsumer s.

L'oggetto opzioni ha le seguenti proprietà:

  • "lib/mappings.wasm" : una String contenente l'URL del file lib/mappings.wasm .
1 2 3
sourceMap.SourceMapConsumer.initialize({ "lib/mappings.wasm": "https://example.com/source-map/lib/mappings.wasm" });

nuovo SourceMapConsumer (rawSourceMap)

L'unico parametro è la mappa sorgente non JSON.parse (sia come stringa che può essere JSON.parse , o come oggetto). Secondo le specifiche, le mappe sorgente hanno i seguenti attributi:

  • version : quale versione della mappa di origine specifica questa mappa sta seguendo.

  • sources : un array di URL ai file di origine originali.

  • names : un array di identificatori a cui è possibile fare riferimento da singole mappature.

  • sourceRoot : facoltativo, la radice dell'URL da cui tutte le origini sono relative.

  • sourcesContent : facoltativo. Un array di contenuti dei file di origine originali.

  • mappings : una stringa di VLQ base64 che contengono le mappature effettive.

  • file : facoltativo Il nome del file generato a cui è associata questa mappa di origine.

Viene restituita la promessa del consumatore della mappa sorgente costruita.

Quando SourceMapConsumer non verrà più utilizzato, è necessario chiamare il suo metodo di destroy .

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

In alternativa, puoi usare SourceMapConsumer.with per evitare di dover ricordare di chiamare destroy .

SourceMapConsumer.with

Costruisci un nuovo nuovo SourceMapConsumer da rawSourceMap e sourceMapUrl (vedi The SourceMapConsumer constructor per i dettagli su Then, richiama The. async function f(SourceMapConsumer) -> T con The New Constructed Consumer, l'attesa per il completamento di f , Chiama destroy ON The Consumer e restituisci f valore di ritorno di.

Non è necessario utilizzare il consumatore dopo che f completa!

Usando with , non è necessario ricordarsi di chiamare manualmente destroy sul consumatore, poiché verrà chiamato automaticamente una volta completato 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 ()

Liberare i dati wasm associati a questo consumatore della mappa sorgente che vengono gestiti manualmente.

1
consumer.destroy();

In alternativa, puoi usare SourceMapConsumer.with per evitare di dover ricordare di chiamare destroy .

SourceMapConsumer.prototype.computeColumnSpans ()

Calcola l'ultima colonna per ogni mappatura generata. L'ultima colonna è inclusa.

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)

Restituisce le informazioni su origine, riga e colonna originali per le posizioni di riga e colonna dell'origine generata. L'unico argomento è un oggetto con le seguenti proprietà:

  • line : il numero di riga nella sorgente generata. I numeri di riga in questa libreria sono basati su 1 (si noti che la specifica della mappa di origine sottostante utilizza numeri di riga basati su 0 - questa libreria gestisce la traduzione).

  • column : il numero di colonna nell'origine generata. I numeri di colonna in questa libreria sono basati su 0.

  • bias : SourceMapConsumer.GREATEST_LOWER_BOUND o SourceMapConsumer.LEAST_UPPER_BOUND . Specifica se restituire l'elemento più vicino che è rispettivamente più piccolo o maggiore di quello che stiamo cercando, se l'elemento esatto non può essere trovato. Il valore predefinito è SourceMapConsumer.GREATEST_LOWER_BOUND .

e viene restituito un oggetto con le seguenti proprietà:

  • source : il file di origine originale o null se questa informazione non è disponibile.

  • line : il numero di riga nella fonte originale o null se questa informazione non è disponibile. Il numero di riga è in base 1.

  • column : il numero di colonna nell'origine originale o null se questa informazione non è disponibile. Il numero di colonna è in base 0.

  • name : l'identificatore originale o null se questa informazione non è disponibile.

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)

Restituisce le informazioni di riga e colonna generate per l'origine originale, la riga e le posizioni di colonna fornite. L'unico argomento è un oggetto con le seguenti proprietà:

  • source : il nome del file della fonte originale.

  • line : il numero di riga nell'origine originale. Il numero di riga è a base 1.

  • column : il numero della colonna nell'origine originale. Il numero della colonna è in base 0.

e viene restituito un oggetto con le seguenti proprietà:

  • line : il numero di riga nell'origine generata o null. Il numero di riga è a base 1.

  • column : il numero di colonna nell'origine generata o null. Il numero di colonna è in base 0.

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

SourceMapConsumer.prototype.allGeneratedPositionsFor (originalPosition)

Restituisce tutte le informazioni sulla riga e sulla colonna generate per l'origine originale, la riga e la colonna fornite. Se non viene fornita alcuna colonna, restituisce tutte le mappature corrispondenti alla riga che stiamo cercando o alla riga successiva più vicina che ha delle mappature. Altrimenti, restituisce tutte le mappature corrispondenti alla riga data e alla colonna che stiamo cercando o alla colonna successiva più vicina che ha degli offset.

L'unico argomento è un oggetto con le seguenti proprietà:

  • source : il nome del file della fonte originale.

  • line : il numero di riga nell'origine originale. Il numero di riga è a base 1.

  • column : facoltativo. Il numero della colonna nell'origine originale. Il numero della colonna è in base 0.

e viene restituito un array di oggetti, ciascuno con le seguenti proprietà:

  • line : il numero di riga nell'origine generata o null. Il numero di riga è a base 1.

  • column : il numero di colonna nell'origine generata o null. Il numero di colonna è in base 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 ()

Restituisce true se abbiamo il contenuto sorgente incorporato per ogni sorgente elencata nella mappa sorgente, altrimenti false.

In altre parole, se questo metodo restituisce true , allora consumer.sourceContentFor(s) avrà esito positivo per ogni sorgente s in consumer.sources .

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

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

Restituisce il contenuto di origine originale per la fonte fornita. L'unico argomento è l'URL del file di origine originale.

Se il contenuto sorgente per la sorgente data non viene trovato, viene generato un errore. Facoltativamente, passare true come secondo parametro per avere invece restituito 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, contesto, ordine)

Ripeti ogni mappatura tra una sorgente / riga / colonna originale e una riga / colonna generata in questa mappa sorgente.

  • callback : la funzione chiamata con ogni mappatura. Le mappature hanno il formato { source, generatedLine, generatedColumn, originalLine, originalColumn, name }

  • context : Opzionale Se specificato, questo oggetto avrà il valore di this ogni volta che viene chiamato il callback .

  • order : SourceMapConsumer.GENERATED_ORDER o SourceMapConsumer.ORIGINAL_ORDER . Specifica se si desidera iterare sui mapping ordinati rispettivamente in base all'ordine di riga / colonna del file generato o all'ordine di origine / riga / colonna SourceMapConsumer.GENERATED_ORDER . Il SourceMapConsumer.GENERATED_ORDER predefinito è 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

Un'istanza di SourceMapGenerator rappresenta una mappa di origine che viene costruita in modo incrementale.

nuovo SourceMapGenerator ([startOfSourceMap])

Puoi passare un oggetto con le seguenti proprietà:

  • file : il nome del file dell'origine generata a cui è associata questa mappa di origine.

  • sourceRoot : una radice per tutti gli URL relativi in ​​questa mappa di origine.

  • skipValidation : Opzionale. Se true , disabilita la convalida delle mappature man mano che vengono aggiunte. Ciò può migliorare le prestazioni ma dovrebbe essere usato con discrezione, come ultima risorsa. Anche in questo caso, si dovrebbe evitare di utilizzare questo flag durante l'esecuzione dei test, se possibile.

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

SourceMapGenerator.fromSourceMap (sourceMapConsumer)

Crea un nuovo SourceMapGenerator da un'istanza SourceMapConsumer esistente.

  • sourceMapConsumer Il SourceMap.
1
var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer);

SourceMapGenerator.prototype.addMapping (mapping)

Aggiungi una singola mappatura dalla riga e colonna di origine originale alla riga e colonna della fonte generata per questa mappa di origine da creare. L'oggetto di mappatura deve avere le seguenti proprietà:

  • generated : un oggetto con le posizioni di riga e colonna generate.

  • original : un oggetto con le posizioni originali di riga e colonna.

  • source : il file sorgente originale (relativo a sourceRoot).

  • name : un nome token originale opzionale per questa mappatura.

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)

Imposta il contenuto di origine per un file di origine originale.

  • sourceFile l'URL del file di origine originale.

  • sourceContent il contenuto del file di origine.

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

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

Applica una SourceMap per un file sorgente a SourceMap. Ogni mappatura al file sorgente fornito viene riscritta utilizzando la SourceMap fornita. Nota: La risoluzione per le mappature risultanti è il minimo di questa mappa e della mappa fornita.

  • sourceMapConsumer : SourceMap da applicare.

  • sourceFile : Facoltativo. Il nome del file di origine. Se omesso, verrà utilizzato sourceMapConsumer.file, se esiste. In caso contrario verrà generato un errore.

  • sourceMapPath : Facoltativo. Il nome della directory del percorso di SourceMap da applicare. Se relativo, è relativo a SourceMap.

    Questo parametro è necessario quando le due SourceMap non si trovano nella stessa directory e la SourceMap da applicare contiene percorsi di origine relativi. In tal caso, tali percorsi di origine relativi devono essere riscritti rispetto a SourceMap.

    Se omesso, si presume che entrambe le SourceMap si trovino nella stessa directory, quindi non è necessaria alcuna riscrittura (la fornitura di '.' Ha lo stesso effetto).

SourceMapGenerator.prototype.toString ()

Visualizza la mappa di origine generata in una stringa.

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

I SourceNodes forniscono un modo per astrarre sugli snippet interpolanti e / o concatenati del codice sorgente JavaScript generato, mantenendo le informazioni di riga e colonna associate tra questi snippet e il codice sorgente originale. Ciò è utile come rappresentazione intermedia finale che un compilatore potrebbe utilizzare prima dell'output il JS generato e la mappa sorgente.

nuovo SourceNode ([riga, colonna, sorgente [, blocco [, nome]]])

  • line : il numero di riga originale associato a questo nodo di origine o null se non è associato a una riga originale. Il numero di riga è in base 1.

  • column : il numero di colonna originale associato a questo nodo di origine o null se non è associato a una colonna originale. Il numero di colonna è a base 0.

  • source : il nome file della fonte originale; null se non viene fornito alcun nome file.

  • chunk : opzionale. Viene immediatamente passato a SourceNode.prototype.add , vedi sotto.

  • name : facoltativo. L'identificatore originale.

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 (code, sourceMapConsumer [, relativePath])

Crea un SourceNode dal codice generato e un SourceMapConsumer.

  • code : il codice generato

  • sourceMapConsumer SourceMap per il codice generato

  • relativePath Il percorso facoltativo a sourceMapConsumer devono essere relative le origini relative in 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 (blocco)

Aggiungi un pezzo di JS generato a questo nodo di origine.

  • chunk : uno snippet di stringa del codice JS generato, un'altra istanza di SourceNode o un array in cui ogni membro è una di quelle cose.
1 2 3
node.add(" + "); node.add(otherNode); node.add([leftHandOperandNode, " + ", rightHandOperandNode]);

SourceNode.prototype.prepend (chunk)

Anteponi un pezzo di JS generato a questo nodo sorgente.

  • chunk : uno snippet di stringa del codice JS generato, un'altra istanza di SourceNode o un array in cui ogni membro è una di quelle cose.
1
node.prepend("/** Build Id: f783haef86324gf **/\n\n");

SourceNode.prototype.setSourceContent (sourceFile, sourceContent)

Imposta il contenuto di origine per un file di origine. Questo verrà aggiunto a SourceMap nel campo sourcesContent .

  • sourceFile : il nome del file di origine

  • sourceContent : il contenuto del file di origine

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

SourceNode.prototype.walk (fn)

Cammina sull'albero degli snippet JS in questo nodo e nei suoi figli. La funzione walking viene chiamata una volta per ogni frammento di JS e viene passato quello snippet e la posizione della riga / colonna della sua origine associata originale.

  • fn : la funzione di attraversamento.
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)

Cammina sull'albero dei SourceNodes La funzione walking viene chiamata per ogni contenuto del file sorgente e viene passato il nome del file e il contenuto sorgente.

  • fn : la funzione di attraversamento.
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 (settembre)

Come Array.prototype.join eccezione di SourceNodes. Inserisce il separatore tra ciascuno degli elementi figlio di questo nodo di origine.

  • sep : il separatore.
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 (pattern, sostituzione)

Chiama String.prototype.replace sullo snippet di origine più a destra. Utile per tagliare lo spazio bianco dalla fine di un nodo di origine, ecc.

  • pattern : il pattern da sostituire.

  • replacement : la cosa con cui sostituire il modello.

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

SourceNode.prototype.toString ()

Restituisce la rappresentazione di stringa di questo nodo sorgente. Attraversa l'albero e concatena tutti i vari frammenti insieme in una stringa.

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

Restituisce la rappresentazione di stringa di questo albero di nodi sorgente, più un SourceMapGenerator che contiene tutte le mappature tra le sorgenti generate e quelle originali.

Gli argomenti sono gli stessi di quelli del 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] }