1 | # accepts
|
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 | Higher level content negotiation based on [negotiator](https://www.npmjs.com/package/negotiator). Extracted from [koa](https://www.npmjs.com/package/koa) for general use.
|
10 |
|
11 | In addition to negotiator, it allows:
|
12 |
|
13 | - Allows types as an array or arguments list, ie `(['text/html', 'application/json'])` as well as `('text/html', 'application/json')`.
|
14 | - Allows type shorthands such as `json`.
|
15 | - Returns `false` when no types match
|
16 | - Treats non-existent headers as `*`
|
17 |
|
18 | ## Installation
|
19 |
|
20 | ```sh
|
21 | npm install accepts
|
22 | ```
|
23 |
|
24 | ## API
|
25 |
|
26 | ```js
|
27 | var accepts = require('accepts')
|
28 | ```
|
29 |
|
30 | ### accepts(req)
|
31 |
|
32 | Create a new `Accepts` object for the given `req`.
|
33 |
|
34 | #### .charset(charsets)
|
35 |
|
36 | Return the first accepted charset. If nothing in `charsets` is accepted,
|
37 | then `false` is returned.
|
38 |
|
39 | #### .charsets()
|
40 |
|
41 | Return the charsets that the request accepts, in the order of the client's
|
42 | preference (most preferred first).
|
43 |
|
44 | #### .encoding(encodings)
|
45 |
|
46 | Return the first accepted encoding. If nothing in `encodings` is accepted,
|
47 | then `false` is returned.
|
48 |
|
49 | #### .encodings()
|
50 |
|
51 | Return the encodings that the request accepts, in the order of the client's
|
52 | preference (most preferred first).
|
53 |
|
54 | #### .language(languages)
|
55 |
|
56 | Return the first accepted language. If nothing in `languages` is accepted,
|
57 | then `false` is returned.
|
58 |
|
59 | #### .languages()
|
60 |
|
61 | Return the languages that the request accepts, in the order of the client's
|
62 | preference (most preferred first).
|
63 |
|
64 | #### .type(types)
|
65 |
|
66 | Return the first accepted type (and it is returned as the same text as what
|
67 | appears in the `types` array). If nothing in `types` is accepted, then `false`
|
68 | is returned.
|
69 |
|
70 | The `types` array can contain full MIME types or file extensions. Any value
|
71 | that is not a full MIME types is passed to `require('mime-types').lookup`.
|
72 |
|
73 | #### .types()
|
74 |
|
75 | Return the types that the request accepts, in the order of the client's
|
76 | preference (most preferred first).
|
77 |
|
78 | ## Examples
|
79 |
|
80 | ### Simple type negotiation
|
81 |
|
82 | This simple example shows how to use `accepts` to return a different typed
|
83 | respond body based on what the client wants to accept. The server lists it's
|
84 | preferences in order and will get back the best match between the client and
|
85 | server.
|
86 |
|
87 | ```js
|
88 | var accepts = require('accepts')
|
89 | var http = require('http')
|
90 |
|
91 | function app(req, res) {
|
92 | var accept = accepts(req)
|
93 |
|
94 | // the order of this list is significant; should be server preferred order
|
95 | switch(accept.type(['json', 'html'])) {
|
96 | case 'json':
|
97 | res.setHeader('Content-Type', 'application/json')
|
98 | res.write('{"hello":"world!"}')
|
99 | break
|
100 | case 'html':
|
101 | res.setHeader('Content-Type', 'text/html')
|
102 | res.write('<b>hello, world!</b>')
|
103 | break
|
104 | default:
|
105 | // the fallback is text/plain, so no need to specify it above
|
106 | res.setHeader('Content-Type', 'text/plain')
|
107 | res.write('hello, world!')
|
108 | break
|
109 | }
|
110 |
|
111 | res.end()
|
112 | }
|
113 |
|
114 | http.createServer(app).listen(3000)
|
115 | ```
|
116 |
|
117 | You can test this out with the cURL program:
|
118 | ```sh
|
119 | curl -I -H'Accept: text/html' http://localhost:3000/
|
120 | ```
|
121 |
|
122 | ## License
|
123 |
|
124 | [MIT](LICENSE)
|
125 |
|
126 | [npm-image]: https://img.shields.io/npm/v/accepts.svg?style=flat
|
127 | [npm-url]: https://npmjs.org/package/accepts
|
128 | [node-version-image]: https://img.shields.io/node/v/accepts.svg?style=flat
|
129 | [node-version-url]: http://nodejs.org/download/
|
130 | [travis-image]: https://img.shields.io/travis/jshttp/accepts.svg?style=flat
|
131 | [travis-url]: https://travis-ci.org/jshttp/accepts
|
132 | [coveralls-image]: https://img.shields.io/coveralls/jshttp/accepts.svg?style=flat
|
133 | [coveralls-url]: https://coveralls.io/r/jshttp/accepts
|
134 | [downloads-image]: https://img.shields.io/npm/dm/accepts.svg?style=flat
|
135 | [downloads-url]: https://npmjs.org/package/accepts
|