1# send
  2
  3[![NPM Version][npm-image]][npm-url]
  4[![NPM Downloads][downloads-image]][downloads-url]
  5[![Build Status][travis-image]][travis-url]
  6[![Test Coverage][coveralls-image]][coveralls-url]
  7[![Gittip][gittip-image]][gittip-url]
  8
  9  Send is Connect's `static()` extracted for generalized use, a streaming static file
 10  server supporting partial responses (Ranges), conditional-GET negotiation, high test coverage, and granular events which may be leveraged to take appropriate actions in your application or framework.
 11
 12## Installation
 13
 14```bash
 15$ npm install send
 16```
 17
 18## API
 19
 20```js
 21var send = require('send')
 22```
 23
 24### send(req, path, [options])
 25
 26Create a new `SendStream` for the given path to send to a `res`. The `req` is
 27the Node.js HTTP request and the `path` is a urlencoded path to send (urlencoded,
 28not the actual file-system path).
 29
 30#### Options
 31
 32##### dotfiles
 33
 34  Set how "dotfiles" are treated when encountered. A dotfile is a file
 35  or directory that begins with a dot ("."). Note this check is done on
 36  the path itself without checking if the path actually exists on the
 37  disk. If `root` is specified, only the dotfiles above the root are
 38  checked (i.e. the root itself can be within a dotfile when when set
 39  to "deny").
 40
 41  The default value is `'ignore'`.
 42
 43  - `'allow'` No special treatment for dotfiles.
 44  - `'deny'` Send a 403 for any request for a dotfile.
 45  - `'ignore'` Pretend like the dotfile does not exist and 404.
 46
 47##### etag
 48
 49  Enable or disable etag generation, defaults to true.
 50
 51##### extensions
 52
 53  If a given file doesn't exist, try appending one of the given extensions,
 54  in the given order. By default, this is disabled (set to `false`). An
 55  example value that will serve extension-less HTML files: `['html', 'htm']`.
 56  This is skipped if the requested file already has an extension.
 57
 58##### index
 59
 60  By default send supports "index.html" files, to disable this
 61  set `false` or to supply a new index pass a string or an array
 62  in preferred order.
 63
 64##### lastModified
 65
 66  Enable or disable `Last-Modified` header, defaults to true. Uses the file
 67  system's last modified value.
 68
 69##### maxAge
 70
 71  Provide a max-age in milliseconds for http caching, defaults to 0.
 72  This can also be a string accepted by the
 73  [ms](https://www.npmjs.org/package/ms#readme) module.
 74
 75##### root
 76
 77  Serve files relative to `path`.
 78
 79### Events
 80
 81The `SendStream` is an event emitter and will emit the following events:
 82
 83  - `error` an error occurred `(err)`
 84  - `directory` a directory was requested
 85  - `file` a file was requested `(path, stat)`
 86  - `headers` the headers are about to be set on a file `(res, path, stat)`
 87  - `stream` file streaming has started `(stream)`
 88  - `end` streaming has completed
 89
 90### .pipe
 91
 92The `pipe` method is used to pipe the response into the Node.js HTTP response
 93object, typically `send(req, path, options).pipe(res)`.
 94
 95## Error-handling
 96
 97  By default when no `error` listeners are present an automatic response will be made, otherwise you have full control over the response, aka you may show a 5xx page etc.
 98
 99## Caching
100
101  It does _not_ perform internal caching, you should use a reverse proxy cache such
102  as Varnish for this, or those fancy things called CDNs. If your application is small enough that it would benefit from single-node memory caching, it's small enough that it does not need caching at all ;).
103
104## Debugging
105
106 To enable `debug()` instrumentation output export __DEBUG__:
107
108```
109$ DEBUG=send node app
110```
111
112## Running tests
113
114```
115$ npm install
116$ npm test
117```
118
119## Examples
120
121  Small:
122
123```js
124var http = require('http');
125var send = require('send');
126
127var app = http.createServer(function(req, res){
128  send(req, req.url).pipe(res);
129}).listen(3000);
130```
131
132  Serving from a root directory with custom error-handling:
133
134```js
135var http = require('http');
136var send = require('send');
137var url = require('url');
138
139var app = http.createServer(function(req, res){
140  // your custom error-handling logic:
141  function error(err) {
142    res.statusCode = err.status || 500;
143    res.end(err.message);
144  }
145
146  // your custom headers
147  function headers(res, path, stat) {
148    // serve all files for download
149    res.setHeader('Content-Disposition', 'attachment');
150  }
151
152  // your custom directory handling logic:
153  function redirect() {
154    res.statusCode = 301;
155    res.setHeader('Location', req.url + '/');
156    res.end('Redirecting to ' + req.url + '/');
157  }
158
159  // transfer arbitrary files from within
160  // /www/example.com/public/*
161  send(req, url.parse(req.url).pathname, {root: '/www/example.com/public'})
162  .on('error', error)
163  .on('directory', redirect)
164  .on('headers', headers)
165  .pipe(res);
166}).listen(3000);
167```
168
169## License 
170
171[MIT](LICENSE)
172
173[npm-image]: https://img.shields.io/npm/v/send.svg?style=flat
174[npm-url]: https://npmjs.org/package/send
175[travis-image]: https://img.shields.io/travis/tj/send.svg?style=flat
176[travis-url]: https://travis-ci.org/tj/send
177[coveralls-image]: https://img.shields.io/coveralls/tj/send.svg?style=flat
178[coveralls-url]: https://coveralls.io/r/tj/send?branch=master
179[downloads-image]: https://img.shields.io/npm/dm/send.svg?style=flat
180[downloads-url]: https://npmjs.org/package/send
181[gittip-image]: https://img.shields.io/gittip/dougwilson.svg?style=flat
182[gittip-url]: https://www.gittip.com/dougwilson/