= 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 up to ES2021 -- see <> for a complete list.

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}

=== Compatibility Matrix

|=== | preset-njs | njs | Babel

| 0.1.0 – 0.2.1 | ≥ 0.5.0 | 7 | 0.7.0 | ≥ 0.7.0 | 7 |===

== Usage

=== With a Configuration File (Recommended)

[source, json, subs="+attributes"]

{
"presets": ["{npm-name}"]
}

=== 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}')],
})

== 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 up to ES2021.

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.

| {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-reserved-words[reserved-words] | ES3 | {not-needed} |

| {babel-plugin-uri}-transform-property-mutators[property-mutators] | ES5 | {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 | {not-needed} | since njs 0.6.0

| {babel-plugin-uri}-transform-classes[classes] | ES2015 | {included} |

| {babel-plugin-uri}-transform-computed-properties[computed-properties] | ES2015 | {not-needed} | since njs 0.3.4

| {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} | Only rest parameters are supported.

| {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 | {not-needed} | since njs 0.6.0

| {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 | {not-needed} | Supported, but not in identifiers (e.g. variable name).

| {babel-plugin-uri}-transform-unicode-regex[unicode-regex] | ES2015 | {included} |

| {babel-plugin-uri}-transform-exponentiation-operator[exponentiation-operator] | ES2016 | {not-needed} |

| {babel-plugin-uri}-transform-async-to-generator[async-to-generator] | ES2017 | {not-needed} | since njs 0.7.0

| {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] | ES2018 | {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-json-strings[json-strings] | ES2019 | {not-needed} |

| {babel-plugin-uri}-proposal-dynamic-import[dynamic-import] | ES2020 | {incompatible} | njs has only limited support of ES modules.

| {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-optional-chaining[optional-chaining] | ES2020 | {included} |

| {babel-plugin-uri}-proposal-logical-assignment-operators[logical-assignment-operators] | ES2021 | {included} |

| {babel-plugin-uri}-proposal-numeric-separator[numeric-separator] | ES2021 | {not-needed} | |===

== Enabled Assumptions

The following assumptions are enabled for better performance and match with the behaviour of the TypeScript transpiler.

{babel-doc-uri}/assumptions#constantsuper[constantSuper] ({babel-plugin-uri}-transform-classes#loose[classes])
{babel-doc-uri}/assumptions#noclasscalls[noClassCalls] ({babel-plugin-uri}-transform-classes#loose[classes])
{babel-doc-uri}/assumptions#setclassmethods[setClassMethods] ({babel-plugin-uri}-transform-classes#loose[classes])
{babel-doc-uri}/assumptions#superiscallableconstructor[superIsCallableConstructor] ({babel-plugin-uri}-transform-classes#loose[classes])
{babel-doc-uri}/assumptions#ignorefunctionlength[ignoreFunctionLength] ({babel-plugin-uri}-transform-parameters#loose[parameters])
{babel-doc-uri}/assumptions#iterableisarray[iterableIsArray] ({babel-plugin-uri}-transform-for-of#assumearray[for-of], {babel-plugin-uri}-transform-spread#loose[spread], {babel-plugin-uri}-transform-destructuring#loose[destructuring])
{babel-doc-uri}/assumptions#nodocumentall[noDocumentAll]
{babel-doc-uri}/assumptions#nonewarrows[noNewArrows]
{babel-doc-uri}/assumptions#setspreadproperties[setSpreadProperties] ({babel-plugin-uri}-proposal-object-rest-spread#loose[object-rest-spread])

endif::npm-readme[]

== References