Cleanup and comments for process and importer

lib/extract.js

@@ -1,7 +1,7 @@
 const Promise = require('bluebird');
 const sass = require('node-sass');
 const { loadCompiledFiles, loadCompiledFilesSync } = require('./load');
-const { processCompiledFiles } = require('./process');
+const { processFiles } = require('./process');
 const { makeImporter, makeSyncImporter } = require('./importer');
 
 Promise.promisifyAll(sass);
@@ -73,7 +73,7 @@ function extract(rendered, { compileOptions = {} } = {}) {
 
   return loadCompiledFiles(includedFiles, entryFilename, compileOptions.data)
   .then(compiledFiles => {
-    const extractions = processCompiledFiles(compiledFiles);
+    const extractions = processFiles(compiledFiles);
     const importer = makeImporter(extractions);
     const extractionCompileOptions = makeExtractionCompileOptions(compileOptions, entryFilename, extractions, importer);
 
@@ -92,7 +92,7 @@ function extractSync(rendered, { compileOptions = {} } = {}) {
   const { entryFilename, includedFiles } = getRenderedStats(rendered);
 
   const compiledFiles = loadCompiledFilesSync(includedFiles, entryFilename, compileOptions.data);
-  const extractions = processCompiledFiles(compiledFiles);
+  const extractions = processFiles(compiledFiles);
   const importer = makeSyncImporter(extractions);
   const extractionCompileOptions = makeExtractionCompileOptions(compileOptions, entryFilename, extractions, importer);
 

lib/importer.js

@@ -1,5 +1,8 @@
 const path = require('path');
 
+/**
+ * Search for the likely absolute path from a relative path using known paths from compilation
+ */
 function findAbsolutePath(extractions, relativePath) {
   const filenames = Object.keys(extractions);
 
@@ -12,10 +15,15 @@ function findAbsolutePath(extractions, relativePath) {
   return relativePath;
 }
 
+/**
+ * Get the absolute file path for a relative @import like './sub/file.scsss'
+ * If the @import is made from a raw data section a best guess path is returned
+ */
 function getImportAbsolutePath(extractions, url, prev) {
   let absolutePath = path.join(path.dirname(prev), url);
   let extension = path.extname(prev);
 
+  // Ensure that both @import 'file' and @import 'file.scss' is mapped correctly
   if(path.extname(absolutePath) !== extension) {
     absolutePath += extension;
   }
@@ -27,13 +35,20 @@ function getImportAbsolutePath(extractions, url, prev) {
   return absolutePath;
 }
 
+/**
+ * Get the resulting source and path for a given @import request
+ */
 function getImportResult(extractions, url, prev) {
   const absolutePath = getImportAbsolutePath(extractions, url, prev);
   const contents = extractions[absolutePath].injectedData;
 
   return { file: absolutePath, contents };
 }
 
+/**
+ * Create an importer that will resolve @import directives with the injected
+ * data found in provided extractions object
+ */
 function makeImporter(extractions) {
   return function(url, prev, done) {
     try {
@@ -45,6 +60,10 @@ function makeImporter(extractions) {
   }
 }
 
+/**
+ * Create a synchronous importer that will resolve @import directives with the injected
+ * data found in provided extractions object
+ */
 function makeSyncImporter(extractions) {
   return function(url, prev) {
     try {

lib/process.js

@@ -1,11 +1,17 @@
 const { injectExtractionFunctions } = require('./inject');
 const { parseDeclarations } = require('./parse');
 
+/**
+ * Get a string id for a filename
+ */
 function getFileId(filename) {
   return new Buffer(filename).toString('base64').replace(/=/g, '');
 }
 
-function processCompiledFile(filename, data) {
+/**
+ * Process a single sass files to get declarations, injected source and functions
+ */
+function processFile(filename, data) {
   const declarations = parseDeclarations(data);
   const variables = { global: {} };
 
@@ -19,21 +25,26 @@ function processCompiledFile(filename, data) {
   const injectedFunctions = injection.injectedFunctions;
 
   return {
+    fileId,
     declarations,
     variables,
     injectedData,
     injectedFunctions,
   };
 }
 
-function processCompiledFiles(compiledFiles) {
+/**
+ * Process a set of sass files to get declarations, injected source and functions
+ * Files are provided in a map of filename -> key entries
+ */
+function processFiles(files) {
   const extractions = {};
 
-  Object.keys(compiledFiles).map(filename => {
-    extractions[filename] = processCompiledFile(filename, compiledFiles[filename]);
+  Object.keys(files).map(filename => {
+    extractions[filename] = processFile(filename, files[filename]);
   });
 
   return extractions;
 }
 
-exports.processCompiledFiles = processCompiledFiles;
+exports.processFiles = processFiles;