<NME> README.md
<BEF> # PerfCascade
Responsive, SVG based [HAR](http://www.softwareishard.com/blog/har-12-spec/) waterfall viewer .

[![npm version](https://img.shields.io/npm/v/perf-cascade.svg?style=flat-square)](https://www.npmjs.com/package/perf-cascade)
[![npm downloads](https://img.shields.io/npm/dt/perf-cascade.svg?style=flat-square)](https://www.npmjs.com/package/perf-cascade)
[![Build status][travis-image]][travis-url]

Install via `npm install perf-cascade`<br/>
Live example: https://micmro.github.io/PerfCascade/

<img src="https://raw.githubusercontent.com/micmro/PerfCascade/gh-pages/img/PerfCascade-sample2.png" alt="example screenshot" width="704" height="707">

## Contents

- [How to use PerfCascade](#how-to-use-perfcascade)
  * [With ES6 Compatible Module Loader (Webpack, Babel, Typescript...)](#with-es6-compatible-module-loader--webpack--babel--typescript-)
  * [As Global Object](#as-global-object)
  * [Use via npm](#use-via-npm)
- [Options](#options)
- [`*.zhar` - zipped HAR files](#--zhar----zipped-har-files)
- [Rendering other formats (than HAR)](#rendering-other-formats--than-har-)
var perfCascadeSvg =  perfCascade.fromHar(harData.log, options)
```

You can find the compiled (and minified) JS in [`src/dist`](https://github.com/micmro/PerfCascade/tree/master/src/dist). Yor the basic version without zHAR support you need [`perf-cascade.min.js`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.min.js) and some basic CSS styles [`perf-cascade.css`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.css).

### Use via npm
As of `2.0.5` you can install PerfCascade via NPM as well:
Install the package
```
npm install perf-cascade --save
````

```javascript
import {fromHar} from 'perf-cascade'

// `myHarDoc` represents your HAR doc

const perfCascadeSvg = fromHar(myHarDoc)
document.appendChild(perfCascadeSvg)
```

_With TypeScript you can additionally import TypeDefinitions for `ChartOptions` (PerfCascade Options) and `harFormat` (namespace for HAR Typings)_

### As Global Object
When using PerfCascade without any module system it just exports as a global object `perfCascade`, you can use as following:
```javascript
/** pass HAR `perfCascade.fromHar` to generate the SVG element*/
var perfCascadeSvg =  perfCascade.fromHar(harData)
document.appendChild(perfCascadeSvg)
```

Or with options:
```javascript
/** override selected options for PerfCascade (all have defaults) */
var options = {
  showIndicatorIcons: false, //default: true
  leftColumnWidth: 30 //default: 25
}

var perfCascadeSvg =  perfCascade.fromHar(harData, options)
document.appendChild(perfCascadeSvg)
```

You can find the compiled (and minified) JS in the [releases tab](https://github.com/micmro/PerfCascade/releases). For the basic version without zHAR support you need [`perf-cascade.min.js`](https://github.com/micmro/PerfCascade/blob/release/perf-cascade.min.js) and some basic CSS styles [`perf-cascade.css`](https://github.com/micmro/PerfCascade/blob/release/perf-cascade.css).

### Use via npm
You can install PerfCascade via NPM as well:
```
npm install perf-cascade
```

Directories:
- `node_modules/perf-cascade/dist/`: bundled UMD modules and the css file in the directory.
- `node_modules/perf-cascade/lib`: contains the full project exported as separate ES6 modules
- `node_modules/perf-cascade/types`: Typescript typings

## Options
see [options.d.ts](https://github.com/micmro/PerfCascade/blob/main/src/ts/typing/options.ts) for source

| Option      | Type | Default Value | Description |
| ----------- | ---- | ------- | ----------- |
| `rowHeight` | `number` | `23` | Height of every request bar block plus spacer pixel (in px) default: 23 |
| `showAlignmentHelpers` | `boolean` | `true` | Show vertical lines to easier spot potential dependencies/blocking between requests |
| `showMimeTypeIcon` | `boolean` | `true` |  Show mime type icon on the left |
| `showIndicatorIcons` | `boolean` | `true` |  Show warning icons for potential issues on the left |
| `leftColumnWidth` | `number` | `25` | Relative width of the info column on the left (in percent) |
| `pageSelector` | `HTMLSelectElement` | `undefined` | DOM `<select>` element to use to select a run if the HAR contains multiple runs. |
| `selectedPage` | `number` | `0` | Zero-based index of the page to initially render.<br/>If `selectedPage` is larger than the number of pages the last page will be selected. |
| `legendHolder` | `HTMLElement`<br/>(DOM element) | `undefined` <br/>(not shown) | If set a legend explaining the waterfall colours is rendered in the `legendHolder` DOM element. |
| `showUserTiming` | `boolean` | `false` | If enabled the [UserTiming](https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API) data in WebPageTest's format `_userTime.*` get parsed and rendered as well.<br/>Matching `_userTime.startTimer-*` and `_userTime.endTimer-*` entries get combined into one block. |
| `showUserTimingEndMarker` | `boolean` | `false` (requires `showUserTiming` to be `true`) | If `showUserTiming` is enabled all `_userTime.endTimer-*` marker are hidden by default, only the UserTiming's start and duration is shown. This option also adds an `_userTime.endTimer-*` marker.

## `*.zhar` - zipped HAR files
By loading `/perf-cascade-file-reader.min.js` as in [this example](https://github.com/micmro/PerfCascade/blob/main/src/index.html#L78-L86) you can use `perfCascadeFileReader.readFile` to read a zip file and convert it to a JSON HAR object.

```javascript
perfCascadeFileReader.readFile(fileFromTheFileInput, fileName, function(error, data){
  if(error){
    // handle error
    console.error(error)
  }else{
    // handle success
    renderPerfCascadeChart(data)
  }
})
```

Optionally `perfCascadeFileReader.readFile` also takes a callback (`(progress:number) => void`) as a forth argument
that gets called whenever a new unzip progress status is available.

## Rendering other formats (than HAR)
PerfCascade is composed of a parser [`src/ts/transformers/har.ts`](https://github.com/micmro/PerfCascade/blob/main/src/ts/transformers/har.ts) that parsed HAR into PerfCascade's agnostic [`WaterfallDocs`](https://github.com/micmro/PerfCascade/blob/main/src/ts/typing/waterfall.ts) format and the renderer (see `PerfCascade()` in [`src/ts/main.ts`](https://github.com/micmro/PerfCascade/blob/main/src/ts/main.ts) that creates the chart SVG.

If you want to render another format, you could fork the repo and create a new parser in [`src/ts/transformers/`](https://github.com/micmro/PerfCascade/blob/main/src/ts/transformers/) and implement a new `fromMyNewFormat` function similar to `fromHar()`in [`src/ts/main.ts`](https://github.com/micmro/PerfCascade/blob/main/src/ts/main.ts) that takes your format, calls its parser and then calls the main `PerfCascade()` function with it and returns it.

It would also be possible to separate the renderer into a separate package, if there is enough interest to justify the effort (create an issue and we can discuss it).

## Dev
- Start live-reload server and Typescript compiler with watch: `npm run watch`
- Create uglified version: `npm run build`

_See `package.json` for other useful tasks like linting, release etc._

## Specs and resources

- [W3C HAR Spec](https://w3c.github.io/web-performance/specs/HAR/Overview.html)
- [HAR 1.2 Spec](http://www.softwareishard.com/blog/har-12-spec)
- [HAR Resources](https://github.com/ahmadnassri/har-resources)

[travis-image]: https://img.shields.io/travis/micmro/PerfCascade.svg?style=flat-square
[travis-url]: https://travis-ci.org/micmro/PerfCascade

<MSG> Push to trigger Travis.
<DFF> @@ -22,7 +22,7 @@ var options = {
 var perfCascadeSvg =  perfCascade.fromHar(harData.log, options)
 ```
 
-You can find the compiled (and minified) JS in [`src/dist`](https://github.com/micmro/PerfCascade/tree/master/src/dist). Yor the basic version without zHAR support you need [`perf-cascade.min.js`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.min.js) and some basic CSS styles [`perf-cascade.css`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.css).
+You can find the compiled (and minified) JS in [`src/dist`](https://github.com/micmro/PerfCascade/tree/master/src/dist). For the basic version without zHAR support you need [`perf-cascade.min.js`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.min.js) and some basic CSS styles [`perf-cascade.css`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.css).
 
 ### Use via npm
 As of `2.0.5` you can install PerfCascade via NPM as well:

{'commit': 'diff --git a/README.md b/README.md\nindex 7c896d9..14b1ea9 100644\n--- a/README.md\n+++ b/README.md\n@@ -22,7 +22,7 @@ var options = {\n var perfCascadeSvg =  perfCascade.fromHar(harData.log, options)\n ```\n \n-You can find the compiled (and minified) JS in [`src/dist`](https://github.com/micmro/PerfCascade/tree/master/src/dist). Yor the basic version without zHAR support you need [`perf-cascade.min.js`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.min.js) and some basic CSS styles [`perf-cascade.css`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.css).\n+You can find the compiled (and minified) JS in [`src/dist`](https://github.com/micmro/PerfCascade/tree/master/src/dist). For the basic version without zHAR support you need [`perf-cascade.min.js`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.min.js) and some basic CSS styles [`perf-cascade.css`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.css).\n \n ### Use via npm\n As of `2.0.5` you can install PerfCascade via NPM as well:\n', 'commit_subject': 'Push to trigger Travis.', 'repo_name': 'micmro/PerfCascade', 'committer': {'name': 'Tobias Lidskog', 'email': '059b8b880f8441509ec8a65b50b4c6ae74ebea76@lidskog.se', 'time_sec': '1482214592', 'tz_offset': '60', 'date': {'seconds': '1482214592'}}, 'commit_tree': 'aae705d9f243df61e7fd3f530955e7cdeb7c0fbb', 'commit_message': 'Push to trigger Travis.', 'language_name': 'TypeScript', 'license': 'mit', 'hunks': '@@ -22,7 +22,7 @@ var options = {\n var perfCascadeSvg =  perfCascade.fromHar(harData.log, options)\n ```\n \n-You can find the compiled (and minified) JS in [`src/dist`](https://github.com/micmro/PerfCascade/tree/master/src/dist). Yor the basic version without zHAR support you need [`perf-cascade.min.js`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.min.js) and some basic CSS styles [`perf-cascade.css`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.css).\n+You can find the compiled (and minified) JS in [`src/dist`](https://github.com/micmro/PerfCascade/tree/master/src/dist). For the basic version without zHAR support you need [`perf-cascade.min.js`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.min.js) and some basic CSS styles [`perf-cascade.css`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.css).\n \n ### Use via npm\n As of `2.0.5` you can install PerfCascade via NPM as well:\n', 'addition_count': 1, 'deletion_count': 1, 'src_file': 'a/README.md', 'tgt_file': 'b/README.md', 'file_extension': '.md', 'before_file': '# PerfCascade\nResponsive, SVG based [HAR](http://www.softwareishard.com/blog/har-12-spec/) waterfall viewer .\n\n[![npm version](https://img.shields.io/npm/v/perf-cascade.svg?style=flat-square)](https://www.npmjs.com/package/perf-cascade)\n[![npm downloads](https://img.shields.io/npm/dt/perf-cascade.svg?style=flat-square)](https://www.npmjs.com/package/perf-cascade)\n[![Build status][travis-image]][travis-url]\n\nInstall via `npm install perf-cascade`<br/>\nLive example: https://micmro.github.io/PerfCascade/\n\n<img src="https://raw.githubusercontent.com/micmro/PerfCascade/gh-pages/img/PerfCascade-sample2.png" alt="example screenshot" width="704" height="707">\n\n## Contents\n\n- [How to use PerfCascade](#how-to-use-perfcascade)\n  * [With ES6 Compatible Module Loader (Webpack, Babel, Typescript...)](#with-es6-compatible-module-loader--webpack--babel--typescript-)\n  * [As Global Object](#as-global-object)\n  * [Use via npm](#use-via-npm)\n- [Options](#options)\n- [`*.zhar` - zipped HAR files](#--zhar----zipped-har-files)\n- [Rendering other formats (than HAR)](#rendering-other-formats--than-har-)\nvar perfCascadeSvg =  perfCascade.fromHar(harData.log, options)\n```\n\nYou can find the compiled (and minified) JS in [`src/dist`](https://github.com/micmro/PerfCascade/tree/master/src/dist). Yor the basic version without zHAR support you need [`perf-cascade.min.js`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.min.js) and some basic CSS styles [`perf-cascade.css`](https://github.com/micmro/PerfCascade/blob/master/src/dist/perf-cascade.css).\n\n### Use via npm\nAs of `2.0.5` you can install PerfCascade via NPM as well:\nInstall the package\n```\nnpm install perf-cascade --save\n````\n\n```javascript\nimport {fromHar} from \'perf-cascade\'\n\n// `myHarDoc` represents your HAR doc\n\nconst perfCascadeSvg = fromHar(myHarDoc)\ndocument.appendChild(perfCascadeSvg)\n```\n\n_With TypeScript you can additionally import TypeDefinitions for `ChartOptions` (PerfCascade Options) and `harFormat` (namespace for HAR Typings)_\n\n### As Global Object\nWhen using PerfCascade without any module system it just exports as a global object `perfCascade`, you can use as following:\n```javascript\n/** pass HAR `perfCascade.fromHar` to generate the SVG element*/\nvar perfCascadeSvg =  perfCascade.fromHar(harData)\ndocument.appendChild(perfCascadeSvg)\n```\n\nOr with options:\n```javascript\n/** override selected options for PerfCascade (all have defaults) */\nvar options = {\n  showIndicatorIcons: false, //default: true\n  leftColumnWidth: 30 //default: 25\n}\n\nvar perfCascadeSvg =  perfCascade.fromHar(harData, options)\ndocument.appendChild(perfCascadeSvg)\n```\n\nYou can find the compiled (and minified) JS in the [releases tab](https://github.com/micmro/PerfCascade/releases). For the basic version without zHAR support you need [`perf-cascade.min.js`](https://github.com/micmro/PerfCascade/blob/release/perf-cascade.min.js) and some basic CSS styles [`perf-cascade.css`](https://github.com/micmro/PerfCascade/blob/release/perf-cascade.css).\n\n### Use via npm\nYou can install PerfCascade via NPM as well:\n```\nnpm install perf-cascade\n```\n\nDirectories:\n- `node_modules/perf-cascade/dist/`: bundled UMD modules and the css file in the directory.\n- `node_modules/perf-cascade/lib`: contains the full project exported as separate ES6 modules\n- `node_modules/perf-cascade/types`: Typescript typings\n\n## Options\nsee [options.d.ts](https://github.com/micmro/PerfCascade/blob/main/src/ts/typing/options.ts) for source\n\n| Option      | Type | Default Value | Description |\n| ----------- | ---- | ------- | ----------- |\n| `rowHeight` | `number` | `23` | Height of every request bar block plus spacer pixel (in px) default: 23 |\n| `showAlignmentHelpers` | `boolean` | `true` | Show vertical lines to easier spot potential dependencies/blocking between requests |\n| `showMimeTypeIcon` | `boolean` | `true` |  Show mime type icon on the left |\n| `showIndicatorIcons` | `boolean` | `true` |  Show warning icons for potential issues on the left |\n| `leftColumnWidth` | `number` | `25` | Relative width of the info column on the left (in percent) |\n| `pageSelector` | `HTMLSelectElement` | `undefined` | DOM `<select>` element to use to select a run if the HAR contains multiple runs. |\n| `selectedPage` | `number` | `0` | Zero-based index of the page to initially render.<br/>If `selectedPage` is larger than the number of pages the last page will be selected. |\n| `legendHolder` | `HTMLElement`<br/>(DOM element) | `undefined` <br/>(not shown) | If set a legend explaining the waterfall colours is rendered in the `legendHolder` DOM element. |\n| `showUserTiming` | `boolean` | `false` | If enabled the [UserTiming](https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API) data in WebPageTest\'s format `_userTime.*` get parsed and rendered as well.<br/>Matching `_userTime.startTimer-*` and `_userTime.endTimer-*` entries get combined into one block. |\n| `showUserTimingEndMarker` | `boolean` | `false` (requires `showUserTiming` to be `true`) | If `showUserTiming` is enabled all `_userTime.endTimer-*` marker are hidden by default, only the UserTiming\'s start and duration is shown. This option also adds an `_userTime.endTimer-*` marker.\n\n## `*.zhar` - zipped HAR files\nBy loading `/perf-cascade-file-reader.min.js` as in [this example](https://github.com/micmro/PerfCascade/blob/main/src/index.html#L78-L86) you can use `perfCascadeFileReader.readFile` to read a zip file and convert it to a JSON HAR object.\n\n```javascript\nperfCascadeFileReader.readFile(fileFromTheFileInput, fileName, function(error, data){\n  if(error){\n    // handle error\n    console.error(error)\n  }else{\n    // handle success\n    renderPerfCascadeChart(data)\n  }\n})\n```\n\nOptionally `perfCascadeFileReader.readFile` also takes a callback (`(progress:number) => void`) as a forth argument\nthat gets called whenever a new unzip progress status is available.\n\n## Rendering other formats (than HAR)\nPerfCascade is composed of a parser [`src/ts/transformers/har.ts`](https://github.com/micmro/PerfCascade/blob/main/src/ts/transformers/har.ts) that parsed HAR into PerfCascade\'s agnostic [`WaterfallDocs`](https://github.com/micmro/PerfCascade/blob/main/src/ts/typing/waterfall.ts) format and the renderer (see `PerfCascade()` in [`src/ts/main.ts`](https://github.com/micmro/PerfCascade/blob/main/src/ts/main.ts) that creates the chart SVG.\n\nIf you want to render another format, you could fork the repo and create a new parser in [`src/ts/transformers/`](https://github.com/micmro/PerfCascade/blob/main/src/ts/transformers/) and implement a new `fromMyNewFormat` function similar to `fromHar()`in [`src/ts/main.ts`](https://github.com/micmro/PerfCascade/blob/main/src/ts/main.ts) that takes your format, calls its parser and then calls the main `PerfCascade()` function with it and returns it.\n\nIt would also be possible to separate the renderer into a separate package, if there is enough interest to justify the effort (create an issue and we can discuss it).\n\n## Dev\n- Start live-reload server and Typescript compiler with watch: `npm run watch`\n- Create uglified version: `npm run build`\n\n_See `package.json` for other useful tasks like linting, release etc._\n\n## Specs and resources\n\n- [W3C HAR Spec](https://w3c.github.io/web-performance/specs/HAR/Overview.html)\n- [HAR 1.2 Spec](http://www.softwareishard.com/blog/har-12-spec)\n- [HAR Resources](https://github.com/ahmadnassri/har-resources)\n\n[travis-image]: https://img.shields.io/travis/micmro/PerfCascade.svg?style=flat-square\n[travis-url]: https://travis-ci.org/micmro/PerfCascade\n', 'message': 'Push to trigger Travis.', 'author_name': 'Tobias Lidskog', 'lang': 'md'}