refactor join API again, additional how-to examples

Author: bholloway

.jshintrc

@@ -23,5 +23,5 @@
   "maxlen": 120,
   "scripturl": true,
   "node": true,
-  "esversion": 6
+  "esversion": 9
 }

packages/resolve-url-loader/docs/advanced-features.md

@@ -12,9 +12,9 @@ var path              = require('path'),
 
 var adjustSourceMap = require('adjust-sourcemap-loader/lib/process');
 
-var valueProcessor   = require('./lib/value-processor');
-var joinFn           = require('./lib/join-function');
-var logToTestHarness = require('./lib/log-to-test-harness');
+var valueProcessor   = require('./lib/value-processor'),
+    joinFn           = require('./lib/join-function'),
+    logToTestHarness = require('./lib/log-to-test-harness');
 
 const DEPRECATED_OPTIONS = {
   engine: [
@@ -74,7 +74,6 @@ function resolveUrlLoader(content, sourceMap) {
   var rawOptions = loaderUtils.getOptions(loader),
       options    = Object.assign(
         {
-          fs       : loader.fs,
           sourceMap: loader.sourceMap,
           engine   : 'postcss',
           silent   : false,
@@ -106,10 +105,24 @@ function resolveUrlLoader(content, sourceMap) {
       'loader misconfiguration',
       '"join" option must be a Function'
     );
-  } else if (options.join.length !== 1) {
+  } else if (options.join.length !== 2) {
     return handleAsError(
       'loader misconfiguration',
-      '"join" Function must take exactly 1 arguments (options hash)'
+      '"join" Function must take exactly 2 arguments (options, loader)'
+    );
+  }
+
+  // validate the result of calling the join option
+  var joinProper = options.join(options, loader);
+  if (typeof joinProper !== 'function') {
+    return handleAsError(
+      'loader misconfiguration',
+      '"join" option must itself return a Function when it is called'
+    );
+  } else if (joinProper.length !== 1) {
+    return handleAsError(
+      'loader misconfiguration',
+      '"join" Function must create a function that takes exactly 1 arguments (item)'
     );
   }
 
@@ -198,10 +211,14 @@ function resolveUrlLoader(content, sourceMap) {
   Promise
     .resolve(engine(loader.resourcePath, content, {
       outputSourceMap     : !!options.sourceMap,
-      transformDeclaration: valueProcessor(loader.resourcePath, options),
       absSourceMap        : absSourceMap,
       sourceMapConsumer   : sourceMapConsumer,
-      removeCR            : options.removeCR
+      removeCR            : options.removeCR,
+      transformDeclaration: valueProcessor({
+        join     : joinProper,
+        root     : options.root,
+        directory: path.dirname(loader.resourcePath)
+      })
     }))
     .catch(onFailure)
     .then(onSuccess);

packages/resolve-url-loader/index.js

@@ -146,7 +146,7 @@ function requireOptionalPeerDependency(moduleName) {
   }
   catch (error) {
     if (error.message === 'Cannot find module \'' + moduleName + '\'') {
-      throw new Error('To use the "rework" engine you must install the optionalPeerDependencies');
+      throw new Error('to use the "rework" engine you must install the optionalPeerDependencies');
     }
     else {
       throw error;

packages/resolve-url-loader/lib/engine/rework.js

@@ -4,43 +4,56 @@
  */
 'use strict';
 
-var path = require('path');
+const path = require('path');
 
-var PACKAGE_NAME = require('../../package.json').name;
+const PACKAGE_NAME = require('../../package.json').name;
+
+/**
+ * Paths are formatted to have posix style path separators and those within the CWD are made relative to CWD.
+ *
+ * @param {string} absolutePath An absolute path to format
+ * @returns {string} the formatted path
+ */
+const pathToString = (absolutePath) => {
+  if (absolutePath === '') {
+    return '-empty-';
+  } else {
+    const relative = path.relative(process.cwd(), absolutePath).split(path.sep);
+    const segments =
+      (relative[0] !== '..') ? ['.'].concat(relative).filter(Boolean) :
+        (relative.lastIndexOf('..') < 2) ? relative :
+          absolutePath.split(path.sep);
+    return segments.join('/');
+  }
+};
+
+exports.pathToString = pathToString;
 
 /**
  * Format a debug message.
  *
- * @param {string} file The file being processed by webpack
+ * @param {string} filename The file being processed by webpack
  * @param {string} uri A uri path, relative or absolute
- * @param {Array<string>} bases Absolute base paths up to and including the found one
- * @param {boolean} isFound Indicates the last base was a positive match
+ * @param {Array<{base:string,joined:string,isSuccess:boolean}>} attempts An array of attempts, possibly empty
  * @return {string} Formatted message
  */
-function formatJoinMessage(file, uri, bases, isFound) {
-  return [PACKAGE_NAME + ': ' + pathToString(file) + ': ' + uri]
-    .concat(bases.map(pathToString))
-    .concat(isFound ? 'FOUND' : 'NOT FOUND')
-    .join('\n  ');
+const formatJoinMessage = (filename, uri, attempts) => {
+  const attemptToCells = (_, i, array) => {
+    const { base: prev } = (i === 0) ? {} : array[i-1];
+    const { base: curr, joined } = array[i];
+    return [(curr === prev) ? '' : pathToString(curr), pathToString(joined)];
+  };
 
-  /**
-   * If given path is within `process.cwd()` then show relative posix path, otherwise show absolute posix path.
-   *
-   * @param {string} absolute An absolute path
-   * @return {string} A relative or absolute path
-   */
-  function pathToString(absolute) {
-    if (!absolute) {
-      return '-empty-';
-    } else {
-      var relative = path.relative(process.cwd(), absolute)
-        .split(path.sep);
+  const formatCells = (lines) => {
+    const maxWidth = lines.reduce((max, [cellA]) => Math.max(max, cellA.length), 0);
+    return lines.map(([cellA, cellB]) => [cellA.padEnd(maxWidth), cellB]).map((cells) => cells.join(' --> '));
+  };
 
-      return ((relative[0] === '..') ? absolute.split(path.sep) : ['.'].concat(relative).filter(Boolean))
-        .join('/');
-    }
-  }
-}
+  return [PACKAGE_NAME + ': ' + pathToString(filename) + ': ' + uri]
+    .concat(attempts.length === 0 ? '-empty-' : formatCells(attempts.map(attemptToCells)))
+    .concat(attempts.some(({ isSuccess }) => isSuccess) ? 'FOUND' : 'NOT FOUND')
+    .join('\n  ');
+};
 
 exports.formatJoinMessage = formatJoinMessage;
 
@@ -56,20 +69,18 @@ exports.formatJoinMessage = formatJoinMessage;
  * @param {function|boolean} debug A boolean or debug function
  * @return {function(function, array):void} A logging function possibly degenerate
  */
-function createDebugLogger(debug) {
-  var log   = !!debug && ((typeof debug === 'function') ? debug : console.log),
-      cache = {};
-  return log ? actuallyLog : noop;
-
-  function noop() {}
-
-  function actuallyLog(msgFn, params) {
-    var key = Function.prototype.toString.call(msgFn) + JSON.stringify(params);
-    if (!cache[key]) {
-      cache[key] = true;
-      log(msgFn.apply(null, params));
-    }
-  }
-}
+const createDebugLogger = (debug) => {
+  const log = !!debug && ((typeof debug === 'function') ? debug : console.log);
+  const cache = {};
+  return log ?
+    ((msgFn, params) => {
+      const key = Function.prototype.toString.call(msgFn) + JSON.stringify(params);
+      if (!cache[key]) {
+        cache[key] = true;
+        log(msgFn.apply(null, params));
+      }
+    }) :
+    (() => undefined);
+};
 
 exports.createDebugLogger = createDebugLogger;