Mappa sorgente

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

Utilizzare con Nodo

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
- 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 di 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 è possibile eseguire query per informazioni sulle posizioni del file originale assegnandole una posizione del file nella fonte 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 l' initialize prima di costruire qualsiasi SourceMapConsumer .

L'oggetto opzioni ha le seguenti proprietà:

"lib/mappings.wasm" : una String contenente l'URL del file lib/mappings.wasm .

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

nuovo SourceMapConsumer (rawSourceMap)

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

version : quale versione delle specifiche della mappa di origine segue questa mappa.
sources : una matrice di URL per i file di origine originali.
names : una matrice di identificatori a cui è possibile fare riferimento da singole mappature.
sourceRoot : facoltativo, la radice dell'URL da cui tutte le fonti sono relative
sourcesContent : facoltativo, un array di contenuti dei file sorgente originali.
mappings : una stringa di VLQ base64 che contengono i mapping effettivi.
file : facoltativo, il nome file generato a cui è associata questa mappa di origine.

Viene restituita la promessa del consumatore di mappe di souce costruite.

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, è possibile utilizzare SourceMapConsumer.with per evitare la necessità di ricordarsi di chiamare destroy .

SourceMapConsumer.with

Costruisci un nuovo nuovo SourceMapConsumer da rawSourceMap e sourceMapUrl (vedi il costruttore SourceMapConsumer per i dettagli di Then, Invoke The. async function f(SourceMapConsumer) -> T con il consumatore appena costruito, attendi il completamento di f , chiama destroy ON Il consumatore e restituisci f valore di ritorno.

Non è necessario utilizzare il consumatore dopo aver completato f !

Usando with , non è necessario ricordare di chiamare manualmente il comando 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 al consumatore di questa mappa di origine gestiti manualmente.

1consumer.destroy();

In alternativa, è possibile utilizzare SourceMapConsumer.with per evitare la necessità di ricordarsi 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 sulla sorgente, sulla riga e sulla colonna originali per la posizione della riga e della colonna della sorgente generata. 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 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 è più piccolo o maggiore di quello che stiamo cercando, rispettivamente, se non è possibile trovare l'elemento esatto. L' SourceMapConsumer.GREATEST_LOWER_BOUND predefinita è SourceMapConsumer.GREATEST_LOWER_BOUND .

e un oggetto viene restituito 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 è basato su 1.
column : il numero di colonna nella fonte originale o null se questa informazione non è disponibile Il numero di colonna è basato su 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 sulla riga e sulla colonna generate per le posizioni di origine, riga e colonna originali fornite. L'unico argomento è un oggetto con le seguenti proprietà:

source : il nome del file della fonte originale.
line : il numero di riga nella fonte originale, il numero di riga è basato su 1.
column : il numero di colonna nella fonte originale, il numero di colonna è basato su 0.

e un oggetto viene restituito con le seguenti proprietà:

line : il numero di riga nell'origine generata o null Il numero di riga è basato su 1.
column : il numero di colonna nella fonte generata o null Il numero di colonna è basato su 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, la riga e la colonna originali fornite. Se non viene fornita alcuna colonna, restituisce tutti i mapping corrispondenti a una riga che stiamo cercando o alla riga successiva più vicina che ha dei mapping. 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 nella fonte originale, il numero di riga è basato su 1.
column : facoltativo Il numero di colonna nella fonte originale Il numero di colonna è basato su 0.

e viene restituita una matrice di oggetti, ciascuno con le seguenti proprietà:

line : il numero di riga nell'origine generata o null Il numero di riga è basato su 1.
column : il numero di colonna nella fonte generata o null Il numero di colonna è basato su 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 , 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 originale per l'origine fornita L'unico argomento è l'URL del file sorgente originale.

Se il contenuto di origine per la fonte data non viene trovato, viene generato un errore. In alternativa, passare true come secondo parametro per 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)

Scorrere su ciascuna mappatura tra una sorgente / linea / colonna originale e una linea / colonna generata in questa mappa di origine.

callback : la funzione chiamata con ciascun mapping I mapping hanno il formato { source, generatedLine, generatedColumn, originalLine, originalColumn, name }
context : facoltativo Se specificato, questo oggetto sarà il valore di this ogni volta che viene callback .
order : SourceMapConsumer.GENERATED_ORDER o SourceMapConsumer.ORIGINAL_ORDER Specifica se si desidera eseguire l'iterazione sui mapping ordinati rispettivamente per l'ordine di riga / colonna del file generato o l'ordine di origine / riga / colonna del SourceMapConsumer.GENERATED_ORDER . L' SourceMapConsumer.GENERATED_ORDER predefinita è 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])

È possibile passare un oggetto con le seguenti proprietà:

file : il nome file della fonte generata a cui è associata questa mappa sorgente.
sourceRoot : una radice per tutti gli URL relativi in questa mappa di origine.
skipValidation : Facoltativo. Se skipValidation true , disabilita la convalida dei mapping man mano che vengono aggiunti. Ciò può migliorare le prestazioni ma dovrebbe essere usato con discrezione, come ultima risorsa. Anche in questo caso, si dovrebbe evitare di usare 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 SourceMap.

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

SourceMapGenerator.prototype.addMapping (mappatura)

Aggiungere una singola mappatura dalla riga e dalla colonna di origine originali alla riga e alla colonna di origine generate per la creazione di questa mappa di origine. L'oggetto di mappatura deve avere le seguenti proprietà:

generated : un oggetto con le posizioni generate di linea e colonna.
original : un oggetto con le posizioni di linea e colonna originali.
source : il file sorgente originale (relativo a sourceRoot).
name : un nome token originale opzionale per questo mapping.

1
2
3
4
5generator.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 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 a SourceMap. Ogni mapping al file di origine fornito viene riscritto utilizzando la SourceMap fornita Nota: la risoluzione per i mapping risultanti è il minimo di questa mappa e della mappa fornita.

sourceMapConsumer : SourceMap da applicare.
sourceFile : facoltativo, il nome file del file sorgente, se omesso verrà utilizzato sourceMapConsumer.file, se presente, altrimenti verrà generato un errore.
sourceMapPath : facoltativo, il nome dir 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 è necessario riscrivere quei percorsi di origine relativi rispetto a SourceMap.
Se omesso, si presume che entrambe le SourceMap si trovino nella stessa directory, quindi non necessitano di alcuna riscrittura (fornire '.' Ha lo stesso effetto).

SourceMapGenerator.prototype.toString ()

Esegue il rendering della 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 SourceNodes forniscono un modo per astrarre sull'interpolazione e / o sulla concatenazione di snippet del codice sorgente JavaScript generato, mantenendo al contempo le informazioni di riga e colonna associate tra tali snippet e il codice sorgente originale. 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, oppure null se non è associato a una riga originale, il numero di riga è basato su 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 è basato su 0.
source : il nome del 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 opzionale 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 (pezzo)

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 queste cose.

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

SourceNode.prototype.prepend (pezzo)

Prepara 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 queste cose.

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

SourceNode.prototype.setSourceContent (sourceFile, sourceContent)

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

sourceFile : il nome file del file sorgente
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 sui suoi figli. La funzione walking viene chiamata una volta per ogni frammento di JS e viene passato lo snippet e la posizione della linea / colonna dell'origine associata originale.

fn : la funzione traversal.

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 di SourceNodes e viene chiamata la funzione walking per ciascun contenuto del file sorgente e viene passato il nome file e il contenuto sorgente.

fn : la funzione traversal.

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 tranne SourceNodes: inserisce il separatore tra i figli di questo nodo sorgente.

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.replace sullo snippet di origine String.prototype.replace destra. Utile per tagliare lo spazio bianco dalla fine di un nodo di origine, ecc.

pattern : il modello 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 in forma di stringa di questo nodo sorgente, cammina sopra 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 in formato stringa di questo albero dei nodi di origine, oltre a un SourceMapGenerator che contiene tutti i mapping tra le origini 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] }

Guida allo sviluppo

Modulo base

Oggetti incorporati

Modulo comunitario