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

   1 # Statuses
   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 HTTP status utility for node.
  10
  11 ## API
  12
  13 ```js
  14 var status = require('statuses')
  15 ```
  16
  17 ### var code = status(Integer || String)
  18
  19 If `Integer` or `String` is a valid HTTP code or status message, then the appropriate `code` will be returned. Otherwise, an error will be thrown.
  20
  21 ```js
  22 status(403) // => 403
  23 status('403') // => 403
  24 status('forbidden') // => 403
  25 status('Forbidden') // => 403
  26 status(306) // throws, as it's not supported by node.js
  27 ```
  28
  29 ### status.codes
  30
  31 Returns an array of all the status codes as `Integer`s.
  32
  33 ### var msg = status[code]
  34
  35 Map of `code` to `status message`. `undefined` for invalid `code`s.
  36
  37 ```js
  38 status[404] // => 'Not Found'
  39 ```
  40
  41 ### var code = status[msg]
  42
  43 Map of `status message` to `code`. `msg` can either be title-cased or lower-cased. `undefined` for invalid `status message`s.
  44
  45 ```js
  46 status['not found'] // => 404
  47 status['Not Found'] // => 404
  48 ```
  49
  50 ### status.redirect[code]
  51
  52 Returns `true` if a status code is a valid redirect status.
  53
  54 ```js
  55 status.redirect[200] // => undefined
  56 status.redirect[301] // => true
  57 ```
  58
  59 ### status.empty[code]
  60
  61 Returns `true` if a status code expects an empty body.
  62
  63 ```js
  64 status.empty[200] // => undefined
  65 status.empty[204] // => true
  66 status.empty[304] // => true
  67 ```
  68
  69 ### status.retry[code]
  70
  71 Returns `true` if you should retry the rest.
  72
  73 ```js
  74 status.retry[501] // => undefined
  75 status.retry[503] // => true
  76 ```
  77
  78 ## Adding Status Codes
  79
  80 The status codes are primarily sourced from http://www.iana.org/assignments/http-status-codes/http-status-codes-1.csv.
  81 Additionally, custom codes are added from http://en.wikipedia.org/wiki/List_of_HTTP_status_codes.
  82 These are added manually in the `lib/*.json` files.
  83 If you would like to add a status code, add it to the appropriate JSON file.
  84
  85 To rebuild `codes.json`, run the following:
  86
  87 ```bash
  88 # update src/iana.json
  89 npm run fetch
  90 # build codes.json
  91 npm run build
  92 ```
  93
  94 [npm-image]: https://img.shields.io/npm/v/statuses.svg
  95 [npm-url]: https://npmjs.org/package/statuses
  96 [node-version-image]: https://img.shields.io/badge/node.js-%3E%3D_0.6-brightgreen.svg
  97 [node-version-url]: https://nodejs.org/en/download
  98 [travis-image]: https://img.shields.io/travis/jshttp/statuses.svg
  99 [travis-url]: https://travis-ci.org/jshttp/statuses
 100 [coveralls-image]: https://img.shields.io/coveralls/jshttp/statuses.svg
 101 [coveralls-url]: https://coveralls.io/r/jshttp/statuses?branch=master
 102 [downloads-image]: https://img.shields.io/npm/dm/statuses.svg
 103 [downloads-url]: https://npmjs.org/package/statuses