implement coffeescript.registerCompiled method (#5130)

* implement coffeescript._addSoucrse method

This method enables an external module to implement caching of
compilation results. When the compiled js source is loaded from cache,
the original coffee code should be added with this method in order to
enable the Error.prepareStackTrace below to correctly adjust the stack
trace for the corresponding file (the source map will be generated on
demand).

* replace _addSource with registerCompiled

* extract the logic from _compileFile into _compileRawFileContent

_compileFile takes care of logging the file and calls _compileRawFileContent

this way an external caching implementation which computes cache key
based on raw content of the sources file, can reuse the logic of
_compileFile and avoid having calling `fs.readFileSync` for the file
more twice in case of cache miss

* remove 'output' argument from registerCompiled

lib/coffeescript/coffeescript.js

@@ -4,7 +4,7 @@
   // on Node.js/V8, or to run CoffeeScript directly in the browser. This module
   // contains the main entry functions for tokenizing, parsing, and compiling
   // source CoffeeScript into JavaScript.
-  var FILE_EXTENSIONS, Lexer, SourceMap, base64encode, checkShebangLine, compile, formatSourcePosition, getSourceMap, helpers, lexer, packageJson, parser, sourceMaps, sources, withPrettyErrors,
+  var FILE_EXTENSIONS, Lexer, SourceMap, base64encode, checkShebangLine, compile, formatSourcePosition, getSourceMap, helpers, lexer, packageJson, parser, registerCompiled, sourceMaps, sources, withPrettyErrors,
     indexOf = [].indexOf;
 
   ({Lexer} = require('./lexer'));
@@ -74,6 +74,24 @@
   // Also save source maps if generated, in form of `(source)`: [`(source map)`].
   sourceMaps = {};
 
+  // This is exported to enable an external module to implement caching of
+  // compilation results. When the compiled js source is loaded from cache, the
+  // original coffee code should be added with this method in order to enable the
+  // Error.prepareStackTrace below to correctly adjust the stack trace for the
+  // corresponding file (the source map will be generated on demand).
+  exports.registerCompiled = registerCompiled = function(filename, source, sourcemap) {
+    if (sources[filename] == null) {
+      sources[filename] = [];
+    }
+    sources[filename].push(source);
+    if (sourcemap != null) {
+      if (sourceMaps[filename] == null) {
+        sourceMaps[filename] = [];
+      }
+      return sourceMaps[filename].push(sourcemap);
+    }
+  };
+
   // Compile CoffeeScript code to JavaScript, using the Coffee/Jison compiler.
 
   // If `options.sourceMap` is specified, then `options.filename` must also be
@@ -94,10 +112,6 @@
     generateSourceMap = options.sourceMap || options.inlineMap || (options.filename == null);
     filename = options.filename || '<anonymous>';
     checkShebangLine(filename, code);
-    if (sources[filename] == null) {
-      sources[filename] = [];
-    }
-    sources[filename].push(code);
     if (generateSourceMap) {
       map = new SourceMap;
     }
@@ -162,10 +176,6 @@
     }
     if (generateSourceMap) {
       v3SourceMap = map.generate(options, code);
-      if (sourceMaps[filename] == null) {
-        sourceMaps[filename] = [];
-      }
-      sourceMaps[filename].push(map);
     }
     if (options.transpile) {
       if (typeof options.transpile !== 'object') {
@@ -196,6 +206,7 @@
       sourceURL = `//# sourceURL=${(ref1 = options.filename) != null ? ref1 : 'coffeescript'}`;
       js = `${js}\n${sourceMapDataURI}\n${sourceURL}`;
     }
+    registerCompiled(filename, code, map);
     if (options.sourceMap) {
       return {
         js,

lib/coffeescript/index.js

@@ -152,9 +152,8 @@
     }
   }
 
-  CoffeeScript._compileFile = function(filename, options = {}) {
-    var answer, err, raw, stripped;
-    raw = fs.readFileSync(filename, 'utf8');
+  CoffeeScript._compileRawFileContent = function(raw, filename, options = {}) {
+    var answer, err, stripped;
     // Strip the Unicode byte order mark, if this file begins with one.
     stripped = raw.charCodeAt(0) === 0xFEFF ? raw.substring(1) : raw;
     options = Object.assign({}, options, {
@@ -175,6 +174,12 @@
     return answer;
   };
 
+  CoffeeScript._compileFile = function(filename, options = {}) {
+    var raw;
+    raw = fs.readFileSync(filename, 'utf8');
+    return CoffeeScript._compileRawFileContent(raw, filename, options);
+  };
+
   module.exports = CoffeeScript;
 
 }).call(this);

src/coffeescript.coffee

@@ -54,6 +54,20 @@ sources = {}
 # Also save source maps if generated, in form of `(source)`: [`(source map)`].
 sourceMaps = {}
 
+# This is exported to enable an external module to implement caching of
+# compilation results. When the compiled js source is loaded from cache, the
+# original coffee code should be added with this method in order to enable the
+# Error.prepareStackTrace below to correctly adjust the stack trace for the
+# corresponding file (the source map will be generated on demand).
+exports.registerCompiled = registerCompiled = (filename, source, sourcemap) ->
+
+  sources[filename] ?= []
+  sources[filename].push source
+
+  if sourcemap?
+    sourceMaps[filename] ?= []
+    sourceMaps[filename].push sourcemap
+
 # Compile CoffeeScript code to JavaScript, using the Coffee/Jison compiler.
 #
 # If `options.sourceMap` is specified, then `options.filename` must also be
@@ -75,8 +89,6 @@ exports.compile = compile = withPrettyErrors (code, options = {}) ->
 
   checkShebangLine filename, code
 
-  sources[filename] ?= []
-  sources[filename].push code
   map = new SourceMap if generateSourceMap
 
   tokens = lexer.tokenize code, options
@@ -126,8 +138,6 @@ exports.compile = compile = withPrettyErrors (code, options = {}) ->
 
   if generateSourceMap
     v3SourceMap = map.generate options, code
-    sourceMaps[filename] ?= []
-    sourceMaps[filename].push map
 
   if options.transpile
     if typeof options.transpile isnt 'object'
@@ -158,6 +168,8 @@ exports.compile = compile = withPrettyErrors (code, options = {}) ->
     sourceURL = "//# sourceURL=#{options.filename ? 'coffeescript'}"
     js = "#{js}\n#{sourceMapDataURI}\n#{sourceURL}"
 
+  registerCompiled filename, code, map
+
   if options.sourceMap
     {
       js

src/index.coffee

@@ -110,8 +110,8 @@ if require.extensions
       Use CoffeeScript.register() or require the coffeescript/register module to require #{ext} files.
       """
 
-CoffeeScript._compileFile = (filename, options = {}) ->
-  raw = fs.readFileSync filename, 'utf8'
+CoffeeScript._compileRawFileContent = (raw, filename, options = {}) ->
+
   # Strip the Unicode byte order mark, if this file begins with one.
   stripped = if raw.charCodeAt(0) is 0xFEFF then raw.substring 1 else raw
 
@@ -131,4 +131,9 @@ CoffeeScript._compileFile = (filename, options = {}) ->
 
   answer
 
+CoffeeScript._compileFile = (filename, options = {}) ->
+  raw = fs.readFileSync filename, 'utf8'
+
+  CoffeeScript._compileRawFileContent raw, filename, options
+
 module.exports = CoffeeScript