Rename stage3 (#421)

experimental/babel-preset-env/README.md

@@ -384,6 +384,25 @@ The starting point where the config search for browserslist will start, and asce
 
 Toggles whether or not [browserslist config sources](https://github.com/ai/browserslist#queries) are used, which includes searching for any browserslist files or referencing the browserslist key inside package.json. This is useful for projects that use a browserslist config for files that won't be compiled with Babel.
 
+### `shippedProposals`
+
+`boolean`, defaults to `false`
+
+Toggles enabling support for builtin/feature proposals that have shipped in browsers. If your target environments have native support for a feature proposal, its matching parser syntax plugin is enabled instead of performing any transform. Note that this _does not_ enable the same transformations as [`babel-preset-stage3`](https://babeljs.io/docs/plugins/preset-stage-3/), since proposals can continue to change before landing in browsers.
+
+The following are currently supported:
+
+**Builtins**
+
+- [Promise.prototype.finally](https://github.com/tc39/proposal-promise-finally)
+
+**Features**
+
+- [Asynchronous Iterators](https://github.com/tc39/proposal-async-iteration)
+- [Object rest/spread properties](https://github.com/tc39/proposal-object-rest-spread)
+- [Optional catch binding](https://github.com/tc39/proposal-optional-catch-binding)
+- [Unicode property escapes in regular expressions](https://github.com/tc39/proposal-regexp-unicode-property-escapes)
+
 ---
 
 ## Examples

experimental/babel-preset-env/data/built-in-features.js

@@ -187,6 +187,6 @@ const es2017 = {
   "es7.string.pad-end": "String padding / String.prototype.padEnd",
 };
 
-const stage3 = require("./stage3").builtIns;
+const proposals = require("./shipped-proposals").builtIns;
 
-module.exports = Object.assign({}, es2015, es2016, es2017, stage3);
+module.exports = Object.assign({}, es2015, es2016, es2017, proposals);

experimental/babel-preset-env/data/plugin-features.js

@@ -135,6 +135,6 @@ const es2017 = {
   }
 };
 
-const stage3 = require("./stage3").plugins;
+const proposals = require("./shipped-proposals").features;
 
-module.exports = Object.assign({}, es2015, es2016, es2017, stage3);
+module.exports = Object.assign({}, es2015, es2016, es2017, proposals);

experimental/babel-preset-env/data/shipped-proposals.js

@@ -1,8 +1,11 @@
+// These mappings represent the builtin/feature proposals that have been
+// shipped by browsers, and are enabled by the `shippedProposals` option.
+
 const builtIns = {
   "es7.promise.finally": "Promise.prototype.finally"
 };
 
-const plugins = {
+const features = {
   "transform-async-generator-functions": "Asynchronous Iterators",
   "transform-object-rest-spread": "object rest/spread properties",
   "transform-optional-catch-binding": "optional catch binding",
@@ -16,4 +19,4 @@ const pluginSyntaxMap = new Map([
   ["transform-unicode-property-regex", null],
 ]);
 
-module.exports = { builtIns, plugins, pluginSyntaxMap };
+module.exports = { builtIns, features, pluginSyntaxMap };

experimental/babel-preset-env/src/index.js

@@ -8,10 +8,10 @@ import moduleTransformations from "./module-transformations";
 import normalizeOptions from "./normalize-options.js";
 import pluginList from "../data/plugins.json";
 import {
-  builtIns as stage3BuiltIns,
-  plugins as stage3Plugins,
+  builtIns as proposalBuiltIns,
+  features as proposalPlugins,
   pluginSyntaxMap,
-} from "../data/stage3.js";
+} from "../data/shipped-proposals.js";
 import useBuiltInsEntryPlugin from "./use-built-ins-entry-plugin";
 import addUsedBuiltInsPlugin from "./use-built-ins-plugin";
 import getTargets from "./targets-parser";
@@ -31,11 +31,15 @@ const getPlugin = (pluginName: string) => {
   return plugin;
 };
 
-const builtInsListWithoutStage3 = filterStageFromList(
+const builtInsListWithoutProposals = filterStageFromList(
   builtInsList,
-  stage3BuiltIns,
+  proposalBuiltIns,
+);
+
+const pluginListWithoutProposals = filterStageFromList(
+  pluginList,
+  proposalPlugins,
 );
-const pluginListWithoutStage3 = filterStageFromList(pluginList, stage3Plugins);
 
 export const isPluginRequired = (
   supportedEnvironments: Targets,
@@ -123,10 +127,10 @@ const filterItems = (
       if (isPluginRequired(targets, list[item])) {
         result.add(item);
       } else {
-        const stage3Syntax = pluginSyntaxMap.get(item);
+        const shippedProposalsSyntax = pluginSyntaxMap.get(item);
 
-        if (stage3Syntax) {
-          result.add(stage3Syntax);
+        if (shippedProposalsSyntax) {
+          result.add(shippedProposalsSyntax);
         }
       }
     }
@@ -154,8 +158,8 @@ export default function buildPreset(
     include: optionsInclude,
     loose,
     modules,
+    shippedProposals,
     spec,
-    stage3,
     targets: optionsTargets,
     useBuiltIns,
   } = normalizeOptions(opts);
@@ -182,7 +186,7 @@ export default function buildPreset(
   const transformTargets = forceAllTransforms || hasUglifyTarget ? {} : targets;
 
   const transformations = filterItems(
-    stage3 ? pluginList : pluginListWithoutStage3,
+    shippedProposals ? pluginList : pluginListWithoutProposals,
     include.plugins,
     exclude.plugins,
     transformTargets,
@@ -195,7 +199,7 @@ export default function buildPreset(
     polyfillTargets = getBuiltInTargets(targets);
 
     polyfills = filterItems(
-      stage3 ? builtInsList : builtInsListWithoutStage3,
+      shippedProposals ? builtInsList : builtInsListWithoutProposals,
       include.builtIns,
       exclude.builtIns,
       polyfillTargets,

experimental/babel-preset-env/src/normalize-options.js

@@ -163,8 +163,12 @@ export default function normalizeOptions(opts: Options) {
     include: validateIncludesAndExcludes(opts.include, "include"),
     loose: validateBoolOption("loose", opts.loose, false),
     modules: validateModulesOption(opts.modules),
+    shippedProposals: validateBoolOption(
+      "shippedProposals",
+      opts.shippedProposals,
+      false,
+    ),
     spec: validateBoolOption("loose", opts.spec, false),
-    stage3: validateBoolOption("stage3", opts.stage3, false),
     targets: opts.targets,
     useBuiltIns: validateUseBuiltInsOption(opts.useBuiltIns),
   };

experimental/babel-preset-env/src/types.js

@@ -20,8 +20,8 @@ export type Options = {
   include: Array<string>,
   loose: boolean,
   modules: ModuleOption,
+  shippedProposals: boolean,
   spec: boolean,
-  stage3: boolean,
   targets: Targets,
   useBuiltIns: BuiltInsOption,
 };

experimental/babel-preset-env/test/debug-fixtures/shippedProposals-chrome60/options.json

@@ -5,7 +5,7 @@
       "targets": {
         "browsers": "chrome 60"
       },
-      "stage3": true,
+      "shippedProposals": true,
       "useBuiltIns": "entry"
     }]
   ]

experimental/babel-preset-env/test/debug-fixtures/shippedProposals/options.json

@@ -2,7 +2,7 @@
   "presets": [
     ["../../lib", {
       "debug": true,
-      "stage3": true,
+      "shippedProposals": true,
       "useBuiltIns": "entry"
     }]
   ]

experimental/babel-preset-env/test/fixtures/preset-options/shippedProposals-use-builtins-entry/options.json

@@ -1,7 +1,7 @@
 {
   "presets": [
     ["../../../../lib", {
-      "stage3": true,
+      "shippedProposals": true,
       "useBuiltIns": "entry"
     }]
   ]

experimental/babel-preset-env/test/fixtures/preset-options/shippedProposals-use-builtins-usage/options.json

@@ -1,7 +1,7 @@
 {
   "presets": [
     ["../../../../lib", {
-      "stage3": true,
+      "shippedProposals": true,
       "useBuiltIns": "usage"
     }]
   ]

experimental/babel-preset-env/test/fixtures/preset-options/shippedProposals/options.json

@@ -1,7 +1,7 @@
 {
   "presets": [
     ["../../../../lib", {
-      "stage3": true
+      "shippedProposals": true
     }]
   ]
 }