Multi Output (#27)

Author: jescalan

README.md

@@ -31,7 +31,7 @@ module.exports = {
   module: {
     rules: [{
       test: /\.html$/,
-      loader: 'reshape',
+      loader: 'reshape-loader',
       options: { plugins: [/* plugins here */] }
     }]
   }
@@ -57,7 +57,7 @@ module.exports = {
   module: {
     rules: [{
       test: /\.html$/,
-      loader: 'reshape',
+      loader: 'reshape-loader',
       options: {
         plugins: (loaderContext) => {
           return [somePlugin({ file: loaderContext.resourcePath })]
@@ -88,9 +88,9 @@ module.exports = {
     rules: [{
       test: /\.html$/,
       use: [
-        { loader: 'html' },
+        { loader: 'source-loader' },
         {
-          loader: 'reshape',
+          loader: 'reshape-loader',
           options: {
             plugins: [expressions()],
             locals: { planet: 'world' }
@@ -109,6 +109,47 @@ console.log(html) // <p>Hello world!</p>
 
 If you do this, you will want at least one other loader in order to integrate the returned source with webpack correctly. For most use cases, the [html-loader](https://github.com/webpack/html-loader) is recommended. If you want to export the html string directly for use in javascript or webpack plugins, we recommend the [source-loader](https://github.com/static-dev/source-loader). Whichever loader you choose, it should be the first loader, followed by reshape, as seen in the example above.
 
+## Producing Multiple Outputs from a Single files
+
+The reshape loader is unique in its ability to take in a single source file, and compile multiple outputs with different options for each output. This ability can be very useful for cases in which a single template is used with a set of different locals to produce variants purely from a data input, such as for internationalization.
+
+In order to use multiple outputs, you can pass the `multi` option. This option should be an array of objects, each one will be merged with the base options (with priority given to the multi object), and used to produce a unique output. It is required that each `multi` object contains a `name` property, which is used to name the output. So for example, if we wanted to produce a static html result with a single template compiled with two different languages, it might look like this:
+
+```html
+<!-- index.html -->
+<p>{{ greeting }}!</p>
+```
+
+```js
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [{
+      test: /\.html$/,
+      use: [
+        { loader: 'source-loader' },
+        {
+          loader: 'reshape-loader',
+          options: {
+            multi: [
+              { locals: { greeting: 'hello' }, name: 'en' },
+              { locals: { greeting: 'hola' }, name: 'es' }
+            ]
+          }
+        }
+      ]
+    }]
+  }
+}
+```
+
+```js
+const html = require('./index.html')
+console.log(html) // { en: "<p>hello!</p>", es: "<p>hola!</p>" }
+```
+
+It should be noted that passing in anything as the `multi` option will return static html, regardless of any other options. If you want to use a template, you don't need the multi option, you can just execute the template with different sets of locals on the client side as needed.
+
 ## Custom Plugin Hooks
 
 Reshape loader adds a custom hook that webpack plugins can utilize called `beforeLoaderCompile` (sync). This hook exposes the options as they stand immediately before being passed to reshape for compilation, allowing them to be read and/or modified by plugins. For example, if you wanted to make a plugin that adds a `test` key to the locals, it might look like this.

lib/index.js

@@ -7,14 +7,16 @@ module.exports = function (source) {
   const cb = this.async()
   let options = parseOptions.call(this, this.query)
 
-  // if the output function doesn't need to be called, we'll take it as a string
-  // and save the time eval'ing it
-  if (!options.locals) {
+  // if we are producing a template (no locals or multi options), we are for
+  // sure going to be returning a string, so we don't need to eval into a
+  // function. we can set the returnString generator option to slice off some
+  // overhead here
+  if (!options.locals && !options.multi) {
     if (!options.generatorOptions) { options.generatorOptions = {} }
     options.generatorOptions.returnString = true
   }
 
-  // set loader override options
+  // set loader override options - filename and deps must be set by the loader
   options = Object.assign(options, {
     filename: this.resourcePath,
     dependencies: []
@@ -23,25 +25,64 @@ module.exports = function (source) {
   // custom plugin hook for options modification
   this._compiler.applyPlugins('before-loader-process', this, options)
 
-  // run reshape
-  reshape(options)
-    .process(source)
-    .then((res) => {
-      // If there are any dependencies reported, add them to webpack
-      if (res.dependencies) {
-        res.dependencies.map((dep) => this.addDependency(dep.file))
+  // if the multi option was specified, we have a slightly different compile
+  // process. basically, we run through each of the multi options, merge it
+  // with priority into the base options, and compile the base template once
+  // for each multi option. The output is an object with the key being the
+  // specified "name", and the value being a string with the compiled contents
+  if (options.multi) {
+    let depsAdded = false
+    promiseReduce.call(this, options.multi, (m, opt) => {
+      // no name is a no-go
+      if (!opt.name) {
+        throw new Error('multi options must have a "name" property')
       }
-      // If the locals option is specified, we call the output function and
-      // return static html. Otherwise, we return the function & runtime to be
-      // used client-side.
-      if (options.locals) {
-        cb(null, res.output(options.locals))
-      } else {
-        // TODO: more efficient shared runtime export
-        cb(null, `var __runtime = ${serializeVerbatim(res.runtime)}; module.exports = ${res.output.substr(1)}`)
-      }
-    })
-    .catch(cb)
+
+      // merge multi options back with default options
+      const mergedOpts = Object.assign({}, options, opt)
+
+      // run it
+      return reshape(mergedOpts)
+        .process(source)
+        .then((res) => {
+          // Only add dependencies once to prevent dupes
+          if (!depsAdded && res.dependencies) {
+            res.dependencies.map((dep) => this.addDependency(dep.file))
+          }
+
+          // Multi always produces a compiled template
+          m[mergedOpts.name] = res.output(mergedOpts.locals)
+          return m
+        })
+        // this needs to add module.exports and skip the source loader
+    }, {}).then((res) => {
+      // hack semi-specific to source-loader to ensure this is loaded
+      // as a js object and not stringified
+      this._module._jsSource = true
+      this._module._outputMultiple = true
+      cb(null, JSON.stringify(res))
+    }).catch(cb)
+  } else {
+    // run reshape
+    reshape(options)
+      .process(source)
+      .then((res) => {
+        // If there are any dependencies reported, add them to webpack
+        if (res.dependencies) {
+          res.dependencies.map((dep) => this.addDependency(dep.file))
+        }
+        // If the locals option is specified, we call the output function and
+        // return static html. Otherwise, we return the function & runtime to be
+        // used client-side.
+        if (options.locals) {
+          cb(null, res.output(options.locals))
+        } else {
+          // TODO: more efficient shared runtime export
+          cb(null, `var __runtime = ${serializeVerbatim(res.runtime)}; module.exports = ${res.output.substr(1)}`)
+        }
+      })
+      .catch(cb)
+  }
 }
 
 // Allows any option to be passed as a function which gets webpack's context
@@ -55,7 +96,7 @@ function parseOptions (opts) {
     generatorOptions: convertFn.call(this, opts.generatorOptions),
     runtime: convertFn.call(this, opts.runtime),
     parser: convertFnSpecial.call(this, opts.parser),
-    generator: convertFnSpecial.call(this, opts.generator)
+    multi: convertFn.call(this, opts.multi)
   })
 }
 
@@ -92,3 +133,8 @@ function serializeVerbatim (obj) {
   })
   return res
 }
+
+function promiseReduce (arr, fn, memo) {
+  return Promise.all(arr.map(fn.bind(this, memo)))
+    .then(_ => memo)
+}

package.json

@@ -13,16 +13,16 @@
     "reshape-include": "^1.0.0"
   },
   "devDependencies": {
-    "ava": "^0.19.1",
+    "ava": "^0.21.0",
     "coveralls": "^2.13.1",
-    "nyc": "^11.0.2",
+    "nyc": "^11.0.3",
     "reshape-custom-elements": "^0.1.0",
     "reshape-expressions": "^0.1.5",
     "snazzy": "^7.0.0",
-    "source-loader": "^0.2.0",
+    "source-loader": "^1.0.0",
     "standard": "^10.0.2",
     "sugarml": "^0.6.0",
-    "webpack": "^3.0.0",
+    "webpack": "^3.3.0",
     "when": "^3.7.8"
   },
   "engine": ">=6",

test/fixtures/multi/app.js

@@ -0,0 +1 @@
+require('./index.html')

test/fixtures/multi/index.html

@@ -0,0 +1 @@
+<p>{{ greeting }}</p>

test/index.js

@@ -115,8 +115,34 @@ test('custom plugin hook works', (t) => {
   })
 })
 
+test('multi output', (t) => {
+  return webpackCompile('multi', {
+    plugins: [exp()],
+    multi: [
+      { locals: { greeting: 'hello' }, name: 'en' },
+      { locals: { greeting: 'hola' }, name: 'es' }
+    ]
+  }).then(({outputPath, src}) => {
+    t.regex(src, /module\.exports = {"en":"<p>hello<\/p>\\n","es":"<p>hola<\/p>\\n"}/g)
+    fs.unlinkSync(outputPath)
+  })
+})
+
+test('multi output without name property errors', (t) => {
+  return webpackCompile('multi', {
+    plugins: [exp()],
+    multi: [
+      { locals: { greeting: 'hello' } },
+      { locals: { greeting: 'hola' } }
+    ]
+  }).catch(({err, outputPath}) => {
+    t.regex(err.toString(), /multi options must have a "name" property/)
+    fs.unlinkSync(outputPath)
+  })
+})
+
 // Utility: compile a fixture with webpack, return results
-function webpackCompile (name, config, qs = {}) {
+function webpackCompile (name, config = {}, qs = {}) {
   const testPath = path.join(fixtures, name)
   const outputPath = path.join(testPath, 'bundle.js')