text: # send
  
  [![NPM Version][npm-image]][npm-url]
  [![NPM Downloads][downloads-image]][downloads-url]
  [![Linux Build][travis-image]][travis-url]
  [![Windows Build][appveyor-image]][appveyor-url]
  [![Test Coverage][coveralls-image]][coveralls-url]
  [![Gratipay][gratipay-image]][gratipay-url]
  
  Send is a library for streaming files from the file system as a http response
  supporting partial responses (Ranges), conditional-GET negotiation (If-Match,
  If-Unmodified-Since, If-None-Match, If-Modified-Since), high test coverage,
  and granular events which may be leveraged to take appropriate actions in your
  application or framework.
  
  Looking to serve up entire folders mapped to URLs? Try [serve-static](https://www.npmjs.org/package/serve-static).
  
  ## Installation
  
  This is a [Node.js](https://nodejs.org/en/) module available through the
  [npm registry](https://www.npmjs.com/). Installation is done using the
  [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
  
  ```bash
  $ npm install send
  ```
  
  ## API
  
  <!-- eslint-disable no-unused-vars -->
  
  ```js
  var send = require('send')
  ```
  
  ### send(req, path, [options])
  
  Create a new `SendStream` for the given path to send to a `res`. The `req` is
  the Node.js HTTP request and the `path` is a urlencoded path to send (urlencoded,
  not the actual file-system path).
  
  #### Options
  
  ##### acceptRanges
  
  Enable or disable accepting ranged requests, defaults to true.
  Disabling this will not send `Accept-Ranges` and ignore the contents
  of the `Range` request header.
  
  ##### cacheControl
  
  Enable or disable setting `Cache-Control` response header, defaults to
  true. Disabling this will ignore the `immutable` and `maxAge` options.
  
  ##### dotfiles
  
  Set how "dotfiles" are treated when encountered. A dotfile is a file
  or directory that begins with a dot ("."). Note this check is done on
  the path itself without checking if the path actually exists on the
  disk. If `root` is specified, only the dotfiles above the root are
  checked (i.e. the root itself can be within a dotfile when when set
  to "deny").
  
    - `'allow'` No special treatment for dotfiles.
    - `'deny'` Send a 403 for any request for a dotfile.
    - `'ignore'` Pretend like the dotfile does not exist and 404.
  
  The default value is _similar_ to `'ignore'`, with the exception that
  this default will not ignore the files within a directory that begins
  with a dot, for backward-compatibility.
  
  ##### end
  
  Byte offset at which the stream ends, defaults to the length of the file
  minus 1. The end is inclusive in the stream, meaning `end: 3` will include
  the 4th byte in the stream.
  
  ##### etag
  
  Enable or disable etag generation, defaults to true.
  
  ##### extensions
  
  If a given file doesn't exist, try appending one of the given extensions,
  in the given order. By default, this is disabled (set to `false`). An
  example value that will serve extension-less HTML files: `['html', 'htm']`.
  This is skipped if the requested file already has an extension.
  
  ##### immutable
  
  Enable or diable the `immutable` directive in the `Cache-Control` response
  header, defaults to `false`. If set to `true`, the `maxAge` option should
  also be specified to enable caching. The `immutable` directive will prevent
  supported clients from making conditional requests during the life of the
  `maxAge` option to check if the file has changed.
  
  ##### index
  
  By default send supports "index.html" files, to disable this
  set `false` or to supply a new index pass a string or an array
  in preferred order.
  
  ##### lastModified
  
  Enable or disable `Last-Modified` header, defaults to true. Uses the file
  system's last modified value.
  
  ##### maxAge
  
  Provide a max-age in milliseconds for http caching, defaults to 0.
  This can also be a string accepted by the
  [ms](https://www.npmjs.org/package/ms#readme) module.
  
  ##### root
  
  Serve files relative to `path`.
  
  ##### start
  
  Byte offset at which the stream starts, defaults to 0. The start is inclusive,
  meaning `start: 2` will include the 3rd byte in the stream.
  
  #### Events
  
  The `SendStream` is an event emitter and will emit the following events:
  
    - `error` an error occurred `(err)`
    - `directory` a directory was requested `(res, path)`
    - `file` a file was requested `(path, stat)`
    - `headers` the headers are about to be set on a file `(res, path, stat)`
    - `stream` file streaming has started `(stream)`
    - `end` streaming has completed
  
  #### .pipe
  
  The `pipe` method is used to pipe the response into the Node.js HTTP response
  object, typically `send(req, path, options).pipe(res)`.
  
  ### .mime
  
  The `mime` export is the global instance of of the
  [`mime` npm module](https://www.npmjs.com/package/mime).
  
  This is used to configure the MIME types that are associated with file extensions
  as well as other options for how to resolve the MIME type of a file (like the
  default type to use for an unknown file extension).
  
  ## Error-handling
  
  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.
  
  ## Caching
  
  It does _not_ perform internal caching, you should use a reverse proxy cache
  such 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 ;).
  
  ## Debugging
  
  To enable `debug()` instrumentation output export __DEBUG__:
  
  ```
  $ DEBUG=send node app
  ```
  
  ## Running tests
  
  ```
  $ npm install
  $ npm test
  ```
  
  ## Examples
  
  ### Small example
  
  ```js
  var http = require('http')
  var parseUrl = require('parseurl')
  var send = require('send')
  
  var server = http.createServer(function onRequest (req, res) {
    send(req, parseUrl(req).pathname).pipe(res)
  })
  
  server.listen(3000)
  ```
  
  ### Custom file types
  
  ```js
  var http = require('http')
  var parseUrl = require('parseurl')
  var send = require('send')
  
  // Default unknown types to text/plain
  send.mime.default_type = 'text/plain'
  
  // Add a custom type
  send.mime.define({
    'application/x-my-type': ['x-mt', 'x-mtt']
  })
  
  var server = http.createServer(function onRequest (req, res) {
    send(req, parseUrl(req).pathname).pipe(res)
  })
  
  server.listen(3000)
  ```
  
  ### Custom directory index view
  
  This is a example of serving up a structure of directories with a
  custom function to render a listing of a directory.
  
  ```js
  var http = require('http')
  var fs = require('fs')
  var parseUrl = require('parseurl')
  var send = require('send')
  
  // Transfer arbitrary files from within /www/example.com/public/*
  // with a custom handler for directory listing
  var server = http.createServer(function onRequest (req, res) {
    send(req, parseUrl(req).pathname, {index: false, root: '/www/example.com/public'})
    .once('directory', directory)
    .pipe(res)
  })
  
  server.listen(3000)
  
  // Custom directory handler
  function directory (res, path) {
    var stream = this
  
    // redirect to trailing slash for consistent url
    if (!stream.hasTrailingSlash()) {
      return stream.redirect(path)
    }
  
    // get directory list
    fs.readdir(path, function onReaddir (err, list) {
      if (err) return stream.error(err)
  
      // render an index for the directory
      res.setHeader('Content-Type', 'text/plain; charset=UTF-8')
      res.end(list.join('\n') + '\n')
    })
  }
  ```
  
  ### Serving from a root directory with custom error-handling
  
  ```js
  var http = require('http')
  var parseUrl = require('parseurl')
  var send = require('send')
  
  var server = http.createServer(function onRequest (req, res) {
    // your custom error-handling logic:
    function error (err) {
      res.statusCode = err.status || 500
      res.end(err.message)
    }
  
    // your custom headers
    function headers (res, path, stat) {
      // serve all files for download
      res.setHeader('Content-Disposition', 'attachment')
    }
  
    // your custom directory handling logic:
    function redirect () {
      res.statusCode = 301
      res.setHeader('Location', req.url + '/')
      res.end('Redirecting to ' + req.url + '/')
    }
  
    // transfer arbitrary files from within
    // /www/example.com/public/*
    send(req, parseUrl(req).pathname, {root: '/www/example.com/public'})
    .on('error', error)
    .on('directory', redirect)
    .on('headers', headers)
    .pipe(res)
  })
  
  server.listen(3000)
  ```
  
  ## License
  
  [MIT](LICENSE)
  
  [npm-image]: https://img.shields.io/npm/v/send.svg
  [npm-url]: https://npmjs.org/package/send
  [travis-image]: https://img.shields.io/travis/pillarjs/send/master.svg?label=linux
  [travis-url]: https://travis-ci.org/pillarjs/send
  [appveyor-image]: https://img.shields.io/appveyor/ci/dougwilson/send/master.svg?label=windows
  [appveyor-url]: https://ci.appveyor.com/project/dougwilson/send
  [coveralls-image]: https://img.shields.io/coveralls/pillarjs/send/master.svg
  [coveralls-url]: https://coveralls.io/r/pillarjs/send?branch=master
  [downloads-image]: https://img.shields.io/npm/dm/send.svg
  [downloads-url]: https://npmjs.org/package/send
  [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
  [gratipay-url]: https://www.gratipay.com/dougwilson/
  