refactoring in preparation for v2

Author: numical

README.md

@@ -59,7 +59,7 @@ All scripts set to `async` except 'first.js' which is sync:
 plugins: [
   new HtmlWebpackPlugin(),
   new ScriptExtHtmlWebpackPlugin({
-    sync: ['first.js'],
+    sync: 'first.js',
     defaultAttribute: 'async'
   })
 ]  
@@ -70,27 +70,31 @@ Configuration offers much more complex options:
 Configuration
 -------------
 You must pass a hash of configuration options to the plugin to cause the addition of attributes:
-- `inline`: array of `String`'s and/or `RegExp`'s defining scripts that should be inlined in the html (default: `[]`);
-- `sync`: array of `String`'s and/or `RegExp`'s defining script names that should have no attribute (default: `[]`);
-- `async`: array of `String`'s and/or `RegExp`'s defining script names that should have an `async` attribute (default: `[]`);
-- `defer`: array of `String`'s and/or `RegExp`'s defining script names that should have a `defer` attribute (default: `[]`);
+- `inline`: a __script matching pattern__ defining scripts that should be inlined in the html (default: `[]`);
+- `sync`: a  __script matching pattern__ defining script names that should have no attribute (default: `[]`);
+- `async`: a __script matching pattern__ defining script names that should have an `async` attribute (default: `[]`);
+- `defer`: a __script matching pattern__ defining script names that should have a `defer` attribute (default: `[]`);
 - `defaultAttribute`: `'sync' | 'async' | 'defer'` The default attribute to set - `'sync'` actually results in no attribute (default: `'sync'`);
-- `module`: array of `String`'s and/or `RegExp`'s defining script names that should have a
+- `module`: a __script matching pattern__ defining script names that should have a
 `type="module"` attribute (default: `[]`);
-- `preload`: array of `String`'s and/or `RegExp`'s defining scripts that should have accompanying preload resource hints (default: `[]`);
-- `prefetch`: array of `String`'s and/or `RegExp`'s defining scripts that should have accompanying prefetch resource hints (default: `[]`);
+- `preload`: a __script matching pattern__ defining scripts that should have accompanying preload resource hints (default: `[]`);
+- `prefetch`: a __script matching pattern__ defining scripts that should have accompanying prefetch resource hints (default: `[]`);
 
-In the arrays a `String` value matches if it is a substring of the script name.
+A __script matching pattern__ matches against a script's name.  It can be one of:
+- a `String`-  matches if it is a substring of the script name;
+- a `RegExp`;
+- an array of `String`'s and/or `RegExp`'s - matches if any one element matches;
+- a hash with property `test` with a value of one of the above.
 
 In more complicated use cases it may prove difficult to ensure that the pattern matching for different attributes are mutually exclusive.  To prevent confusion, the plugin operates a simple precedence model:
 
-1. if a script name matches a `RegEx` or `String` from the `inline` option, it will be inlined;
+1. if a script name matches the`inline` script matching pattern, it will be inlined;
 
-2. if a script name matches a `Regex` or `String` from the `sync` option, it will have no attribute, *unless* it matched condition 1;
+2. if a script name matches the `sync` script matching pattern, it will have no attribute, *unless* it matched condition 1;
 
-3. if a script name matches a `Regex` or `String` from the `async` option, it will have the `async` attribute, *unless* it matched conditions 1 or 2;
+3. if a script name the `async` script matching pattern, it will have the `async` attribute, *unless* it matched conditions 1 or 2;
 
-4. if a script name matches a `Regex` or `String` from the `defer` option, it will have the `defer` attribute, *unless* it matched conditions 1, 2 or 3;
+4. if a script name matches the `defer` script matching pattern, it will have the `defer` attribute, *unless* it matched conditions 1, 2 or 3;
 
 5. if a script name does not match any of the previous conditions, it will have the `defaultAttribute' attribute.
 
@@ -104,7 +108,7 @@ All scripts with 'important' in their name are sync and all others set to `defer
 plugins: [
   new HtmlWebpackPlugin(),
   new ScriptExtHtmlWebpackPlugin({
-    sync: ['important'],
+    sync: 'important'
     defaultAttribute: 'defer'
   })
 ]  
@@ -115,7 +119,7 @@ Alternatively, using a regular expression:
 plugins: [
   new HtmlWebpackPlugin(),
   new ScriptExtHtmlWebpackPlugin({
-    sync: [/important/],
+    sync: /important/,
     defaultAttribute: 'defer'
   })
 ]  
@@ -126,8 +130,8 @@ All scripts with 'mod' in their name are async and type 'module', all others are
 plugins: [
   new HtmlWebpackPlugin(),
   new ScriptExtHtmlWebpackPlugin({
-    async: ['mod'],
-    module: ['mod']
+    async: 'mod',
+    module: 'mod'
   })
 ]  
 ```
@@ -137,25 +141,24 @@ Script 'startup.js' is inlined whilst all other scripts are async and preloaded:
 plugins: [
   new HtmlWebpackPlugin(),
   new ScriptExtHtmlWebpackPlugin({
-    inline: ['startup'],
-    preload: [/\.js$/],
+    inline: 'startup',
+    preload: /\.js$/,
     defaultAttribute: 'async'
   })
 ]  
 ```
 
 
-
 And so on, to craziness:
 ```javascript
 plugins: [
   new HtmlWebpackPlugin(),
   new ScriptExtHtmlWebpackPlugin({
-    inline: ['startup'],  
+    inline: 'startup',  
     sync: [/imp(1|2){1,3}}/, 'initial'],
     defer: ['slow', /big.*andslow/],
     module: [/^((?!sync).)*/, 'mod'],
-    prefetch: ['indirectly-referenced.js'],
+    prefetch: 'indirectly-referenced.js',
     defaultAttribute: 'async'
   })
 ]  
@@ -229,7 +232,8 @@ Change History
 
 v1.5.x
 * added resource hints
-* works with webpack 2.2.0
+* works with webpack 2.2.1
+* enhanced API (no need to use array), fully backwardly compatible
 
 v1.4.x
 * updated internal mechanism to use new(ish) [HtmlWebpackPlugin event](https://github.com/ampedandwired/html-webpack-plugin#events)

dynavers.json

@@ -1,6 +1,6 @@
 {
   "path": "dynavers_modules",
   "versions": {
-    "webpack" : ["1.14.0", "2.2.0"]
+    "webpack" : ["1.14.0", "2.2.1"]
   }
 }

lib/common.js

@@ -1,10 +1,6 @@
 'use strict';
 
 const debug = require('debug')('ScriptExt');
-const PLUGIN = 'ScriptExtHtmlWebpackPlugin';
-const EVENT = 'html-webpack-plugin-alter-asset-tags';
-const INLINE = 'inline';
-const PUBLIC_PATH_PREFIX = /^.*\//;
 
 const matches = (scriptName, tagOptions) => {
   return tagOptions.test.some((pattern) => {
@@ -18,9 +14,5 @@ const matches = (scriptName, tagOptions) => {
 
 module.exports = {
   debug,
-  PLUGIN,
-  EVENT,
-  INLINE,
-  PUBLIC_PATH_PREFIX,
   matches
 };

lib/config.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { PLUGIN } = require('./common.js');
+const PLUGIN = require('./constants.js').PLUGIN;
 
 const DEFAULT_HASH = Object.freeze({
   test: []

lib/constants.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const PLUGIN = 'ScriptExtHtmlWebpackPlugin';
+const EVENT = 'html-webpack-plugin-alter-asset-tags';
+const INLINE = 'inline';
+const PUBLIC_PATH_PREFIX = /^.*\//;
+
+module.exports = {
+  PLUGIN,
+  EVENT,
+  INLINE,
+  PUBLIC_PATH_PREFIX
+};

lib/elements.js

@@ -1,13 +1,16 @@
 'use strict';
 
-const { debug, PLUGIN, EVENT, INLINE, PUBLIC_PATH_PREFIX } = require('./common.js');
+const CONSTANTS = require('./constants.js');
 const SYNC = 'sync';
 const ATTRIBUTE_PRIORITIES = [SYNC, 'async', 'defer'];
 const MODULE = 'module';
 
-const shouldUpdateElements = (options) => {
+const debug = require('./common.js').debug;
+const matches = require('./common.js').matches;
+
+const shouldUpdate = (options) => {
   if (ATTRIBUTE_PRIORITIES.indexOf(options.defaultAttribute) < 0) {
-    throw new Error(`${PLUGIN}: invalid default attribute`);
+    throw new Error(`${CONSTANTS.PLUGIN}: invalid default attribute`);
   }
   return !(options.defaultAttribute === SYNC &&
            options.inline.test.length === 0 &&
@@ -16,7 +19,7 @@ const shouldUpdateElements = (options) => {
            options.module.test.length === 0);
 };
 
-const updateElements = (compilation, options, tags) => {
+const update = (compilation, options, tags) => {
   const update = updateElement.bind(null, compilation, options);
   return tags.map(update);
 };
@@ -30,42 +33,32 @@ const updateElement = (compilation, options, tag) => {
 const isScript = (tag) => tag.tagName === 'script';
 
 const updateScriptElement = (compilation, options, tag) => {
-  debug(`${EVENT}: processing <script> element: ${JSON.stringify(tag)}`);
+  debug(`${CONSTANTS.EVENT}: processing <script> element: ${JSON.stringify(tag)}`);
   return (isInline(options, tag))
     ? replaceWithInlineElement(compilation, tag)
     : updateSrcElement(options, tag);
 };
 
-const isInline = (options, tag) => matches(tag.attributes.src, options[INLINE]);
-
-const matches = (scriptName, tagOptions) => {
-  return tagOptions.test.some((pattern) => {
-    if (pattern instanceof RegExp) {
-      return pattern.test(scriptName);
-    } else {
-      return scriptName.includes(pattern);
-    }
-  });
-};
+const isInline = (options, tag) => matches(tag.attributes.src, options[CONSTANTS.INLINE]);
 
 const replaceWithInlineElement = (compilation, tag) => {
   const scriptName = getScriptName(tag);
   const asset = compilation.assets[scriptName];
-  if (!asset) throw new Error(`${PLUGIN}: no asset with href '${scriptName}'`);
+  if (!asset) throw new Error(`${CONSTANTS.PLUGIN}: no asset with href '${scriptName}'`);
   const newTag = {
     tagName: 'script',
     closeTag: true,
     innerHTML: asset.source()
   };
-  debug(`${PLUGIN}: replaced by: ${JSON.stringify(newTag)}`);
+  debug(`${CONSTANTS.PLUGIN}: replaced by: ${JSON.stringify(newTag)}`);
   return newTag;
 };
 
 const getScriptName = (tag) => {
   let scriptName = getRawScriptName(tag);
   // remove publicPath prefix
   if (scriptName.includes('/')) {
-    scriptName = scriptName.replace(PUBLIC_PATH_PREFIX, '');
+    scriptName = scriptName.replace(CONSTANTS.PUBLIC_PATH_PREFIX, '');
   }
   return scriptName;
 };
@@ -90,11 +83,11 @@ const updateSrcElement = (options, tag) => {
   if (matches(scriptName, options[MODULE])) {
     tag.attributes.type = 'module';
   }
-  debug(`${PLUGIN}: updated to: ${JSON.stringify(tag)}`);
+  debug(`${CONSTANTS.PLUGIN}: updated to: ${JSON.stringify(tag)}`);
   return tag;
 };
 
 module.exports = {
-  shouldUpdateElements,
-  updateElements
+  shouldUpdate,
+  update
 };

lib/plugin.js

@@ -1,11 +1,18 @@
 'use strict';
 
-const { debug, EVENT, INLINE, matches } = require('./common.js');
+const CONSTANTS = require('./constants.js');
+
+const debug = require('./common.js').debug;
+const matches = require('./common.js').matches;
 const denormaliseOptions = require('./config.js');
-const { shouldAddResourceHints, addResourceHints } = require('./resource-hints.js');
-const { shouldUpdateElements, updateElements } = require('./elements.js');
+const resourceHints = require('./resource-hints.js');
+const elements = require('./elements.js');
+
+const debugEvent = msg => {
+  debug(`${CONSTANTS.EVENT}: ${msg}`);
+};
 
-const falsySafeConcat = (arrays) => {
+const falsySafeConcat = arrays => {
   return arrays.reduce(
     (combined, array) => array ? combined.concat(array) : combined,
     []
@@ -19,35 +26,35 @@ class ScriptExtHtmlWebpackPlugin {
   apply (compiler) {
     const options = this.options;
     compiler.plugin('compilation', (compilation) => {
-      compilation.plugin(EVENT, (pluginArgs, callback) => {
+      compilation.plugin(CONSTANTS.EVENT, (pluginArgs, callback) => {
         try {
-          debug(`${EVENT}: starting`);
-          if (shouldUpdateElements(options)) {
-            debug(`${EVENT}: replacing <head> <script> elements`);
-            pluginArgs.head = updateElements(compilation, options, pluginArgs.head);
-            debug(`${EVENT}: replacing <body> <script> elements`);
-            pluginArgs.body = updateElements(compilation, options, pluginArgs.body);
+          debugEvent('starting');
+          if (elements.shouldUpdate(options)) {
+            debugEvent('replacing <head> <script> elements');
+            pluginArgs.head = elements.update(compilation, options, pluginArgs.head);
+            debugEvent('replacing <body> <script> elements');
+            pluginArgs.body = elements.update(compilation, options, pluginArgs.body);
           }
-          if (shouldAddResourceHints(options)) {
-            debug(`${EVENT}: adding resource hints`);
+          if (resourceHints.shouldAdd(options)) {
+            debugEvent('adding resource hints');
             pluginArgs.head = falsySafeConcat([
               pluginArgs.head,
-              addResourceHints(options, pluginArgs.head),
-              addResourceHints(options, pluginArgs.body)
+              resourceHints.add(options, pluginArgs.head),
+              resourceHints.add(options, pluginArgs.body)
             ]);
           }
-          debug(`${EVENT}: completed`);
+          debugEvent('completed');
           callback(null, pluginArgs);
         } catch (err) {
           callback(err);
         }
       });
     });
     compiler.plugin('emit', (compilation, callback) => {
-      if (options[INLINE].length > 0 && options.removeInlinedAssets) {
+      if (options[CONSTANTS.INLINE].length > 0 && options.removeInlinedAssets) {
         debug('emit: deleting assets');
         Object.keys(compilation.assets).forEach((assetName) => {
-          if (matches(assetName, options[INLINE])) {
+          if (matches(assetName, options[CONSTANTS.INLINE])) {
             debug(`emit: deleting asset '${assetName}'`);
             delete compilation.assets[assetName];
           }

lib/resource-hints.js

@@ -1,13 +1,14 @@
 'use strict';
 
-const { PUBLIC_PATH_PREFIX, matches } = require('./common.js');
+const PUBLIC_PATH_PREFIX = require('./constants.js').PUBLIC_PATH_PREFIX;
+const matches = require('./common.js').matches;
 
-const shouldAddResourceHints = (options) => {
+const shouldAdd = options => {
   return !(options.prefetch.test.length === 0 &&
            options.preload.test.length === 0);
 };
 
-const addResourceHints = (options, tags) => {
+const add = (options, tags) => {
   return tags
     .filter(hasScriptName)
     .reduce((hints, tag) => {
@@ -23,7 +24,7 @@ const addResourceHints = (options, tags) => {
     );
 };
 
-const getScriptName = (tag) => {
+const getScriptName = tag => {
   let scriptName = getRawScriptName(tag);
   // remove publicPath prefix
   if (scriptName.includes('/')) {
@@ -32,9 +33,9 @@ const getScriptName = (tag) => {
   return scriptName;
 };
 
-const getRawScriptName = (tag) => tag.attributes.src;
+const getRawScriptName = tag => tag.attributes.src;
 
-const hasScriptName = (tag) => tag.attributes && tag.attributes.src;
+const hasScriptName = tag => tag.attributes && tag.attributes.src;
 
 const createResourceHint = (rel, tag) => {
   return {
@@ -49,6 +50,6 @@ const createResourceHint = (rel, tag) => {
 };
 
 module.exports = {
-  shouldAddResourceHints,
-  addResourceHints
+  shouldAdd,
+  add
 };

package.json

@@ -44,7 +44,7 @@
     "dynavers": "^0.2.0",
     "handlebars": "^4.0.6",
     "handlebars-loader": "^1.4.0",
-    "html-webpack-plugin": "^2.26.0",
+    "html-webpack-plugin": "^2.28.0",
     "jasmine": "^2.5.3",
     "jasmine-spec-reporter": "^3.2.0",
     "jasmine2-custom-message": "^0.8.2",