node_modules/type-is/README.md

   1 # type-is
   2
   3 [![NPM Version][npm-version-image]][npm-url]
   4 [![NPM Downloads][npm-downloads-image]][npm-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 Infer the content-type of a request.
  10
  11 ### Install
  12
  13 This is a [Node.js](https://nodejs.org/en/) module available through the
  14 [npm registry](https://www.npmjs.com/). Installation is done using the
  15 [`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
  16
  17 ```sh
  18 $ npm install type-is
  19 ```
  20
  21 ## API
  22
  23 ```js
  24 var http = require('http')
  25 var typeis = require('type-is')
  26
  27 http.createServer(function (req, res) {
  28   var istext = typeis(req, ['text/*'])
  29   res.end('you ' + (istext ? 'sent' : 'did not send') + ' me text')
  30 })
  31 ```
  32
  33 ### typeis(request, types)
  34
  35 Checks if the `request` is one of the `types`. If the request has no body,
  36 even if there is a `Content-Type` header, then `null` is returned. If the
  37 `Content-Type` header is invalid or does not matches any of the `types`, then
  38 `false` is returned. Otherwise, a string of the type that matched is returned.
  39
  40 The `request` argument is expected to be a Node.js HTTP request. The `types`
  41 argument is an array of type strings.
  42
  43 Each type in the `types` array can be one of the following:
  44
  45 - A file extension name such as `json`. This name will be returned if matched.
  46 - A mime type such as `application/json`.
  47 - A mime type with a wildcard such as `*/*` or `*/json` or `application/*`.
  48   The full mime type will be returned if matched.
  49 - A suffix such as `+json`. This can be combined with a wildcard such as
  50   `*/vnd+json` or `application/*+json`. The full mime type will be returned
  51   if matched.
  52
  53 Some examples to illustrate the inputs and returned value:
  54
  55 <!-- eslint-disable no-undef -->
  56
  57 ```js
  58 // req.headers.content-type = 'application/json'
  59
  60 typeis(req, ['json']) // => 'json'
  61 typeis(req, ['html', 'json']) // => 'json'
  62 typeis(req, ['application/*']) // => 'application/json'
  63 typeis(req, ['application/json']) // => 'application/json'
  64
  65 typeis(req, ['html']) // => false
  66 ```
  67
  68 ### typeis.hasBody(request)
  69
  70 Returns a Boolean if the given `request` has a body, regardless of the
  71 `Content-Type` header.
  72
  73 Having a body has no relation to how large the body is (it may be 0 bytes).
  74 This is similar to how file existence works. If a body does exist, then this
  75 indicates that there is data to read from the Node.js request stream.
  76
  77 <!-- eslint-disable no-undef -->
  78
  79 ```js
  80 if (typeis.hasBody(req)) {
  81   // read the body, since there is one
  82
  83   req.on('data', function (chunk) {
  84     // ...
  85   })
  86 }
  87 ```
  88
  89 ### typeis.is(mediaType, types)
  90
  91 Checks if the `mediaType` is one of the `types`. If the `mediaType` is invalid
  92 or does not matches any of the `types`, then `false` is returned. Otherwise, a
  93 string of the type that matched is returned.
  94
  95 The `mediaType` argument is expected to be a
  96 [media type](https://tools.ietf.org/html/rfc6838) string. The `types` argument
  97 is an array of type strings.
  98
  99 Each type in the `types` array can be one of the following:
 100
 101 - A file extension name such as `json`. This name will be returned if matched.
 102 - A mime type such as `application/json`.
 103 - A mime type with a wildcard such as `*/*` or `*/json` or `application/*`.
 104   The full mime type will be returned if matched.
 105 - A suffix such as `+json`. This can be combined with a wildcard such as
 106   `*/vnd+json` or `application/*+json`. The full mime type will be returned
 107   if matched.
 108
 109 Some examples to illustrate the inputs and returned value:
 110
 111 <!-- eslint-disable no-undef -->
 112
 113 ```js
 114 var mediaType = 'application/json'
 115
 116 typeis.is(mediaType, ['json']) // => 'json'
 117 typeis.is(mediaType, ['html', 'json']) // => 'json'
 118 typeis.is(mediaType, ['application/*']) // => 'application/json'
 119 typeis.is(mediaType, ['application/json']) // => 'application/json'
 120
 121 typeis.is(mediaType, ['html']) // => false
 122 ```
 123
 124 ## Examples
 125
 126 ### Example body parser
 127
 128 ```js
 129 var express = require('express')
 130 var typeis = require('type-is')
 131
 132 var app = express()
 133
 134 app.use(function bodyParser (req, res, next) {
 135   if (!typeis.hasBody(req)) {
 136     return next()
 137   }
 138
 139   switch (typeis(req, ['urlencoded', 'json', 'multipart'])) {
 140     case 'urlencoded':
 141       // parse urlencoded body
 142       throw new Error('implement urlencoded body parsing')
 143     case 'json':
 144       // parse json body
 145       throw new Error('implement json body parsing')
 146     case 'multipart':
 147       // parse multipart body
 148       throw new Error('implement multipart body parsing')
 149     default:
 150       // 415 error code
 151       res.statusCode = 415
 152       res.end()
 153       break
 154   }
 155 })
 156 ```
 157
 158 ## License
 159
 160 [MIT](LICENSE)
 161
 162 [coveralls-image]: https://badgen.net/coveralls/c/github/jshttp/type-is/master
 163 [coveralls-url]: https://coveralls.io/r/jshttp/type-is?branch=master
 164 [node-version-image]: https://badgen.net/npm/node/type-is
 165 [node-version-url]: https://nodejs.org/en/download
 166 [npm-downloads-image]: https://badgen.net/npm/dm/type-is
 167 [npm-url]: https://npmjs.org/package/type-is
 168 [npm-version-image]: https://badgen.net/npm/v/type-is
 169 [travis-image]: https://badgen.net/travis/jshttp/type-is/master
 170 [travis-url]: https://travis-ci.org/jshttp/type-is