feat: introduce Plugins API, fix tests (#545)

* feat: introduce Plugins API, fix tests * chore: update changelog * chore: lgtm tweaks? * start plugins tests; update exports * chore(custom-plugins-tests): make it really passing * chore: more tests; add nyc test coverage * chore: move to GitHub Actions CI * fix: respect form hash option on incoming octect/stream requests close #407 * fix: tests, use dezalgo and once for parse callback - it is recommended plugins to return the this/self/formidable instance - add 2 deps: `once` and `dezalgo` for ensurance of the `cb` param of .parse() + otherwise it COULD (and happened already few times) be called multiple times - update unit tests to use Jest * chore: tweaks, publish `dev` dist-tag (with Plugins API) * chore: sync & tweak * fix: check strictly for multipart/form-data in multipart parser * chore: publish dev.2 * fix: tests updates * fix: it seems we support multipart/related too * chore: download badges * Update package.json * chore: sync Signed-off-by: Charlike Mike Reagent <opensource@tunnckocore.com> Co-authored-by: Claudio Poli <masterkain@gmail.com>
node-formidable · Feb 12, 2020 · 037a738 · 037a738
1 parent d413c13
commit 037a738
Show file tree

Hide file tree

Showing 23 changed files with 1,116 additions and 317 deletions.
diff --git a/CHANGELOG.md b/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)

diff --git a/README.md b/README.md
@@ -290,6 +290,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
@@ -509,4 +571,5 @@ Formidable is licensed under the [MIT License][license-url].
 [npm-monthly-img]: https://badgen.net/npm/dm/formidable?icon=npm&cache=300
 [npm-yearly-img]: https://badgen.net/npm/dy/formidable?icon=npm&cache=300
 [npm-alltime-img]: https://badgen.net/npm/dt/formidable?icon=npm&cache=300
+
 <!-- prettier-ignore-end -->
diff --git a/package.json b/package.json
@@ -4,11 +4,12 @@
   "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",
+  "funding": "https://tidelift.com/funding/github/npm/formidable",
   "repository": "node-formidable/node-formidable",
   "main": "./src/index.js",
   "files": [
-    "src"
+    "src",
+    "test"
   ],
   "publishConfig": {
     "access": "public",
@@ -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.2",
     "jest": "^25.1.0",
+    "koa": "^2.11.0",
     "lint-staged": "^10.0.7",
     "nyc": "^15.0.0",
     "prettier": "^1.19.1",
     "prettier-plugin-pkgjson": "^0.2.3",
     "request": "^2.88.2",
+    "supertest": "^4.0.2",
     "urun": "^0.0.8",
     "utest": "^0.0.8"
   },