Changes to become v1.x

.gitignore

@@ -2,3 +2,6 @@
 node_modules/
 coverage/
 npm-debug.log
+*.swp
+test/fixtures/tmp/
+nyc_output/

README.md

@@ -1,88 +1,88 @@
-engine-munger 
+engine-munger
 =============
 
-Lead Maintainer: [Aria Stewart](https://github.com/aredridel)  
+A replacement Express view class that provides asynchronous resolution, allows engines to use the lookup method to locate partials, and extends the lookup method to be configurable based on i18n locale and a template specialization rule map.
+
+Lead Maintainer: [Aria Stewart](https://github.com/aredridel)
 
 [![Build Status](https://travis-ci.org/krakenjs/engine-munger.svg?branch=master)](https://travis-ci.org/krakenjs/engine-munger)
 
-A template engine munging library.
-It looks for appropriate template consolidation library for specified view engine and includes i18n and specialization in the workflow.
+What does i18n mean?
+--------------------
+
+i18n means "internationalization". Given a `locale` property in the render options, `engine-munger` will look for content in a locale-specific directory (or in a fallback locale if that is not a match) for templates and partials. This is particularly useful with template engines that pre-localize their compiled forms, such as with [`localizr`](https://github.com/krakenjs/localizr) and [`dustjs-linkedin`](http://dustjs.com/) together.
 
-Note: If you use specialization features, you must use dustjs before 2.6.0.
+What does specialization mean?
+------------------------------
 
-###### What does i18n mean ?
-Localization of included content tags for a specified locale. Currently supported only for dust templating engine and internally uses the module [localizr](https://github.com/krakenjs/localizr) for translating content tags included in the templates
+Ability to switch a specific template with another based on a rule set specified in the app config. The actual rule parsing is done using the module [`karka`](https://github.com/krakenjs/karka).
 
-###### What does specialization mean ?
-Ability to switch a specific template with another based on a rule set specified in the app config. The actual rule parsing is done using the module [karka](https://github.com/krakenjs/karka) and can be extended and used in any templating engine and not dust.
 All engine-munger does is includes a specialization map with the list of key value pairs using the karka module.
+
 ```javascript
 {
-    _specialization : {
-        ...
-        originalTemplate : <mappedTemplate>
-        ...
+    specialization : {
+        'jekyll': [
+            {
+                is: 'hyde',
+                when: {
+                    'whoAmI': 'badGuy'
+                }
+            }
+        ]
     }
 }
 ```
 
-##### Currently supported template engines out of the box:
+The above will switch the template from `jekyll` to `hyde` if the render options contain `"whoAmI": "badGuy"`. Rules can be as complex as you need for your application and are particularly good for running A/B tests.
 
-* Dust: Engine types 'js' and 'dust'
+Using engine-munger in an application
+=====================================
 
-
-Simple Usage:
+This example uses the [`adaro`](https://github.com/krakenjs/adaro) template engine, which wraps dust up as an express view engine, and uses engine-munger's more sophisticated lookup method to find partials, allowing them to be localized and specialized based on the render options.
 
 ```javascript
-var engine-munger = require('engine-munger'),
-    app = require('express')();
+var munger = require('engine-munger');
+var adaro = require('adaro');
+var app = require('express')();
+
+var specialization = {
+    'jekyll': [
+        {
+            is: 'hyde',
+            when: {
+                'whoAmI': 'badGuy'
+            }
+        }
+    ]
+};
+app.set("view", munger.makeViewClass({
+    "dust": {
+        specialization: specialization
+    },
+    "js": {
+        specialization: specialization,
+        i18n: {
+            fallback: 'en-US',
+            contentPath: 'locales'
+        }
+    }
+});
 
-app.engine('dust', engine-munger['dust'](settings, config));
-app.engine('js', engine-munger['js'](settings, config));
-```
+var engineConfig = {}; // Configuration for your view engine
 
-* settings : [JSON] Arguments you want passed to the templating engine,
-* config: [JSON] used to specify whether you need i18n/specialization enabled. It also compulsarily requires the 'view' and 'view engine' settings passed into express app.
-
- If you are using kraken-js 1.0 along with engine-munger, the kraken generator will automatically set this all up for you.
- But if you want to use this with a stand alone express app with dust as templating engine, you can specify as follows:
-
- Example params:
-
- ```javascript
- var settings  = {cache: false},
-     config = {
-         'views': 'public/templates',
-         'view engine': 'dust',
-         'i18n': {
-             'fallback': 'en-US',
-             'contentPath': 'locales'
-         },
-         specialization: {
-             'jekyll': [
-                 {
-                     is: 'hyde',
-                     when: {
-                         'whoAmI': 'badGuy'
-                     }
-                 }
-             ]
-
-         }
-     };
- ```
+app.engine('dust', adaro.dust(engineConfig));
+app.engine('js', adaro.js(engineConfig));
+```
 
 Running Tests:
 
+```shell
+npm test
 ```
-To run tests:
-$ npm test
 
-To run coverage
-$ npm run-script cover
+To run coverage:
 
-To run lint
-$ npm run-script lint
+```shell
+npm run cover
 ```
-
-

index.js

@@ -15,51 +15,198 @@
  │   See the License for the specific language governing permissions and       │
  │   limitations under the License.                                            │
  \*───────────────────────────────────────────────────────────────────────────*/
+"use strict";
+var path = require('path');
+var debug = require('debuglog')('engine-munger');
+var fs = require('fs');
+var permutron = require('permutron');
+var oldView = require('express/lib/view');
+var karka = require('karka');
+var aproba = require('aproba');
+var bcp47 = require('bcp47');
+var bcp47stringify = require('bcp47-stringify');
 
-'use strict';
-var engine = require('adaro'),
-    munger = require('./lib/munger');
+/**
+ * Make a View class that uses our configuration, set far in advance of
+ * instantiation because Express passes very little to the actual constructor.
+ */
+function makeViewClass(config) {
+    aproba('O', arguments);
 
+    var conf = normalizeConfigs(config);
 
-exports.dust = function (setting, config) {
-    var settings =  (arguments.length > 1) ? setting : {},
-        configs = (arguments.length > 1) ? config : setting,
-        renderer;
+    var proto = Object.create(oldView.prototype);
 
-    if (!configs || !(configs.specialization || configs.i18n)) {
-        return engine.dust(settings);
-    }
+    // Unfortunately, since we don't know the actual file to resolve until
+    // we get request context (in `render`), we can't say whether it exists or not.
+    //
+    // Express checks that this is truthy to see if it should return an error or
+    // run the render, so we hard code it to true.
+    proto.path = true;
+
+    proto.lookup = function lookup(name, options, cb) {
+        if (arguments.length === 1) {
+            // This is the unoverriden constructor calling us. Ignore the call.
+            return true;
+        }
+
+        var ext = path.extname(name);
+
+        if (conf[ext] && conf[ext].specialization) {
+            var nameNoExt = name.slice(0, -ext.length);
+            var newName = conf[ext].specialization.resolve(nameNoExt, options) + ext;
+            debug("specialization mapped '%s' to '%s'", name, newName);
+            name = newName;
+        }
+
+        var search = [];
+        search.push([].concat(conf[ext] && conf[ext].root ? conf[ext].root : this.root));
+
+        if (conf[ext] && conf[ext].i18n) {
+            var i18n = conf[ext].i18n;
+            var locales = [];
+            if (options.locale) {
+                locales.push(i18n.formatPath(typeof options.locale === 'object' ? options.locale : bcp47.parse(options.locale.replace(/_/g, '-'))));
+            }
+            if (i18n.fallback) {
+                locales.push(i18n.formatPath(i18n.fallback));
+            }
+            debug("trying locales %j", locales);
+            search.push(locales);
+        }
+
+        search.push([name, path.join(path.basename(name), 'index' + ext)]);
+
+        debug('lookup "%s"', name);
+
+        permutron.raw(search, function (candidate, next) {
+            var resolved = path.resolve.apply(null, candidate);
+            limitStat(resolved, function (err, stat) {
+                if (!err && stat.isFile()) {
+                    debug('found "%s"', resolved);
+                    cb(null, resolved);
+                } else if ((!err && stat.isDirectory()) || (err && err.code === 'ENOENT')) {
+                    next();
+                } else {
+                    cb(err);
+                }
+            });
+        }, cb);
+    };
 
-    if (configs['view engine'] === 'dust') {
-        munger.wrapDustOnLoad('dust', configs, settings.cache);
+    /**
+     * Render with the given `options` and callback `fn(err, str)`.
+     *
+     * @param {Object} options
+     * @param {Function} fn
+     * @api private
+     */
+    proto.render = function render(options, fn) {
+        aproba('OF', arguments);
+        var view = this;
+        view.lookupMain(options, function (err) {
+            if (err) {
+                fn(err);
+            } else {
+                debug('render "%s"', view.path);
+                view.engine(view.path, options, fn);
+            }
+        });
+    };
+
+    /** Resolve the main template for this view
+     *
+     * @param {function} cb
+     * @private
+     */
+    proto.lookupMain = function lookupMain(options, cb) {
+        if (this.path && this.path !== true) {
+            return cb();
+        }
+        var view = this;
+        var name = path.extname(this.name) === this.ext ? this.name : this.name + this.ext;
+        this.lookup(name, options, function (err, path) {
+            if (err) {
+                return cb(err);
+            } else if (!path) {
+                var dirs = Array.isArray(view.root) && view.root.length > 1 ? 'directories "' + view.root.slice(0, -1).join('", "') + '" or "' + view.root[view.root.length - 1] + '"' : 'directory "' + view.root + '"';
+                var viewError = new Error('Failed to lookup view "' + name + '" in views ' + dirs);
+                viewError.view = view;
+                return cb(viewError);
+            } else {
+                view.path = path;
+                cb();
+            }
+        });
+    };
+
+    function View(name, options) {
+        oldView.call(this, name, options);
     }
 
-    // Disabling cache
-    // since we add our own caching layer below. (Clone it first so we don't muck with the original object.)
-    settings.cache = false;
+    View.prototype = proto;
+    View.prototype.constructor = View;
+    return View;
+}
+
+module.exports = makeViewClass;
+
+/**
+ * an fs.stat call that limits the number of outstanding requests to 10.
+ *
+ * @param {String} path
+ * @param {Function} cb
+ */
+var pendingStats = [];
+var numPendingStats = 0;
 
-    // For i18n we silently switch to the JS engine for all requests, passing config
-    renderer = configs.i18n ? engine.js(settings): engine.dust(settings);
-    return munger.wrapEngine(configs, renderer);
-};
+function limitStat(path, cb) {
+    debug('stat "%s"', path);
+    if (++numPendingStats > 10) {
+        pendingStats.push([path, cb]);
+    } else {
+        fs.stat(path, dequeue(cb));
+    }
 
-exports.js = function (setting, config) {
-    var settings =  (arguments.length > 1) ? setting : {},
-        configs = (arguments.length > 1) ? config : setting,
-        renderer;
+    function dequeue(cb) {
+        return function (err, stat) {
+            cb(err, stat);
+            var next = pendingStats.shift();
+            if (next) {
+                fs.stat(next[0], dequeue(next[1]));
+            } else {
+                numPendingStats--;
+            }
+        };
+    }
+}
 
-    if (!configs || !(configs.specialization || configs.i18n)) {
-        return engine.js(settings);
+function normalizeConfigs(config) {
+    var out = {};
+    for (var ext in config) {
+        if (ext[0] === '.') {
+            out[ext] = normalizeConfig(config[ext]);
+        } else {
+            out['.' + ext] = normalizeConfig(config[ext]);
+        }
     }
 
-    if (configs['view engine'] === 'js') {
-        munger.wrapDustOnLoad('js', configs, settings.cache);
+    return out;
+}
+
+function normalizeConfig(config) {
+    var out = {};
+    if (config.i18n) {
+        out.i18n = {
+            fallback: config.i18n.fallback && bcp47.parse(config.i18n.fallback.replace(/_/g, '-')),
+            formatPath: config.i18n.formatPath || bcp47stringify,
+            contentPath: config.i18n.contentPath
+        };
     }
 
-    // Disabling cache
-    // since we add our own caching layer below. (Clone it first so we don't muck with the original object.)
-    settings.cache = false;
-    renderer = engine.js(settings);
-    return (configs.specialization) ? munger.wrapEngine(configs, renderer) : renderer;
-};
+    if (config.specialization) {
+        out.specialization = karka.create(config.specialization);
+    }
 
+    return out;
+}