feat: introduce Plugins API, fix tests

CHANGELOG.md

@@ -20,6 +20,8 @@
  * fix(tests): include multipart and qs parser unit tests, part of [#415](https://github.com/node-formidable/node-formidable/issues/415)
  * fix: reorganize exports + move parsers to `src/parsers/`
  * fix: update docs and examples [#544](https://github.com/node-formidable/node-formidable/pull/544) ([#248](https://github.com/node-formidable/node-formidable/issues/248), [#335](https://github.com/node-formidable/node-formidable/issues/335), [#371](https://github.com/node-formidable/node-formidable/issues/371), [#372](https://github.com/node-formidable/node-formidable/issues/372), [#387](https://github.com/node-formidable/node-formidable/issues/387), partly [#471](https://github.com/node-formidable/node-formidable/issues/471), [#535](https://github.com/node-formidable/node-formidable/issues/535))
+ * feat: introduce Plugins API, fix silent failing tests ([#545](https://github.com/node-formidable/node-formidable/pull/545), [#391](https://github.com/node-formidable/node-formidable/pull/391), [#407](https://github.com/node-formidable/node-formidable/pull/407), [#386](https://github.com/node-formidable/node-formidable/pull/386), [#374](https://github.com/node-formidable/node-formidable/pull/374), [#521](https://github.com/node-formidable/node-formidable/pull/521), [#267](https://github.com/node-formidable/node-formidable/pull/267))
+ * respect form hash option on incoming octect/stream requests ([#407](https://github.com/node-formidable/node-formidable/pull/407))
  * fix: exposing file writable stream errors ([#520](https://github.com/node-formidable/node-formidable/pull/520), [#316](https://github.com/node-formidable/node-formidable/pull/316), [#469](https://github.com/node-formidable/node-formidable/pull/469), [#470](https://github.com/node-formidable/node-formidable/pull/470))
 
 ### v1.2.1 (2018-03-20)

README.md

@@ -287,6 +287,68 @@ form.on('data', ({ name, key, value, buffer, start, end, ...more }) => {
 });
 ```
 
+### .use(plugin: Plugin)
+
+A method that allows you to extend the Formidable library. By default we include
+4 plugins, which esentially are adapters to plug the different built-in parsers.
+
+**The plugins added by this method are always enabled.**
+
+_See [src/plugins/](./src/plugins/) for more detailed look on default plugins._
+
+The `plugin` param has such signature:
+
+```typescript
+function(formidable: Formidable, options: Options): void;
+```
+
+The architecture is simple. The `plugin` is a function that is passed with the
+Formidable instance (the `form` across the README examples) and the options.
+
+**Note:** the plugin function's `this` context is also the same instance.
+
+```js
+const formidable = require('formidable');
+
+const form = formidable({ keepExtensions: true });
+
+form.use((self, options) => {
+  // self === this === form
+  console.log('woohoo, custom plugin');
+  // do your stuff; check `src/plugins` for inspiration
+});
+
+form.parse(req, (error, fields, files) => {
+  console.log('done!');
+});
+```
+
+**Important to note**, is that inside plugin `this.options`, `self.options` and
+`options` MAY or MAY NOT be the same. General best practice is to always use the
+`this`, so you can later test your plugin independently and more easily.
+
+If you want to disable some parsing capabilities of Formidable, you can disable
+the plugin which corresponds to the parser. For example, if you want to disable
+multipart parsing (so the [src/parsers/Multipart.js](./src/parsers/Multipart.js)
+which is used in [src/plugins/multipart.js](./src/plugins/multipart.js)), then
+you can remove it from the `options.enabledPlugins`, like so
+
+```js
+const { Formidable } = require('formidable');
+
+const form = new Formidable({
+  hash: 'sha1',
+  enabledPlugins: ['octetstream', 'querystring', 'json'],
+});
+```
+
+**Be aware** that the order _MAY_ be important too. The names corresponds 1:1 to
+files in [src/plugins/](./src/plugins) folder.
+
+Pull requests for new built-in plugins MAY be accepted - for example, more
+advanced querystring parser. Add your plugin as a new file in `src/plugins/`
+folder (lowercased) and follow how the other plugins are made.
+
 ### form.onPart
 
 If you want to use Formidable to only handle certain parts for you, you can do

package.json

@@ -1,18 +1,19 @@
 {
   "name": "formidable",
-  "version": "2.0.0-canary.20200131.1",
+  "version": "2.0.0-dev.20200131.2",
   "license": "MIT",
   "description": "A node.js module for parsing form data, especially file uploads.",
   "homepage": "https://github.com/node-formidable/node-formidable",
   "funding": "https://ko-fi.com/tunnckoCore/commissions",
   "repository": "node-formidable/node-formidable",
   "main": "./src/index.js",
   "files": [
-    "src"
+    "src",
+    "test"
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "canary"
+    "tag": "dev"
   },
   "scripts": {
     "bench": "node benchmark",
@@ -26,6 +27,10 @@
     "pretest:ci": "yarn pretest",
     "test:ci": "nyc node test/run.js"
   },
+  "dependencies": {
+    "dezalgo": "^1.0.3",
+    "once": "^1.4.0"
+  },
   "devDependencies": {
     "@commitlint/cli": "^8.3.5",
     "@commitlint/config-conventional": "^8.3.4",
@@ -37,11 +42,13 @@
     "eslint-plugin-prettier": "^3.1.2",
     "husky": "^4.2.1",
     "jest": "^25.1.0",
+    "koa": "^2.11.0",
     "lint-staged": "^10.0.6",
     "nyc": "^15.0.0",
     "prettier": "^1.19.1",
     "prettier-plugin-pkgjson": "^0.2.0",
     "request": "^2.88.0",
+    "supertest": "^4.0.2",
     "urun": "^0.0.8",
     "utest": "^0.0.8"
   },