diff --git a/packages/babel-plugin-syntax-trailing-function-commas/README.md b/packages/babel-plugin-syntax-trailing-function-commas/README.md index f64894538d..fd7022b23f 100644 --- a/packages/babel-plugin-syntax-trailing-function-commas/README.md +++ b/packages/babel-plugin-syntax-trailing-function-commas/README.md @@ -14,7 +14,7 @@ clownPuppiesEverywhere( 'bar', ); ``` -[Try in REPL](/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=function%20clownPuppiesEverywhere(%0A%20%20param1%2C%0A%20%20param2%2C%0A)%20%7B%20%2F*%20...%20*%2F%20%7D%0A%0AclownPuppiesEverywhere(%0A%20%20'foo'%2C%0A%20%20'bar'%2C%0A)%3B) +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=function%20clownPuppiesEverywhere(%0A%20%20param1%2C%0A%20%20param2%2C%0A)%20%7B%20%2F*%20...%20*%2F%20%7D%0A%0AclownPuppiesEverywhere(%0A%20%20'foo'%2C%0A%20%20'bar'%2C%0A)%3B) ## Example diff --git a/packages/babel-plugin-transform-class-constructor-call/README.md b/packages/babel-plugin-transform-class-constructor-call/README.md index f52cb9eeea..badb23aef9 100644 --- a/packages/babel-plugin-transform-class-constructor-call/README.md +++ b/packages/babel-plugin-transform-class-constructor-call/README.md @@ -23,7 +23,7 @@ class Point { let p1 = new Point(1, 2); // OK let p2 = Point(3, 4); // OK ``` -[Try in REPL](/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=class%20Point%20%7B%0A%0A%20%20constructor(x%2C%20y)%20%7B%0A%20%20%20%20this.x%20%3D%20x%3B%0A%20%20%20%20this.y%20%3D%20y%3B%0A%20%20%7D%0A%0A%20%20call%20constructor(x%2C%20y)%20%7B%0A%20%20%20%20return%20new%20Point(x%2C%20y)%3B%0A%20%20%7D%0A%0A%7D%0A%0Alet%20p1%20%3D%20new%20Point(1%2C%202)%3B%20%2F%2F%20OK%0Alet%20p2%20%3D%20Point(3%2C%204)%3B%20%2F%2F%20OK) +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=class%20Point%20%7B%0A%0A%20%20constructor(x%2C%20y)%20%7B%0A%20%20%20%20this.x%20%3D%20x%3B%0A%20%20%20%20this.y%20%3D%20y%3B%0A%20%20%7D%0A%0A%20%20call%20constructor(x%2C%20y)%20%7B%0A%20%20%20%20return%20new%20Point(x%2C%20y)%3B%0A%20%20%7D%0A%0A%7D%0A%0Alet%20p1%20%3D%20new%20Point(1%2C%202)%3B%20%2F%2F%20OK%0Alet%20p2%20%3D%20Point(3%2C%204)%3B%20%2F%2F%20OK) ## Example @@ -60,7 +60,7 @@ class Date { let now = new Date(); // Get a Date instance let nowStr = Date(); // Use the 'call constructor()' part to get a string value of the current date ``` -[Try in REPL](/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=class%20Date%20%7B%0A%20%20constructor()%20%7B%0A%20%20%20%20%2F%2F%20...%0A%20%20%7D%0A%0A%20%20call%20constructor()%20%7B%0A%20%20%20%20let%20date%20%3D%20new%20Date()%3B%0A%20%20%20%20return%20date.toString()%3B%0A%20%20%7D%0A%7D%0A%0Alet%20now%20%3D%20new%20Date()%3B%20%2F%2F%20Get%20a%20Date%20instance%0Alet%20nowStr%20%3D%20Date()%3B%20%2F%2F%20Use%20the%20'call%20constructor()'%20part%20to%20get%20a%20string%20value%20of%20the%20current%20date) +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=class%20Date%20%7B%0A%20%20constructor()%20%7B%0A%20%20%20%20%2F%2F%20...%0A%20%20%7D%0A%0A%20%20call%20constructor()%20%7B%0A%20%20%20%20let%20date%20%3D%20new%20Date()%3B%0A%20%20%20%20return%20date.toString()%3B%0A%20%20%7D%0A%7D%0A%0Alet%20now%20%3D%20new%20Date()%3B%20%2F%2F%20Get%20a%20Date%20instance%0Alet%20nowStr%20%3D%20Date()%3B%20%2F%2F%20Use%20the%20'call%20constructor()'%20part%20to%20get%20a%20string%20value%20of%20the%20current%20date) ## Installation diff --git a/packages/babel-plugin-transform-class-properties/README.md b/packages/babel-plugin-transform-class-properties/README.md index a9604f7b6e..a4c7ea02c0 100644 --- a/packages/babel-plugin-transform-class-properties/README.md +++ b/packages/babel-plugin-transform-class-properties/README.md @@ -1,16 +1,46 @@ # babel-plugin-transform-class-properties +> This plugin transforms es2015 static class properties as well as properties declared with the es2016 property initializer syntax. + +## Example + +Below is a class with four class properties which will be transformed. + +```js + class Bork { + //Property initializer syntax + instanceProperty = "bork"; + boundFunction = () => { + return this.instanceProperty; + } + + //Static class properties + static staticProperty = "babeliscool"; + static staticFunction = function() { + return Bork.staticProperty; + } + } + + let myBork = new Bork; + + //Property initializers are not on the prototype. + console.log(myBork.prototype.boundFunction); // > undefined + + //Bound functions are bound to the class instance. + console.log(myBork.boundFunction.call(undefined)); // > "bork" + + //Static function exists on the class. + console.log(Bork.staticFunction()); // > "babelIsCool" +``` + +[Try in REPL](http://babeljs.io/repl/#?babili=false&evaluate=false&lineWrap=false&presets=es2016%2Clatest%2Cstage-2&code=%20%20class%20Bork%20%7B%0A%20%20%20%20%2F%2FProperty%20initilizer%20syntax%0A%20%20%20%20instanceProperty%20%3D%20%22bork%22%3B%0A%20%20%20%20boundFunction%20%3D%20()%20%3D%3E%20%7B%0A%20%20%20%20%20%20return%20this.instanceProperty%3B%0A%20%20%20%20%7D%0A%20%20%20%20%0A%20%20%20%20%2F%2FStatic%20class%20properties%0A%20%20%20%20static%20staticProperty%20%3D%20%22babeliscool%22%3B%0A%20%20%20%20static%20staticFunction%20%3D%20function()%20%7B%0A%20%20%20%20%20%20return%20Bork.staticProperty%3B%0A%20%20%20%20%7D%0A%20%20%7D%0A%0A%20%20let%20myBork%20%3D%20new%20Bork%3B%0A%0A%20%20%2F%2FProperty%20initializers%20are%20not%20on%20the%20prototype.%0A%20%20console.log(Bork.prototype.boundFunction)%3B%20%2F%2F%20%3E%20undefined%0A%0A%20%20%2F%2FBound%20functions%20are%20bound%20to%20the%20class%20instance.%0A%20%20console.log(myBork.boundFunction.call(undefined))%3B%20%2F%2F%20%3E%20%22bork%22%0A%0A%20%20%2F%2FStatic%20function%20exists%20on%20the%20class.%0A%20%20console.log(Bork.staticFunction())%3B%20%2F%2F%20%3E%20%22babelIsCool%22) + ## Installation ```sh npm install --save-dev babel-plugin-transform-class-properties ``` -### Options: `spec` - -- Class properties are compiled to use `Object.defineProperty` -- Static fields are now defined even if they are not initialized - ## Usage ### Via `.babelrc` (Recommended) @@ -44,3 +74,11 @@ require("babel-core").transform("code", { plugins: ["transform-class-properties"] }); ``` + +## Options + +* `spec` - Class properties are compiled to use `Object.defineProperty. Static fields are now defined even if they are not initialized + +## References + +* [Proposal: ES Class Fields & Static Properties](https://github.com/jeffmo/es-class-static-properties-and-fields) diff --git a/packages/babel-plugin-transform-decorators/README.md b/packages/babel-plugin-transform-decorators/README.md index fba4863f52..71fee789b4 100644 --- a/packages/babel-plugin-transform-decorators/README.md +++ b/packages/babel-plugin-transform-decorators/README.md @@ -1,6 +1,50 @@ # babel-plugin-transform-decorators -Compile class and object decorators to ES5 +> Compile class and object decorators to ES5 + +## Example + +(examples are from proposal) + +### Simple class decorator + +```js +@annotation +class MyClass { } + +function annotation(target) { + target.annotated = true; +} +``` + +### Class decorator + +```js +@isTestable(true) +class MyClass { } + +function isTestable(value) { + return function decorator(target) { + target.isTestable = value; + } +} +``` + +### Class function decorator + +```js +class C { + @enumerable(false) + method() { } +} + +function enumerable(value) { + return function (target, key, descriptor) { + descriptor.enumerable = value; + return descriptor; + } +} +``` ## Installation @@ -33,3 +77,7 @@ require("babel-core").transform("code", { plugins: ["transform-decorators"] }); ``` + +## References + +* [Proposal: Javascript Decorators](https://github.com/wycats/javascript-decorators/blob/master/README.md) diff --git a/packages/babel-plugin-transform-do-expressions/README.md b/packages/babel-plugin-transform-do-expressions/README.md index 937c3474f1..44e252e17d 100644 --- a/packages/babel-plugin-transform-do-expressions/README.md +++ b/packages/babel-plugin-transform-do-expressions/README.md @@ -1,6 +1,88 @@ # babel-plugin-transform-do-expressions -Compile do expressions to ES5 +> Compile `do` expressions to ES5 + +## Detail + +> The `do { .. }` expression executes a block (with one or many statements in it), and the final statement completion value inside the block becomes the completion value of the do expression. + +from [You Don't Know JS](https://github.com/getify/You-Dont-Know-JS/blob/master/types%20%26%20grammar/ch5.md#statement-completion-values) + +It can be seen as a complex version of the [ternary operator](http://mdn.io/ternary): + +```js +let a = do { + if(x > 10) { + 'big'; + } else { + 'small'; + } +}; +// is equivalent to: +let a = x > 10 ? 'big' : 'small'; +``` + +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=%0Alet%20x%20%3D%20100%3B%0A%0Alet%20a%20%3D%20do%20%7B%0A%20%20if(x%20%3E%2010)%20%7B%0A%20%20%20%20'big'%3B%0A%20%20%7D%20else%20%7B%0A%20%20%20%20'small'%3B%0A%20%20%7D%0A%7D%3B%0A%0Aconsole.log(a)%3B) + +This example is not the best usage because it is too simple and using a ternary operator is a better option but you can have a much more complex condition in the `do { ... }` expression with several `if ... else` chains: + +```js +let x = 100; +let y = 20; + +let a = do { + if(x > 10) { + if(y > 20) { + 'big x, big y'; + } else { + 'big x, small y'; + } + } else { + if(y > 10) { + 'small x, big y'; + } else { + 'small x, small y'; + } + } +}; +``` + +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=let%20x%20%3D%20100%3B%0Alet%20y%20%3D%2020%3B%0A%0Alet%20a%20%3D%20do%20%7B%0A%20%20if(x%20%3E%2010)%20%7B%0A%20%20%20%20if(y%20%3E%2020)%20%7B%0A%20%20%20%20%20%20'big%20x%2C%20big%20y'%3B%0A%20%20%20%20%7D%20else%20%7B%0A%20%20%20%20%20%20'big%20x%2C%20small%20y'%3B%0A%20%20%20%20%7D%0A%20%20%7D%20else%20%7B%0A%20%20%20%20if(y%20%3E%2010)%20%7B%0A%20%20%20%20%20%20'small%20x%2C%20big%20y'%3B%0A%20%20%20%20%7D%20else%20%7B%0A%20%20%20%20%20%20'small%20x%2C%20small%20y'%3B%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D%3B%0A%0Aconsole.log(a)%3B) + +## Example + +### In JSX +One of the most useful usage of the `do` expression is inside JSX. If we want to conditionally display a component we usually have to call another function which would implement the condition and return the correct value, for example: + +```js +const getColoredComponent = color => { + if(color === 'blue') { return ; } + if(color === 'red') { return ; } + if(color === 'green') { return ; } +} + +const Component = props => +
+ {getColoredComponent()} +
+; +``` + +Using a do expression you can add logic inside JSX: + +```js +const Component = props => +
+ {do { + if(color === 'blue') { ; } + if(color === 'red') { ; } + if(color === 'green') { ; } + }} +
+; +``` + +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Creact%2Cstage-0&code=const%20Component%20%3D%20props%20%3D%3E%0A%20%20%3Cdiv%20className%3D'myComponent'%3E%0A%20%20%20%20%7Bdo%20%7B%0A%20%20%20%20%20%20if(color%20%3D%3D%3D%20'blue')%20%7B%20%3CBlueComponent%2F%3E%3B%20%7D%0A%20%20%20%20%20%20if(color%20%3D%3D%3D%20'red')%20%7B%20%3CRedComponent%2F%3E%3B%20%7D%0A%20%20%20%20%20%20if(color%20%3D%3D%3D%20'green')%20%7B%20%3CGreenComponent%2F%3E%3B%20%7D%0A%20%20%20%20%7D%7D%0A%20%20%3C%2Fdiv%3E%0A%3B) ## Installation @@ -33,3 +115,8 @@ require("babel-core").transform("code", { plugins: ["transform-do-expressions"] }); ``` + +## References +- [Proposal](http://wiki.ecmascript.org/doku.php?id=strawman:do_expressions) +- [You Don't Know JS](https://github.com/getify/You-Dont-Know-JS/blob/master/types%20%26%20grammar/ch5.md#statement-completion-values) +- Very handy for conditions inside JSX: [reactjs/react-future#35](https://github.com/reactjs/react-future/issues/35#issuecomment-120009203) diff --git a/packages/babel-plugin-transform-es2015-classes/README.md b/packages/babel-plugin-transform-es2015-classes/README.md index 1673e52a8b..aa68fde1ca 100644 --- a/packages/babel-plugin-transform-es2015-classes/README.md +++ b/packages/babel-plugin-transform-es2015-classes/README.md @@ -5,7 +5,7 @@ ## Caveats Built-in classes such as `Date`, `Array`, `DOM` etc cannot be properly subclassed -due to limitations in ES5 (for the [es2015-classes](/docs/plugins/transform-es2015-classes) plugin). +due to limitations in ES5 (for the [es2015-classes](http://babeljs.io/docs/plugins/transform-es2015-classes) plugin). You can try to use [babel-plugin-transform-builtin-extend](https://github.com/loganfsmyth/babel-plugin-transform-builtin-extend) based on `Object.setPrototypeOf` and `Reflect.construct`, but it also has some limitations. ## Installation diff --git a/packages/babel-plugin-transform-es2015-duplicate-keys/README.md b/packages/babel-plugin-transform-es2015-duplicate-keys/README.md index cb265db5b7..bfcb7c4257 100644 --- a/packages/babel-plugin-transform-es2015-duplicate-keys/README.md +++ b/packages/babel-plugin-transform-es2015-duplicate-keys/README.md @@ -1,6 +1,6 @@ # babel-plugin-transform-es2015-duplicate-keys -> Compile objects with duplicate keys to valid strict ES5. This plugin actually converts duplicate keys in objects to be computed properties, which then must be handled by the [transform-es2015-computed-properties](/docs/plugins/transform-es2015-computed-properties) plugin. The final result won't contain any object literals with duplicate keys. +> Compile objects with duplicate keys to valid strict ES5. This plugin actually converts duplicate keys in objects to be computed properties, which then must be handled by the [transform-es2015-computed-properties](http://babeljs.io/docs/plugins/transform-es2015-computed-properties) plugin. The final result won't contain any object literals with duplicate keys. ## Example diff --git a/packages/babel-plugin-transform-es2015-parameters/README.md b/packages/babel-plugin-transform-es2015-parameters/README.md index 51ad31c49f..bd55bbc350 100644 --- a/packages/babel-plugin-transform-es2015-parameters/README.md +++ b/packages/babel-plugin-transform-es2015-parameters/README.md @@ -12,7 +12,7 @@ npm install --save-dev babel-plugin-transform-es2015-parameters Default parameters desugar into `let` declarations to retain proper semantics. If this is not supported in your environment then you'll need the -[transform-block-scoping](/docs/plugins/transform-es2015-block-scoping) plugin. +[transform-block-scoping](http://babeljs.io/docs/plugins/transform-es2015-block-scoping) plugin. ## Usage diff --git a/packages/babel-plugin-transform-es2015-typeof-symbol/README.md b/packages/babel-plugin-transform-es2015-typeof-symbol/README.md index bf98e87568..53b9236ab3 100644 --- a/packages/babel-plugin-transform-es2015-typeof-symbol/README.md +++ b/packages/babel-plugin-transform-es2015-typeof-symbol/README.md @@ -1,6 +1,6 @@ # babel-plugin-transform-es2015-typeof-symbol -> ES6 introduces a new native type called [symbols](/docs/learn-es6#symbols). This transformer wraps all `typeof` expressions with a method that replicates native behaviour. (ie. returning "symbol" for symbols) +> ES6 introduces a new native type called [symbols](http://babeljs.io/docs/learn-es6#symbols). This transformer wraps all `typeof` expressions with a method that replicates native behaviour. (ie. returning "symbol" for symbols) ## Example diff --git a/packages/babel-plugin-transform-es3-member-expression-literals/README.md b/packages/babel-plugin-transform-es3-member-expression-literals/README.md index e4672582d0..030f482902 100644 --- a/packages/babel-plugin-transform-es3-member-expression-literals/README.md +++ b/packages/babel-plugin-transform-es3-member-expression-literals/README.md @@ -1,6 +1,20 @@ # babel-plugin-transform-es3-member-expression-literals -Ensure that reserved words are quoted in property accesses +> Ensure that reserved words are quoted in property accesses + +## Example + +**In** + +```javascript +foo.catch; +``` + +**Out** + +```javascript +foo["catch"]; +``` ## Installation diff --git a/packages/babel-plugin-transform-es3-property-literals/README.md b/packages/babel-plugin-transform-es3-property-literals/README.md index b094e74a4b..9cf9976a8b 100644 --- a/packages/babel-plugin-transform-es3-property-literals/README.md +++ b/packages/babel-plugin-transform-es3-property-literals/README.md @@ -1,6 +1,24 @@ # babel-plugin-transform-es3-property-literals -Ensure that reserved words are quoted in object property keys +> Ensure that reserved words are quoted in object property keys + +## Example + +**In** + +```javascript +var foo = { + catch: function () {} +}; +``` + +**Out** + +```javascript +var foo = { + "catch": function () {} +}; +``` ## Installation diff --git a/packages/babel-plugin-transform-es5-property-mutators/README.md b/packages/babel-plugin-transform-es5-property-mutators/README.md index 12c0b597d6..a9bb7c252d 100644 --- a/packages/babel-plugin-transform-es5-property-mutators/README.md +++ b/packages/babel-plugin-transform-es5-property-mutators/README.md @@ -1,6 +1,32 @@ # babel-plugin-transform-es5-property-mutators -Compile ES5 property mutator shorthand syntax to Object.defineProperty +> This plugin allows Babel to transform [object initializer mutators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#Method_definitions) into `Object.defineProperties`. + +## Example + +**In** + +```javascript +var foo = { + get bar() { + return "bar"; + } +}; +``` + +**Out** + +```javascript +var foo = Object.defineProperties({}, { + bar: { + get: function () { + return "bar"; + }, + enumerable: true, + configurable: true + } +}); +``` ## Installation diff --git a/packages/babel-plugin-transform-eval/README.md b/packages/babel-plugin-transform-eval/README.md index ee33b7e197..8a67afe8ce 100644 --- a/packages/babel-plugin-transform-eval/README.md +++ b/packages/babel-plugin-transform-eval/README.md @@ -1,6 +1,6 @@ # babel-plugin-transform-eval -Compile eval calls with string literals +> This plugin allows Babel to compile eval calls with string literals. ## Example diff --git a/packages/babel-plugin-transform-exponentiation-operator/README.md b/packages/babel-plugin-transform-exponentiation-operator/README.md index dea0a03c01..82769d80a3 100644 --- a/packages/babel-plugin-transform-exponentiation-operator/README.md +++ b/packages/babel-plugin-transform-exponentiation-operator/README.md @@ -1,6 +1,30 @@ # babel-plugin-transform-exponentiation-operator -Compile exponentiation operator to ES5 +> Compile exponentiation operator to ES5 + +## Example + +```js +// x ** y + +let squared = 2 ** 2; +// same as: 2 * 2 + +let cubed = 2 ** 3; +// same as: 2 * 2 * 2 + + +// x **= y + +let a = 2; +a **= 2; +// same as: a = a * a; + +let b = 3; +b **= 3; +// same as: b = b * b * b; +``` +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=%2F%2F%20x%20**%20y%0A%0Alet%20squared%20%3D%202%20**%202%3B%0A%2F%2F%20same%20as%3A%202%20*%202%0A%0Alet%20cubed%20%3D%202%20**%203%3B%0A%2F%2F%20same%20as%3A%202%20*%202%20*%202%0A%0A%0A%2F%2F%20x%20**%3D%20y%0A%0Alet%20a%20%3D%202%3B%0Aa%20**%3D%202%3B%0A%2F%2F%20same%20as%3A%20a%20%3D%20a%20*%20a%3B%0A%0Alet%20b%20%3D%203%3B%0Ab%20**%3D%203%3B%0A%2F%2F%20same%20as%3A%20b%20%3D%20b%20*%20b%20*%20b%3B) ## Installation @@ -33,3 +57,8 @@ require("babel-core").transform("code", { plugins: ["transform-exponentiation-operator"] }); ``` + +## References + +* [Proposal: Exponentiation Operator](https://github.com/rwaldron/exponentiation-operator) +* [Spec: Exponential Operator](https://rwaldron.github.io/exponentiation-operator/) diff --git a/packages/babel-plugin-transform-export-extensions/README.md b/packages/babel-plugin-transform-export-extensions/README.md index 5a1a60b74b..26f7d51278 100644 --- a/packages/babel-plugin-transform-export-extensions/README.md +++ b/packages/babel-plugin-transform-export-extensions/README.md @@ -1,6 +1,14 @@ # babel-plugin-transform-export-extensions -Compile export extensions to ES2015 +> Compile additional export-from statements to ES2015 + +## Example + +```js +export * as ns from 'mod'; +export v from 'mod'; +``` +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=export%20*%20as%20ns%20from%20'mod'%3B%0Aexport%20v%20from%20'mod'%3B) ## Installation @@ -33,3 +41,8 @@ require("babel-core").transform("code", { plugins: ["transform-export-extensions"] }); ``` +## References + +* ~~[Proposal: Additional export-from statements in ES7](https://github.com/leebyron/ecmascript-more-export-from)~~ (Withdrawn) +* [ECMAScript Proposal: export ns from](https://github.com/leebyron/ecmascript-export-ns-from) +* [ECMAScript Proposal: export default from](https://github.com/leebyron/ecmascript-export-default-from) diff --git a/packages/babel-plugin-transform-flow-comments/README.md b/packages/babel-plugin-transform-flow-comments/README.md index 2c1c58cf49..46beb7a301 100644 --- a/packages/babel-plugin-transform-flow-comments/README.md +++ b/packages/babel-plugin-transform-flow-comments/README.md @@ -1,10 +1,10 @@ # babel-plugin-transform-flow-comments -Turn flow type annotations into comments. +> Turn flow type annotations into comments. You should be able to use this plugin instead of `babel-plugin-flow-strip-types` to preserve the `/* @flow */` directive and still use flow. -http://flowtype.org/blog/2015/02/20/Flow-Comments.html +[Flow Comments Blog Post](http://flowtype.org/blog/2015/02/20/Flow-Comments.html) ## Example diff --git a/packages/babel-plugin-transform-flow-strip-types/README.md b/packages/babel-plugin-transform-flow-strip-types/README.md index 01a4a03b6b..afde54949b 100644 --- a/packages/babel-plugin-transform-flow-strip-types/README.md +++ b/packages/babel-plugin-transform-flow-strip-types/README.md @@ -1,6 +1,23 @@ # babel-plugin-transform-flow-strip-types -Strip flow type annotations from your output code. +> Strip all [flow](http://flowtype.org) type annotations and declarations from your output code. + +## Example + +**In** + +```javascript +function foo(one: any, two: number, three?): string {} +``` + +**Out** + +```javascript +function foo(one, two, three) {} +``` + +[Try in REPL](http://babeljs.io/repl/#?babili=false&evaluate=true&lineWrap=false&presets=react&code=function%20foo(one%3A%20any%2C%20two%3A%20number%2C%20three%3F)%3A%20string%20%7B%7D&experimental=false&loose=false&spec=false&playground=false&stage=0 +) ## Installation diff --git a/packages/babel-plugin-transform-function-bind/README.md b/packages/babel-plugin-transform-function-bind/README.md index 26321f0592..8e11aeae86 100644 --- a/packages/babel-plugin-transform-function-bind/README.md +++ b/packages/babel-plugin-transform-function-bind/README.md @@ -1,6 +1,86 @@ # babel-plugin-transform-function-bind -Compile function bind operator to ES5 +> Compile the new function bind operator `::` to ES5. + +## Detail + +```js +obj::func +// is equivalent to: +func.bind(obj) + +obj::func(val) +// is equivalent to: +func.call(obj, val) + +::obj.func(val) +// is equivalent to: +func.call(obj, val) +``` + +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=obj%3A%3Afunc%3B%0A%0Aobj%3A%3Afunc(val)%3B%0A%0A%3A%3Aobj.func(val)%3B) + +## Example + +### Basic + +```js +const box = { + weight: 2, + getWeight() { return this.weight; }, +}; + +const { getWeight } = box; + +console.log(box.getWeight()); // prints '2' + +const bigBox = { weight: 10 }; +console.log(bigBox::getWeight()); // prints '10' + +// Can be chained: +function add(val) { return this + val; } + +console.log(bigBox::getWeight()::add(5)); // prints '15' +``` + +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=const%20box%20%3D%20%7B%0A%20%20weight%3A%202%2C%0A%20%20getWeight()%20%7B%20return%20this.weight%3B%20%7D%2C%0A%7D%3B%0A%0Aconst%20%7B%20getWeight%20%7D%20%3D%20box%3B%0A%0Aconsole.log(box.getWeight())%3B%20%2F%2F%20prints%20'2'%0A%0Aconst%20bigBox%20%3D%20%7B%20weight%3A%2010%20%7D%3B%0Aconsole.log(bigBox%3A%3AgetWeight())%3B%20%2F%2F%20prints%20'10'%0A%2F%2F%20bigBox%3A%3AgetWeight()%20is%20equivalent%20to%20getWeight.call(bigBox)%0A%0A%2F%2F%20Can%20be%20chained%3A%0Afunction%20add(val)%20%7B%20return%20this%20%2B%20val%3B%20%7D%0A%0Aconsole.log(bigBox%3A%3AgetWeight()%3A%3Aadd(5))%3B%20%2F%2F%20prints%20'15') + +### Using with `document.querySelectorAll` + +It can be very handy when used with `document.querySelectorAll`: + +```js +const { map, filter } = Array.prototype; + +let sslUrls = document.querySelectorAll('a') + ::map(node => node.href) + ::filter(href => href.substring(0, 5) === 'https'); + +console.log(sslUrls); +``` + +[Try in REPL](http://babeljs.io/repl/#?evaluate=true&presets=es2015%2Cstage-0&code=%0Aconst%20%7B%20map%2C%20filter%20%7D%20%3D%20Array.prototype%3B%0A%0Alet%20sslUrls%20%3D%20document.querySelectorAll('a')%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3A%3Amap(node%20%3D%3E%20node.href)%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%3A%3Afilter(href%20%3D%3E%20href.substring(0%2C%205)%20%3D%3D%3D%20'https')%3B%0A%0Aconsole.log(sslUrls)%3B%0A) + +`document.querySelectorAll` returns a `NodeList` element which is not a plain array, so you normally can't use the `map` function on it, and have to use it this way: `Array.prototype.map.call(document.querySelectorAll(...), node => { ... })`. The above code using the `::` will work because it is equivalent to: + +```js +const { map, filter } = Array.prototype; + +let sslUrls = document.querySelectorAll('a'); +sslUrls = map.call(sslUrls, node => node.href); +sslUrls = filter.call(sslUrls, href => href.substring(0, 5) === 'https'); + +console.log(sslUrls); +``` + +### Auto self binding +When nothing is specified before the `::` operator, the function is bound to its object: + +```js +$('.some-link').on('click', ::view.reset); +// is equivalent to: +$('.some-link').on('click', view.reset.bind(view)); +``` ## Installation @@ -33,3 +113,8 @@ require("babel-core").transform("code", { plugins: ["transform-function-bind"] }); ``` + +## References + +* [Proposal](https://github.com/zenparsing/es-function-bind) +* [Babel Blog: Function Bind Syntax](/blog/2015/05/14/function-bind) \ No newline at end of file diff --git a/packages/babel-plugin-transform-jscript/README.md b/packages/babel-plugin-transform-jscript/README.md index 095da826d9..5595b21b55 100644 --- a/packages/babel-plugin-transform-jscript/README.md +++ b/packages/babel-plugin-transform-jscript/README.md @@ -1,6 +1,28 @@ # babel-plugin-transform-jscript -Babel plugin to fix buggy JScript named function expressions +> This plugin allows Babel to transform named function expressions into function declarations to get around some [particularly nasty JScript bugs](https://kangax.github.io/nfe/#jscript-bugs) related to name function expressions. + +## Example + +**In** + +```javascript +var foo = function bar() { + +}; +``` + +**Out** + +```javascript +"use strict"; + +var foo = (function () { + function bar() {} + + return bar; +})(); +``` ## Installation diff --git a/packages/babel-plugin-transform-object-set-prototype-of-to-assign/README.md b/packages/babel-plugin-transform-object-set-prototype-of-to-assign/README.md index 02e5f5e8e9..e11da1d99d 100644 --- a/packages/babel-plugin-transform-object-set-prototype-of-to-assign/README.md +++ b/packages/babel-plugin-transform-object-set-prototype-of-to-assign/README.md @@ -1,7 +1,6 @@ # babel-plugin-transform-object-set-prototype-of-to-assign - -The `object-set-prototype-of-to-assign` plugin will transform all `Object.setPrototypeOf` calls to a method that will do a shallow defaults of all properties. +> This plugin will transform all `Object.setPrototypeOf` calls to a method that will do a shallow defaults of all properties. **NOTE:** There are some caveats when using this plugin, see the [`babel-plugin-transform-proto-to-assign` README](https://github.com/babel/babel/tree/master/packages/babel-plugin-transform-proto-to-assign) for more information.. diff --git a/packages/babel-plugin-transform-proto-to-assign/README.md b/packages/babel-plugin-transform-proto-to-assign/README.md index 1f41851e8b..9e6997265b 100644 --- a/packages/babel-plugin-transform-proto-to-assign/README.md +++ b/packages/babel-plugin-transform-proto-to-assign/README.md @@ -1,7 +1,8 @@ # babel-plugin-transform-proto-to-assign -The `proto-to-assign`plugin will transform all `__proto__` assignments to a method that will do a shallow copy of -all properties. +> This plugin allows Babel to transform all `__proto__` assignments to a method that will do a shallow copy of all properties. + +## Detail This means that the following **will** work: diff --git a/packages/babel-plugin-transform-runtime/README.md b/packages/babel-plugin-transform-runtime/README.md index 98eb124fd8..747c11d09a 100644 --- a/packages/babel-plugin-transform-runtime/README.md +++ b/packages/babel-plugin-transform-runtime/README.md @@ -1,18 +1,20 @@ # babel-plugin-transform-runtime -Externalise references to helpers and builtins, automatically polyfilling your code without polluting globals. +> Externalise references to helpers and builtins, automatically polyfilling your code without polluting globals. (This plugin is recommended in a library/tool) + +NOTE: Instance methods such as `"foobar".includes("foo")` will not work since that would require modification of existing builtins (Use [`babel-polyfill`](http://babeljs.io/docs/usage/polyfill) for that). ## Why? Babel uses very small helpers for common functions such as `_extend`. By default this will be added to every file that requires it. This duplication is sometimes unnecessary, especially when your application is spread out over multiple files. -This is where the runtime transformer plugin comes in: all of the helpers will reference the module babel-runtime to avoid duplication across your compiled output. The runtime will be compiled into your build. +This is where the `transform-runtime` plugin comes in: all of the helpers will reference the module `babel-runtime` to avoid duplication across your compiled output. The runtime will be compiled into your build. -Another purpose of this transformer is to create a sandboxed environment for your code. If you use [babel-polyfill](https://babeljs.io/docs/usage/polyfill/) and the built-ins it provides such as `Promise`, `Set` and `Map`, those will pollute the global scope. While this might be ok for an app or a command line tool, it becomes a problem if your code is a library which you intend to publish for others to use or if you can't exactly control the environment in which your code will run. +Another purpose of this transformer is to create a sandboxed environment for your code. If you use [babel-polyfill](http://babeljs.io/docs/usage/polyfill/) and the built-ins it provides such as `Promise`, `Set` and `Map`, those will pollute the global scope. While this might be ok for an app or a command line tool, it becomes a problem if your code is a library which you intend to publish for others to use or if you can't exactly control the environment in which your code will run. The transformer will alias these built-ins to `core-js` so you can use them seamlessly without having to require the polyfill. -See the technical details section for more information on how this works and the types of transformations that occur. +See the [technical details](#technical-details) section for more information on how this works and the types of transformations that occur. ## Installation @@ -20,9 +22,14 @@ See the technical details section for more information on how this works and the npm install --save-dev babel-plugin-transform-runtime ``` -It is also recommended you install the `babel-runtime` package as a -runtime dependency, if you haven't already, as the transformed code will -require that package. See the examples below for more details. +It is also recommended you install the [babel-runtime](https://www.npmjs.com/package/babel-runtime) package as a runtime dependency, if you haven't already, as the transformed code will require that package. See the examples below for more details. + +**NOTE - Production vs. development dependencies** + +In most cases, you should install `babel-plugin-transform-runtime` as a development dependency (with `--save-dev`) and `babel-runtime` as a production dependency (with `--save`). + +The transformation plugin is typically used only in development, but the runtime itself will be depended on by your deployed/published code. + ## Usage diff --git a/packages/babel-plugin-transform-strict-mode/README.md b/packages/babel-plugin-transform-strict-mode/README.md index e03dd92c23..d6c258d300 100644 --- a/packages/babel-plugin-transform-strict-mode/README.md +++ b/packages/babel-plugin-transform-strict-mode/README.md @@ -1,11 +1,26 @@ # babel-plugin-transform-strict-mode -Add the `"use strict";` directive to the top of your files if it is not there -already. +> This plugin places a `"use strict";` directive at the top of all files to enable [strict mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode). -> This plugin may be enabled via `babel-plugin-transform-es2015-modules-commonjs`. -> If you wish to disable it you can either turn `strict` off or pass -> `strictMode: false` as an option to the commonjs transform. +This plugin may be enabled via `babel-plugin-transform-es2015-modules-commonjs`. +If you wish to disable it you can either turn `strict` off or pass +`strictMode: false` as an option to the commonjs transform. + +## Example + +**In** + +```javascript +foo(); +``` + +**Out** + +```javascript +"use strict"; + +foo(); +``` ## Installation diff --git a/packages/babel-plugin-undeclared-variables-check/README.md b/packages/babel-plugin-undeclared-variables-check/README.md index 34ddfff0fd..5bdf1b783a 100644 --- a/packages/babel-plugin-undeclared-variables-check/README.md +++ b/packages/babel-plugin-undeclared-variables-check/README.md @@ -1,6 +1,27 @@ # babel-plugin-undeclared-variables-check -Throw a compile-time error on references to undeclared variables +> This plugin throws a compile-time error on references to undeclared variables. + +## Example + +**In** + +```javascript +function foo() {} +foo(); +bar(); +``` + +**Out** + +``` +ReferenceError: stdin: Line 3: Reference to undeclared variable "bar" - did you mean "foo"? + 1 | function foo() {} + 2 | foo(); +> 3 | bar(); + | ^ + 4 | +``` ## Installation