Some missing source maps variants and options in TypeScript compiler

Please consider the following in your on going efforts:

From node-sass readme https://github.com/sass/node-sass/#sourcecomments:

omitSourceMapUrl

Type: Boolean Default: false

true values disable the inclusion of source map information in the output file.

sourceComments

Type: Boolean Default: false

true enables additional debugging information in the output file as CSS comments

sourceMapContents

Type: Boolean Default: false

true includes the contents in the source map information

sourceMapEmbed

Type: Boolean Default: false

true embeds the source map as a data URI

---

Notes:

omitSourceMapUrl sounds crazy, but there really are use cases when you want the transpiler to generate .map file while ignoring the sourceMappingURI in JS.

With sourceComments, it does not generate the real, cryptic source-maps, but instead put a comment on each line like /* Line: _, Column:_, File:_ */ in generated code pointing to the source file. Turning on this option has no effect on regular source-map; both options can be enabled and hence the map file produced also keep the line comments into consideration (both can be generated in parallel with little trickery, as you can preemptively determine where the debug comments will appear).

sourceMapContents: this embeds contents of all source (.ts) files in .map as contents array. The order of this array corresponds to sources array.

sourceMapEmbed: compiler generates the source-maps in-memory and instead of stamping out to .map file, it applies the base64 text encoding and append it as a value of sourceMappingURI.

[DanielRosenwasser]

omitSourceMapUrl sounds crazy, but there really are use cases

What are some of those use cases?

sourceComments [... puts] a comment on each line like /* Line: _, Column:_, File:_ */

While this is an interesting suggestion, it springs two questions:

• We may emit nodes that span multiple lines to a single line; how would this be dealt with?
• Why do users need this feature?
  • When do users find the sourcemaps coming short that they need to resort to this?
  • TypeScript is generally so close to the emitted JavaScript that I've always found myself able to easily Ctrl+F/⌘+F to find corresponding portions of a file, so does this buy users that much?

sourceMapContents: this embeds contents of all source (.ts) files in .map as contents array.

This sounds interesting; when is this handy?

sourceMapEmbed

I believe this is being covered in #2484.

[DanielRosenwasser]

Actually, sourceMapContents might also be part of #2484 (i.e. the inlineSources option) - @mhegazy, can you comment? If so, maybe we should call it sourceMapContents instead of inlineSources.

[tinganho]

With sourceComments, it does not generate the real, cryptic source-maps, but instead put a comment on each line like /* Line: , Column:, File:_ */ in generated code pointing to the source file. Turning on this option has no effect on regular source-map; both options can be enabled and hence the map file produced also keep the line comments into consideration (both can be generated in parallel with little trickery, as you can preemptively determine where the debug comments will appear).

I think this is not so useful anymore both for the SASS and TS project. It was a hack to support "source map" in browsers, before source map got standardized and used widely.

omitSourceMapUrl sounds crazy, but there really are use cases when you want the transpiler to generate .map file while ignoring the sourceMappingURI in JS.

I guess the use case here is by supporting referencing by HTTP header X-SourceMap: /path/to/file.js.map?

[mhegazy]

sourceMapEmbed is also covered by #2484.

[mhegazy]

sourceComments --> how would u uses this?

[DanielRosenwasser]

I guess the use case here is by supporting referencing by HTTP header X-SourceMap

Interesting; here's the relevant part of the spec:

The HTTP header should supply the source map URL reference as:

SourceMap: <url>

Note: previous revisions of this document recommended a header name of “X-SourceMap”. This is now deprecated; “SourceMap” is now expected.

Are there any actual advantages between one or the other though?

[tinganho]

@DanielRosenwasser I can't see any advantages.

I can't see any advantages.

then why even bother commenting here?

@tinganho, if you try hard, you can dismiss about any argument in the world. Try the other way around and find the reason and perhaps some solace in life. So take it easy!

---

Advantages:

sourceComments:

• It is unobtrusive way of presenting "debug info" unlike B64-VLQ (aka gibberish) encoded source-maps.
• Makes debugging easier for an average joe.

omitSourceMapUrl:

Zoon-out and think beyond web browser.

• Editor extensions. More specifically: Web Essentials (2013) calls node.exe internally and then makes use of "in-memory" result for "editor enhancements".
  • To answer the next probable question: Which editor enhancements?
    • F12 t Go to Definition.
    • Scroll preview pane when user scrolls source pane and vice versa.

If there is no such option to prevent omit sourceMappingURL generation, like present, then this is what happens:

• WE2013 provides an option to disable source-map generation.
• This options is not mutually exclusive with the other option: show preview pane, in which WE provides aforementioned enhancement features.
• If user has disables source-maps and enabled preview pane, WE compile files "with" source-map option enables and then after loading the mappings, it manually delete the source-mapping URL using regex. (two unwanted expensive operations: IO delete, and regexing large output file!)
• Note in case of TypeScript, WE2013 does not call node.exe but uses out of the box typescript compiler in VS. But still it need to delete the map file and use regex to delete source-map URL comment. So it is good to have this option around.

I think similar extensions for sublime are also doing the same thing.

Another user-case is, if you are building a production release, and you don't want to emit source-mapping-url, but still want to generate maps for future reference. This one is weak, and many will start advocating against it, but we use it in our environment and it helps!

sourceMapContents:

Your source files are inaccessible from network and browser can't reach it, enabling this option will prevent browser from loading individual sources.

sourceMapEmbed:

If you are the bundle-lover; and hate browser loading extra stuff after the fact, you will probably be the heaviest user of this option. It packs the mapping info into the generated code. Enabling source-map-content with this option even saves more file loading!

[DanielRosenwasser]

Let's all take it easy - I think we can agree that everybody here has quality in mind for TypeScript. 😄

---

sourceMapContents and sourceMapEmbed are planned, so we see the justification in that. Hopefully that'll be in our master branch soon.

---

I'm still not personally sold on sourceComments. This is analogous to requesting that a compiler emit assembly/IL with comments for corresponding lines of code because the debugger file format isn't understandable. Sure, it's great to get a sense of what the compiler is doing, but the utility of it falls short outside of mild curiosity - especially given that TypeScript tends to emit code that is canonical JavaScript, so your output should look decently readable anyway.

---

I'm admittedly on the fence on omitSourceMapUrl. I'd like to hear from @mhegazy about it.

[mhegazy]

regarding omitSourceMapURL i am still not clear about the value of adding this option. the web essential scenario you list above is better achieved using the compiler API to generate these. i think this is what you want to do generally. I will have to see more compelling scenarios to be convinced.

as for, sourceComments, we will have to decline this request. We put a lot of effort to make sure the output code is similar to the input as much as possible. This has been one of the TypeScript axioms from the beginning and still is. Even with renamed variables or generate temporary names, the compiler bases them on user defined variables to make sure the generate .js code is readable and recognizable. For debugging, TypeScript has supported source maps since 0.8 time. and almost all browsers and developer tools do support them as well; so i do not see the need for yet another form of mapping.

We put a lot of effort to make sure the output code is similar to the input as much as possible

The only exception being one cannot figure out to which file, certain portion of generated source belongs.

[mhegazy]

that is a different request then.. you want a comment with the original file name when using --out. is this accurate?

It is related to sourceComments.
For example, libsass produces this format: /* Line: _, Column:_, File:_ */ in generated CSS with source_comments=true, which captures all the require detail in a single snap.

[mhegazy]

Still not convinced :)