README
= babel-preset-njs :npm-name: babel-preset-njs :gh-name: jirutka/{npm-name} :gh-branch: master :ci-workflow: npmjs :babel-doc-uri: https://babeljs.io/docs/en :object-rest-spread-mdn-uri: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#Spread_in_object_literals :array-spread-mdn-uri: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#Spread_in_array_literals :array-destructuring-mdn-uri: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment#Array_destructuring
ifdef::env-github[] image:https://img.shields.io/npm/v/{npm-name}.svg[npm Version, link="https://www.npmjs.org/package/{npm-name}"] image:https://github.com/{gh-name}/workflows/{ci-workflow}/badge.svg[CI State, link=https://github.com/{gh-name}/actions?query=workflow%3A%22{ci-workflow}%22] endif::env-github[]
A https://babeljs.io[Babel] https://babeljs.io/docs/en/presets[preset] for transforming JavaScript code with modern language features into code compatible with https://github.com/nginx/njs[njs] (NGINX JavaScript).
This preset includes support for all the ECMAScript features that TypeScript supports (https://tc39.es/process-document/[Stage] 3+) -- see <
TIP: Take a look at https://github.com/jirutka/njs-typescript-starter[njs-typescript-starter] for a complete starter template for developing njs scripts for https://nginx.org[NGINX] server in https://www.typescriptlang.org[TypeScript] (including integration tests).
== Installation
[source, sh, subs="+attributes"]
using npm:
npm install --save-dev {npm-name}
or using yarn:
yarn add --dev {npm-name}
== Usage
=== With a Configuration File (Recommended)
[source, json, subs="+attributes"]
{ "presets": ["{npm-name}"] }
[source, json, subs="+attributes"]
{ "presets": [ ["{npm-name}", { "assumeArrayIterables": false }] ] }
=== Via CLI
[source, sh, subs="+attributes"] babel --presets {npm-name} script.js
=== Via Node API
[source, js, subs="+attributes"]
require('@babel/core').transform('code', { presets: [require('{npm-name}')], })
== Options
=== assumeArrayIterables
boolean
, defaults to true
Assume that all iterables used in for\...of
loops, {array-spread-mdn-uri}[array spread syntax] and {array-destructuring-mdn-uri}[array destructuring] are arrays.
This produces more compact and significantly more performant code, but it will fail in runtime if the iterable is not an array.
TypeScript transpiler uses the same approach for ES5 target when downlevelIteration
is disabled.
It also indicates error when the iterable is not an array.
It sets the following plugin options:
- {babel-doc-uri}/babel-plugin-transform-for-of#assumearray[for-of]:
assumeArray
- {babel-doc-uri}/babel-plugin-transform-spread#loose[spread]:
loose
- {babel-doc-uri}/babel-plugin-transform-destructuring#loose[destructuring]:
loose
=== asyncHelpers
'external'
, 'local'
, 'inline'
Toggles how https://github.com/rpetrich/babel-plugin-transform-async-to-promises[async-to-promises] injects its helpers:
'external'
-- injects import frombabel-plugin-transform-async-to-promises/helpers
into each file with async/await'local'
-- injects the needed helper functions into each file with async/await'inline'
-- inlines the needed helper code in place of each occurrence of async/await
Defaults to 'external'
if Rollup or webpack is detected, otherwise 'local'
.
It sets the following plugin options:
- https://github.com/rpetrich/babel-plugin-transform-async-to-promises[async-to-promises]:
externalHelpers
,inlineHelpers
=== looseClasses
boolean
, defaults to true
Define class methods and properties using a simple assignment expression instead of Object.defineProperty()
.
This produces more compact and performant code, but it might produce unexpected results in some (corner) cases.
TypeScript transpiler uses the same approach.
It sets the following plugin options:
- {babel-doc-uri}/babel-plugin-transform-classes#loose[classes]:
loose
- {babel-doc-uri}/babel-plugin-proposal-class-properties#loose[class-properties]:
loose
- {babel-doc-uri}/babel-plugin-proposal-private-property-in-object#loose[private-property-in-object]:
loose
=== looseObjectRestSpread
boolean
, defaults to true
Transform {object-rest-spread-mdn-uri}[object rest/spread properties] using Object.assign()
instead of Babel’s objectSpread
helper.
This produces more compact and performant code, but it might produce unexpected results in some (corner) cases (when overwriting read-only target property).
TypeScript transpiler uses the same approach.
It sets the following plugin options:
- {babel-doc-uri}/babel-plugin-proposal-object-rest-spread#loose[object-rest-spread]:
loose
=== looseParameters
boolean
, defaults to true
In loose mode, function parameters with default values will be counted into the arity of the function. This is not spec behaviour where these parameters do not add to function arity, but it produces more compact and performant code. TypeScript transpiler uses the same approach.
It sets the following plugin options:
- {babel-doc-uri}/babel-plugin-transform-parameters#loose[parameters]:
loose
== Plugins :babel-plugin-uri: https://babeljs.io/docs/en/babel-plugin :included: ✓{nbsp}included :not-needed: ✗{nbsp}not{nbsp}needed :incompatible: ⚠{nbsp}incompatible
ifdef::npm-readme[] The list of included Babel plugins is available https://github.com/{gh-name}/blob/{gh-branch}/README.adoc#plugins[here].
endif::npm-readme[] ifndef::npm-readme[] The following table lists all relevant https://babeljs.io/docs/en/plugins#transform-plugins[Babel transform plugins] for ECMAScript features in at least https://tc39.es/process-document/[stage 3].
The State column is one of:
- {included} -- The plugin is included in this preset, i.e. njs doesn’t support this feature (or part of it) yet.
- {not-needed} -- The plugin is not needed, i.e. njs already supports this feature.
- {incompatible} -- The plugin is not compatible with njs, i.e. requires features that njs doesn’t support yet.
[cols="30,10,20,40"] |=== | Plugin | ECMAScript | State | Notes
| {babel-plugin-uri}-transform-member-expression-literals[member-expression-literals] | ES3 | {not-needed} |
| {babel-plugin-uri}-transform-property-literals[property-literals] | ES3 | {not-needed} |
| {babel-plugin-uri}-transform-property-mutators[property-mutators] | ES5 | {not-needed} |
| {babel-plugin-uri}-transform-reserved-words[reserved-words] | ES3 | {not-needed} |
| {babel-plugin-uri}-transform-arrow-functions[arrow-functions] | ES2015 | {not-needed} |
| {babel-plugin-uri}-transform-block-scoped-functions[block-scoped-functions] | ES2015 | {not-needed} |
| {babel-plugin-uri}-transform-block-scoping[block-scoping] | ES2015 | {included} |
| {babel-plugin-uri}-transform-classes[classes] | ES2015 | {included} |
| {babel-plugin-uri}-transform-computed-properties[computed-properties] | ES2015 | {included} |
| {babel-plugin-uri}-transform-destructuring[destructuring] | ES2015 | {included} |
| {babel-plugin-uri}-transform-duplicate-keys[duplicate-keys] | ES2015 | {not-needed} |
| {babel-plugin-uri}-transform-for-of[for-of] | ES2015 | {not-needed} |
| {babel-plugin-uri}-transform-function-name[function-name] | ES2015 | {incompatible} | https://github.com/nginx/njs/issues/360[njs bug #360]
| {babel-plugin-uri}-transform-instanceof[instanceof] | ES2015 | {not-needed} |
| {babel-plugin-uri}-transform-literals[literals] | ES2015 | {not-needed} |
| {babel-plugin-uri}-transform-new-target[new-target] | ES2015 | {not-needed} |
| {babel-plugin-uri}-transform-object-super[object-super] | ES2015 | {included} |
| {babel-plugin-uri}-transform-parameters[parameters] | ES2015 | {included} |
| {babel-plugin-uri}-transform-shorthand-properties[shorthand-properties] | ES2015 | {not-needed} |
| {babel-plugin-uri}-transform-spread[spread] | ES2015 | {included} |
| {babel-plugin-uri}-transform-sticky-regex[sticky-regex]
| ES2015
| {incompatible}
| njs doesn’t support regexp flag y
at all
| {babel-plugin-uri}-transform-template-literals[template-literals] | ES2015 | {not-needed} |
| {babel-plugin-uri}-transform-typeof-symbol[typeof-symbol] | ES2015 | {not-needed} |
| {babel-plugin-uri}-transform-unicode-escapes[unicode-escapes] | ES2015 | {included} |
| {babel-plugin-uri}-transform-unicode-regex[unicode-regex] | ES2015 | {included} |
| {babel-plugin-uri}-transform-exponentiation-operator[exponentiation-operator] | ES2016 | {not-needed} |
| https://github.com/rpetrich/babel-plugin-transform-async-to-promises[async-to-promises] | ES2017 | {included} | This is a third-party plugin, i.e. not included in any Babel presets.
| {babel-plugin-uri}-transform-async-to-generator[async-to-generator] | ES2017 | {incompatible} | njs doesn’t support generators yes; replaced by https://github.com/rpetrich/babel-plugin-transform-async-to-promises[async-to-promises]
| {babel-plugin-uri}-proposal-async-generator-functions[async-generator-functions] | ES2018 | {incompatible} | njs doesn’t support generators yet
| {babel-plugin-uri}-transform-dotall-regex[dotall-regex] | ES2017 | {included} |
| {babel-plugin-uri}-transform-named-capturing-groups-regex[named-capturing-groups-regex] | ES2018 | {not-needed} |
| {babel-plugin-uri}-proposal-object-rest-spread[object-rest-spread] | ES2018 | {included} |
| {babel-plugin-uri}-proposal-unicode-property-regex[unicode-property-regex] | ES2018 | {included} |
| {babel-plugin-uri}-proposal-optional-catch-binding[optional-catch-binding] | ES2019 | {included} |
| {babel-plugin-uri}-proposal-export-namespace-from[export-namespace-from] | ES2020 | {included} |
| {babel-plugin-uri}-proposal-nullish-coalescing-operator[nullish-coalescing-operator] | ES2020 | {not-needed} |
| {babel-plugin-uri}-proposal-private-property-in-object[private-property-in-object] | ES2020 | {included} |
| {babel-plugin-uri}-proposal-optional-chaining[optional-chaining] | ES2020 | {included} |
| {babel-plugin-uri}-proposal-logical-assignment-operators[logical-assignment-operators] | https://github.com/tc39/proposal-logical-assignment[Stage 4] | {included} |
| {babel-plugin-uri}-proposal-numeric-separator[numeric-separator] | https://github.com/tc39/proposal-numeric-separator[Stage 4] | {not-needed} |
| {babel-plugin-uri}-proposal-class-properties[class-properties] | https://github.com/tc39/proposal-class-fields[Stage 3] | {included} | |===
endif::npm-readme[]
== References
- http://nginx.org/en/docs/njs/compatibility.html[njs ECMAScript Compatibility]
== License
This project is licensed under http://opensource.org/licenses/MIT/[MIT License].