Mòdul de comunitat impressionant

Mapa font

Estat de la compilació

NPM

Es tracta d’una biblioteca per generar i consumir el format de mapa font descrit aquí .

Utilitzeu-lo amb Node

1
$ npm install source-map

Ús al 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>

Taula de continguts

Exemples

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

Guia detallada: compilació de JavaScript i depuració amb mapes d'origen

Amb SourceNode (API d'alt nivell)

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

Amb SourceMapGenerator (API de baix nivell)

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

Obteniu una referència al mòdul:

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

Una SourceMapConsumerinstància representa un mapa de fonts analitzades que podem consultar per obtenir informació sobre les posicions originals del fitxer donant-li una posició de fitxer a la font generada.

SourceMapConsumer.initialize (opcions)

Quan utilitzeu SourceMapConsumerfora de node.js, per exemple, al web, ha de saber de quina URL es carrega lib/mappings.wasm. Heu d'informar-ho trucant initializeabans de construir cap SourceMapConsumers.

L'objecte opcions té les propietats següents:

  • "lib/mappings.wasm": A Stringque conté l'URL del lib/mappings.wasmfitxer.
1 2 3
sourceMap.SourceMapConsumer.initialize({ "lib/mappings.wasm": "https://example.com/source-map/lib/mappings.wasm" });

nou SourceMapConsumer (rawSourceMap)

L'únic paràmetre és el mapa d'origen en brut (ja sigui com una cadena JSON.parseo objecte). Segons l'especificació, els mapes d'origen tenen els atributs següents:

  • version: Quina versió de l'especificació del mapa d'origen segueix aquest mapa.

  • sources: Un conjunt d'URL als fitxers font originals.

  • names: Un conjunt d'identificadors als quals es pot fer referència mitjançant mapes individuals.

  • sourceRoot: Opcional. L'arrel URL de la qual totes les fonts són relatives.

  • sourcesContent: Opcional: matriu de contingut dels fitxers font originals.

  • mappings: Una cadena de VLQ de base64 que contenen els mapatges reals.

  • file: Opcional. El nom de fitxer generat amb el qual s'associa aquest mapa font.

Es torna la promesa del consumidor del mapa de souce construït.

Quan SourceMapConsumerja no s'utilitzi, haureu de trucar al seu destroymètode.

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

Com a alternativa, podeu utilitzar SourceMapConsumer.withper evitar la necessitat de recordar trucar destroy.

SourceMapConsumer.with

Construïu un nou a SourceMapConsumerpartir de rawSourceMapi sourceMapUrl (vegeu el SourceMapConsumerconstructor per obtenir més detalls. A continuació, invoqueu-lo async function f(SourceMapConsumer) -> Tamb el consumidor acabat de construir, espereu fa completar-lo, crideu destroy-lo i torneu fel valor retornat.

No heu d’utilitzar el consumidor després d’ facabar-ho.

En utilitzar with-lo, no haureu de recordar trucar manualment destroyal consumidor, ja que es cridarà automàticament un cop ffinalitzada.

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

Allibereu les dades de wasm associades al consumidor d'aquest mapa font que es gestionen manualment.

1
consumer.destroy();

Com a alternativa, podeu utilitzar SourceMapConsumer.withper evitar la necessitat de recordar trucar destroy.

SourceMapConsumer.prototype.computeColumnSpans ()

Calculeu l'última columna per a cada assignació generada. La darrera columna és inclosa.

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)

Retorna la informació original de la font, la línia i la columna de les posicions de línia i columna de la font generada. L'únic argument és un objecte amb les propietats següents:

  • line: El número de línia de la font generada. Els números de línia d'aquesta biblioteca es basen en 1 (tingueu en compte que l'especificació del mapa de font subjacent utilitza números de línia basats en 0: aquesta biblioteca s'encarrega de la traducció).

  • column: El número de columna de la font generada. Els números de columna d'aquesta biblioteca es basen en 0.

  • bias: O SourceMapConsumer.GREATEST_LOWER_BOUNDo SourceMapConsumer.LEAST_UPPER_BOUNDEspecifica si s'ha de retornar l'element més proper que és menor o major que la que estem buscant, respectivament, si l'element exacte no es pot trobar als valors predeterminats .. SourceMapConsumer.GREATEST_LOWER_BOUND.

i es retorna un objecte amb les propietats següents:

  • source: El fitxer font original o nul si aquesta informació no està disponible.

  • line: El número de línia de la font original o nul si aquesta informació no està disponible. El número de línia es basa en 1.

  • column: El número de columna de la font original o nul si aquesta informació no està disponible. El número de columna es basa en 0.

  • name: L'identificador original o nul si aquesta informació no està disponible.

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)

Retorna la informació de línia i columna generada per a les posicions originals, de línia i de columna proporcionades. L'únic argument és un objecte amb les propietats següents:

  • source: El nom del fitxer de la font original.

  • line: El número de línia de la font original. El número de línia es basa en 1.

  • column: El número de columna de la font original. El número de columna es basa en 0.

i es retorna un objecte amb les propietats següents:

  • line: El número de línia de la font generada o nul. El número de línia es basa en 1.

  • column: El número de columna de la font generada o nul. El número de columna es basa en 0.

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

SourceMapConsumer.prototype.allGeneratedPositionsFor (originalPosition)

Retorna tota la informació de línia i columna generada per a la font, la línia i la columna originals proporcionades. Si no es proporciona cap columna, torna tots els mapatges corresponents a la línia que estem cercant o a la següent línia més propera que tingui assignacions. En cas contrari, torna totes les assignacions corresponents a la línia donada i a la columna que cerquem o a la següent columna més propera que tingui desplaçaments.

L'únic argument és un objecte amb les propietats següents:

  • source: El nom del fitxer de la font original.

  • line: El número de línia de la font original. El número de línia es basa en 1.

  • column: Opcional. El número de columna de la font original. El número de columna es basa en 0.

i es retorna una matriu d'objectes, cadascun amb les propietats següents:

  • line: El número de línia de la font generada o nul. El número de línia es basa en 1.

  • column: El número de columna de la font generada o nul. El número de columna es basa en 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 ()

Torneu a true si tenim el contingut font incrustat per a totes les fonts que apareixen al mapa d'origen, en cas contrari, és fals.

En altres paraules, si torna aquest mètode true, consumer.sourceContentFor(s)tindrà èxit per a totes les fonts sde consumer.sources.

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

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

Retorna el contingut original de la font proporcionada. L'únic argument és l'URL del fitxer font original.

Si no es troba el contingut font de la font donada, es produeix un error. Opcionalment, passeu truecom a segon paràmetre que hagi nulltornat.

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 (devolució de trucada, context, ordre)

Repeteix cada assignació entre una font / línia / columna original i una línia / columna generada en aquest mapa d'origen.

  • callback: La funció que s'anomena amb cada assignació. Les assignacions tenen la forma { source, generatedLine, generatedColumn, originalLine, originalColumn, name }

  • context: Opcional. Si s'especifica, aquest objecte serà el valor de this cada vegada que callbackes cridi.

  • order: O SourceMapConsumer.GENERATED_ORDERo SourceMapConsumer.ORIGINAL_ORDERespecifica si es desitja per repetir les assignacions ordenats per ordre de les columnes de l'arxiu generat línia / o ordre de font / línia / columna de l'original, respectivament. Per omissió és. 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

Una instància de SourceMapGenerator representa un mapa de fonts que es construeix de forma incremental.

nou SourceMapGenerator ([startOfSourceMap])

Podeu passar un objecte amb les propietats següents:

  • file: El nom de fitxer de la font generada a la qual s'associa aquest mapa d'origen.

  • sourceRoot: Una arrel per a tots els URL relatius d'aquest mapa d'origen.

  • skipValidation: Opcional. Quan truedesactiva la validació de mapes a mesura que s'afegeixen. Això pot millorar el rendiment, però s'ha d'utilitzar amb discreció com a últim recurs. Fins i tot llavors, si és possible, s'ha d'evitar l'ús d'aquest indicador quan s'executin proves.

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 una nova a SourceMapGeneratorpartir d'una SourceMapConsumerinstància existent .

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

SourceMapGenerator.prototype.addMapping (mapatge)

Afegiu una única assignació des de la línia i columna d'origen originals a la línia i columna de la font generada per al mapa d'origen que s'està creant. L'objecte de mapatge hauria de tenir les propietats següents:

  • generated: Un objecte amb les posicions de línia i columna generades.

  • original: Un objecte amb la posició original de la línia i de la columna.

  • source: El fitxer d'origen original (relatiu a l'arrel font).

  • name: Un nom de testimoni original opcional per a aquesta assignació.

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)

Definiu el contingut d'origen d'un fitxer d'origen original.

  • sourceFile l'URL del fitxer font original.

  • sourceContent el contingut del fitxer font.

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

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

Aplica un SourceMap per a un fitxer font al SourceMap. Cada assignació al fitxer font subministrat es reescriu mitjançant SourceMap subministrat. Nota: La resolució dels mapatges resultants és la mínima d’aquest mapa i del mapa subministrat.

  • sourceMapConsumer: El mapa font que s'ha d'aplicar.

  • sourceFile: Opcional. El nom del fitxer font. Si s'omet, s'utilitzarà sourceMapConsumer.file, si existeix. En cas contrari, es produirà un error.

  • sourceMapPath: Opcional. El nom de direcció del camí d'accés al SourceMap que s'ha d'aplicar. Si és relatiu, és relatiu al SourceMap.

    Aquest paràmetre és necessari quan els dos mapes de font no es troben al mateix directori i el mapa de fonts que s'ha d'aplicar conté camins d'origen relatius. Si és així, aquests camins d'origen relatius s'han de reescriure en relació amb el mapa de fonts.

    Si s'omet, s'assumeix que ambdós SourceMaps es troben al mateix directori, de manera que no necessiten cap reescriptura (el subministrament '.'té el mateix efecte).

SourceMapGenerator.prototype.toString ()

Representa el mapa d'origen que es genera a una cadena.

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 proporciona una manera de fer abstractes sobre la interpolació i / o concatenació de fragments de codi font generat de JavaScript, tot mantenint la informació de línia i columna associada entre aquests fragments i el codi font original. Això és útil ja que la representació intermèdia final que podria utilitzar un compilador abans de publicar-la el mapa generat de JS i font.

nou SourceNode ([línia, columna, font [, tros [, nom]]])

  • line: El número de línia original associat amb aquest node d'origen o nul si no està associat amb una línia original. El número de línia es basa en 1.

  • column: El número de columna original associat amb aquest node d'origen o nul si no està associat amb una columna original. El número de columna es basa en 0.

  • source: El nom de fitxer de la font original; nul si no es proporciona cap nom de fitxer.

  • chunk: Opcional. Es passa immediatament a SourceNode.prototype.add, vegeu més avall.

  • name: Opcional. L'identificador original.

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

Crea un SourceNode a partir del codi generat i un SourceMapConsumer.

  • code: El codi generat

  • sourceMapConsumer El SourceMap per al codi generat

  • relativePathEl camí opcional al qual sourceMapConsumer haurien de ser relatius els recursos relatius.

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 (tros)

Afegiu un tros de JS generat a aquest node d'origen.

  • chunk: Un fragment de cadena de codi JS generat, una altra instància de SourceNodeo una matriu on cada membre és una d'aquestes coses.
1 2 3
node.add(" + "); node.add(otherNode); node.add([leftHandOperandNode, " + ", rightHandOperandNode]);

SourceNode.prototype.prepend (tros)

Prepara un tros de JS generat a aquest node d'origen.

  • chunk: Un fragment de cadena de codi JS generat, una altra instància de SourceNodeo una matriu on cada membre és una d'aquestes coses.
1
node.prepend("/** Build Id: f783haef86324gf **/\n\n");

SourceNode.prototype.setSourceContent (sourceFile, sourceContent)

Establir el continguts de programari per a un arxiu d'origen. Això s'afegeix a la SourceMapal sourcesContentcamp.

  • sourceFile: El nom del fitxer font

  • sourceContent: El contingut del fitxer font

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

SourceNode.prototype.walk (fn)

Passeu per sobre de l'arbre de fragments de JS en aquest node i els seus fills. La funció de marxa s'anomena una vegada per a cada fragment de JS i es passa aquest fragment i la ubicació de línia / columna de la font original associada.

  • fn: La funció de recorregut.
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)

Passeu per sobre de l'arbre de SourceNodes. La funció de caminada es diu per a cada contingut del fitxer font i es transmet el nom del fitxer i el contingut font.

  • fn: La funció de recorregut.
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)

Igual Array.prototype.joinexcepte SourceNodes. Insereix el separador entre cadascun dels fills del node font.

  • sep: El separador.
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 (patró, substitució)

Truqueu String.prototype.replaceal fragment de font més a la dreta. Útil per retallar espais en blanc des del final d’un node d’origen, etc.

  • pattern: El patró a substituir.

  • replacement: La cosa per substituir el patró.

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

SourceNode.prototype.toString ()

Torneu la representació de cadena d'aquest node d'origen. Passeja per l'arbre i concatena tots els fragments en una sola cadena.

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

Retorna la representació de cadena d'aquest arbre de nodes d'origen, més un SourceMapGenerator que conté totes les assignacions entre les fonts generades i les originals.

Els arguments són els mateixos que els de 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] }