@parcel/source-map - npm Package Compare versions

Comparing version 2.0.0-alpha.4.10 to 2.0.0-alpha.4.11

dist/node.js

@@ -22,2 +22,14 @@ "use strict";
 
+  toBuffer() {
+    return this.sourceMapInstance.toBuffer();
+  }
+
+  findClosestMapping(line, column) {
+    let mapping = this.sourceMapInstance.findClosestMapping(line, column);
+    let v = this.indexedMappingToStringMapping(mapping);
+    return v;
+  }
+
+  delete() {}
+
   static generateEmptyMap(sourceName, sourceContent, lineOffset = 0) {
@@ -24,0 +36,0 @@ let map = new NodeSourceMap();

dist/SourceMap.js

@@ -15,2 +15,21 @@ "use strict";
 class SourceMap {
+  /**
+   * Generates an empty map from the provided fileName and sourceContent
+   *
+   * @param sourceName path of the source file
+   * @param sourceContent content of the source file
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   */
+  static generateEmptyMap(sourceName, sourceContent, lineOffset = 0) {
+    throw new Error("SourceMap.generateEmptyMap() must be implemented when extending SourceMap");
+  }
+  /**
+   * Generates an empty map from the provided fileName and sourceContent
+   *
+   * @param sourceName path of the source file
+   * @param sourceContent content of the source file
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   */
+
+
   addEmptyMap(sourceName, sourceContent, lineOffset = 0) {
@@ -20,3 +39,13 @@ this.sourceMapInstance.addEmptyMap(sourceName, sourceContent, lineOffset);
   }
+  /**
+   * Appends raw VLQ mappings to the sourcemaps
+   *
+   * @param mappings a string containing the Base64 encoded VLQ Mappings
+   * @param sources an array of source filepaths used in the raw sourcemap
+   * @param names an array of the names used in the raw sourcemap
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   * @param columnOffset  an offset that gets added to the sourceColumn index of each mapping
+   */
 
+
   addRawMappings(mappings, sources, names, lineOffset = 0, columnOffset = 0) {
@@ -26,3 +55,12 @@ this.sourceMapInstance.addRawMappings(mappings, sources, names, lineOffset, columnOffset);
   }
+  /**
+   * Appends a flatbuffer to this sourcemap
+   * Note: The flatbuffer buffer should be generated by this library
+   *
+   * @param buffer the sourcemap buffer that should get appended to this sourcemap
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   * @param columnOffset  an offset that gets added to the sourceColumn index of each mapping
+   */
 
+
   addBufferMappings(buffer, lineOffset = 0, columnOffset = 0) {
@@ -32,3 +70,12 @@ this.sourceMapInstance.addBufferMappings(buffer, lineOffset, columnOffset);
   }
+  /**
+   * Appends a Mapping object to this sourcemap
+   * Note: line numbers start at 1 due to mozilla's source-map library
+   *
+   * @param mapping the mapping that should be appended to this sourcemap
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   * @param columnOffset  an offset that gets added to the sourceColumn index of each mapping
+   */
 
+
   addIndexedMapping(mapping, lineOffset = 0, columnOffset = 0) {
@@ -39,3 +86,14 @@ let hasValidOriginal = mapping.original && typeof mapping.original.line === "number" && !isNaN(mapping.original.line) && typeof mapping.original.column === "number" && !isNaN(mapping.original.column);
     hasValidOriginal ? mapping.original.column : -1, mapping.source || "", mapping.name || "");
-  } // line numbers start at 1 so we have the same api as `source-map` by mozilla
+  }
+  /**
+   * Appends an array of Mapping objects to this sourcemap
+   * This is useful when improving performance if a library provides the non-serialised mappings
+   *
+   * Note: This is only faster if they generate the serialised map lazily
+   * Note: line numbers start at 1 due to mozilla's source-map library
+   *
+   * @param mappings an array of mapping objects
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   * @param columnOffset  an offset that gets added to the sourceColumn index of each mapping
+   */
 
@@ -50,35 +108,96 @@
   }
+  /**
+   * Appends a name to the sourcemap
+   *
+   * @param name the name that should be appended to the names array
+   * @returns the index of the added name in the names array
+   */
 
+
   addName(name) {
     return this.sourceMapInstance.addName(name);
   }
+  /**
+   * Appends an array of names to the sourcemap's names array
+   *
+   * @param names an array of names to add to the sourcemap
+   * @returns an array of indexes of the names in the sourcemap's names array, has the same order as the provided names array
+   */
 
+
   addNames(names) {
     return names.map(n => this.addName(n));
   }
+  /**
+   * Appends a source to the sourcemap's sources array
+   *
+   * @param source a filepath that should be appended to the sources array
+   * @returns the index of the added source filepath in the sources array
+   */
 
+
   addSource(source) {
     return this.sourceMapInstance.addSource(source);
   }
+  /**
+   * Appends an array of sources to the sourcemap's sources array
+   *
+   * @param sources an array of filepaths which should sbe appended to the sources array
+   * @returns an array of indexes of the sources that have been added to the sourcemap, returned in the same order as provided in the argument
+   */
 
+
   addSources(sources) {
     return sources.map(s => this.addSource(s));
   }
+  /**
+   * Get the index in the sources array for a certain source file filepath
+   *
+   * @param source the filepath of the source file
+   */
 
+
   getSourceIndex(source) {
     return this.sourceMapInstance.getSourceIndex(source);
   }
+  /**
+   * Get the source file filepath for a certain index of the sources array
+   *
+   * @param index the index of the source in the sources array
+   */
 
+
   getSource(index) {
     return this.sourceMapInstance.getSource(index);
   }
+  /**
+   * Get the index in the names array for a certain name
+   *
+   * @param name the name you want to find the index of
+   */
 
+
   getNameIndex(name) {
     return this.sourceMapInstance.getNameIndex(name);
   }
+  /**
+   * Get the name for a certain index of the names array
+   *
+   * @param index the index of the name in the names array
+   */
 
+
   getName(index) {
     return this.sourceMapInstance.getName(index);
   }
+  /**
+   * Convert a Mapping object that uses indexes for name and source to the actual value of name and source
+   *
+   * Note: This is only used internally, should not be used externally and will probably eventually get
+   * handled directly in C++ for improved performance
+   *
+   * @param index the Mapping that should get converted to a string-based Mapping
+   */
 
+
   indexedMappingToStringMapping(mapping) {
@@ -100,9 +219,13 @@ if (!mapping) return mapping;
   }
+  /**
+   * Remaps original positions from this map to the ones in the provided map
+   *
+   * This works by finding the closest generated mapping in the provided map
+   * to original mappings of this map and remapping those to be the original
+   * mapping of the provided map.
+   *
+   * @param buffer exported SourceMap as a flatbuffer
+   */
 
-  findClosestMapping(line, column) {
-    let mapping = this.sourceMapInstance.findClosestMapping(line, column);
-    return this.indexedMappingToStringMapping(mapping);
-  } // Remaps original positions from this map to the ones in the provided map
 
-
   extends(buffer) {
@@ -112,15 +235,55 @@ this.sourceMapInstance.extends(buffer);
   }
+  /**
+   * Returns an object with mappings, sources and names
+   * This should only be used for tests, debugging and visualising sourcemaps
+   *
+   * Note: This is a fairly slow operation
+   */
 
+
   getMap() {
     return this.sourceMapInstance.getMap();
   }
+  /**
+   * Searches through the sourcemap and returns a mapping that is close to the provided generated line and column
+   *
+   * @param line the line in the generated code (starts at 1)
+   * @param column the column in the generated code (starts at 0)
+   */
 
+
+  findClosestMapping(line, column) {
+    throw new Error("SourceMap.findClosestMapping() must be implemented when extending SourceMap");
+  }
+  /**
+   * Returns a flatbuffer that represents this sourcemap, used for caching
+   */
+
+
   toBuffer() {
-    return this.sourceMapInstance.toBuffer();
+    throw new Error("SourceMap.toBuffer() must be implemented when extending SourceMap");
   }
+  /**
+   * Returns a serialised map using VLQ Mappings
+   */
 
+
   toVLQ() {
     return this.sourceMapInstance.stringify();
   }
+  /**
+   * A function that has to be called at the end of the SourceMap's lifecycle to ensure all memory and native bindings get de-allocated
+   */
 
+
+  delete() {
+    throw new Error("SourceMap.delete() must be implemented when extending SourceMap");
+  }
+  /**
+   * Returns a serialised map
+   *
+   * @param options options used for formatting the serialised map
+   */
+
+
   async stringify(options) {
@@ -127,0 +290,0 @@ return (0, _utils.partialVlqMapToSourceMap)(this.toVLQ(), options);

dist/utils.js

@@ -17,2 +17,22 @@ "use strict";
 
+function normalisePath(filepath) {
+  return filepath.replace(/\\/g, "/");
+}
+
+function relatifyPath(filepath, rootDir) {
+  // Sourcemaps are made for web, so replace backslashes with regular slashes
+  filepath = normalisePath(filepath); // Make root paths relative to the rootDir
+
+  if (filepath[0] === "/") {
+    filepath = normalisePath(_path.default.relative(rootDir, filepath));
+  } // Prefix relative paths with ./ as it makes it more clear and probably prevents issues
+
+
+  if (filepath[0] !== ".") {
+    filepath = `./${filepath}`;
+  }
+
+  return filepath;
+}
+
 async function partialVlqMapToSourceMap(map, {
@@ -24,13 +44,18 @@ fs,
   rootDir,
-  inlineMap,
   format = "string"
 }) {
-  map.version = 3;
-  map.file = file;
-  map.sourceRoot = sourceRoot;
+  let root = normalisePath(rootDir || "/");
+  let resultMap = { ...map,
+    version: 3,
+    file,
+    sourceRoot
+  };
+  resultMap.sources = resultMap.sources.map(sourceFilePath => {
+    return relatifyPath(sourceFilePath, root);
+  });
 
   if (inlineSources && fs) {
-    map.sourcesContent = await Promise.all(map.sources.map(async sourceName => {
+    resultMap.sourcesContent = await Promise.all(resultMap.sources.map(async sourceName => {
       try {
-        return await fs.readFile(_path.default.resolve(rootDir || "", sourceName), "utf-8");
+        return await fs.readFile(_path.default.resolve(root, sourceName), "utf-8");
       } catch (e) {
@@ -40,15 +65,15 @@ return null;
     }));
-  } // Handle deprecated option
+  }
 
+  if (format === "inline" || format === "string") {
+    let stringifiedMap = JSON.stringify(resultMap);
 
-  if (inlineMap) {
-    format = "inline";
-  }
+    if (format === "inline") {
+      return generateInlineMap(stringifiedMap);
+    }
 
-  if (format === "inline" || format === "string") {
-    let stringifiedMap = JSON.stringify(map);
-    return format === "inline" ? generateInlineMap(stringifiedMap) : stringifiedMap;
+    return stringifiedMap;
   }
 
-  return map;
+  return resultMap;
 }

dist/wasm.js

@@ -69,2 +69,4 @@ "use strict";
     this.sourceMapInstance.addRawMappings(mappings, sourcesVector, namesVector, lineOffset, columnOffset);
+    sourcesVector.delete();
+    namesVector.delete();
     return this;
@@ -79,3 +81,5 @@ }
     } else {
-      return this.indexedMappingToStringMapping(patchMapping(mapping));
+      let m = { ...mapping
+      };
+      return this.indexedMappingToStringMapping(patchMapping(m));
     }
@@ -101,2 +105,10 @@ }
 
+  toBuffer() {
+    return new Uint8Array(this.sourceMapInstance.toBuffer());
+  }
+
+  delete() {
+    this.sourceMapInstance.delete();
+  }
+
 }
@@ -103,0 +115,0 @@

package.json

 {
   "name": "@parcel/source-map",
-  "version": "2.0.0-alpha.4.10",
+  "version": "2.0.0-alpha.4.11",
   "main": "./dist/node.js",
@@ -14,3 +14,3 @@ "browser": "./dist/wasm-browser.js",
     "benchmark:wasm": "cross-env BACKEND=wasm node ./bench/run",
-    "compile-wasm": "make",
+    "compile-wasm": "make -j4",
     "transpile": "babel ./src/*.js --out-dir ./dist && flow-copy-source -v src dist",
@@ -22,4 +22,5 @@ "prebuild": "prebuildify -t 10.20.1 --napi --strip --tag-libc",
     "prepublish": "npm run transpile",
-    "lint": "prettier --write src/*.js",
-    "typecheck": "flow"
+    "lint": "prettier --write bench/run.js src/*.js",
+    "typecheck": "flow",
+    "compile-schema": "./flatc --cpp -o ./src ./src/sourcemap-schema.fbs"
   },
@@ -26,0 +27,0 @@ "files": [

README.md

 # Parcel's source-map library
 
-A purpose build source-maps library for combining and manipulating source-maps.
+A source map library purpose-build for the Parcel bundler with a focus on fast combining and manipulating of source-maps.
 
-For just reading source-maps, this library does not outperform the probably more stable and well-known package `source-map` by Mozilla.
+## How to use this library?
 
-## Why did we write this library
+If you want to use this library in your project or are looking to write a Parcel plugin with sourcemap support this should explain how you could get started.
 
+For more information we have added doctypes to each function of the SourceMap class so you can have an in depth look at what everything does.
+
+### Creating a SourceMap instance
+
+You can create a sourcemap from another sourcemap or by creating it one mapping at a time.
+
+#### Creating from existing sourcemap
+
+To create a sourcemap from an existing sourcemap you have to ensure it is a JS Object first by asking for the object version from whichever transpiler you're running or by parsing the serialised map using `JSON.parse`.
+
+After this you can call the function `addRawMappings(mappings, sources, names, lineOffset, columnOffset)` this function takes in the parameters `mappings`, `sources`, `names`, `lineOffset` and `columnOffset`. These correspond to the mappings, sources and names fields in the sourcemap object. The line and column offset are optional parameters used for offsetting the generated line and column. (this can be used when post-processing or wrapping the code linked to the sourcemap, in Parcel this is used when combining maps).
+
+Example:
+
+```JS
+import SourceMap from '@parcel/source-map';
+
+const RAW_SOURCEMAP = {
+  version: 3,
+  file: "helloworld.js",
+  sources: ["helloworld.coffee"],
+  names: [],
+  mappings: "AAAA;AAAA,EAAA,OAAO,CAAC,GAAR,CAAY,aAAZ,CAAA,CAAA;AAAA",
+};
+
+let sourcemap = new SourceMap();
+sourcemap.addRawMappings(RAW_SOURCEMAP.mappings, RAW_SOURCEMAP.sources, RAW_SOURCEMAP.names);
+
+// This function removes the underlying references in the native code
+sourcemap.delete();
+```
+
+#### Creating a sourcemap one mapping at a time
+
+If you want to use this library to create a sourcemap from scratch you can, for this you can call the `addIndexedMapping(mapping, lineOffset, columnOffset)` function.
+
+Example:
+
+```JS
+import SourceMap from '@parcel/source-map';
+
+let sourcemap = new SourceMap();
+
+// Add a single mapping
+sourcemap.addIndexedMapping({
+  generated: {
+    // line index starts at 1
+    line: 1,
+    // column index starts at 0
+    column: 4
+  },
+  original: {
+    // line index starts at 1
+    line: 1,
+    // column index starts at 0
+    column: 4
+  },
+  source: 'index.js',
+  // Name is optional
+  name: 'A'
+});
+
+// This function removes the underlying references in the native code
+sourcemap.delete();
+```
+
+### Caching
+
+For caching sourcemaps we have a `toBuffer()` function which returns a buffer that can be saved on disk for later use and combining sourcemaps very quickly.
+
+You can add a cached map to a SourceMap instance using the `addBufferMappings(buffer, lineOffset, columnOffset)` function, where you can also offset the generated line and column.
+
+## Inspiration and purpose
+
+### Why did we write this library
+
 Parcel is a performance concious bundler, and therefore we like to optimise Parcel's performance as much as possible.
@@ -15,6 +91,36 @@
 
-## Compile flatbuffer schema
+### Previous works and inspiration
 
+Without these libraries this library wouldn't be as good as it is today. We've inspired and optimised our code using ideas and patterns used inside these libraries as well as used it to figure out how sourcemaps should be handled properly.
+
+- [source-map by Mozilla](https://github.com/mozilla/source-map)
+- [source-map-mappings by Nick Fitzgerald](https://github.com/fitzgen/source-map-mappings)
+- [sourcemap-codec by Rich Harris](https://github.com/Rich-Harris/sourcemap-codec)
+
+## Contributing to this library
+
+All contributions to this library are welcome as is with any part of Parcel's vast collection of libraries and tools.
+
+### Prerequisites
+
+To be able to build and work on this project you need to have the following tools installed:
+
+- [`emscripten`](https://emscripten.org/docs/getting_started/downloads.html)
+- [`node.js`](https://nodejs.org/en/)
+- `make`
+
+### Building the project
+
+For development purposes you might want to build or rebuild the project, for this you need to build the N-API module, JS Code and WASM bindings.
+
+To do this run the following commmand: (for more information about this you can have a look in `./package.json` and `./Makefile`)
+
+```shell
+yarn transpile && yarn build:dev && make clean && make all
+```
+
+### Compile flatbuffer schema
+
 ```bash
-cd ./src && ../flatc --cpp ./sourcemap-schema.fbs && cd ..
+./flatc -o ./src --cpp ./src/sourcemap-schema.fbs
 ```

src/node.js

@@ -19,2 +19,14 @@ // @flow
 
+  toBuffer(): Buffer {
+    return this.sourceMapInstance.toBuffer();
+  }
+
+  findClosestMapping(line: number, column: number): ?IndexedMapping<string> {
+    let mapping = this.sourceMapInstance.findClosestMapping(line, column);
+    let v = this.indexedMappingToStringMapping(mapping);
+    return v;
+  }
+
+  delete() {}
+
   static generateEmptyMap(
@@ -21,0 +33,0 @@ sourceName: string,

src/SourceMap.js

@@ -15,2 +15,26 @@ // @flow
 
+  /**
+   * Generates an empty map from the provided fileName and sourceContent
+   *
+   * @param sourceName path of the source file
+   * @param sourceContent content of the source file
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   */
+  static generateEmptyMap(
+    sourceName: string,
+    sourceContent: string,
+    lineOffset: number = 0
+  ): SourceMap {
+    throw new Error(
+      "SourceMap.generateEmptyMap() must be implemented when extending SourceMap"
+    );
+  }
+
+  /**
+   * Generates an empty map from the provided fileName and sourceContent
+   *
+   * @param sourceName path of the source file
+   * @param sourceContent content of the source file
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   */
   addEmptyMap(
@@ -20,3 +44,3 @@ sourceName: string,
     lineOffset: number = 0
-  ) {
+  ): SourceMap {
     this.sourceMapInstance.addEmptyMap(sourceName, sourceContent, lineOffset);
@@ -26,2 +50,11 @@ return this;
 
+  /**
+   * Appends raw VLQ mappings to the sourcemaps
+   *
+   * @param mappings a string containing the Base64 encoded VLQ Mappings
+   * @param sources an array of source filepaths used in the raw sourcemap
+   * @param names an array of the names used in the raw sourcemap
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   * @param columnOffset  an offset that gets added to the sourceColumn index of each mapping
+   */
   addRawMappings(
@@ -33,3 +66,3 @@ mappings: string,
     columnOffset: number = 0
-  ) {
+  ): SourceMap {
     this.sourceMapInstance.addRawMappings(
@@ -45,2 +78,10 @@ mappings,
 
+  /**
+   * Appends a flatbuffer to this sourcemap
+   * Note: The flatbuffer buffer should be generated by this library
+   *
+   * @param buffer the sourcemap buffer that should get appended to this sourcemap
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   * @param columnOffset  an offset that gets added to the sourceColumn index of each mapping
+   */
   addBufferMappings(
@@ -50,3 +91,3 @@ buffer: Buffer,
     columnOffset: number = 0
-  ) {
+  ): SourceMap {
     this.sourceMapInstance.addBufferMappings(buffer, lineOffset, columnOffset);
@@ -56,2 +97,10 @@ return this;
 
+  /**
+   * Appends a Mapping object to this sourcemap
+   * Note: line numbers start at 1 due to mozilla's source-map library
+   *
+   * @param mapping the mapping that should be appended to this sourcemap
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   * @param columnOffset  an offset that gets added to the sourceColumn index of each mapping
+   */
   addIndexedMapping(
@@ -61,3 +110,3 @@ mapping: IndexedMapping<string>,
     columnOffset?: number = 0
-  ) {
+  ): void {
     let hasValidOriginal =
@@ -82,3 +131,13 @@ mapping.original &&
 
-  // line numbers start at 1 so we have the same api as `source-map` by mozilla
+  /**
+   * Appends an array of Mapping objects to this sourcemap
+   * This is useful when improving performance if a library provides the non-serialised mappings
+   *
+   * Note: This is only faster if they generate the serialised map lazily
+   * Note: line numbers start at 1 due to mozilla's source-map library
+   *
+   * @param mappings an array of mapping objects
+   * @param lineOffset an offset that gets added to the sourceLine index of each mapping
+   * @param columnOffset  an offset that gets added to the sourceColumn index of each mapping
+   */
   addIndexedMappings(
@@ -88,3 +147,3 @@ mappings: Array<IndexedMapping<string>>,
     columnOffset?: number = 0
-  ) {
+  ): SourceMap {
     for (let mapping of mappings) {
@@ -96,2 +155,8 @@ this.addIndexedMapping(mapping, lineOffset, columnOffset);
 
+  /**
+   * Appends a name to the sourcemap
+   *
+   * @param name the name that should be appended to the names array
+   * @returns the index of the added name in the names array
+   */
   addName(name: string): number {
@@ -101,2 +166,8 @@ return this.sourceMapInstance.addName(name);
 
+  /**
+   * Appends an array of names to the sourcemap's names array
+   *
+   * @param names an array of names to add to the sourcemap
+   * @returns an array of indexes of the names in the sourcemap's names array, has the same order as the provided names array
+   */
   addNames(names: Array<string>): Array<number> {
@@ -106,2 +177,8 @@ return names.map((n) => this.addName(n));
 
+  /**
+   * Appends a source to the sourcemap's sources array
+   *
+   * @param source a filepath that should be appended to the sources array
+   * @returns the index of the added source filepath in the sources array
+   */
   addSource(source: string): number {
@@ -111,2 +188,8 @@ return this.sourceMapInstance.addSource(source);
 
+  /**
+   * Appends an array of sources to the sourcemap's sources array
+   *
+   * @param sources an array of filepaths which should sbe appended to the sources array
+   * @returns an array of indexes of the sources that have been added to the sourcemap, returned in the same order as provided in the argument
+   */
   addSources(sources: Array<string>): Array<number> {
@@ -116,2 +199,7 @@ return sources.map((s) => this.addSource(s));
 
+  /**
+   * Get the index in the sources array for a certain source file filepath
+   *
+   * @param source the filepath of the source file
+   */
   getSourceIndex(source: string): number {
@@ -121,2 +209,7 @@ return this.sourceMapInstance.getSourceIndex(source);
 
+  /**
+   * Get the source file filepath for a certain index of the sources array
+   *
+   * @param index the index of the source in the sources array
+   */
   getSource(index: number): string {
@@ -126,2 +219,7 @@ return this.sourceMapInstance.getSource(index);
 
+  /**
+   * Get the index in the names array for a certain name
+   *
+   * @param name the name you want to find the index of
+   */
   getNameIndex(name: string): number {
@@ -131,2 +229,7 @@ return this.sourceMapInstance.getNameIndex(name);
 
+  /**
+   * Get the name for a certain index of the names array
+   *
+   * @param index the index of the name in the names array
+   */
   getName(index: number): string {
@@ -136,2 +239,10 @@ return this.sourceMapInstance.getName(index);
 
+  /**
+   * Convert a Mapping object that uses indexes for name and source to the actual value of name and source
+   *
+   * Note: This is only used internally, should not be used externally and will probably eventually get
+   * handled directly in C++ for improved performance
+   *
+   * @param index the Mapping that should get converted to a string-based Mapping
+   */
   indexedMappingToStringMapping(
@@ -156,9 +267,12 @@ mapping: ?IndexedMapping<number>
 
-  findClosestMapping(line: number, column: number): ?IndexedMapping<string> {
-    let mapping = this.sourceMapInstance.findClosestMapping(line, column);
-    return this.indexedMappingToStringMapping(mapping);
-  }
-
-  // Remaps original positions from this map to the ones in the provided map
-  extends(buffer: Buffer) {
+  /**
+   * Remaps original positions from this map to the ones in the provided map
+   *
+   * This works by finding the closest generated mapping in the provided map
+   * to original mappings of this map and remapping those to be the original
+   * mapping of the provided map.
+   *
+   * @param buffer exported SourceMap as a flatbuffer
+   */
+  extends(buffer: Buffer): SourceMap {
     this.sourceMapInstance.extends(buffer);
@@ -168,2 +282,8 @@ return this;
 
+  /**
+   * Returns an object with mappings, sources and names
+   * This should only be used for tests, debugging and visualising sourcemaps
+   *
+   * Note: This is a fairly slow operation
+   */
   getMap(): ParsedMap {
@@ -173,6 +293,26 @@ return this.sourceMapInstance.getMap();
 
+  /**
+   * Searches through the sourcemap and returns a mapping that is close to the provided generated line and column
+   *
+   * @param line the line in the generated code (starts at 1)
+   * @param column the column in the generated code (starts at 0)
+   */
+  findClosestMapping(line: number, column: number): ?IndexedMapping<string> {
+    throw new Error(
+      "SourceMap.findClosestMapping() must be implemented when extending SourceMap"
+    );
+  }
+
+  /**
+   * Returns a flatbuffer that represents this sourcemap, used for caching
+   */
   toBuffer(): Buffer {
-    return this.sourceMapInstance.toBuffer();
+    throw new Error(
+      "SourceMap.toBuffer() must be implemented when extending SourceMap"
+    );
   }
 
+  /**
+   * Returns a serialised map using VLQ Mappings
+   */
   toVLQ(): VLQMap {
@@ -182,5 +322,21 @@ return this.sourceMapInstance.stringify();
 
-  async stringify(options: SourceMapStringifyOptions) {
+  /**
+   * A function that has to be called at the end of the SourceMap's lifecycle to ensure all memory and native bindings get de-allocated
+   */
+  delete() {
+    throw new Error(
+      "SourceMap.delete() must be implemented when extending SourceMap"
+    );
+  }
+
+  /**
+   * Returns a serialised map
+   *
+   * @param options options used for formatting the serialised map
+   */
+  async stringify(
+    options: SourceMapStringifyOptions
+  ): Promise<string | VLQMap> {
     return partialVlqMapToSourceMap(this.toVLQ(), options);
   }
 }

src/types.js

@@ -39,6 +39,3 @@ // @flow
   format?: "inline" | "string" | "object",
-
-  // !Deprecated
-  inlineMap?: boolean,
   ...
 };

src/utils.js

@@ -6,3 +6,3 @@ // @flow
 
-export function generateInlineMap(map: string) {
+export function generateInlineMap(map: string): string {
   return `data:application/json;charset=utf-8;base64,${Buffer.from(
@@ -13,2 +13,23 @@ map
 
+function normalisePath(filepath: string): string {
+  return filepath.replace(/\\/g, "/");
+}
+
+function relatifyPath(filepath: string, rootDir: string): string {
+  // Sourcemaps are made for web, so replace backslashes with regular slashes
+  filepath = normalisePath(filepath);
+
+  // Make root paths relative to the rootDir
+  if (filepath[0] === "/") {
+    filepath = normalisePath(path.relative(rootDir, filepath));
+  }
+
+  // Prefix relative paths with ./ as it makes it more clear and probably prevents issues
+  if (filepath[0] !== ".") {
+    filepath = `./${filepath}`;
+  }
+
+  return filepath;
+}
+
 export async function partialVlqMapToSourceMap(
@@ -22,18 +43,22 @@ map: VLQMap,
     rootDir,
-    inlineMap,
     format = "string",
   }: SourceMapStringifyOptions
-) {
-  map.version = 3;
-  map.file = file;
-  map.sourceRoot = sourceRoot;
+): Promise<VLQMap | string> {
+  let root = normalisePath(rootDir || "/");
+  let resultMap = {
+    ...map,
+    version: 3,
+    file,
+    sourceRoot,
+  };
 
+  resultMap.sources = resultMap.sources.map((sourceFilePath) => {
+    return relatifyPath(sourceFilePath, root);
+  });
+
   if (inlineSources && fs) {
-    map.sourcesContent = await Promise.all(
-      map.sources.map(async (sourceName) => {
+    resultMap.sourcesContent = await Promise.all(
+      resultMap.sources.map(async (sourceName) => {
         try {
-          return await fs.readFile(
-            path.resolve(rootDir || "", sourceName),
-            "utf-8"
-          );
+          return await fs.readFile(path.resolve(root, sourceName), "utf-8");
         } catch (e) {
@@ -46,15 +71,11 @@ return null;
 
-  // Handle deprecated option
-  if (inlineMap) {
-    format = "inline";
-  }
-
   if (format === "inline" || format === "string") {
-    let stringifiedMap = JSON.stringify(map);
-    return format === "inline"
-      ? generateInlineMap(stringifiedMap)
-      : stringifiedMap;
+    let stringifiedMap = JSON.stringify(resultMap);
+    if (format === "inline") {
+      return generateInlineMap(stringifiedMap);
+    }
+    return stringifiedMap;
   }
 
-  return map;
+  return resultMap;
 }

src/wasm.js

@@ -75,2 +75,6 @@ // @flow
     );
+
+    sourcesVector.delete();
+    namesVector.delete();
+
     return this;
@@ -84,3 +88,4 @@ }
     } else {
-      return this.indexedMappingToStringMapping(patchMapping(mapping));
+      let m = { ...mapping };
+      return this.indexedMappingToStringMapping(patchMapping(m));
     }
@@ -109,2 +114,10 @@ }
   }
+
+  toBuffer(): Uint8Array {
+    return new Uint8Array(this.sourceMapInstance.toBuffer());
+  }
+
+  delete() {
+    this.sourceMapInstance.delete();
+  }
 }
@@ -111,0 +124,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Uses eval

Supply chain risk

Package uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Uses eval

Supply chain risk

Package uses dynamic code execution (e.g., eval()), which is a dangerous practice. This can prevent the code from running in certain environments and increases the risk that the code may contain exploits or malicious behavior.

Found 1 instance in 1 package

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1506952

increased by7.02%

Lines of code

1545

increased by62.97%

Number of low quality alerts

2

decreased by-33.33%

Number of lines in readme file

126

increased by530%

Worsened metrics

Number of medium supply chain risk alerts

17

increased by13.33%

No dependency changes