README.md (5183B)
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