feature #19 Lazy controllers for user-land controllers (weaverryan)

This PR was merged into the main branch.

Discussion
----------

Lazy controllers for user-land controllers

Hi!

This allows users to make their own controllers "lazy" by adding a special comment above their controllers:

```js
// assets/controllers/hello_controller.js
import { Controller } from 'stimulus';

/* stimulusFetch: 'lazy' */
export default class extends Controller {
    // ...
}
```

When you do this, your controller (and its dependencies) are *not* included in the main `app.js` built file. Instead, they are split into their own chunk/file. This file is loaded asynchronously the moment that the *first* element appears on the page for this controller (e.g. `<div data-controller="hello">`). This follows up on #15 (and only the last commit is new to this PR). The `/* stimulusFetch: 'lazy' */` is inspired by Webpack's `/* webpackMode: 'lazy' */` comments and uses the same mechanism to parse them.

To activate this, you only need to process your controllers through a new loader:

```diff
// assets/bootstrap.js

export const app = startStimulusApp(require.context(
-    './controllers',
+    '@symfony/stimulus-bridge/lazy-controller-loader!./controllers',
    true,
    /\.(j|t)sx?$/
));
```

That looks a bit ugly, but this is code that we'll give users via the recipe anyways. I've tested this in a real app and it works beautifully ❤️ .

Cheers!

Commits
-------

bbf8ab0 Implementing a way to make user-land controllers lazy

Author: tgalopin

CHANGELOG.md

@@ -15,8 +15,10 @@
   in `controllers.json` to `lazy`, your controller will not
   be downloaded until the controller element first appears on the page.
 
-* The `webpackMode` option in `controllers.json` was deprecated. Use
-  the new `fetch` option instead.
+* Support for making your own controllers "lazy" (as described above)
+  can now be achieved by loading your controllers through the
+  `@symfony/stimulus-bridge/lazy-controller-loader` loader and
+  adding a `/* stimulusFetch: 'lazy' */` comment above your controller.
 
 ## 1.1.0
 

README.md

@@ -190,6 +190,37 @@ ordered from least to most lazy:
   separate file and only downloaded asynchronously if (and when) the `data-controller`
   HTML appears on the page.
 
+## Lazy Controllers
+
+You can also make your own controllers "lazy": giving them the same behavior
+as the `lazy-controller` explained above. In this case, your controller isn't
+downloaded until an element for that controller first appears on the page.
+
+To activate this, first make sure that you're using the special loader -
+`@symfony/stimulus-bridge/lazy-controller-loader` - when loading your controllers:
+
+```js
+// assets/bootstrap.js
+
+export const app = startStimulusApp(require.context(
+    '@symfony/stimulus-bridge/lazy-controller-loader!./controllers',
+    true,
+    /\.(j|t)sx?$/
+));
+```
+
+Next, you can make any controllers lazy by adding a `/* stimulusFetch: 'lazy' */`
+comment above that controller:
+
+```js
+import { Controller } from 'stimulus';
+
+/* stimulusFetch: 'lazy' */
+export default class extends Controller {
+    // ...
+}
+```
+
 ## Run tests
 
 ```sh

dist/util/get-stimulus-comment-options.js

@@ -0,0 +1,86 @@
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+'use strict';
+
+function _createForOfIteratorHelper(o, allowArrayLike) { var it; if (typeof Symbol === "undefined" || o[Symbol.iterator] == null) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = o[Symbol.iterator](); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it["return"] != null) it["return"](); } finally { if (didErr) throw err; } } }; }
+
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+var acorn = require('acorn');
+
+var vm = require('vm');
+
+var stimulusCommentRegExp = new RegExp(/(^|\W)stimulus[A-Z]{1,}[A-Za-z]{1,}:/);
+var EMPTY_COMMENT_OPTIONS = {
+  options: {},
+  errors: []
+};
+
+function getCommentsFromSource(source) {
+  var comments = [];
+  acorn.parse(source, {
+    onComment: comments,
+    sourceType: 'module',
+    ecmaVersion: 2020
+  });
+  return comments;
+}
+/**
+ * Inspired by Webpack's JavaScriptParser
+ */
+
+
+module.exports = function parseComments(source) {
+  var comments;
+
+  try {
+    comments = getCommentsFromSource(source);
+  } catch (e) {
+    return EMPTY_COMMENT_OPTIONS;
+  }
+
+  if (comments.length === 0) {
+    return EMPTY_COMMENT_OPTIONS;
+  }
+
+  var options = {};
+  var errors = [];
+
+  var _iterator = _createForOfIteratorHelper(comments),
+      _step;
+
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var comment = _step.value;
+      var value = comment.value;
+
+      if (value && stimulusCommentRegExp.test(value)) {
+        // try compile only if stimulus options comment is present
+        try {
+          var val = vm.runInNewContext("(function(){return {".concat(value, "};})()"));
+          Object.assign(options, val);
+        } catch (e) {
+          e.comment = comment;
+          errors.push(e);
+        }
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+
+  return {
+    options: options,
+    errors: errors
+  };
+};

dist/webpack/lazy-controller-loader.js

@@ -0,0 +1,66 @@
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+'use strict';
+
+function _createForOfIteratorHelper(o, allowArrayLike) { var it; if (typeof Symbol === "undefined" || o[Symbol.iterator] == null) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = o[Symbol.iterator](); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it["return"] != null) it["return"](); } finally { if (didErr) throw err; } } }; }
+
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+var generateLazyController = require('./generate-lazy-controller');
+
+var getStimulusCommentOptions = require('../util/get-stimulus-comment-options');
+/**
+ * Loader that can make a Stimulus controller lazy.
+ *
+ * This loader is meant to be used to load the Stimulus controllers
+ * themselves. It detects a stimulusFetch: 'lazy' comment above the
+ * controller. If present, the controller is replaced by a controller
+ * that will lazily import the real controller the first time the
+ * element appears.
+ *
+ * @param {string} source of a module that exports a Stimulus controller
+ * @return {string}
+ */
+
+
+module.exports = function (source) {
+  var _getStimulusCommentOp = getStimulusCommentOptions(source),
+      options = _getStimulusCommentOp.options,
+      errors = _getStimulusCommentOp.errors;
+
+  var _iterator = _createForOfIteratorHelper(errors),
+      _step;
+
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var error = _step.value;
+      this.emitError(new Error("Invalid comment found:\n\n    \"/* ".concat(error.comment.value.trim(), " */\".\n\nCheck your syntax.")));
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+
+  var stimulusFetch = typeof options.stimulusFetch !== 'undefined' ? options.stimulusFetch : 'eager';
+
+  if (!['eager', 'lazy'].includes(stimulusFetch)) {
+    this.emitError(new Error("Invalid value \"".concat(stimulusFetch, "\" found for \"stimulusFetch\". Allowed values are \"lazy\" or \"eager\"")));
+  }
+
+  var isLazy = stimulusFetch === 'lazy';
+
+  if (!isLazy) {
+    return source;
+  }
+
+  return "import { Controller } from 'stimulus';\nexport default ".concat(generateLazyController(this.resource, 0));
+};

lazy-controller-loader.js

@@ -0,0 +1,12 @@
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+'use strict';
+
+module.exports = require('./dist/webpack/lazy-controller-loader');

package.json

@@ -15,7 +15,9 @@
     "peerDependencies": {
         "stimulus": "^2.0"
     },
-    "dependencies": {},
+    "dependencies": {
+        "acorn": "^8.0.5"
+    },
     "devDependencies": {
         "@babel/cli": "^7.12.1",
         "@babel/core": "^7.12.3",
@@ -35,6 +37,7 @@
     "files": [
         "src/",
         "dist/",
-        "controllers.json"
+        "controllers.json",
+        "lazy-controller-loader.js"
     ]
 }

src/util/get-stimulus-comment-options.js

@@ -0,0 +1,64 @@
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+'use strict';
+
+const acorn = require('acorn');
+const vm = require('vm');
+
+const stimulusCommentRegExp = new RegExp(/(^|\W)stimulus[A-Z]{1,}[A-Za-z]{1,}:/);
+
+const EMPTY_COMMENT_OPTIONS = {
+    options: {},
+    errors: [],
+};
+
+function getCommentsFromSource(source) {
+    const comments = [];
+    acorn.parse(source, {
+        onComment: comments,
+        sourceType: 'module',
+        ecmaVersion: 2020,
+    });
+
+    return comments;
+}
+
+/**
+ * Inspired by Webpack's JavaScriptParser
+ */
+module.exports = function parseComments(source) {
+    let comments;
+    try {
+        comments = getCommentsFromSource(source);
+    } catch (e) {
+        return EMPTY_COMMENT_OPTIONS;
+    }
+
+    if (comments.length === 0) {
+        return EMPTY_COMMENT_OPTIONS;
+    }
+
+    let options = {};
+    let errors = [];
+    for (const comment of comments) {
+        const { value } = comment;
+        if (value && stimulusCommentRegExp.test(value)) {
+            // try compile only if stimulus options comment is present
+            try {
+                const val = vm.runInNewContext(`(function(){return {${value}};})()`);
+                Object.assign(options, val);
+            } catch (e) {
+                e.comment = comment;
+                errors.push(e);
+            }
+        }
+    }
+    return { options, errors };
+};

src/webpack/lazy-controller-loader.js

@@ -0,0 +1,52 @@
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+'use strict';
+
+const generateLazyController = require('./generate-lazy-controller');
+const getStimulusCommentOptions = require('../util/get-stimulus-comment-options');
+
+/**
+ * Loader that can make a Stimulus controller lazy.
+ *
+ * This loader is meant to be used to load the Stimulus controllers
+ * themselves. It detects a stimulusFetch: 'lazy' comment above the
+ * controller. If present, the controller is replaced by a controller
+ * that will lazily import the real controller the first time the
+ * element appears.
+ *
+ * @param {string} source of a module that exports a Stimulus controller
+ * @return {string}
+ */
+module.exports = function (source) {
+    const { options, errors } = getStimulusCommentOptions(source);
+
+    for (const error of errors) {
+        this.emitError(
+            new Error(`Invalid comment found:\n\n    "/* ${error.comment.value.trim()} */".\n\nCheck your syntax.`)
+        );
+    }
+
+    const stimulusFetch = typeof options.stimulusFetch !== 'undefined' ? options.stimulusFetch : 'eager';
+    if (!['eager', 'lazy'].includes(stimulusFetch)) {
+        this.emitError(
+            new Error(
+                `Invalid value "${stimulusFetch}" found for "stimulusFetch". Allowed values are "lazy" or "eager"`
+            )
+        );
+    }
+    const isLazy = stimulusFetch === 'lazy';
+
+    if (!isLazy) {
+        return source;
+    }
+
+    return `import { Controller } from 'stimulus';
+export default ${generateLazyController(this.resource, 0)}`;
+};