twitst4tz

twitter statistics web application
Log | Files | Refs | README | LICENSE

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