Asynchronous file bootstrap hooks, aka async initFileFn (#329)

## Ability to use asynchronous initFileFn.
This is a follow-up (and proper implementation) of #296 (reverted in e867d54)

This could be use to initialize a stream, a reader, fetch a remote resource, ... during the FlowFile initialization.
`asyncAddFile` and `asyncAddFiles` are introduced which support this mechanism.
These function return promises of one (or multiple) FlowFile(s).

To implement this:
- An AsyncFlowFile class extending a FlowFile is created, overriding the bootstrap part
- In order to keep code-duplication low, a filterFileList generator yield files
  in way common to async and non-async addFiles() functions.

The possibly async' nature of initializing file affects events firing.
(#319) in general and `fileAdded`
in particular (#271) and the current
confusion between hooks altering bootstraping and simple events.

- fileAdded is now assumed an event. If we detect a return value, a warning is sent.
- preFilterFile is introduced and allow filtering the raw file before bootstrap()
- postFilterFile is introduced and allow filtering the FlowFile after a (possibly async) bootstrap()
- filesAdded is preserved

About parameters:
- `initFileFn` is only used during bootstrap
- If such a helper exists, it's tightly related to addFile* functions.
As such, it was deemed adequate to provide it as a parameter to `*addFile*()`
 (but `opts.initFileFn` is still supported)

An `Eventizer` class is added where all the necessary code exist.
- Hooks alter code processing and could be `synchronous` or not.
- Events are CustomEvent dispatched asynchronously for informative purpose.

A warning is triggered if an obsolete event name is used

## Other changes
* uploadNextChunk: use transpilation instead of relying upon the each() helper
* FlowFile: don't bootstrap within the constructor. This must be done manually now
* README/CHANGELOG
* Also trigger async hooks in sync-mode (but don't wait for them to return)

# tests:
- switch uploadSpec to createFakeServer
- move some useful helpers related to final file consistency
- bugfix. xhr_server.restore() is not enough. Recreating the object fix some failures under particular tests sequences
- added new tests for the async initFileFn and related asynAddFile(s) functions
- modified tests to take into account changes related to hooks & events

* builds

Author: Raphaël Droz

CHANGELOG.md

@@ -1,3 +1,18 @@
+# 3.0.0
+
+## Breaking Changes
+
+### Events
+ - Events are distincts from hooks.
+ - Recognized events and hooks are now lower-snake-case (case-sensitive).
+ - Hooks are "file-added", "files-added", "files-submitted". "filter-file" is a filtering hook.
+ - Events are passed a native CustomEvent. IE:
+    v2: `flow.on('fileRemoved',  (file) => { ... });`
+    v3: `flow.on('file-removed', ({detail: [file]}) => { ... });`
+
+### Other
+ - FlowFile does not run bootstrap() upon instanciation. This must be done manually (or rely on *addFile* functions).
+
 # 2.0.0
 
 ## Features
@@ -34,4 +49,4 @@
  that calling **Resumable.upload()** method in these events will not start uploading current
  files. To start upload use **filesSubmitted** event instead.
  - **throttleProgressCallbacks** parameter was replaced with **progressCallbacksInterval** and it
-  is now measured in milliseconds.
+  is now measured in milliseconds.

README.md

@@ -173,7 +173,17 @@ parameter must be adjusted together with `progressCallbacksInterval` parameter.
 * `.cancel()` Cancel upload of all `FlowFile` objects and remove them from the list.
 * `.progress()` Returns a float between 0 and 1 indicating the current upload progress of all files.
 * `.isUploading()` Returns a boolean indicating whether or not the instance is currently uploading anything.
-* `.addFile(file)` Add a HTML5 File object to the list of files.
+* `.addFile(file, event = null, initFileFn = undefined)` Add a HTML5 File object to the list of files.
+    * Accept the same `event` and `initFileFn` parameters thant `addFiles` which is used under the hood.
+* `.addFiles([files], event = null, initFileFn = undefined)` Add multiple File objects to the list of files.
+    * `event` The optional event that trigger the addition (for internal purposes)
+    * `initFileFn` An override of Flow.initFileFn
+* `.asyncAddFile(file, event = null, initFileFn = undefined)` Add a HTML5 File object to the list of files.
+* `.asyncAddFiles([files], event = null, initFileFn = undefined)` Add multiple File objects to the list of files.
+    * `asyncAddFile` and `asyncAddFiles` rely on the same parameters than they non-async counterparts with one
+      difference: They accept an asynchronous `initFileFn` file function and return, in a promise, the corresponding FlowFiles.
+    * Note: Calling `asyncAddFile` or `asyncAddFiles` with no `initFileFn` being defined is aimed identical to there non-async
+      counterpart but this may change in the future [TBD].
 * `.removeFile(file)` Cancel upload of a specific `FlowFile` object on the list from the list.
 * `.getFromUniqueIdentifier(uniqueIdentifier)` Look up a `FlowFile` object by its unique identifier.
 * `.getSize()` Returns the total size of the upload in bytes.
@@ -182,29 +192,46 @@ parameter must be adjusted together with `progressCallbacksInterval` parameter.
 
 #### Events
 
-* `.fileSuccess(file, message, chunk)` A specific file was completed. First argument `file` is instance of `FlowFile`, second argument `message` contains server response. Response is always a string. 
-Third argument `chunk` is instance of `FlowChunk`. You can get response status by accessing xhr 
-object `chunk.xhr.status`.
-* `.fileProgress(file, chunk)` Uploading progressed for a specific file.
-* `.fileAdded(file, event)` This event is used for file validation. To reject this file return false.
-This event is also called before file is added to upload queue,
-this means that calling `flow.upload()` function will not start current file upload.
-Optionally, you can use the browser `event` object from when the file was
-added.
-* `.filesAdded(array, event)` Same as fileAdded, but used for multiple file validation.
-* `.filesSubmitted(array, event)` Same as filesAdded, but happens after the file is added to upload queue. Can be used to start upload of currently added files.
-* `.fileRemoved(file)` The specific file was removed from the upload queue. Combined with filesSubmitted, can be used to notify UI to update its state to match the upload queue.
-* `.fileRetry(file, chunk)` Something went wrong during upload of a specific file, uploading is being 
-retried.
-* `.fileError(file, message, chunk)` An error occurred during upload of a specific file.
-* `.uploadStart()` Upload has been started on the Flow object.
-* `.complete()` Uploading completed.
-* `.progress()` Uploading progress.
-* `.error(message, file, chunk)` An error, including fileError, occurred.
-* `.catchAll(event, ...)` Listen to all the events listed above with the same callback function.
+Events are native, synchronous and provide information about the internal state of the application without being given a chance to alter it.
+
+* `file-success(<FlowFile> file, <string> message, <FlowChunk> chunk)` A specific file was completed (`message` comes from `xhr.responseText`, `chunk` is instance of `FlowChunk` representing the last chunk for this file. You can get response status by accessing xhr object `chunk.xhr.status`).
+* `file-progress(<FlowFile> file, <FlowChunk> chunk)` Upload progressed for a specific file.
+* `file-removed(<FlowFile> file)` The specific file was removed from the upload queue. Combined with the `files-submitted` hook, it can be used to notify UI to update its state to match the upload queue.
+* `file-retry(<FlowFile> file, <FlowChunk> chunk)` Something went wrong during upload of a specific file, uploading is being retried.
+* `file-error(<FlowFile> file, <string> message, <FlowChunk> chunk)` An error occurred during upload of a specific file. `message` comes from `xhr.responseText`.
+* `upload-start()` Upload started on the Flow object.
+* `complete()` Upload completed.
+* `progress()` Upload progress.
+* `error(<string> message, <FlowFile> file, <FlowChunk> chunk)` An error, including fileError, occurred.
+* `catch-all(<string> event-name, ...)` Receive all above events listed above and their corresponding parameters.
+
+#### Processing hooks
+
+Hooks allows for either synchronous or asynchronous operations and allow altering the regular processing of the file(s) from addition to upload completion. 
+It's user responsability to use or not the `async` version of `(async)?addFile` and `(async)?addFiles` according to the behavior of its processing hooks.
+ (Defining `async` callbacks for the `asyncAddFile(s)`)
+
+* `file-added(<FlowFile> file, event) : null` This event is also called before file is added to upload queue and after it's been fully initialized. `event` is the browser `event` object from when the file was added.
+* `files-added([<FlowFile> files], event) : null` Same as `file-added`, but used for multiple file validation.
+* `files-submitted([<FlowFile> files], event) : null` Same as `files-added`, but happens after the file is added to upload queue. Can be used to start upload of currently added files.
+* `filter-file(<FlowFile> file, event) : boolean` The boolean return value decide whether this particular file must be processed or ignored.
+
+### Hooks and events format
+- Events and hooks name are case-sensitive, snake-cased and return CustomEvent passed straight to `Flow.on()` callback.
+- Sample use `flow.on('file-removed', ({detail: [file]}) => { ... });`
+- In an attempt of backward compatibility, some support of camelCase events exist:
+```
+flow.on('filesAdded', async (files, event) => { // v2 events prototype
+   if (files instanceof CustomEvent) { // Handle v3+ events
+      var [files, event] = files.detail;
+   }
+   // Do something with files
+});
+```
 
 ### FlowFile
 FlowFile constructor can be accessed in `Flow.FlowFile`.
+
 #### Properties
 
 * `.flowObj` A back-reference to the parent `Flow` object.