Add capability to use Babel runtime (#32)

* Add capability to use Babel runtime

* Pull test runtime version from manifest

* Change option to runtime and add docs

* Use snapshot tests for debug logs

Author: steverep

.yarnrc.yml

@@ -0,0 +1,3 @@
+defaultSemverRangePrefix: ""
+
+pnpEnableEsmLoader: true

README.md

@@ -8,7 +8,7 @@
 
 ## How it works
 
-The plugin works by transforming async modules using [`@babel/preset-env`](https://babeljs.io/docs/babel-preset-env) right before they are ready to be written to a chunk. It is expected that modules are already transpiled using [`babel-loader`](https://www.npmjs.com/package/babel-loader), so the primary transformations occurring are simply to the `async function`:
+The plugin works by transforming async modules using [Babel](https://babeljs.io) right before they are ready to be written to a chunk. It is expected that modules are already transpiled (e.g. by using [`babel-loader`](https://www.npmjs.com/package/babel-loader)), so the primary transformations occurring are simply to the `async function`:
 
 1. [`@babel/plugin-transform-async-to-generator`](https://babeljs.io/docs/babel-plugin-transform-async-to-generator) to convert to a generator function, and
 2. [`@babel/plugin-transform-regenerator`](https://babeljs.io/docs/babel-plugin-transform-regenerator) to convert the ES2015 generator
@@ -47,12 +47,30 @@ export default {
 
 ## Options
 
-The options passed to the plugin are optional. Properties are a subset of [Babel options to specify targets](https://babeljs.io/docs/options#output-targets), and are passed directly to the transform function.
+The plugin takes the following options, all of which are optional:
 
 ```ts
 interface TransformAsyncModulesPluginOptions {
-  targets?: Targets; // see Babel docs for details
+  targets?: Targets;
   browserslistConfigFile?: boolean;
   browserslistEnv?: string;
+  runtime?: boolean | RuntimeOptions;
 }
 ```
+
+### targets, browserslistConfigFile, and browserslistEnv
+
+Controls how the async modules will be transpiled. These properties are a subset of [Babel options to specify targets](https://babeljs.io/docs/options#output-targets), and are passed directly to Babel.
+
+### runtime
+
+Allows importing helpers and regenerator from `@babel/runtime` instead of repeating them for each async module. If it is falsey, the runtime will not be used. This option takes a subset of relevant [options for `@babel/plugin-transform-runtime`](https://babeljs.io/docs/babel-plugin-transform-runtime#options):
+
+```ts
+interface RuntimeOptions {
+  absoluteRuntime?: boolean | string;
+  version?: string;
+}
+```
+
+The default for `version` is the minimum required version for the plugin, so it is recommended this property be specified as the version installed when using the runtime.

mocha.config.cjs

@@ -1,8 +1,9 @@
 module.exports = {
-  require: "ts-node/register",
+  require: ["ts-node/register", "./test/snapshot-setup.ts"],
   loader: ["ts-node/esm", "./.pnp.loader.mjs"],
   asyncOnly: true,
   forbidOnly: true,
-  spec: ["test/**/*.spec.*"],
+  enableSourceMaps: true,
+  spec: ["test/**/*.spec.ts"],
   watchFiles: ["src"],
 };

package.json

@@ -36,7 +36,6 @@
   ],
   "exports": "./dist/index.cjs",
   "types": "./dist/index.d.cts",
-  "sideEffects": false,
   "scripts": {
     "lint:js": "eslint --cache-location=node_modules/.cache/eslint/.eslintcache .",
     "lint:format": "prettier --cache --check .",
@@ -52,18 +51,25 @@
   },
   "dependencies": {
     "@babel/core": "^7.13.0",
+    "@babel/plugin-transform-runtime": "^7.13.0",
     "@babel/preset-env": "^7.13.0"
   },
   "peerDependencies": {
     "@babel/core": "^7.13.0",
+    "@babel/plugin-transform-runtime": "^7.13.0",
     "@babel/preset-env": "^7.13.0",
+    "@babel/runtime": "^7.13.0",
     "webpack": "^5.0.0"
   },
   "devDependencies": {
+    "@babel/runtime": "7.24.1",
     "@eslint/eslintrc": "3.0.2",
     "@eslint/js": "8.57.0",
     "@types/babel__core": "7.20.5",
+    "@types/babel__plugin-transform-runtime": "7.9.5",
+    "@types/babel__preset-env": "7.9.6",
     "@types/chai": "4.3.14",
+    "@types/chai-jest-snapshot": "1.3.8",
     "@types/eslint-config-prettier": "6.11.3",
     "@types/eslint__eslintrc": "2.1.1",
     "@types/eslint__js": "8.42.3",
@@ -72,6 +78,7 @@
     "@typescript-eslint/eslint-plugin": "7.5.0",
     "@typescript-eslint/parser": "7.5.0",
     "chai": "5.1.0",
+    "chai-jest-snapshot": "2.0.0",
     "eslint": "8.57.0",
     "eslint-config-prettier": "9.1.0",
     "globals": "15.0.0",

src/babel-plugin-runtime-dependency.cts

@@ -0,0 +1,71 @@
+import { types as t, type PluginObj, type PluginPass } from "@babel/core";
+
+export interface RuntimeDependencyOptions {
+  map: Map<string, string>;
+  record?: boolean;
+}
+
+interface ThisPluginPass extends PluginPass {
+  opts: RuntimeDependencyOptions;
+  counter: number;
+}
+
+const ID_PREFIX = "__TAMP";
+
+// This plugin is designed to run after transform-runtime, and operates in one
+// of two modes:
+// - In record mode, it just records the source request and a mangled
+//   identifier for Webpack to inject in the provided map.
+// - Not in record mode, it expects that Webpack has injected the recorded
+//   identifiers as variable bindings, and essentially swaps the Babel import
+//   for a renamed Webpack variable.
+export const runtimeDependencyPlugin = (): PluginObj<ThisPluginPass> => ({
+  name: "runtime-dependency",
+  pre() {
+    this.counter = 0;
+  },
+  visitor: {
+    ImportDeclaration(path) {
+      // Make sure we only have a single default specifier.
+      if (
+        path.node.specifiers.length !== 1 ||
+        !t.isImportDefaultSpecifier(path.node.specifiers[0])
+      ) {
+        throw Error(
+          `Expected only a default import specifier:\n${path.getSource()}`,
+        );
+      }
+      const localID = path.node.specifiers[0].local.name;
+      // In record mode, just save the request and exit.
+      if (this.opts.record) {
+        const dependencyID = ID_PREFIX + localID;
+        this.opts.map.set(path.node.source.value, dependencyID);
+        return;
+      }
+      // Find the identifier that Webpack injected for this source.
+      const dependencyID = this.opts.map.get(path.node.source.value);
+      if (!dependencyID) {
+        throw Error(
+          `Encountered a dependency that was not recorded:\n${path.getSource()}`,
+        );
+      }
+      // Check that the dependency was declared at the top scope, rename it,
+      // and delete the import.
+      if (!path.scope.hasOwnBinding(dependencyID)) {
+        throw Error(`Identifier ${dependencyID} was not injected by Webpack`);
+      }
+      path.scope.rename(dependencyID, localID);
+      path.remove();
+      this.counter++;
+    },
+  },
+  post() {
+    // Check that each recorded/declared dependency was renamed.
+    const nDeps = this.opts.map.size;
+    if (!this.opts.record && this.counter !== nDeps) {
+      throw Error(
+        `Injected ${nDeps} dependencies but only swapped ${this.counter} imports`,
+      );
+    }
+  },
+});