Mappa di origine

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

Usa con Nodo

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 sorgente
- 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 le 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 SourceMapConsumeresempio rappresenta una mappa fonte analizzata che siamo in grado di eseguire una query per informazioni sulle posizioni dei file originali di dandogli una posizione di file nella sorgente generato.

SourceMapConsumer.initialize(opzioni)

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

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 di origine grezza (come una stringa che può essere JSON.parseo un oggetto) .Secondo le specifiche, le mappe di origine hanno i seguenti attributi:

version: Quale versione della specifica della mappa di origine sta seguendo questa mappa.
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 di origine costruita.

Quando SourceMapConsumernon sarà più utilizzato, è necessario chiamare il suo destroymetodo.

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

In alternativa, puoi utilizzare SourceMapConsumer.withper evitare di dover ricordare di chiamare destroy.

SourceMapConsumer.con

Costruisci un nuovo SourceMapConsumerfrom rawSourceMape sourceMapUrl (vedi il SourceMapConsumercostruttore per i dettagli. Quindi, invoca async function f(SourceMapConsumer) -> Tcon il consumer appena costruito, attendi il fcompletamento, chiama destroyil consumer e restituisci fil valore di ritorno di .

Non è necessario utilizzare il consumatore dopo aver fcompletato!

Utilizzando with, non è necessario ricordarsi di chiamare manualmente destroyl'utente, 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 di questa mappa di origine gestiti manualmente.

1consumer.destroy();

In alternativa, puoi utilizzare SourceMapConsumer.withper 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 di origine, riga e 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 nella sorgente generata.I numeri di riga in questa libreria sono basati su 1 (notare 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 in base 0.
bias: O SourceMapConsumer.GREATEST_LOWER_BOUNDo SourceMapConsumer.LEAST_UPPER_BOUNDSpecifica se restituire l'elemento più vicino che è minore o maggiore di quello che stiamo cercando, rispettivamente, 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 queste informazioni non sono disponibili.
line: il numero di riga nell'origine originale o null se queste informazioni non sono disponibili.Il numero di riga è in base 1.
column: il numero di colonna nell'origine originale o null se queste informazioni non sono disponibili.Il numero di colonna è in base 0.
name: l'identificatore originale o null se queste informazioni non sono disponibili.

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, la riga e le posizioni di 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 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: 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 di riga e colonna generate per l'origine, la riga e la colonna originali fornite. Se non viene fornita alcuna colonna, restituisce tutte le mappature corrispondenti alla riga che stiamo cercando o alla riga successiva più vicina con mappature. In caso contrario, restituisce tutte le mappature corrispondenti alla riga data 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: 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 vero se abbiamo il contenuto di origine incorporato per ogni fonte elencata nella mappa di origine, falso in caso contrario.

In altre parole, se questo metodo restituisce true, consumer.sourceContentFor(s)avrà esito positivo 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 l'origine specificata non viene trovato, viene generato un errore.Facoltativamente, passare truecome secondo parametro nullrestituito.

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)

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

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: o SourceMapConsumer.GENERATED_ORDERo SourceMapConsumer.ORIGINAL_ORDERSpecifica se si desidera eseguire l'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 di origine.
sourceRoot: una radice per tutti gli URL relativi in questa mappa di origine.
skipValidation: Opzionale. Quando true, disabilita la convalida delle mappature man mano che vengono aggiunte. Questo 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 SourceMapGeneratorda SourceMapConsumerun'istanza 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 alla colonna dell'origine generata per questa mappa di origine in fase di creazione. L'oggetto di mappatura dovrebbe avere le seguenti proprietà:

generated: un oggetto con le posizioni di riga e colonna generate.
original: un oggetto con le posizioni di riga e colonna originali.
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(sourceFile, sourceContent)

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

sourceFile l'URL del file sorgente 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 un SourceMap per un file di origine a 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 la mappa fornita.

sourceMapConsumer: SourceMap da applicare.
sourceFile: Facoltativo. Il nome del file di origine. Se omesso, verrà utilizzato sourceMapConsumer.file, se esiste. Altrimenti verrà generato un errore.
sourceMapPath: Facoltativo. Il nome dir del percorso alla SourceMap da applicare. Se relativo, è relativo alla SourceMap.

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

Se omesso, si presume che entrambi i SourceMap si trovino 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 interpolando e/o concatenando frammenti del codice sorgente JavaScript generato, mantenendo le informazioni di riga e colonna 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 di origine.

nuovo SourceNode([line, column, source[, chunk[, name]]])

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, 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 La SourceMap per il codice generato
relativePathIl percorso facoltativo a cui sourceMapConsumer devono 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(chunk)

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

chunk: un frammento 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 di origine.

chunk: un frammento 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)

Impostare il contenuto di origine per un file di origine. Questo sarà aggiunto alla SourceMapnel sourcesContentcampo.

sourceFile: Il nome del file sorgente
sourceContent: Il contenuto del file sorgente

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 snippet di JS e gli viene passato quel frammento 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 walking viene chiamata per ogni contenuto del file sorgente e gli vengono passati 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(set)

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 (schema, sostituzione)

Richiama String.prototype.replacelo snippet sorgente più a destra. Utile per tagliare lo spazio bianco dalla fine di un nodo sorgente, ecc.

pattern: il motivo da sostituire.
replacement: La cosa con cui sostituire il motivo.

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

SourceNode.prototype.toString()

Restituisce la rappresentazione di stringa di questo nodo di origine. Cammina sull'albero e concatena tutti i vari frammenti 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