www.aleph1.co.uk Git - yaffs-website/blob - node_modules/type-is/README.md

   1 # type-is
   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 Infer the content-type of a request.
  10
  11 ### Install
  12
  13 ```sh
  14 $ npm install type-is
  15 ```
  16
  17 ## API
  18
  19 ```js
  20 var http = require('http')
  21 var is   = require('type-is')
  22
  23 http.createServer(function (req, res) {
  24   var istext = is(req, ['text/*'])
  25   res.end('you ' + (istext ? 'sent' : 'did not send') + ' me text')
  26 })
  27 ```
  28
  29 ### type = is(request, types)
  30
  31 `request` is the node HTTP request. `types` is an array of types.
  32
  33 ```js
  34 // req.headers.content-type = 'application/json'
  35
  36 is(req, ['json'])             // 'json'
  37 is(req, ['html', 'json'])     // 'json'
  38 is(req, ['application/*'])    // 'application/json'
  39 is(req, ['application/json']) // 'application/json'
  40
  41 is(req, ['html']) // false
  42 ```
  43
  44 ### is.hasBody(request)
  45
  46 Returns a Boolean if the given `request` has a body, regardless of the
  47 `Content-Type` header.
  48
  49 Having a body has no relation to how large the body is (it may be 0 bytes).
  50 This is similar to how file existence works. If a body does exist, then this
  51 indicates that there is data to read from the Node.js request stream.
  52
  53 ```js
  54 if (is.hasBody(req)) {
  55   // read the body, since there is one
  56
  57   req.on('data', function (chunk) {
  58     // ...
  59   })
  60 }
  61 ```
  62
  63 ### type = is.is(mediaType, types)
  64
  65 `mediaType` is the [media type](https://tools.ietf.org/html/rfc6838) string. `types` is an array of types.
  66
  67 ```js
  68 var mediaType = 'application/json'
  69
  70 is.is(mediaType, ['json'])             // 'json'
  71 is.is(mediaType, ['html', 'json'])     // 'json'
  72 is.is(mediaType, ['application/*'])    // 'application/json'
  73 is.is(mediaType, ['application/json']) // 'application/json'
  74
  75 is.is(mediaType, ['html']) // false
  76 ```
  77
  78 ### Each type can be:
  79
  80 - An extension name such as `json`. This name will be returned if matched.
  81 - A mime type such as `application/json`.
  82 - A mime type with a wildcard such as `*/*` or `*/json` or `application/*`. The full mime type will be returned if matched.
  83 - A suffix such as `+json`. This can be combined with a wildcard such as `*/vnd+json` or `application/*+json`. The full mime type will be returned if matched.
  84
  85 `false` will be returned if no type matches or the content type is invalid.
  86
  87 `null` will be returned if the request does not have a body.
  88
  89 ## Examples
  90
  91 #### Example body parser
  92
  93 ```js
  94 var is = require('type-is');
  95
  96 function bodyParser(req, res, next) {
  97   if (!is.hasBody(req)) {
  98     return next()
  99   }
 100
 101   switch (is(req, ['urlencoded', 'json', 'multipart'])) {
 102     case 'urlencoded':
 103       // parse urlencoded body
 104       throw new Error('implement urlencoded body parsing')
 105       break
 106     case 'json':
 107       // parse json body
 108       throw new Error('implement json body parsing')
 109       break
 110     case 'multipart':
 111       // parse multipart body
 112       throw new Error('implement multipart body parsing')
 113       break
 114     default:
 115       // 415 error code
 116       res.statusCode = 415
 117       res.end()
 118       return
 119   }
 120 }
 121 ```
 122
 123 ## License
 124
 125 [MIT](LICENSE)
 126
 127 [npm-image]: https://img.shields.io/npm/v/type-is.svg
 128 [npm-url]: https://npmjs.org/package/type-is
 129 [node-version-image]: https://img.shields.io/node/v/type-is.svg
 130 [node-version-url]: https://nodejs.org/en/download/
 131 [travis-image]: https://img.shields.io/travis/jshttp/type-is/master.svg
 132 [travis-url]: https://travis-ci.org/jshttp/type-is
 133 [coveralls-image]: https://img.shields.io/coveralls/jshttp/type-is/master.svg
 134 [coveralls-url]: https://coveralls.io/r/jshttp/type-is?branch=master
 135 [downloads-image]: https://img.shields.io/npm/dm/type-is.svg
 136 [downloads-url]: https://npmjs.org/package/type-is