diff --git a/examples/README.md b/examples/README.md index 213c82706..526d71bba 100644 --- a/examples/README.md +++ b/examples/README.md @@ -75,3 +75,41 @@ request.post('https://up.flickr.com/services/upload', { // assert.equal(typeof body, 'object') }) ``` + +# Streams + +## `POST` data + +Use Request as a Writable stream to easily `POST` Readable streams (like files, other HTTP requests, or otherwise). + +TL;DR: Pipe a Readable Stream onto Request via: + +``` +READABLE.pipe(request.post(URL)); +``` + +A more detailed example: + +```js +var fs = require('fs') + , path = require('path') + , http = require('http') + , request = require('request') + , TMP_FILE_PATH = path.join(path.sep, 'tmp', 'foo') +; + +// write a temporary file: +fs.writeFileSync(TMP_FILE_PATH, 'foo bar baz quk\n'); + +http.createServer(function(req, res) { + console.log('the server is receiving data!\n'); + req + .on('end', res.end.bind(res)) + .pipe(process.stdout) + ; +}).listen(3000).unref(); + +fs.createReadStream(TMP_FILE_PATH) + .pipe(request.post('http://127.0.0.1:3000')) +; +```