+# formidable monorepo
-# formidable [![npm version][npmv-img]][npmv-url] [![MIT license][license-img]][license-url] [![Libera Manifesto][libera-manifesto-img]][libera-manifesto-url] [![Twitter][twitter-img]][twitter-url]
-
-> A Node.js module for parsing form data, especially file uploads.
-
-[![Code style][codestyle-img]][codestyle-url]
-[![linux build status][linux-build-img]][build-url]
-[![macos build status][macos-build-img]][build-url]
-
-
-If you have any _how-to_ kind of questions, please read the [Contributing
-Guide][contributing-url] and [Code of Conduct][code_of_conduct-url]
-documents. For bugs reports and feature requests, [please create an
-issue][open-issue-url] or ping [@wgw_eth / @wgw_lol][twitter-url]
-at Twitter.
-
-[![Conventional Commits][ccommits-img]][ccommits-url]
-[![Minimum Required Nodejs][nodejs-img]][npmv-url]
-[![Buy me a Kofi][kofi-img]][kofi-url]
-[![Make A Pull Request][prs-welcome-img]][prs-welcome-url]
-
-
-
-This project is [semantically versioned](https://semver.org) and if you want support in migrating between versions you can schedule us for training or support us through donations, so we can prioritize.
-
-> [!CAUTION]
-> As of April 2025, old versions like v1 and v2 are still the most used, while they are deperecated for years -- they are also vulnerable to attacks if you are not implementing it properly. **Please upgrade!** We are here to help, and AI Editors & Agents could help a lot in such codemod-like migrations.
-
-> [!TIP]
-> If you are starting a fresh project, you can check out the `formidable-mini` which is a super minimal version of Formidable (not quite configurable yet, but when it does it could become the basis for `formidable@v4`), using web standards like FormData API and File API, and you can use it to stream uploads directly to S3 or other such services.
-
-
-
-[![][npm-weekly-img]][npmv-url] [![][npm-monthly-img]][npmv-url]
-[![][npm-yearly-img]][npmv-url] [![][npm-alltime-img]][npmv-url]
-
-## Project Status: Maintained
-
-> [!NOTE]
-> Check [VERSION NOTES](https://github.com/node-formidable/formidable/blob/master/VERSION_NOTES.md) for more information on v1, v2, and v3 plans, NPM dist-tags and branches._
-
-This module was initially developed by
-[**@felixge**](https://github.com/felixge) for
-[Transloadit](http://transloadit.com/), a service focused on uploading and
-encoding images and videos. It has been battle-tested against hundreds of GBs of
-file uploads from a large variety of clients and is considered production-ready
-and is used in production for years.
-
-Currently, we are few maintainers trying to deal with it. :) More contributors
-are always welcome! :heart: Jump on
-[issue #412](https://github.com/felixge/node-formidable/issues/412) which is
-closed, but if you are interested we can discuss it and add you after strict
-rules, like enabling Two-Factor Auth in your npm and GitHub accounts.
-
-## Highlights
-
-- [Fast (~900-2500 mb/sec)](#benchmarks) & streaming multipart parser
-- Automatically writing file uploads to disk (optional, see
- [`options.fileWriteStreamHandler`](#options))
-- [Plugins API](#useplugin-plugin) - allowing custom parsers and plugins
-- Low memory footprint
-- Graceful error handling
-- Very high test coverage
-
-## Install
-
-This package is a dual ESM/commonjs package.
-
-> [!NOTE]
-> This project requires `Node.js >= 20`. Install it using [yarn](https://yarnpkg.com) or [npm](https://npmjs.com). _We highly recommend to use Yarn when you think to contribute to this project._
-
-This is a low-level package, and if you're using a high-level framework it _may_
-already be included. Check the examples below and the [examples/](https://github.com/node-formidable/formidable/tree/master/examples) folder.
-
-```
-# v2
-npm install formidable@v2
-
-# v3
-npm install formidable
-npm install formidable@v3
-```
-
-_**Note:** Future not ready releases will be published on `*-next` dist-tags for the corresponding version._
-
-
-## Examples
-
-For more examples look at the `examples/` directory.
-
-### with Node.js http module
-
-Parse an incoming file upload, with the
-[Node.js's built-in `http` module](https://nodejs.org/api/http.html).
-
-```js
-import http from 'node:http';
-import formidable, {errors as formidableErrors} from 'formidable';
-
-const server = http.createServer(async (req, res) => {
- if (req.url === '/api/upload' && req.method.toLowerCase() === 'post') {
- // parse a file upload
- const form = formidable({});
- let fields;
- let files;
- try {
- [fields, files] = await form.parse(req);
- } catch (err) {
- // example to check for a very specific error
- if (err.code === formidableErrors.maxFieldsExceeded) {
-
- }
- console.error(err);
- res.writeHead(err.httpCode || 400, { 'Content-Type': 'text/plain' });
- res.end(String(err));
- return;
- }
- res.writeHead(200, { 'Content-Type': 'application/json' });
- res.end(JSON.stringify({ fields, files }, null, 2));
- return;
- }
-
- // show a file upload form
- res.writeHead(200, { 'Content-Type': 'text/html' });
- res.end(`
-
With Node.js "http" module
-
- `);
-});
-
-server.listen(8080, () => {
- console.log('Server listening on http://localhost:8080/ ...');
-});
-```
-
-### with Express.js
-
-There are multiple variants to do this, but Formidable just need Node.js Request
-stream, so something like the following example should work just fine, without
-any third-party [Express.js](https://ghub.now.sh/express) middleware.
-
-Or try the
-[examples/with-express.js](https://github.com/node-formidable/formidable/blob/master/examples/with-express.js)
-
-```js
-import express from 'express';
-import formidable from 'formidable';
-
-const app = express();
-
-app.get('/', (req, res) => {
- res.send(`
-
With "express" npm package
-
- `);
-});
-
-app.post('/api/upload', (req, res, next) => {
- const form = formidable({});
-
- form.parse(req, (err, fields, files) => {
- if (err) {
- next(err);
- return;
- }
- res.json({ fields, files });
- });
-});
-
-app.listen(3000, () => {
- console.log('Server listening on http://localhost:3000 ...');
-});
-```
-
-### with Koa and Formidable
-
-Of course, with [Koa v1, v2 or future v3](https://ghub.now.sh/koa) the things
-are very similar. You can use `formidable` manually as shown below or through
-the [koa-better-body](https://ghub.now.sh/koa-better-body) package which is
-using `formidable` under the hood and support more features and different
-request bodies, check its documentation for more info.
-
-_Note: this example is assuming Koa v2. Be aware that you should pass `ctx.req`
-which is Node.js's Request, and **NOT** the `ctx.request` which is Koa's Request
-object - there is a difference._
-
-```js
-import Koa from 'Koa';
-import formidable from 'formidable';
-
-const app = new Koa();
-
-app.on('error', (err) => {
- console.error('server error', err);
-});
-
-app.use(async (ctx, next) => {
- if (ctx.url === '/api/upload' && ctx.method.toLowerCase() === 'post') {
- const form = formidable({});
-
- // not very elegant, but that's for now if you don't want to use `koa-better-body`
- // or other middlewares.
- await new Promise((resolve, reject) => {
- form.parse(ctx.req, (err, fields, files) => {
- if (err) {
- reject(err);
- return;
- }
-
- ctx.set('Content-Type', 'application/json');
- ctx.status = 200;
- ctx.state = { fields, files };
- ctx.body = JSON.stringify(ctx.state, null, 2);
- resolve();
- });
- });
- await next();
- return;
- }
-
- // show a file upload form
- ctx.set('Content-Type', 'text/html');
- ctx.status = 200;
- ctx.body = `
-
With "koa" npm package
-
- `;
-});
-
-app.use((ctx) => {
- console.log('The next middleware is called');
- console.log('Results:', ctx.state);
-});
-
-app.listen(3000, () => {
- console.log('Server listening on http://localhost:3000 ...');
-});
-```
-
-## Benchmarks
-
-The benchmark is quite old, from the old codebase. But maybe quite true though.
-Previously the numbers was around ~500 mb/sec. Currently with moving to the new
-Node.js Streams API it's faster. You can clearly see the differences between the
-Node versions.
-
-_Note: a lot better benchmarking could and should be done in future._
-
-Benchmarked on 8GB RAM, Xeon X3440 (2.53 GHz, 4 cores, 8 threads)
-
-```
-~/github/node-formidable master
-❯ nve --parallel 8 10 12 13 node benchmark/bench-multipart-parser.js
-
- ⬢ Node 8
-
-1261.08 mb/sec
-
- ⬢ Node 10
-
-1113.04 mb/sec
-
- ⬢ Node 12
-
-2107.00 mb/sec
-
- ⬢ Node 13
-
-2566.42 mb/sec
-```
-
-
-
-## API
-
-### Formidable / IncomingForm
-
-All shown are equivalent.
-
-_Please pass [`options`](#options) to the function/constructor, not by assigning
-them to the instance `form`_
-
-```js
-import formidable from 'formidable';
-const form = formidable(options);
-```
-
-### Options
-
-See it's defaults in [src/Formidable.js DEFAULT_OPTIONS](./src/Formidable.js)
-(the `DEFAULT_OPTIONS` constant).
-
-- `options.encoding` **{string}** - default `'utf-8'`; sets encoding for
- incoming form fields,
-- `options.uploadDir` **{string}** - default `os.tmpdir()`; the directory for
- placing file uploads in. You can move them later by using `fs.rename()`.
-- `options.keepExtensions` **{boolean}** - default `false`; to include the
- extensions of the original files or not
-- `options.allowEmptyFiles` **{boolean}** - default `false`; allow upload empty
- files
-- `options.minFileSize` **{number}** - default `1` (1byte); the minium size of
- uploaded file.
-- `options.maxFiles` **{number}** - default `Infinity`;
- limit the amount of uploaded files, set Infinity for unlimited
-- `options.maxFileSize` **{number}** - default `200 * 1024 * 1024` (200mb);
- limit the size of each uploaded file.
-- `options.maxTotalFileSize` **{number}** - default `options.maxFileSize`;
- limit the size of the batch of uploaded files.
-- `options.maxFields` **{number}** - default `1000`; limit the number of fields, set Infinity for unlimited
-- `options.maxFieldsSize` **{number}** - default `20 * 1024 * 1024` (20mb);
- limit the amount of memory all fields together (except files) can allocate in
- bytes.
-- `options.hashAlgorithm` **{string | false}** - default `false`; include checksums calculated
- for incoming files, set this to some hash algorithm, see
- [crypto.createHash](https://nodejs.org/api/crypto.html#crypto_crypto_createhash_algorithm_options)
- for available algorithms
-- `options.fileWriteStreamHandler` **{function}** - default `null`, which by
- default writes to host machine file system every file parsed; The function
- should return an instance of a
- [Writable stream](https://nodejs.org/api/stream.html#stream_class_stream_writable)
- that will receive the uploaded file data. With this option, you can have any
- custom behavior regarding where the uploaded file data will be streamed for.
- If you are looking to write the file uploaded in other types of cloud storages
- (AWS S3, Azure blob storage, Google cloud storage) or private file storage,
- this is the option you're looking for. When this option is defined the default
- behavior of writing the file in the host machine file system is lost.
-- `options.filename` **{function}** - default `undefined` Use it to control
- newFilename. Must return a string. Will be joined with options.uploadDir.
-
-- `options.filter` **{function}** - default function that always returns true.
- Use it to filter files before they are uploaded. Must return a boolean. Will not make the form.parse error
-
-- `options.createDirsFromUploads` **{boolean}** - default false. If true, makes direct folder uploads possible. Use `` to create a form to upload folders. Has to be used with the options `options.uploadDir` and `options.filename` where `options.filename` has to return a string with the character `/` for folders to be created. The base will be `options.uploadDir`.
-
-
-#### `options.filename` **{function}** function (name, ext, part, form) -> string
-
-where part can be decomposed as
-
-```js
-const { originalFilename, mimetype} = part;
-```
-
-_**Note:** If this size of combined fields, or size of some file is exceeded, an
-`'error'` event is fired._
-
-```js
-// The amount of bytes received for this form so far.
-form.bytesReceived;
-```
-
-```js
-// The expected number of bytes in this form.
-form.bytesExpected;
-```
-
-#### `options.filter` **{function}** function ({name, originalFilename, mimetype}) -> boolean
-
-Behaves like Array.filter: Returning false will simply ignore the file and go to the next.
-
-```js
-const options = {
- filter: function ({name, originalFilename, mimetype}) {
- // keep only images
- return mimetype && mimetype.includes("image");
- }
-};
-```
-
-**Note:** use an outside variable to cancel all uploads upon the first error
-
-**Note:** use form.emit('error') to make form.parse error
-
-```js
-let cancelUploads = false;// create variable at the same scope as form
-const options = {
- filter: function ({name, originalFilename, mimetype}) {
- // keep only images
- const valid = mimetype && mimetype.includes("image");
- if (!valid) {
- form.emit('error', new formidableErrors.default('invalid type', 0, 400)); // optional make form.parse error
- cancelUploads = true; //variable to make filter return false after the first problem
- }
- return valid && !cancelUploads;
- }
-};
-```
-
-
-### .parse(request, ?callback)
-
-Parses an incoming Node.js `request` containing form data. If `callback` is not provided a promise is returned.
-
-```js
-const form = formidable({ uploadDir: __dirname });
-
-form.parse(req, (err, fields, files) => {
- console.log('fields:', fields);
- console.log('files:', files);
-});
-
-// with Promise
-const [fields, files] = await form.parse(req);
-```
-
-You may overwrite this method if you are interested in directly accessing the
-multipart stream. Doing so will disable any `'field'` / `'file'` events
-processing which would occur otherwise, making you fully responsible for
-handling the processing.
-
-About `uploadDir`, given the following directory structure
-```
-project-name
-├── src
-│ └── server.js
-│
-└── uploads
- └── image.jpg
-```
-
-`__dirname` would be the same directory as the source file itself (src)
-
-
-```js
- `${__dirname}/../uploads`
-```
-
-to put files in uploads.
-
-Omitting `__dirname` would make the path relative to the current working directory. This would be the same if server.js is launched from src but not project-name.
-
-
-`null` will use default which is `os.tmpdir()`
-
-Note: If the directory does not exist, the uploaded files are __silently discarded__. To make sure it exists:
-
-```js
-import {createNecessaryDirectoriesSync} from "filesac";
-
-
-const uploadPath = `${__dirname}/../uploads`;
-createNecessaryDirectoriesSync(`${uploadPath}/x`);
-```
-
-
-In the example below, we listen on couple of events and direct them to the
-`data` listener, so you can do whatever you choose there, based on whether its
-before the file been emitted, the header value, the header name, on field, on
-file and etc.
-
-Or the other way could be to just override the `form.onPart` as it's shown a bit
-later.
-
-```js
-form.once('error', console.error);
-
-form.on('fileBegin', (formname, file) => {
- form.emit('data', { name: 'fileBegin', formname, value: file });
-});
-
-form.on('file', (formname, file) => {
- form.emit('data', { name: 'file', formname, value: file });
-});
-
-form.on('field', (fieldName, fieldValue) => {
- form.emit('data', { name: 'field', key: fieldName, value: fieldValue });
-});
-
-form.once('end', () => {
- console.log('Done!');
-});
-
-// If you want to customize whatever you want...
-form.on('data', ({ name, key, value, buffer, start, end, formname, ...more }) => {
- if (name === 'partBegin') {
- }
- if (name === 'partData') {
- }
- if (name === 'headerField') {
- }
- if (name === 'headerValue') {
- }
- if (name === 'headerEnd') {
- }
- if (name === 'headersEnd') {
- }
- if (name === 'field') {
- console.log('field name:', key);
- console.log('field value:', value);
- }
- if (name === 'file') {
- console.log('file:', formname, value);
- }
- if (name === 'fileBegin') {
- console.log('fileBegin:', formname, value);
- }
-});
-```
-
-### .use(plugin: Plugin)
-
-A method that allows you to extend the Formidable library. By default we include
-4 plugins, which essentially 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 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
-import formidable, {octetstream, querystring, json} from "formidable";
-const form = formidable({
- hashAlgorithm: '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
-something similar. Or see
-[#387](https://github.com/node-formidable/node-formidable/issues/387) for
-inspiration, you can for example validate the mime-type.
-
-```js
-const form = formidable();
-
-form.onPart = (part) => {
- part.on('data', (buffer) => {
- // do whatever you want here
- });
-};
-```
-
-For example, force Formidable to be used only on non-file "parts" (i.e., html
-fields)
-
-```js
-const form = formidable();
-
-form.onPart = function (part) {
- // let formidable handle only non-file parts
- if (part.originalFilename === '' || !part.mimetype) {
- // used internally, please do not override!
- form._handlePart(part);
- }
-};
-```
-
-### File
-
-```ts
-export interface File {
- // The size of the uploaded file in bytes.
- // If the file is still being uploaded (see `'fileBegin'` event),
- // this property says how many bytes of the file have been written to disk yet.
- file.size: number;
-
- // The path this file is being written to. You can modify this in the `'fileBegin'` event in
- // case you are unhappy with the way formidable generates a temporary path for your files.
- file.filepath: string;
-
- // The name this file had according to the uploading client.
- file.originalFilename: string | null;
-
- // calculated based on options provided
- file.newFilename: string | null;
-
- // The mime type of this file, according to the uploading client.
- file.mimetype: string | null;
-
- // A Date object (or `null`) containing the time this file was last written to.
- // Mostly here for compatibility with the [W3C File API Draft](http://dev.w3.org/2006/webapi/FileAPI/).
- file.mtime: Date | null;
-
- file.hashAlgorithm: false | |'sha1' | 'md5' | 'sha256'
- // If `options.hashAlgorithm` calculation was set, you can read the hex digest out of this var (at the end it will be a string)
- file.hash: string | object | null;
-}
-```
-
-#### file.toJSON()
-
-This method returns a JSON-representation of the file, allowing you to
-`JSON.stringify()` the file which is useful for logging and responding to
-requests.
-
-### Events
-
-#### `'progress'`
-
-Emitted after each incoming chunk of data that has been parsed. Can be used to
-roll your own progress bar. **Warning** Use this only for server side progress bar. On the client side better use `XMLHttpRequest` with `xhr.upload.onprogress =`
-
-```js
-form.on('progress', (bytesReceived, bytesExpected) => {});
-```
-
-#### `'field'`
-
-Emitted whenever a field / value pair has been received.
-
-```js
-form.on('field', (name, value) => {});
-```
-
-#### `'fileBegin'`
-
-Emitted whenever a new file is detected in the upload stream. Use this event if
-you want to stream the file to somewhere else while buffering the upload on the
-file system.
-
-```js
-form.on('fileBegin', (formName, file) => {
- // accessible here
- // formName the name in the form () or http filename for octetstream
- // file.originalFilename http filename or null if there was a parsing error
- // file.newFilename generated hexoid or what options.filename returned
- // file.filepath default pathname as per options.uploadDir and options.filename
- // file.filepath = CUSTOM_PATH // to change the final path
-});
-```
-
-#### `'file'`
-
-Emitted whenever a field / file pair has been received. `file` is an instance of
-`File`.
-
-```js
-form.on('file', (formname, file) => {
- // same as fileBegin, except
- // it is too late to change file.filepath
- // file.hash is available if options.hash was used
-});
-```
-
-#### `'error'`
-
-Emitted when there is an error processing the incoming form. A request that
-experiences an error is automatically paused, you will have to manually call
-`request.resume()` if you want the request to continue firing `'data'` events.
-
-May have `error.httpCode` and `error.code` attached.
-
-```js
-form.on('error', (err) => {});
-```
-
-#### `'aborted'`
-
-Emitted when the request was aborted by the user. Right now this can be due to a
-'timeout' or 'close' event on the socket. After this event is emitted, an
-`error` event will follow. In the future there will be a separate 'timeout'
-event (needs a change in the node core).
-
-```js
-form.on('aborted', () => {});
-```
-
-#### `'end'`
-
-Emitted when the entire request has been received, and all contained files have
-finished flushing to disk. This is a great place for you to send your response.
-
-```js
-form.on('end', () => {});
-```
-
-
-### Helpers
-
-#### firstValues
-
-Gets first values of fields, like pre 3.0.0 without multiples pass in a list of optional exceptions where arrays of strings is still wanted (`
-