@ampproject/remapping - npm Package Compare versions

Comparing version 2.0.4 to 2.1.0

dist/remapping.umd.js

@@ -190,3 +190,3 @@ (function (global, factory) {
     function buildSourceMapTree(input, loader) {
-        const maps = asArray(input).map((m) => new traceMapping.TraceMap(m));
+        const maps = asArray(input).map((m) => new traceMapping.TraceMap(m, ''));
         const map = maps.pop();
@@ -199,3 +199,3 @@ for (let i = 0; i < maps.length; i++) {
         }
-        let tree = build(map, loader);
+        let tree = build(map, '', loader);
         for (let i = maps.length - 1; i >= 0; i--) {
@@ -206,15 +206,24 @@ tree = new SourceMapTree(maps[i], [tree]);
     }
-    function build(map, loader) {
+    function build(map, importer, loader) {
         const { resolvedSources, sourcesContent } = map;
         const children = resolvedSources.map((sourceFile, i) => {
-            const source = sourceFile || '';
+            // The loading context gives the loader more information about why this file is being loaded
+            // (eg, from which importer). It also allows the loader to override the location of the loaded
+            // sourcemap/original source, or to override the content in the sourcesContent field if it's
+            // an unmodified source file.
+            const ctx = {
+                importer,
+                source: sourceFile || '',
+                content: undefined,
+            };
             // Use the provided loader callback to retrieve the file's sourcemap.
             // TODO: We should eventually support async loading of sourcemap files.
-            const sourceMap = loader(source);
+            const sourceMap = loader(ctx.source, ctx);
+            const { source, content } = ctx;
             // If there is no sourcemap, then it is an unmodified source file.
             if (!sourceMap) {
-                // The source file's actual contents must be included in the sourcemap
-                // (done when generating the sourcemap) for it to be included as a
-                // sourceContent in the output sourcemap.
-                const sourceContent = sourcesContent ? sourcesContent[i] : null;
+                // The contents of this unmodified source file can be overridden via the loader context,
+                // allowing it to be explicitly null or a string. If it remains undefined, we fall back to
+                // the importing sourcemap's `sourcesContent` field.
+                const sourceContent = content !== undefined ? content : sourcesContent ? sourcesContent[i] : null;
                 return new OriginalSource(source, sourceContent);
@@ -224,3 +233,3 @@ }
             // source files.
-            return build(new traceMapping.TraceMap(sourceMap, source), loader);
+            return build(new traceMapping.TraceMap(sourceMap, source), source, loader);
         });
@@ -227,0 +236,0 @@ return new SourceMapTree(map, children);

dist/types/types.d.ts

@@ -29,3 +29,8 @@ interface SourceMapV3 {
 export declare type SourceMapInput = string | RawSourceMap | DecodedSourceMap;
-export declare type SourceMapLoader = (file: string) => SourceMapInput | null | undefined;
+export declare type LoaderContext = {
+    readonly importer: string;
+    source: string;
+    content: string | null | undefined;
+};
+export declare type SourceMapLoader = (file: string, ctx: LoaderContext) => SourceMapInput | null | undefined;
 export declare type Options = {
@@ -32,0 +37,0 @@ excludeContent?: boolean;

package.json

 {
   "name": "@ampproject/remapping",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "Remap sequential sourcemaps through transformations to point at the original source code",
@@ -5,0 +5,0 @@ "keywords": [

README.md

@@ -24,5 +24,15 @@ # @ampproject/remapping
   map: SourceMap | SourceMap[],
-  loader: (file: string) => (SourceMap | null | undefined),
+  loader: (file: string, ctx: LoaderContext) => (SourceMap | null | undefined),
   options?: { excludeContent: boolean, decodedMappings: boolean }
 ): SourceMap;
+
+// LoaderContext gives the loader the importing sourcemap, and the ability to override the "source"
+// location (where nested sources are resolved relative to, and where an original source exists),
+// and the ability to override the "content" of an original sourcemap for inclusion in the output
+// sourcemap.
+type LoaderContext = {
+ readonly importer: string;
+ source: string;
+ content: string | null | undefined;
+}
 ```
@@ -59,6 +69,9 @@
   minifiedTransformedMap,
-  (file) => {
+  (file, ctx) => {
 
     // The "transformed.js" file is an transformed file.
     if (file === 'transformed.js') {
+      // The root importer is empty.
+      console.assert(ctx.importer === '');
+
       return transformedMap;
@@ -69,2 +82,4 @@ }
     console.assert(file === 'helloworld.js');
+    // `transformed.js`'s sourcemap points into `helloworld.js`.
+    console.assert(ctx.importer === 'transformed.js');
     return null;
@@ -116,2 +131,72 @@ }
 
+### Advanced control of the loading graph
+
+#### `source`
+
+The `source` property can overridden to any value to change the location of the current load. Eg,
+for an original source file, it allows us to change the filepath to the original source regardless
+of what the sourcemap source entry says. And for transformed files, it allows us to change the
+resolving location for nested sources files of the loaded sourcemap.
+
+```js
+const remapped = remapping(
+  minifiedTransformedMap,
+  (file, ctx) => {
+
+    if (file === 'transformed.js') {
+      // We pretend the transformed.js file actually exists in the 'src/' directory. When the nested
+      // source files are loaded, they will now be relative to `src/`.
+      ctx.source = 'src/transformed.js';
+      return transformedMap;
+    }
+
+    console.assert(file === 'src/helloworld.js');
+    // We could futher change the source of this original file, eg, to be inside a nested directory
+    // itself. This will be reflected in the remapped sourcemap.
+    ctx.source = 'src/nested/transformed.js';
+    return null;
+  }
+);
+
+console.log(remapped);
+// {
+//   …,
+//   sources: ['src/nested/helloworld.js'],
+// };
+```
+
+
+#### `content`
+
+The `content` property can be overridden when we encounter an original source file. Eg, this allows
+you to manually provide the source content of the file regardless of whether the `sourcesContent`
+field is present in the parent sourcemap. Or, it can be set to `null` to remove the source content.
+
+```js
+const remapped = remapping(
+  minifiedTransformedMap,
+  (file, ctx) => {
+
+    if (file === 'transformed.js') {
+      // transformedMap does not include a `sourcesContent` field, so usually the remapped sourcemap
+      // would not include any `sourcesContent` values.
+      return transformedMap;
+    }
+
+    console.assert(file === 'helloworld.js');
+    // We can read the file to provide the source content.
+    ctx.content = fs.readFileSync(file, 'utf8');
+    return null;
+  }
+);
+
+console.log(remapped);
+// {
+//   …,
+//   sourcesContent: [
+//     'console.log("Hello world!")',
+//   ],
+// };
+```
+
 ### Options
@@ -118,0 +203,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

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

Improved metrics

Total package byte prevSize

64326

increased by7.53%

Lines of code

689

increased by3.45%

Number of lines in readme file

212

increased by66.93%

No dependency changes