node_modules/content-disposition/README.md

   1 # content-disposition
   2
   3 [![NPM Version][npm-image]][npm-url]
   4 [![NPM Downloads][downloads-image]][downloads-url]
   5 [![Node.js Version][node-version-image]][node-version-url]
   6 [![Build Status][travis-image]][travis-url]
   7 [![Test Coverage][coveralls-image]][coveralls-url]
   8
   9 Create and parse HTTP `Content-Disposition` header
  10
  11 ## Installation
  12
  13 ```sh
  14 $ npm install content-disposition
  15 ```
  16
  17 ## API
  18
  19 <!-- eslint-disable no-unused-vars -->
  20
  21 ```js
  22 var contentDisposition = require('content-disposition')
  23 ```
  24
  25 ### contentDisposition(filename, options)
  26
  27 Create an attachment `Content-Disposition` header value using the given file name,
  28 if supplied. The `filename` is optional and if no file name is desired, but you
  29 want to specify `options`, set `filename` to `undefined`.
  30
  31 <!-- eslint-disable no-undef -->
  32
  33 ```js
  34 res.setHeader('Content-Disposition', contentDisposition('∫ maths.pdf'))
  35 ```
  36
  37 **note** HTTP headers are of the ISO-8859-1 character set. If you are writing this
  38 header through a means different from `setHeader` in Node.js, you'll want to specify
  39 the `'binary'` encoding in Node.js.
  40
  41 #### Options
  42
  43 `contentDisposition` accepts these properties in the options object.
  44
  45 ##### fallback
  46
  47 If the `filename` option is outside ISO-8859-1, then the file name is actually
  48 stored in a supplemental field for clients that support Unicode file names and
  49 a ISO-8859-1 version of the file name is automatically generated.
  50
  51 This specifies the ISO-8859-1 file name to override the automatic generation or
  52 disables the generation all together, defaults to `true`.
  53
  54   - A string will specify the ISO-8859-1 file name to use in place of automatic
  55     generation.
  56   - `false` will disable including a ISO-8859-1 file name and only include the
  57     Unicode version (unless the file name is already ISO-8859-1).
  58   - `true` will enable automatic generation if the file name is outside ISO-8859-1.
  59
  60 If the `filename` option is ISO-8859-1 and this option is specified and has a
  61 different value, then the `filename` option is encoded in the extended field
  62 and this set as the fallback field, even though they are both ISO-8859-1.
  63
  64 ##### type
  65
  66 Specifies the disposition type, defaults to `"attachment"`. This can also be
  67 `"inline"`, or any other value (all values except inline are treated like
  68 `attachment`, but can convey additional information if both parties agree to
  69 it). The type is normalized to lower-case.
  70
  71 ### contentDisposition.parse(string)
  72
  73 <!-- eslint-disable no-undef, no-unused-vars -->
  74
  75 ```js
  76 var disposition = contentDisposition.parse('attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt')
  77 ```
  78
  79 Parse a `Content-Disposition` header string. This automatically handles extended
  80 ("Unicode") parameters by decoding them and providing them under the standard
  81 parameter name. This will return an object with the following properties (examples
  82 are shown for the string `'attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt'`):
  83
  84  - `type`: The disposition type (always lower case). Example: `'attachment'`
  85
  86  - `parameters`: An object of the parameters in the disposition (name of parameter
  87    always lower case and extended versions replace non-extended versions). Example:
  88    `{filename: "€ rates.txt"}`
  89
  90 ## Examples
  91
  92 ### Send a file for download
  93
  94 ```js
  95 var contentDisposition = require('content-disposition')
  96 var destroy = require('destroy')
  97 var fs = require('fs')
  98 var http = require('http')
  99 var onFinished = require('on-finished')
 100
 101 var filePath = '/path/to/public/plans.pdf'
 102
 103 http.createServer(function onRequest (req, res) {
 104   // set headers
 105   res.setHeader('Content-Type', 'application/pdf')
 106   res.setHeader('Content-Disposition', contentDisposition(filePath))
 107
 108   // send file
 109   var stream = fs.createReadStream(filePath)
 110   stream.pipe(res)
 111   onFinished(res, function () {
 112     destroy(stream)
 113   })
 114 })
 115 ```
 116
 117 ## Testing
 118
 119 ```sh
 120 $ npm test
 121 ```
 122
 123 ## References
 124
 125 - [RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1][rfc-2616]
 126 - [RFC 5987: Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP) Header Field Parameters][rfc-5987]
 127 - [RFC 6266: Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)][rfc-6266]
 128 - [Test Cases for HTTP Content-Disposition header field (RFC 6266) and the Encodings defined in RFCs 2047, 2231 and 5987][tc-2231]
 129
 130 [rfc-2616]: https://tools.ietf.org/html/rfc2616
 131 [rfc-5987]: https://tools.ietf.org/html/rfc5987
 132 [rfc-6266]: https://tools.ietf.org/html/rfc6266
 133 [tc-2231]: http://greenbytes.de/tech/tc2231/
 134
 135 ## License
 136
 137 [MIT](LICENSE)
 138
 139 [npm-image]: https://img.shields.io/npm/v/content-disposition.svg
 140 [npm-url]: https://npmjs.org/package/content-disposition
 141 [node-version-image]: https://img.shields.io/node/v/content-disposition.svg
 142 [node-version-url]: https://nodejs.org/en/download
 143 [travis-image]: https://img.shields.io/travis/jshttp/content-disposition.svg
 144 [travis-url]: https://travis-ci.org/jshttp/content-disposition
 145 [coveralls-image]: https://img.shields.io/coveralls/jshttp/content-disposition.svg
 146 [coveralls-url]: https://coveralls.io/r/jshttp/content-disposition?branch=master
 147 [downloads-image]: https://img.shields.io/npm/dm/content-disposition.svg
 148 [downloads-url]: https://npmjs.org/package/content-disposition