Mappa delle fonti

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

Utilizzare con Node

1
$ npm install source-map

Utilizzo 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
- Consumo di una mappa di origine
- Generazione di una mappa di origine
  - Con SourceNode (API di alto livello)
  - Con SourceMapGenerator (API di basso livello)
API

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 SourceMapConsumerrappresenta una mappa sorgente analizzata su cui possiamo interrogare informazioni sulle posizioni dei file originali assegnandole una posizione file nella sorgente generata.

SourceMapConsumer.initialize(opzioni)

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

L'oggetto opzioni ha le seguenti proprietà:

"lib/mappings.wasm": A Stringcontenente l'URL del lib/mappings.wasmfile.

1
2
3sourceMap.SourceMapConsumer.initialize({
  "lib/mappings.wasm": "https://example.com/source-map/lib/mappings.wasm"
});

nuovo SourceMapConsumer(rawSourceMap)

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

version: quale versione delle specifiche della mappa di origine sta seguendo questa mappa.
sources: una serie di URL ai file di origine originali.
names: un array di identificatori a cui è possibile fare riferimento tramite mappature individuali.
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.

La promessa del consumatore della mappa sorgente costruita viene restituita.

Quando SourceMapConsumernon verrà più utilizzato, sarà necessario richiamare il relativo destroymetodo.

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

In alternativa è possibile utilizzare SourceMapConsumer.withper evitare di doversi ricordare di chiamare destroy.

SourceMapConsumer.con

Costruisci un new SourceMapConsumerfrom rawSourceMapand sourceMapUrl (vedi il SourceMapConsumercostruttore per i dettagli. Quindi, invoca il async function f(SourceMapConsumer) -> Tcon il consumatore appena costruito, attendi fil completamento, chiama destroyil consumatore e restituisci fil valore restituito.

Non è necessario utilizzare il consumatore dopo fil completamento!

Utilizzando with, non è necessario ricordarsi di chiamare manualmente destroyil consumatore, poiché verrà chiamato automaticamente una volta fcompletato.

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 al consumatore della mappa di origine gestiti manualmente.

1consumer.destroy();

In alternativa è possibile utilizzare SourceMapConsumer.withper evitare di doversi ricordare di chiamare destroy.

SourceMapConsumer.prototype.computeColumnSpans()

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

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 sull'origine, sulla riga e sulla colonna originali per le posizioni di riga e colonna dell'origine generata fornite. L'unico argomento è un oggetto con le seguenti proprietà:

line: il numero di riga nell'origine generata. I numeri di riga in questa libreria sono in base 1 (nota che la specifica della mappa sorgente sottostante utilizza numeri di riga in base 0: questa libreria gestisce la traduzione).
column: il numero di colonna nell'origine generata. I numeri di colonna in questa libreria sono in base 0.
bias: Oppure SourceMapConsumer.GREATEST_LOWER_BOUNDo SourceMapConsumer.LEAST_UPPER_BOUNDSpecifica se restituire l'elemento più vicino che è rispettivamente più piccolo o più grande di quello che stiamo cercando, se non è possibile trovare l'elemento esatto 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 nell'origine originale o null se questa informazione non è disponibile. Il numero di riga è in base 1.
column: il numero di colonna nell'origine originale oppure 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(posizioneoriginale)

Restituisce le informazioni sulla riga e sulla colonna generate per l'origine originale, la riga e le posizioni delle colonne 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 è in base 1.
column: il numero di colonna nell'origine originale. Il numero di 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 è in base 1.
column: 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 generate sulla riga e sulla colonna per l'origine originale, la riga e la colonna fornita. Se non viene fornita alcuna colonna, restituisce tutte le mappature corrispondenti alla riga che stiamo cercando o alla riga successiva più vicina che presenta mappature. Altrimenti, restituisce tutte le mappature corrispondenti alla riga specificata e alla colonna che stiamo cercando o alla colonna successiva più vicina che presenta eventuali 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 è in base 1.
column: facoltativo.Il numero di colonna nell'origine originale.Il numero di 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 è in base 1.
column: 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 vero se abbiamo il contenuto sorgente incorporato per ogni fonte elencata nella mappa sorgente, falso altrimenti.

In altre parole, se questo metodo restituisce true, consumer.sourceContentFor(s)avrà successo per ogni origine sin 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 l'origine fornita. L'unico argomento è l'URL del file di origine originale.

Se il contenuto di origine per la fonte specificata non viene trovato, viene generato un errore. Facoltativamente, passa invece truecome secondo parametro da restituire.null

1
2
3
4
5
6
7
8
9
10
11consumer.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)

Itera su ogni mappatura tra una sorgente/linea/colonna originale e una linea/colonna generata in questa mappa sorgente.

callback: La funzione che viene chiamata con ogni mappatura. Le mappature hanno la forma{ source, generatedLine, generatedColumn, originalLine, originalColumn, name }
context: facoltativo.Se specificato, questo oggetto sarà il valore di this ogni volta che callbackviene chiamato.
order: Oppure SourceMapConsumer.GENERATED_ORDERo SourceMapConsumer.ORIGINAL_ORDERSpecifica se si desidera eseguire un'iterazione sulle mappature ordinate rispettivamente in base all'ordine di riga/colonna del file generato o all'ordine di origine/riga/colonna dell'originale 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 creata in modo incrementale.

nuovo SourceMapGenerator([startOfSourceMap])

Puoi passare un oggetto con le seguenti proprietà:

file: il nome file dell'origine generata a cui è associata questa mappa origine.
sourceRoot: una radice per tutti gli URL relativi in questa mappa di origine.
skipValidation: Opzionale. When true, disabilita la convalida delle mappature man mano che vengono aggiunte. Ciò può migliorare le prestazioni ma deve essere utilizzato 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 una nuova istanza SourceMapGeneratorda SourceMapConsumerun'istanza esistente.

sourceMapConsumerLa mappa delle fonti.

1
var generator = sourceMap.SourceMapGenerator.fromSourceMap(consumer);

SourceMapGenerator.prototype.addMapping(mappatura)

Aggiungi una singola mappatura dalla riga e colonna di origine originale alla riga e colonna dell'origine generata per questa mappa di origine in fase di creazione. 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 facoltativo per questa mappatura.

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

SourceMapGenerator.prototype.setSourceContent(filesorgente, contenutosorgente)

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

sourceFilel'URL del file sorgente originale.
sourceContentil contenuto del file sorgente.

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 di origine alla SourceMap. Ogni mappatura al file di origine fornito viene riscritta utilizzando la SourceMap fornita. Nota: la risoluzione per le mappature risultanti è il minimo di questa mappa e della mappa fornita.

sourceMapConsumer: la SourceMap da applicare.
sourceFile: Opzionale.Il nome file del file di origine.Se omesso, verrà utilizzato sourceMapConsumer.file, se esiste.In caso contrario verrà generato un errore.
sourceMapPath: Opzionale.Il dirname del percorso della SourceMap da applicare.Se relativo, è relativo alla 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 alla SourceMap.

Se omesso, si presuppone che entrambe le SourceMap siano nella stessa directory, quindi non è necessaria alcuna riscrittura (l'alimentazione '.'ha lo stesso effetto).

SourceMapGenerator.prototype.toString()

Rende la mappa di origine generata in una stringa.

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

SourceNode

I SourceNode forniscono un modo per astrarre, interpolare e/o concatenare frammenti di codice sorgente JavaScript generato, mantenendo le informazioni su righe e colonne associate tra tali frammenti 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.

new SourceNode([riga, colonna, sorgente[, pezzo[, 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 è in base 0.
source: il nome file della fonte originale; null se non viene fornito alcun nome file.
chunk: Facoltativo. Viene immediatamente passato a SourceNode.prototype.add, vedere di seguito.
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(codice, sourceMapConsumer[, relativePath])

Crea un SourceNode dal codice generato e un SourceMapConsumer.

code:Il codice generato
sourceMapConsumerSourceMap per il codice generato
relativePathIl percorso facoltativo a cui sourceMapConsumer dovrebbero essere relative le origini relative.

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

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

chunk: uno snippet di stringa di codice JS generato, un'altra istanza di SourceNodeo un array in cui ciascun membro è una di queste cose.

1
2
3
node.add(" + ");
node.add(otherNode);
node.add([leftHandOperandNode, " + ", rightHandOperandNode]);

SourceNode.prototype.prepend(pezzo)

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

chunk: uno snippet di stringa di codice JS generato, un'altra istanza di SourceNodeo un array in cui ciascun membro è una di queste cose.

1
node.prepend("/** Build Id: f783haef86324gf **/\n\n");

SourceNode.prototype.setSourceContent(filesorgente, contenutosorgente)

Imposta il contenuto di origine per un file di origine. Questo verrà aggiunto al SourceMapcampo 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 di camminata viene chiamata una volta per ogni snippet di JS e gli viene passato lo snippet e la posizione della riga/colonna della sorgente 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 di camminata viene chiamata per ogni contenuto del file di origine e gli vengono passati il nome del file e il contenuto di origine.

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

Come Array.prototype.jointranne che per SourceNodes. Inserisce il separatore tra ciascuno dei figli 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(modello, sostituzione)

Chiama String.prototype.replacelo snippet di origine più a destra. Utile per tagliare gli spazi bianchi dalla fine di un nodo di origine, ecc.

pattern: il disegno da sostituire.
replacement: L'oggetto con cui sostituire il pattern.

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

SourceNode.prototype.toString()

Restituisce la rappresentazione di stringa di questo nodo sorgente. Cammina sull'albero e concatena tutti i vari frammenti insieme in un'unica 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 di origine, più un SourceMapGenerator che contiene tutte le mappature tra le origini generate e quelle originali.

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

Guida allo sviluppo

Modulo base

oggetti incorporati

modulo comunitario