raml-json-enhance-template.html

<!--
@license
Copyright 2016 The Advanced REST client authors <arc@mulesoft.com>
Licensed under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance with the License. You may obtain a copy of
the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations under
the License.
-->
<link rel="import" href="../polymer/polymer.html">
<!--
The `<raml-json-enhance>` enhaces the JSON output from the RAML parser so it can
be used in the ARC elements (which expects enhanced data structure).

The work is asynchronous. After the `json` property is set/changed it will call the
worker automatically and report the result via the `raml-json-enhance-ready` event.

Polymer application can bind to the `result` property which will notify the change.

### Example
```
<raml-json-enhance json="{...}"></raml-json-enhance>
window.addEventListener('raml-json-enhance-ready', function(e) {
  console.log(e.detail.json);
  // equals to
  console.log(e.target.result);
});
```

**Note** This element MUST be used to enhance parser JSON output in order to use
any RAML related ARC element. Enhancer creates common data structure and
expands RAML types. Element expects the JSON object to contain complete data
about method / endpoint / type / security scheme and so on. It will not look for
the data in the root of raml definition. Thanks to this, you can push just a part
of the JSON object to a specific element to make it work.

For example, the `<raml-docs-method-viewer>` viewer expects the `raml` propety to
be a method definition only (without of the rest of the RAML structure). If
enhanced with the library, the JSON object describing the method will contain
all required information to render the view.

The element contains a set of Polyfills so it will work in IE11+ browsers.

### Biuld process
This element uses web workers to expand JSON result (normalize it).
The element will attempty to load following scitps from the same location where
this script resides:
- polyfills.js
- browser/index.js
- raml2object.js
Build scripts should ensure that this resources are included in the final build.

## Affected properties
- `types`, `traits`, `resourceTypes`, `annotationTypes`, `securitySchemes` - Becomes an object instead of array, keys are object name (with library variable name if applicable)
- `responses`, `body`, `queryParameters`, `headers`, `properties`, `baseUriParameters`, `annotations`, `uriParameters` are recusively transformed into the arrays
- types/{object} - Expanded form for a RAML type and a canonical form with computed inheritance and pushed unions to the top level of the type structure. See documantaion for the [expansion library](https://github.com/raml-org/raml-parser-toolbelt/tree/master/tools/datatype-expansion).
- resource/parentUrl - a full URL of the parent resource
- resource/allUriParameters - list of all URI parameters that apply to this resource (computed from the root down to current resource)
- resource/securedBy - Replaces security schema name with schema's definition.
- method/allUriParameters - The same as for a resource but applied to a method that is direct child of the resource.
- method/absoluteUri - Full, absolute URL to the method containg URI parametes in their RAML's form, eg `/{fileId}`
- method/securedBy - The same as for the resource
- method/*/headers - Full list of all possible headers compured from traits, security schemes etc
- method/*/queryParameters - Full list of all possible queryParameters compured from traits, security schemes etc
- method/responses - Full list of all possible response compured from traits, security schemes etc
- type/properties/items - replaces type name with type definition
- */example(s) - always produces `examples` as an array of example contents
- */structuredExample - content is moved to the *.example array

## Developing this element

Unlike other web components this component has to be build. Make any
changes to the `raml-json-enhance-template.html`. After making a change call
`npm run build`. It will concatenate all required files
and insert generated web worker contentnt into the element's body.

The `raml-json-enhance.html` will be regenerated each time you call build
script.

@group RAML Elements
@element raml-json-enhance
@demo demo/index.html
-->
<dom-module id="raml-json-enhance">
  <template>
    <style>
     :host {
      display: none;
    }
    </style>
    <script id="normalizer" type="javascript/worker">{{RAML2OBJ_CONTENT}}</script>
  </template>
  <script>
  (function() {
  /**
   * Making the a private propery not available in element's API.
   * Contains a list of currently running workers.
   *
   * @type {Array}
   */
  var WORKERS = [];
  /**
   * @param {String} name Name of the worker.
   * @return {Worker} A worker object for the name.
   */
  function getWorker(name) {
    for (var i = 0, len = WORKERS.length; i < len; i++) {
      if (WORKERS[i].name === name) {
        return WORKERS[i].ref;
      }
    }
  }
  Polymer({
    is: 'raml-json-enhance',
    properties: {
      /**
       * A JSON retuned by the `toJson()` function of the RAML JS parser's
       * API object.
       */
      json: {
        type: Object,
        observer: '_jsonChnaged'
      },
      // The result of enhancing the `json` object.
      result: {
        type: Object,
        notify: true,
        readOnly: true
      },
      // Flag set to true when currently JSON is being enhanced.
      expanding: {
        type: Boolean,
        notify: true,
        readOnly: true
      },
      /**
       * If true it will instruct `raml2obj` library to measure execution
       * time. It will be printed to the console after RAML is enhanced
       */
      printMeasurements: Boolean
    },
    // Handler for the `json` property change.
    _jsonChnaged: function(json) {
      if (!json) {
        return this._setResult(undefined);
      }
      this._noSupportedError();
      if (json.specification) {
        json = json.specification;
      }
      this._killWorkers();
      this.enhance(json);
    },
    /**
     * Sends an error when running from unsupported browser.
     */
    _noSupportedError: function() {
      var ie10 = /msie 10/i.test(navigator.userAgent);
      if (!ie10) {
        return;
      }
      this._setResult(undefined);
      this.fire('error', {
        message: 'This browser is not supported.'
      });
      throw new Error('This browser is not supported.');
    },
    /**
     * Terminates currently running workers.
     * Thisa is helpful when another process is requested and old process is
     * still running. It terminates workers so messages from them won't be
     * sent to the main thread and notified outside for old api call.
     *
     * It also clears data URL object created by URL.createObjectURL().
     *
     * This resets state to 0.
     */
    _killWorkers: function() {
      for (var i = WORKERS.length - 1; i >= 0; i--) {
        this.__terminateWorker(WORKERS[i]);
        WORKERS.splice(i, 1);
      }
    },
    /**
     * Terminates the worker if it exists and is running
     *
     * @param {Object} workerRef An object created by `__createWorker` function
     */
    __terminateWorker: function(workerRef) {
      workerRef.ref.terminate();
      workerRef.ref.removeEventListener('message', workerRef.data);
      workerRef.ref.removeEventListener('error', workerRef.error);
      this.__clearDataUrl(workerRef.url);
    },
    /**
     * Clears a data URL created by URL.createObjectURL().
     *
     * @param {String} url The URL to clean
     */
    __clearDataUrl: function(url) {
      if (url) {
        window.URL.revokeObjectURL(url);
      }
    },
    /**
     * Creates a web workers before the work starts.
     */
    _createWorkers: function() {
      var norm = this.__createWorker('_normalize', this.$.normalizer.textContent);
      WORKERS.push(norm);
    },
    /**
     * Creates an instance of web worker from a text content.
     *
     * @param {String} property Name of the worker. `this` must contains
     * functions for handling data and errors named `property` + `DataHandler`
     * and `property` + `ErrorHandler`
     * @param {String} body Body of the worker
     */
    __createWorker: function(property, body) {
      var blob = new Blob([body]);
      var workerUrl = window.URL.createObjectURL(blob);
      var worker = new Worker(workerUrl);
      var dataHandler = this[property + 'DataHandler'].bind(this);
      var errorHandler = this[property + 'ErrorHandler'].bind(this);
      worker.addEventListener('message', dataHandler);
      worker.addEventListener('error', errorHandler);

      return {
        name: property,
        ref: worker,
        url: workerUrl,
        error: errorHandler,
        data: dataHandler
      };
    },
    /**
     * Enhances the JavaScript object.
     *
     * @param {Object} json An object returned from RAML js parser after calling
     * `toJSON`.
     */
    enhance: function(json) {
      this._setExpanding(true);
      this._createWorkers();
      var worker = getWorker('_normalize');
      var message = {
        payload: 'parse',
        json: json,
        takeMeasurements: this.printMeasurements
      };
      worker.postMessage(message);
    },
    /**
     * Reports results to the called by dispatching the
     * `raml-json-enhance-ready` event.
     *
     * @param {Object} result Expanded and normalized object.
     */
    _reportResult: function(result) {
      this._setResult(result);
      this.fire('raml-json-enhance-ready', {
        json: result
      });
      this._killWorkers();
    },
    /**
     * Reports an error
     *
     * @param {String} errorMessage Error message to report.
     */
    _reportError: function(errorMessage) {
      var err = new Error(errorMessage);
      this.fire('error', {
        message: err.message
      });
      this._killWorkers();
      throw err;
    },
    /**
     * Handler for a message from the normalize worker.
     * Depending on current state it calls next function in the chain.
     */
    _normalizeDataHandler: function(e) {
      this._setExpanding(false);
      var data = e.data;
      if (data.error) {
        this._reportError(data.message);
        return;
      }
      var json = data.result.json;
      this._reportResult(json);
      if (data.result.measurement) {
        console.table(data.result.measurement);
      }
    },
    /**
     * Normalize worker error handler.
     */
    _normalizeErrorHandler: function(e) {
      var message = (e && e.message) ? 'Normalize worker: ' + e.message :
        'Unknown normalize worker error.';
      this._reportError(message);
    }
  });
  })();
  </script>
</dom-module>