js-openstack-lib/doc/source/specs/es2015.rst

::

  Copyright 2016 Hewlett Packard Development Corporation, L.P.

  This work is licensed under a Creative Commons Attribution 3.0
  Unported License.
  http://creativecommons.org/licenses/by/3.0/legalcode

..

===========================
Support for ECMAScript 2015
===========================

We need to make a decision on what language this project will use, and
whether we will transpile to other languages. If we want to use a transpiler,
we need to support it both for Node.js and browser builds and tests.

Problem Description
===================

There are four languages currently in active use in the JavaScript community.
ECMAScript 2015, ECMAScript 5, CoffeeScript, and TypeScript. It also needs to
support multiple runtimes: Browser and Node.js. We need to settle on which
language to use, and how to support all of our targeted runtimes.

Proposed Change
===============

This project will use ECMAScript 2015 as its primary language. Support for
projects that do not support this language will be provided using Babel as
a transpiler.

Setting up Babel
----------------

Babel should be configured using `.babelrc` file, so that configuration will
be used for all the environments we're targeting.

.. code-block:: json

  {
    "presets": ["es2015"]
  }

Node.js Build
-------------

We're targeting Node.js v4, which doesn't support all the ES2015 features, so
usage of Babel is required. Babel can be integrated by specifying `prepublish`
hook which runs Babel to transpile library's code and overriding main module in
`package.json`.

.. code-block:: json

  {
    "main": "./dist/index.js",
    "scripts": {
      "build": "babel ./src --out-dir ./dist",
      "prepublish": "npm run build"
    }
  }

Browser Build
-------------

Webpack will be used to create ES5 builds which are intended to run in
browsers. `babel-loader` should be used to integrate Webpack and Babel.

Since `node-fetch` module which is used for sending HTTP requests isn't
supposed to be run in browser environments, it should be substituted with
`whatwg-fetch` polyfill using Webpack's `node` configuration option.

Here is an example of `webpack.config.js` file:

.. code-block:: javascript

  module.exports = {
    entry: [
      './src/index.js'
    ],
    output: {
      path: require('path').join(__dirname, '/dist/browser/'),
      chunkFilename: null,
      filename: 'openstack-lib-browser.js',
      sourceMapFilename: 'openstack-lib-browser.js.map'
    },
    module: {
      loaders: [
        {
          test: /\.js$/,
          loader: 'babel',
          exclude: [/node_modules\//],
          query: {cacheDirectory: true}
        }
      ]
    },
    node: {
      "node-fetch": "whatwg-fetch"
    }
  };

Node.js Testing
---------------

It was agreed that we're using Jasmine for tests. Jasmine can be easily
integrated with Babel by adding the following entry to `jasmine.json`:

.. code-block:: json

  {
    "helpers": [
      "../node_modules/babel-register/lib/node.js"
    ]
  }

Browser Testing
---------------

One of the popular test runners Karma can be easily integrated with Babel and
Webpack using `karma-webpack` plugin. There is also `karma-babel-preprocessor`
module, but it's not needed since integration with Babel is described in
`webpack.config.js` file.

Here is an example of `karma.conf.js` file:

.. code-block:: javascript

module.exports = function(config) {
  config.set({
    browsers: ['Chrome', 'Firefox'],
    plugins: [
      'karma-webpack'
    ],
    preprocessors: {
      'tests/**/*.js': ['webpack']
    },
    webpack: require('./webpack.config')
  });
};

Gulp Integration
----------------

The latest version of Gulp can be easily integrated with Babel just by renaming
`gulpfile.js` to `gulpfile.babel.js`. Gulp will transpile the Gulpfile using
Babel configuration from `.babelrc` file.

Implementation
==============

Assignee(s)
-----------

Primary assignee:
  vkramskikh

Gerrit Topic
------------

Use Gerrit topic "jsdk_es2015" for all patches related to this spec.

.. code-block:: bash

    git-review -t jsdk_es2015

Work Items
----------

* Babel and related dependencies should be added.
* Babel configuration should be added.
* Jasmine and Karma configuration files should be updated to support Babel.
* Webpack should be added and configured to use Babel.
* NPM scripts to run node/browser builds/tests should be added to package.json.

Documentation
-------------

We will need project setup documentation for browsers and node applications.
All documentation code samples should include examples using all available
languages.

Testing
-------

* All code samples should be tested.
* Our test suite should be run separately on each transpiled artifact.