formstream 0.0.6 → 1.1.0

package/History.md

@@ -1,4 +1,29 @@
 
+1.1.0 / 2016-12-19
+==================
+
+  * deps: upgrade mime to latest version (#9)
+
+1.0.0 / 2014-11-04
+==================
+
+ * fix(field): support stream.field(String, Number)
+ * chore: fix links
+ * chore: use npm scripts instead of Makefile
+ * fix test case on node@0.8
+
+0.0.8 / 2014-01-17 
+==================
+
+  * destroy source stream when formstream destroy()
+  * add more test cases
+
+0.0.7 / 2013-07-25 
+==================
+
+  * feature: always try to infer `Content-Length` (@xingrz)
+  * doc improve
+
 0.0.6 / 2013-07-15 
 ==================
 

package/README.md

@@ -1,7 +1,21 @@
-formstream [![Build Status](https://secure.travis-ci.org/fengmk2/formstream.png)](http://travis-ci.org/fengmk2/formstream) [![Coverage Status](https://coveralls.io/repos/fengmk2/formstream/badge.png)](https://coveralls.io/r/fengmk2/formstream)
-==========
-
-![logo](https://raw.github.com/fengmk2/formstream/master/logo.png)
+# formstream
+
+[![NPM version][npm-image]][npm-url]
+[![build status][travis-image]][travis-url]
+[![Test coverage][coveralls-image]][coveralls-url]
+[![David deps][david-image]][david-url]
+[![npm download][download-image]][download-url]
+
+[npm-image]: https://img.shields.io/npm/v/formstream.svg?style=flat-square
+[npm-url]: https://npmjs.org/package/formstream
+[travis-image]: https://img.shields.io/travis/node-modules/formstream.svg?style=flat-square
+[travis-url]: https://travis-ci.org/node-modules/formstream
+[coveralls-image]: https://img.shields.io/coveralls/node-modules/formstream.svg?style=flat-square
+[coveralls-url]: https://coveralls.io/r/node-modules/formstream?branch=master
+[david-image]: https://img.shields.io/david/node-modules/formstream.svg?style=flat-square
+[david-url]: https://david-dm.org/node-modules/formstream
+[download-image]: https://img.shields.io/npm/dm/formstream.svg?style=flat-square
+[download-url]: https://npmjs.org/package/formstream
 
 A [multipart/form-data](http://tools.ietf.org/html/rfc2388) encoded stream, helper for file upload.
 
@@ -45,49 +59,21 @@ var req = http.request(options, function (res) {
 form.pipe(req);
 ```
 
-### Uploading with known `Content-Length`
-
-If you know the `ReadStream` total size and you must to set `Content-Length`.
-You may want to use `form.setTotalStreamSize(size)`.
+### Chaining
 
 ```js
-var formstream = require('formstream');
-var http = require('http');
 var fs = require('fs');
+var formstream = require('formstream');
 
-fs.stat('./logo.png', function (err, stat) {
-  var form = formstream();
-  form.file('file', './logo.png', 'upload-logo.png');
-  form.setTotalStreamSize(stat.size);
-  var options = {
-    method: 'POST',
-    host: 'upload.cnodejs.net',
-    path: '/store',
-    headers: form.headers()
-  };
-  var req = http.request(options, function (res) {
-    console.log('Status: %s', res.statusCode);
-    res.on('data', function (data) {
-      console.log(data.toString());
-    });
-  });
-  form.pipe(req);
+var filepath = './logo.png';
+fs.stat(filepath, function (err, stat) {
+  formstream().field('status', 'share picture')
+      .field('access_token', 'your access token')
+      .file('pic', filepath, 'logo.png', stat.size)
+      .pipe(process.stdout); // your request stream
 });
 ```
 
-### Chaining
-
-```js
-var stat = require('fs').statSync;
-var form = require('formstream')();
-
-form.field('status', 'share picture')
-    .field('access_token', 'dk10f88bhza-39kgna.d91')
-    .file('pic', './logo.png', 'logo.png')
-    .setTotalStreamSize(stat('./logo.png').size)
-    .pipe(/* your request stream */);
-```
-
 ## API Doc
 
 ### formstream()
@@ -96,7 +82,7 @@ Create a form instance.
 
 #### Returns
 
-`form`
+Form - form instance
 
 ### FormStream#field(name, value)
 
@@ -109,9 +95,9 @@ Add a normal field to the form.
 
 #### Returns
 
-`form`
+Form - form instance
 
-### FormStream#file(name, filepath[, filename])
+### FormStream#file(name, filepath[, filename][, filesize])
 
 Add a local file to be uploaded to the form.
 
@@ -120,10 +106,11 @@ Add a local file to be uploaded to the form.
 - **name** String - Name of file field
 - **filepath** String - Local path of the file to be uploaded
 - ***filename*** String - Optional. Name of the file (will be the base name of `filepath` if empty)
+- ***filesize*** Number - Optional. Size of the file (will not generate `Content-Length` header if not specified)
 
 #### Returns
 
-`form`
+Form - form instance
 
 ### FormStream#buffer(name, buffer, filename[, contentType])
 
@@ -138,9 +125,9 @@ Add a buffer as a file to upload.
 
 #### Returns
 
-`form`
+Form - form instance
 
-### FormStream#stream(name, stream, filename[, contentType])
+### FormStream#stream(name, stream, filename[, contentType][, size])
 
 Add a readable stream as a file to upload. Event 'error' will be emitted if an error occured.
 
@@ -150,38 +137,27 @@ Add a readable stream as a file to upload. Event 'error' will be emitted if an e
 - **stream** [stream.Readable](http://nodejs.org/api/stream.html#stream_class_stream_readable) - A readable stream to be piped
 - **filename** String - The file name that tells the remote server
 - ***contentType*** String - Optional. Content-Type (aka. MIME Type) of content (will be infered with `filename` if empty)
+- ***size*** Number - Optional. Size of the stream (will not generate `Content-Length` header if not specified)
 
 #### Returns
 
-`form`
+Form - form instance
 
-### FormStream#setTotalStreamSize(size)
+### FormStream#headers([headers])
 
-In some case you may want a `Content-Length` sent with the POST request. If the total size of streams are known, you can tell it with this method.
+Get headers for the request.
 
 #### Arguments
 
-- **size** Number - Size of total stream in bytes.
-
-#### Returns
-
-`form`
-
-### FormStream#headers(headers)
-
-Add headers to the form payload.
-
-#### Arguments
-
-- **headers** Object - An object contains headers you want to add
+- ***headers*** Object - Additional headers
 
 #### Example
 
 ```js
-form.headers({
+var headers = form.headers({
   'Authorization': 'Bearer kei2akc92jmznvnkeh09sknzdk',
   'Accept': 'application/vnd.github.v3.full+json'
-})
+});
 ```
 
 #### Returns
@@ -204,26 +180,12 @@ Emitted when the stream has received no more 'data' events will happen.
 
 See [Node.js Documentation](http://nodejs.org/api/stream.html#stream_event_end) for more.
 
-## Authors
-
-```bash
-$ git summary 
-
- project  : formstream
- repo age : 9 months
- active   : 12 days
- commits  : 24
- files    : 14
- authors  : 
-    19  fengmk2                 79.2%
-     5  XiNGRZ                  20.8%
-```
-
 ## License
 
 (The MIT License)
 
-Copyright (c) 2012 - 2013 fengmk2 <fengmk2@gmail.com>
+Copyright (c) 2012 - 2014 fengmk2 <fengmk2@gmail.com>
+Copyright(c) node-modules and other contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

package/lib/formstream.js

@@ -1,8 +1,4 @@
-/*!
- * formstream - lib/formstream.js
- * Copyright(c) 2012 - 2013 fengmk2 <fengmk2@gmail.com>
- * MIT Licensed
- *
+/**
  * Data format:
  *
 
@@ -25,18 +21,15 @@ Content-Type: image/png\r\n
  *
  */
 
-"use strict";
+'use strict';
 
-/**
- * Module dependencies.
- */
-require('buffer-concat');
 var Stream = require('stream');
 var parseStream = require('pause-stream');
 var util = require('util');
 var mime = require('mime');
 var path = require('path');
 var fs = require('fs');
+var destroy = require('destroy');
 
 var PADDING = '--';
 var NEW_LINE = '\r\n';
@@ -48,11 +41,14 @@ function FormStream() {
   }
 
   FormStream.super_.call(this);
+
   this._boundary = this._generateBoundary();
   this._streams = [];
-  this._fields = [];
   this._buffers = [];
   this._endData = new Buffer(PADDING + this._boundary + PADDING + NEW_LINE);
+  this._contentLength = 0;
+  this._isAllStreamSizeKnown = true;
+  this._knownStreamSize = 0;
 }
 
 util.inherits(FormStream, Stream);
@@ -70,37 +66,21 @@ FormStream.prototype._generateBoundary = function() {
   return boundary;
 };
 
-/**
- * Set total stream size.
- *
- * You know total stream data size and you want to set `Content-Length` in headers.
- */
 FormStream.prototype.setTotalStreamSize = function (size) {
-  size = size || 0;
-  // plus fileds data size
-  this._formatFields();
-  if (this._fieldsData) {
-    size += this._fieldsData.length;
+  // this method should not make any sense if the length of each stream is known.
+  if (this._isAllStreamSizeKnown) {
+    return this;
   }
 
-  // plus stream field data size
+  size = size || 0;
+
   for (var i = 0; i < this._streams.length; i++) {
-    var item = this._streams[i];
-    size += item[0].length;
+    size += this._streams[i][0].length;
     size += NEW_LINE_BUFFER.length; // stream field end pedding size
   }
 
-  // plus buffers size
-  for (var i = 0; i < this._buffers.length; i++) {
-    var item = this._buffers[i];
-    size += item[0].length;
-    size += item[1].length;
-    size += NEW_LINE_BUFFER.length;
-  }
-
-  // end padding data size
-  size += this._endData.length;
-  this._contentLength = size;
+  this._knownStreamSize = size;
+  this._isAllStreamSizeKnown = true;
 
   return this;
 };
@@ -109,113 +89,155 @@ FormStream.prototype.headers = function (options) {
   var headers = {
     'Content-Type': 'multipart/form-data; boundary=' + this._boundary
   };
-  if (typeof this._contentLength === 'number') {
+
+  // calculate total stream size
+  this._contentLength += this._knownStreamSize;
+
+  // calculate length of end padding
+  this._contentLength += this._endData.length;
+
+  if (this._isAllStreamSizeKnown) {
     headers['Content-Length'] = String(this._contentLength);
   }
+
   if (options) {
     for (var k in options) {
       headers[k] = options[k];
     }
   }
+
   return headers;
 };
 
-FormStream.prototype.file = function (name, filepath, filename) {
+FormStream.prototype.file = function (name, filepath, filename, filesize) {
   var mimeType = mime.lookup(filepath);
-  if (!filename) {
+
+  if (typeof filename === 'number' && !filesize) {
+    filesize = filename;
+    filename = path.basename(filepath);
+  } else if (!filename) {
     filename = path.basename(filepath);
   }
-  this.stream(name, fs.createReadStream(filepath), filename, mimeType);
 
-  return this;
+  var stream = fs.createReadStream(filepath);
+
+  return this.stream(name, stream, filename, mimeType, filesize);
 };
 
+/**
+ * Add a form field
+ * @param  {String} name field name
+ * @param  {String|Buffer} value field value
+ * @return {this}
+ */
 FormStream.prototype.field = function (name, value) {
-  this._fields.push([name, value]);
-  process.nextTick(this.resume.bind(this));
-
-  return this;
+  if (!Buffer.isBuffer(value)) {
+    // field(String, Number)
+    // https://github.com/qiniu/nodejs-sdk/issues/123
+    if (typeof value === 'number') {
+      value = String(value);
+    }
+    value = new Buffer(value);
+  }
+  return this.buffer(name, value);
 };
 
-FormStream.prototype.stream = function (name, stream, filename, mimeType) {
-  mimeType = mimeType || mime.lookup(filename);
-  stream.on('error', this.emit.bind(this, 'error'));
+FormStream.prototype.stream = function (name, stream, filename, mimeType, size) {
+  if (typeof mimeType === 'number' && !size) {
+    size = mimeType;
+    mimeType = mime.lookup(filename);
+  } else if (!mimeType) {
+    mimeType = mime.lookup(filename);
+  }
+
+  stream.once('error', this.emit.bind(this, 'error'));
+  // if form stream destroy, also destroy the source stream
+  this.once('destroy', function () {
+    destroy(stream);
+  });
+
+  var leading = this._leading({ name: name, filename: filename }, mimeType);
+
   var ps = parseStream().pause();
   stream.pipe(ps);
-  this._streams.push([
-    this._formatStreamField(name, filename, mimeType),
-    ps
-  ]);
+
+  this._streams.push([leading, ps]);
+
+  // if the size of this stream is known, plus the total content-length;
+  // otherwise, content-length is unknown.
+  if (typeof size === 'number') {
+    this._knownStreamSize += leading.length;
+    this._knownStreamSize += size;
+    this._knownStreamSize += NEW_LINE_BUFFER.length;
+  } else {
+    this._isAllStreamSizeKnown = false;
+  }
+
   process.nextTick(this.resume.bind(this));
 
   return this;
 };
 
 FormStream.prototype.buffer = function (name, buffer, filename, mimeType) {
-  mimeType = mimeType || mime.lookup(filename);
-  this._buffers.push([
-    this._formatStreamField(name, filename, mimeType),
-    buffer
-  ]);
+  if (filename && !mimeType) {
+    mimeType = mime.lookup(filename);
+  }
+
+  var disposition = { name: name };
+  if (filename) {
+    disposition.filename = filename;
+  }
+
+  var leading = this._leading(disposition, mimeType);
+
+  this._buffers.push([leading, buffer]);
+
+  // plus buffer length to total content-length
+  this._contentLength += leading.length;
+  this._contentLength += buffer.length;
+  this._contentLength += NEW_LINE_BUFFER.length;
+
   process.nextTick(this.resume.bind(this));
 
   return this;
 };
 
-FormStream.prototype._emitEnd = function () {
-  // ending format:
-  //
-  // --{boundary}--\r\n
-  this.emit('data', this._endData);
-  this.emit('end');
-};
+FormStream.prototype._leading = function (disposition, type) {
+  var leading = [PADDING + this._boundary];
 
-FormStream.prototype._formatFields = function () {
-  if (!this._fields.length) {
-    return;
-  }
+  var disps = [];
 
-  var lines = '';
-  for (var i = 0; i < this._fields.length; i++) {
-    var field = this._fields[i];
-    lines += PADDING + this._boundary + NEW_LINE;
-    lines += 'Content-Disposition: form-data; name="' + field[0] + '"' + NEW_LINE;
-    lines += NEW_LINE;
-    lines += field[1];
-    lines += NEW_LINE;
+  if (disposition) {
+    for (var k in disposition) {
+      disps.push(k + '="' + disposition[k] + '"');
+    }
   }
-  this._fieldsData = new Buffer(lines);
-  this._fields = [];
-};
 
-FormStream.prototype._emitFields = function () {
-  this._formatFields();
-  if (this._fieldsData) {
-    var data = this._fieldsData;
-    this._fieldsData = null;
-    this.emit('data', data);
+  leading.push('Content-Disposition: form-data; ' + disps.join('; '));
+
+  if (type) {
+    leading.push('Content-Type: ' + type);
   }
+
+  leading.push('');
+  leading.push('');
+
+  return new Buffer(leading.join(NEW_LINE));
 };
 
 FormStream.prototype._emitBuffers = function () {
   if (!this._buffers.length) {
     return;
   }
+
   for (var i = 0; i < this._buffers.length; i++) {
     var item = this._buffers[i];
-    this.emit('data', item[0]);
-    this.emit('data', item[1]);
+    this.emit('data', item[0]); // part leading
+    this.emit('data', item[1]); // part content
     this.emit('data', NEW_LINE_BUFFER);
   }
-  this._buffers = [];
-};
 
-FormStream.prototype._formatStreamField = function (name, filename, mimeType) {
-  var data = PADDING + this._boundary + NEW_LINE;
-  data += 'Content-Disposition: form-data; name="' + name +'"; filename="' + filename + '"' + NEW_LINE;
-  data += 'Content-Type: ' + mimeType + NEW_LINE;
-  data += NEW_LINE;
-  return new Buffer(data);
+  this._buffers = [];
 };
 
 FormStream.prototype._emitStream = function (item) {
@@ -234,24 +256,38 @@ FormStream.prototype._emitStream = function (item) {
   stream.resume();
 };
 
+FormStream.prototype._emitEnd = function () {
+  // ending format:
+  //
+  // --{boundary}--\r\n
+  this.emit('data', this._endData);
+  this.emit('end');
+};
+
 FormStream.prototype.drain = function () {
-  this._emitFields();
   this._emitBuffers();
+
   var item = this._streams.shift();
   if (item) {
     this._emitStream(item);
   } else {
-    // end
     this._emitEnd();
   }
+
   return this;
 };
 
 FormStream.prototype.resume = function () {
   this.paused = false;
+
   if (!this._draining) {
     this._draining = true;
     this.drain();
   }
+
   return this;
 };
+
+FormStream.prototype.close = FormStream.prototype.destroy = function () {
+  this.emit('destroy');
+};

package/package.json

@@ -1,16 +1,21 @@
 {
   "name": "formstream",
-  "version": "0.0.6",
+  "version": "1.1.0",
   "description": "A multipart/form-data encoded stream, helper for file upload.",
-  "main": "index.js",
+  "main": "lib/formstream.js",
+  "files": [
+    "lib"
+  ],
   "scripts": {
-    "test": "make test-all",
-    "blanket": { "pattern": "formstream/lib" },
-    "travis-cov": { "threshold": 100 }
+    "test": "mocha -R spec -t 5000 -r should test/*.test.js",
+    "test-cov": "istanbul cover node_modules/.bin/_mocha -- -t 5000 -r should test/*.test.js",
+    "test-travis": "istanbul cover node_modules/.bin/_mocha --report lcovonly -- -t 5000 -r should test/*.test.js",
+    "jshint": "jshint .",
+    "autod": "autod -w --prefix '^'"
   },
   "repository": {
     "type": "git",
-    "url": "git://github.com/fengmk2/formstream.git"
+    "url": "git://github.com/node-modules/formstream.git"
   },
   "keywords": [
     "form",
@@ -22,19 +27,19 @@
     "request"
   ],
   "dependencies": {
-    "mime": "1.2.9",
-    "buffer-concat": "0.0.1",
-    "pause-stream": ">=0.0.10"
+    "destroy": "^1.0.4",
+    "mime": "^1.3.4",
+    "pause-stream": "~0.0.11"
   },
   "devDependencies": {
-    "connect": "*",
-    "should": "*",
-    "pedding": "*",
-    "blanket": "*",
-    "travis-cov": "*",
-    "coveralls": "*",
-    "mocha-lcov-reporter": "*",
-    "mocha": "*"
+    "autod": "*",
+    "connect-multiparty": "1",
+    "express": "4",
+    "istanbul": "*",
+    "mocha": "*",
+    "pedding": "1",
+    "should": "4",
+    "urllib": "2"
   },
   "author": "fengmk2 <fengmk2@gmail.com> (http://fengmk2.github.com)",
   "license": "MIT"

package/.npmignore

@@ -1,7 +0,0 @@
-test/
-example/
-coverage.html
-lib-cov/
-Makefile
-.travis.yml
-logo.png

package/LICENSE.txt

@@ -1,21 +0,0 @@
-This software is licensed under the MIT License.
-
-Copyright (C) 2012 - 2013 by fengmk2 <fengmk2@gmail.com>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

package/index.js

@@ -1 +0,0 @@
-module.exports = require('./lib/formstream');