babel-preset-njs

A Babel preset for njs - NGINX JavaScript.

Usage no npm install needed!

<script type="module">
  import babelPresetNjs from 'https://cdn.skypack.dev/babel-preset-njs';
</script>

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 <> 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}

== 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 from babel-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:

=== 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

== License

This project is licensed under http://opensource.org/licenses/MIT/[MIT License].