minor #115 Add Encore.configureRuntimeEnvironment() method to the public API (Lyrkan)

This PR was squashed before being merged into the master branch (closes #115).

Discussion
----------

Add Encore.configureRuntimeEnvironment() method to the public API

This PR fixes #109 by adding an `Encore.configureRuntimeEnvironment` and an `Encore.clearRuntimeEnvironment` method to the public API.

---

Basically, until now if you tried requiring `@symfony/webpack-encore` without using `./node_modules/.bin/encore`, it would throw an `Are you trying to require index.js directly?` error.

This prevented retrieving the Webpack configuration object easily, which can be needed in some cases (e.g. if you use [karma-webpack](https://github.com/webpack-contrib/karma-webpack#usage)).

With these changes, requiring `index.js` doesn't create a `WebpackConfig` instance anymore if the runtime environment isn't available, which removes the need of having a check at that time.

In order to deal with methods of the public API that need the `WebpackConfig` to be available, a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) of the API is exported instead of the real object. This proxy only allows calls to `configureRuntimeEnvironment` and `clearRuntimeEnvironment` if the `WebpackConfig` isn't initialized, or act as a passthrough if it is.

This also fixes #55 since it allows to add a `try { ... }  catch { ... }` quite easily around all the methods of the API.

The `Encore.clearRuntimeEnvironment()` (that nullifies `runtimeConfig` and `webpackConfig`) was needed to write tests but since I doubt it'll really be useful outside of that case let me know if you see another way to do it.

---

**Examples:**

```js
const Encore = require('@symfony/webpack-encore');
Encore
    .setOutputPath('build/')
    .setPublicPath('/')
    .addEntry('main', './src/index.ts');
```
If executed directly would result in the following error:
```
Error: Encore.setOutputPath() cannot be called yet because the runtime environment doesn't appear to be configured. Try calling Encore.configureRuntimeEnvironment() first.
```

Whereas the following would work:

```js
const Encore = require('@symfony/webpack-encore');
Encore
    .configureRuntimeEnvironment('dev-server')
    .setOutputPath('build/')
    .setPublicPath('/')
    .addEntry('main', './src/index.ts');
```

It is also possible to pass the same options that are available using the usual CLI tool using the second argument of `configureRuntimeEnvironment` and camel-cased names:

```js
const Encore = require('@symfony/webpack-encore');
Encore
    .configureRuntimeEnvironment('dev-server', {
        keepPublicPath: true,
        https: true,
    })
    .setOutputPath('build/')
    .setPublicPath('/')
    .addEntry('main', './src/index.ts');
```

Commits
-------

f760e52 Remove some tests related to the public API proxy and improve some texts/comments
ce6e7d3 Add Encore.configureRuntimeEnvironment() and Encore.clearRuntimeEnvironment() methods

Author: weaverryan

index.js

@@ -13,20 +13,27 @@ const WebpackConfig = require('./lib/WebpackConfig');
 const configGenerator = require('./lib/config-generator');
 const validator = require('./lib/config/validator');
 const PrettyError = require('pretty-error');
-const runtimeConfig = require('./lib/context').runtimeConfig;
 const logger = require('./lib/logger');
+const parseRuntime = require('./lib/config/parse-runtime');
 
-// at this time, the encore executable should have set the runtimeConfig
-if (!runtimeConfig) {
-    throw new Error('Are you trying to require index.js directly?');
+let webpackConfig = null;
+let runtimeConfig = require('./lib/context').runtimeConfig;
+
+function initializeWebpackConfig() {
+    if (runtimeConfig.verbose) {
+        logger.verbose();
+    }
+
+    webpackConfig = new WebpackConfig(runtimeConfig);
 }
 
-let webpackConfig = new WebpackConfig(runtimeConfig);
-if (runtimeConfig.verbose) {
-    logger.verbose();
+// If runtimeConfig is already set webpackConfig can directly
+// be initialized here.
+if (runtimeConfig) {
+    initializeWebpackConfig();
 }
 
-module.exports = {
+const publicApi = {
     /**
      * The directory where your files should be output.
      *
@@ -493,17 +500,9 @@ module.exports = {
      * @returns {*}
      */
     getWebpackConfig() {
-        try {
-            validator(webpackConfig);
-
-            return configGenerator(webpackConfig);
-        } catch (error) {
-            // prettifies errors thrown by our library
-            const pe = new PrettyError();
+        validator(webpackConfig);
 
-            console.log(pe.render(error));
-            process.exit(1); // eslint-disable-line
-        }
+        return configGenerator(webpackConfig);
     },
 
     /**
@@ -516,5 +515,98 @@ module.exports = {
      */
     reset() {
         webpackConfig = new WebpackConfig(runtimeConfig);
-    }
+    },
+
+    /**
+     * Initialize the runtime environment.
+     *
+     * This can be used to configure the Encore runtime if you're
+     * using Encore without executing the "./node_module/.bin/encore"
+     * utility (e.g. with karma-webpack).
+     *
+     * Encore.configureRuntimeEnvironment(
+     *     // Environment to use (dev, dev-server, production)
+     *     'dev-server',
+     *
+     *     // Same options you would use with the
+     *     // CLI utility with their name in
+     *     // camelCase.
+     *     {
+     *         https: true,
+     *         keepPublicPath: true
+     *     }
+     * )
+     *
+     * Be aware than using this method will also reset the current
+     * webpack configuration.
+     *
+     * @param {string} environment
+     * @param {object} options
+     * @returns {exports}
+     */
+    configureRuntimeEnvironment(environment, options = {}) {
+        runtimeConfig = parseRuntime(
+            Object.assign(
+                {},
+                require('yargs/yargs')([environment]).argv,
+                options
+            ),
+            process.cwd()
+        );
+
+        initializeWebpackConfig();
+
+        return this;
+    },
+
+    /**
+     * Clear the runtime environment.
+     *
+     * Be aware than using this method will also reset the
+     * current webpack configuration.
+     *
+     * @returns {void}
+     */
+    clearRuntimeEnvironment() {
+        runtimeConfig = null;
+        webpackConfig = null;
+    },
 };
+
+// Proxy the API in order to prevent calls to most of its methods
+// if the webpackConfig object hasn't been initialized yet.
+const publicApiProxy = new Proxy(publicApi, {
+    get: (target, prop) => {
+        if (typeof target[prop] === 'function') {
+            // These methods of the public API can be called even if the
+            // webpackConfig object hasn't been initialized yet.
+            const safeMethods = [
+                'configureRuntimeEnvironment',
+                'clearRuntimeEnvironment',
+            ];
+
+            if (!webpackConfig && (safeMethods.indexOf(prop) === -1)) {
+                throw new Error(`Encore.${prop}() cannot be called yet because the runtime environment doesn't appear to be configured. Make sure you're using the encore executable or call Encore.configureRuntimeEnvironment() first if you're purposely not calling Encore directly.`);
+            }
+
+            // Either a safe method has been called or the webpackConfig
+            // object is already available. In this case act as a passthrough.
+            return (...parameters) => {
+                try {
+                    const res = target[prop](...parameters);
+                    return (res === target) ? publicApiProxy : res;
+                } catch (error) {
+                    // prettifies errors thrown by our library
+                    const pe = new PrettyError();
+
+                    console.log(pe.render(error));
+                    process.exit(1); // eslint-disable-line
+                }
+            };
+        }
+
+        return target[prop];
+    }
+});
+
+module.exports = publicApiProxy;

test/index.js

@@ -10,10 +10,12 @@
 'use strict';
 
 const expect = require('chai').expect;
-require('../lib/context').runtimeConfig = {};
 const api = require('../index');
 
 describe('Public API', () => {
+    beforeEach(() => {
+        api.configureRuntimeEnvironment('dev');
+    });
 
     describe('setOutputPath', () => {
 
@@ -230,4 +232,27 @@ describe('Public API', () => {
         });
 
     });
+
+    describe('configureRuntimeEnvironment', () => {
+
+        it('should return the API object', () => {
+            const returnedValue = api.configureRuntimeEnvironment('dev');
+            expect(returnedValue).to.equal(api);
+        });
+
+    });
+
+    describe('Runtime environment proxy', () => {
+        beforeEach(() => {
+            api.clearRuntimeEnvironment();
+        });
+
+        it('safe methods should be callable even if the runtime environment has not been configured', () => {
+            expect(() => api.clearRuntimeEnvironment()).to.not.throw();
+        });
+
+        it('unsafe methods should NOT be callable if the runtime environment has not been configured', () => {
+            expect(() => api.setOutputPath('/')).to.throw('Encore.setOutputPath() cannot be called yet');
+        });
+    });
 });