<h1>Form-Data <a href="https://www.npmjs.com/package/form-data" rel="nofollow"><img src="https://img.shields.io/npm/v/form-data.svg" alt="NPM Module"></a> <a href="https://gitter.im/form-data/form-data" rel="nofollow"><img src="http://form-data.github.io/images/gitterbadge.svg"></a></h1>

<p>A library to create readable <code>&#34;multipart/form-data&#34;</code> streams. Can be used to submit forms and file uploads to other web applications.</p>

<p>The API of this library is inspired by the <a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/Overview.html#the-formdata-interface" rel="nofollow">XMLHttpRequest-2 FormData Interface</a>.</p>

<p><a href="https://travis-ci.org/form-data/form-data" rel="nofollow"><img src="https://img.shields.io/travis/form-data/form-data/master.svg?label=linux:4.x-9.x" alt="Linux Build"></a>
<a href="https://travis-ci.org/form-data/form-data" rel="nofollow"><img src="https://img.shields.io/travis/form-data/form-data/master.svg?label=macos:4.x-9.x" alt="MacOS Build"></a>
<a href="https://ci.appveyor.com/project/alexindigo/form-data" rel="nofollow"><img src="https://img.shields.io/appveyor/ci/alexindigo/form-data/master.svg?label=windows:4.x-9.x" alt="Windows Build"></a></p>

<p><a href="https://coveralls.io/github/form-data/form-data?branch=master" rel="nofollow"><img src="https://img.shields.io/coveralls/form-data/form-data/master.svg?label=code+coverage" alt="Coverage Status"></a>
<a href="https://david-dm.org/form-data/form-data" rel="nofollow"><img src="https://img.shields.io/david/form-data/form-data.svg" alt="Dependency Status"></a>
<a href="https://www.bithound.io/github/form-data/form-data" rel="nofollow"><img src="https://www.bithound.io/github/form-data/form-data/badges/score.svg" alt="bitHound Overall Score"></a></p>

<h2>Install</h2>

<pre><code>npm install --save form-data
</code></pre>

<h2>Usage</h2>

<p>In this example we are constructing a form with 3 fields that contain a string,
a buffer and a file stream.</p>

<pre><code class="language-javascript">var FormData = require(&#39;form-data&#39;);
var fs = require(&#39;fs&#39;);

var form = new FormData();
form.append(&#39;my_field&#39;, &#39;my value&#39;);
form.append(&#39;my_buffer&#39;, new Buffer(10));
form.append(&#39;my_file&#39;, fs.createReadStream(&#39;/foo/bar.jpg&#39;));
</code></pre>

<p>Also you can use http-response stream:</p>

<pre><code class="language-javascript">var FormData = require(&#39;form-data&#39;);
var http = require(&#39;http&#39;);

var form = new FormData();

http.request(&#39;http://nodejs.org/images/logo.png&#39;, function(response) {
  form.append(&#39;my_field&#39;, &#39;my value&#39;);
  form.append(&#39;my_buffer&#39;, new Buffer(10));
  form.append(&#39;my_logo&#39;, response);
});
</code></pre>

<p>Or @mikeal&#39;s <a href="https://github.com/request/request" rel="nofollow">request</a> stream:</p>

<pre><code class="language-javascript">var FormData = require(&#39;form-data&#39;);
var request = require(&#39;request&#39;);

var form = new FormData();

form.append(&#39;my_field&#39;, &#39;my value&#39;);
form.append(&#39;my_buffer&#39;, new Buffer(10));
form.append(&#39;my_logo&#39;, request(&#39;http://nodejs.org/images/logo.png&#39;));
</code></pre>

<p>In order to submit this form to a web application, call <code>submit(url, [callback])</code> method:</p>

<pre><code class="language-javascript">form.submit(&#39;http://example.org/&#39;, function(err, res) {
  // res – response object (http.IncomingMessage)  //
  res.resume();
});

</code></pre>

<p>For more advanced request manipulations <code>submit()</code> method returns <code>http.ClientRequest</code> object, or you can choose from one of the alternative submission methods.</p>

<h3>Custom options</h3>

<p>You can provide custom options, such as <code>maxDataSize</code>:</p>

<pre><code class="language-javascript">var FormData = require(&#39;form-data&#39;);

var form = new FormData({ maxDataSize: 20971520 });
form.append(&#39;my_field&#39;, &#39;my value&#39;);
form.append(&#39;my_buffer&#39;, /* something big */);
</code></pre>

<p>List of available options could be found in <a href="https://github.com/felixge/node-combined-stream/blob/master/lib/combined_stream.js#L7-L15" rel="nofollow">combined-stream</a></p>

<h3>Alternative submission methods</h3>

<p>You can use node&#39;s http client interface:</p>

<pre><code class="language-javascript">var http = require(&#39;http&#39;);

var request = http.request({
  method: &#39;post&#39;,
  host: &#39;example.org&#39;,
  path: &#39;/upload&#39;,
  headers: form.getHeaders()
});

form.pipe(request);

request.on(&#39;response&#39;, function(res) {
  console.log(res.statusCode);
});
</code></pre>

<p>Or if you would prefer the <code>&#39;Content-Length&#39;</code> header to be set for you:</p>

<pre><code class="language-javascript">form.submit(&#39;example.org/upload&#39;, function(err, res) {
  console.log(res.statusCode);
});
</code></pre>

<p>To use custom headers and pre-known length in parts:</p>

<pre><code class="language-javascript">var CRLF = &#39;\r\n&#39;;
var form = new FormData();

var options = {
  header: CRLF + &#39;--&#39; + form.getBoundary() + CRLF + &#39;X-Custom-Header: 123&#39; + CRLF + CRLF,
  knownLength: 1
};

form.append(&#39;my_buffer&#39;, buffer, options);

form.submit(&#39;http://example.com/&#39;, function(err, res) {
  if (err) throw err;
  console.log(&#39;Done&#39;);
});
</code></pre>

<p>Form-Data can recognize and fetch all the required information from common types of streams (<code>fs.readStream</code>, <code>http.response</code> and <code>mikeal&#39;s request</code>), for some other types of streams you&#39;d need to provide &#34;file&#34;-related information manually:</p>

<pre><code class="language-javascript">someModule.stream(function(err, stdout, stderr) {
  if (err) throw err;

  var form = new FormData();

  form.append(&#39;file&#39;, stdout, {
    filename: &#39;unicycle.jpg&#39;, // ... or:
    filepath: &#39;photos/toys/unicycle.jpg&#39;,
    contentType: &#39;image/jpeg&#39;,
    knownLength: 19806
  });

  form.submit(&#39;http://example.com/&#39;, function(err, res) {
    if (err) throw err;
    console.log(&#39;Done&#39;);
  });
});
</code></pre>

<p>The <code>filepath</code> property overrides <code>filename</code> and may contain a relative path. This is typically used when uploading <a href="https://wicg.github.io/entries-api/#dom-htmlinputelement-webkitdirectory" rel="nofollow">multiple files from a directory</a>.</p>

<p>For edge cases, like POST request to URL with query string or to pass HTTP auth credentials, object can be passed to <code>form.submit()</code> as first parameter:</p>

<pre><code class="language-javascript">form.submit({
  host: &#39;example.com&#39;,
  path: &#39;/probably.php?extra=params&#39;,
  auth: &#39;username:password&#39;
}, function(err, res) {
  console.log(res.statusCode);
});
</code></pre>

<p>In case you need to also send custom HTTP headers with the POST request, you can use the <code>headers</code> key in first parameter of <code>form.submit()</code>:</p>

<pre><code class="language-javascript">form.submit({
  host: &#39;example.com&#39;,
  path: &#39;/surelynot.php&#39;,
  headers: {&#39;x-test-header&#39;: &#39;test-header-value&#39;}
}, function(err, res) {
  console.log(res.statusCode);
});
</code></pre>

<h3>Integration with other libraries</h3>

<h4>Request</h4>

<p>Form submission using  <a href="https://github.com/request/request" rel="nofollow">request</a>:</p>

<pre><code class="language-javascript">var formData = {
  my_field: &#39;my_value&#39;,
  my_file: fs.createReadStream(__dirname + &#39;/unicycle.jpg&#39;),
};

request.post({url:&#39;http://service.com/upload&#39;, formData: formData}, function(err, httpResponse, body) {
  if (err) {
    return console.error(&#39;upload failed:&#39;, err);
  }
  console.log(&#39;Upload successful!  Server responded with:&#39;, body);
});
</code></pre>

<p>For more details see <a href="https://github.com/request/request#multipartform-data-multipart-form-uploads" rel="nofollow">request readme</a>.</p>

<h4>node-fetch</h4>

<p>You can also submit a form using <a href="https://github.com/bitinn/node-fetch" rel="nofollow">node-fetch</a>:</p>

<pre><code class="language-javascript">var form = new FormData();

form.append(&#39;a&#39;, 1);

fetch(&#39;http://example.com&#39;, { method: &#39;POST&#39;, body: form })
    .then(function(res) {
        return res.json();
    }).then(function(json) {
        console.log(json);
    });
</code></pre>

<h2>Notes</h2>

<ul>
<li><code>getLengthSync()</code> method DOESN&#39;T calculate length for streams, use <code>knownLength</code> options as workaround.</li>
<li>Starting version <code>2.x</code> FormData has dropped support for <code>node@0.10.x</code>.</li>
</ul>

<h2>License</h2>

<p>Form-Data is released under the <a href="/zhengbingbing/ZLJ_UI_V6.0/src/9980a48d8008399e53be1d869e798386aed8c720/ZljCallCenterWeb.MiniProgram/node_modules/form-data/License" rel="nofollow">MIT</a> license.</p>