A library to create readable {\ttfamily \char`\"{}multipart/form-\/data\char`\"{}} streams. Can be used to submit forms and file uploads to other web applications.

The API of this library is inspired by the \href{http://dev.w3.org/2006/webapi/XMLHttpRequest-2/Overview.html\#the-formdata-interface}{\texttt{ XMLHttp\+Request-\/2 Form\+Data Interface}}.

\href{https://travis-ci.org/form-data/form-data}{\texttt{ }} \href{https://travis-ci.org/form-data/form-data}{\texttt{ }} \href{https://ci.appveyor.com/project/alexindigo/form-data}{\texttt{ }}

\href{https://coveralls.io/github/form-data/form-data?branch=master}{\texttt{ }} \href{https://david-dm.org/form-data/form-data}{\texttt{ }} \href{https://www.bithound.io/github/form-data/form-data}{\texttt{ }}\hypertarget{md_sfcode_node_modules_form_data_README_autotoc_md10837}{}\doxysection{Install}\label{md_sfcode_node_modules_form_data_README_autotoc_md10837}

\begin{DoxyCode}{0}
\DoxyCodeLine{npm install -\/-\/save form-\/data }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_form_data_README_autotoc_md10838}{}\doxysection{Usage}\label{md_sfcode_node_modules_form_data_README_autotoc_md10838}
In this example we are constructing a form with 3 fields that contain a string, a buffer and a file stream.


\begin{DoxyCode}{0}
\DoxyCodeLine{var FormData = require('form-\/data');}
\DoxyCodeLine{var fs = require('fs');}
\DoxyCodeLine{}
\DoxyCodeLine{var form = new FormData();}
\DoxyCodeLine{form.append('my\_field', 'my value');}
\DoxyCodeLine{form.append('my\_buffer', new Buffer(10));}
\DoxyCodeLine{form.append('my\_file', fs.createReadStream('/foo/bar.jpg')); }

\end{DoxyCode}


Also you can use http-\/response stream\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var FormData = require('form-\/data');}
\DoxyCodeLine{var http = require('http');}
\DoxyCodeLine{}
\DoxyCodeLine{var form = new FormData();}
\DoxyCodeLine{}
\DoxyCodeLine{http.request('http://nodejs.org/images/logo.png', function(response) \{}
\DoxyCodeLine{  form.append('my\_field', 'my value');}
\DoxyCodeLine{  form.append('my\_buffer', new Buffer(10));}
\DoxyCodeLine{  form.append('my\_logo', response);}
\DoxyCodeLine{\}); }

\end{DoxyCode}


Or @mikeal\textquotesingle{}s \href{https://github.com/request/request}{\texttt{ request}} stream\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var FormData = require('form-\/data');}
\DoxyCodeLine{var request = require('request');}
\DoxyCodeLine{}
\DoxyCodeLine{var form = new FormData();}
\DoxyCodeLine{}
\DoxyCodeLine{form.append('my\_field', 'my value');}
\DoxyCodeLine{form.append('my\_buffer', new Buffer(10));}
\DoxyCodeLine{form.append('my\_logo', request('http://nodejs.org/images/logo.png')); }

\end{DoxyCode}


In order to submit this form to a web application, call {\ttfamily submit(url, \mbox{[}callback\mbox{]})} method\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{form.submit('http://example.org/', function(err, res) \{}
\DoxyCodeLine{  // res – response object (http.IncomingMessage)  //}
\DoxyCodeLine{  res.resume();}
\DoxyCodeLine{\});}

\end{DoxyCode}


For more advanced request manipulations {\ttfamily submit()} method returns {\ttfamily http.\+Client\+Request} object, or you can choose from one of the alternative submission methods.\hypertarget{md_sfcode_node_modules_form_data_README_autotoc_md10839}{}\doxysubsection{Custom options}\label{md_sfcode_node_modules_form_data_README_autotoc_md10839}
You can provide custom options, such as {\ttfamily max\+Data\+Size}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var FormData = require('form-\/data');}
\DoxyCodeLine{}
\DoxyCodeLine{var form = new FormData(\{ maxDataSize: 20971520 \});}
\DoxyCodeLine{form.append('my\_field', 'my value');}
\DoxyCodeLine{form.append('my\_buffer', /* something big */); }

\end{DoxyCode}


List of available options could be found in \href{https://github.com/felixge/node-combined-stream/blob/master/lib/combined_stream.js\#L7-L15}{\texttt{ combined-\/stream}}\hypertarget{md_sfcode_node_modules_form_data_README_autotoc_md10840}{}\doxysubsection{Alternative submission methods}\label{md_sfcode_node_modules_form_data_README_autotoc_md10840}
You can use node\textquotesingle{}s http client interface\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var http = require('http');}
\DoxyCodeLine{}
\DoxyCodeLine{var request = http.request(\{}
\DoxyCodeLine{  method: 'post',}
\DoxyCodeLine{  host: 'example.org',}
\DoxyCodeLine{  path: '/upload',}
\DoxyCodeLine{  headers: form.getHeaders()}
\DoxyCodeLine{\});}
\DoxyCodeLine{}
\DoxyCodeLine{form.pipe(request);}
\DoxyCodeLine{}
\DoxyCodeLine{request.on('response', function(res) \{}
\DoxyCodeLine{  console.log(res.statusCode);}
\DoxyCodeLine{\}); }

\end{DoxyCode}


Or if you would prefer the `\textquotesingle{}Content-\/\+Length'\`{} header to be set for you\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{form.submit('example.org/upload', function(err, res) \{}
\DoxyCodeLine{  console.log(res.statusCode);}
\DoxyCodeLine{\}); }

\end{DoxyCode}


To use custom headers and pre-\/known length in parts\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var CRLF = '\(\backslash\)r\(\backslash\)n';}
\DoxyCodeLine{var form = new FormData();}
\DoxyCodeLine{}
\DoxyCodeLine{var options = \{}
\DoxyCodeLine{  header: CRLF + '-\/-\/' + form.getBoundary() + CRLF + 'X-\/Custom-\/Header: 123' + CRLF + CRLF,}
\DoxyCodeLine{  knownLength: 1}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{form.append('my\_buffer', buffer, options);}
\DoxyCodeLine{}
\DoxyCodeLine{form.submit('http://example.com/', function(err, res) \{}
\DoxyCodeLine{  if (err) throw err;}
\DoxyCodeLine{  console.log('Done');}
\DoxyCodeLine{\}); }

\end{DoxyCode}


Form-\/\+Data can recognize and fetch all the required information from common types of streams ({\ttfamily fs.\+read\+Stream}, {\ttfamily http.\+response} and {\ttfamily mikeal\textquotesingle{}s request}), for some other types of streams you\textquotesingle{}d need to provide \char`\"{}file\char`\"{}-\/related information manually\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{someModule.stream(function(err, stdout, stderr) \{}
\DoxyCodeLine{  if (err) throw err;}
\DoxyCodeLine{}
\DoxyCodeLine{  var form = new FormData();}
\DoxyCodeLine{}
\DoxyCodeLine{  form.append('file', stdout, \{}
\DoxyCodeLine{    filename: 'unicycle.jpg', // ... or:}
\DoxyCodeLine{    filepath: 'photos/toys/unicycle.jpg',}
\DoxyCodeLine{    contentType: 'image/jpeg',}
\DoxyCodeLine{    knownLength: 19806}
\DoxyCodeLine{  \});}
\DoxyCodeLine{}
\DoxyCodeLine{  form.submit('http://example.com/', function(err, res) \{}
\DoxyCodeLine{    if (err) throw err;}
\DoxyCodeLine{    console.log('Done');}
\DoxyCodeLine{  \});}
\DoxyCodeLine{\}); }

\end{DoxyCode}


The {\ttfamily filepath} property overrides {\ttfamily filename} and may contain a relative path. This is typically used when uploading \href{https://wicg.github.io/entries-api/\#dom-htmlinputelement-webkitdirectory}{\texttt{ multiple files from a directory}}.

For edge cases, like POST request to URL with query string or to pass HTTP auth credentials, object can be passed to {\ttfamily form.\+submit()} as first parameter\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{form.submit(\{}
\DoxyCodeLine{  host: 'example.com',}
\DoxyCodeLine{  path: '/probably.php?extra=params',}
\DoxyCodeLine{  auth: 'username:password'}
\DoxyCodeLine{\}, function(err, res) \{}
\DoxyCodeLine{  console.log(res.statusCode);}
\DoxyCodeLine{\}); }

\end{DoxyCode}


In case you need to also send custom HTTP headers with the POST request, you can use the {\ttfamily headers} key in first parameter of {\ttfamily form.\+submit()}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{form.submit(\{}
\DoxyCodeLine{  host: 'example.com',}
\DoxyCodeLine{  path: '/surelynot.php',}
\DoxyCodeLine{  headers: \{'x-\/test-\/header': 'test-\/header-\/value'\}}
\DoxyCodeLine{\}, function(err, res) \{}
\DoxyCodeLine{  console.log(res.statusCode);}
\DoxyCodeLine{\}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_form_data_README_autotoc_md10841}{}\doxysubsection{Integration with other libraries}\label{md_sfcode_node_modules_form_data_README_autotoc_md10841}
\hypertarget{md_sfcode_node_modules_form_data_README_autotoc_md10842}{}\doxysubsubsection{Request}\label{md_sfcode_node_modules_form_data_README_autotoc_md10842}
Form submission using \href{https://github.com/request/request}{\texttt{ request}}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var formData = \{}
\DoxyCodeLine{  my\_field: 'my\_value',}
\DoxyCodeLine{  my\_file: fs.createReadStream(\_\_dirname + '/unicycle.jpg'),}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{request.post(\{url:'http://service.com/upload', formData: formData\}, function(err, httpResponse, body) \{}
\DoxyCodeLine{  if (err) \{}
\DoxyCodeLine{    return console.error('upload failed:', err);}
\DoxyCodeLine{  \}}
\DoxyCodeLine{  console.log('Upload successful!  Server responded with:', body);}
\DoxyCodeLine{\}); }

\end{DoxyCode}


For more details see \href{https://github.com/request/request\#multipartform-data-multipart-form-uploads}{\texttt{ request readme}}.\hypertarget{md_sfcode_node_modules_form_data_README_autotoc_md10843}{}\doxysubsubsection{node-\/fetch}\label{md_sfcode_node_modules_form_data_README_autotoc_md10843}
You can also submit a form using \href{https://github.com/bitinn/node-fetch}{\texttt{ node-\/fetch}}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{var form = new FormData();}
\DoxyCodeLine{}
\DoxyCodeLine{form.append('a', 1);}
\DoxyCodeLine{}
\DoxyCodeLine{fetch('http://example.com', \{ method: 'POST', body: form \})}
\DoxyCodeLine{    .then(function(res) \{}
\DoxyCodeLine{        return res.json();}
\DoxyCodeLine{    \}).then(function(json) \{}
\DoxyCodeLine{        console.log(json);}
\DoxyCodeLine{    \}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_form_data_README_autotoc_md10844}{}\doxysection{Notes}\label{md_sfcode_node_modules_form_data_README_autotoc_md10844}

\begin{DoxyItemize}
\item {\ttfamily get\+Length\+Sync()} method DOESN\textquotesingle{}T calculate length for streams, use {\ttfamily known\+Length} options as workaround.
\item Starting version {\ttfamily 2.\+x} Form\+Data has dropped support for {\ttfamily node@0.\+10.\+x}.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_form_data_README_autotoc_md10845}{}\doxysection{License}\label{md_sfcode_node_modules_form_data_README_autotoc_md10845}
Form-\/\+Data is released under the \mbox{[}MIT\mbox{]}(License) license. 