You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

203 lines
4.8 KiB

  1. # negotiator
  2. [![NPM Version][npm-image]][npm-url]
  3. [![NPM Downloads][downloads-image]][downloads-url]
  4. [![Node.js Version][node-version-image]][node-version-url]
  5. [![Build Status][github-actions-ci-image]][github-actions-ci-url]
  6. [![Test Coverage][coveralls-image]][coveralls-url]
  7. An HTTP content negotiator for Node.js
  8. ## Installation
  9. ```sh
  10. $ npm install negotiator
  11. ```
  12. ## API
  13. ```js
  14. var Negotiator = require('negotiator')
  15. ```
  16. ### Accept Negotiation
  17. ```js
  18. availableMediaTypes = ['text/html', 'text/plain', 'application/json']
  19. // The negotiator constructor receives a request object
  20. negotiator = new Negotiator(request)
  21. // Let's say Accept header is 'text/html, application/*;q=0.2, image/jpeg;q=0.8'
  22. negotiator.mediaTypes()
  23. // -> ['text/html', 'image/jpeg', 'application/*']
  24. negotiator.mediaTypes(availableMediaTypes)
  25. // -> ['text/html', 'application/json']
  26. negotiator.mediaType(availableMediaTypes)
  27. // -> 'text/html'
  28. ```
  29. You can check a working example at `examples/accept.js`.
  30. #### Methods
  31. ##### mediaType()
  32. Returns the most preferred media type from the client.
  33. ##### mediaType(availableMediaType)
  34. Returns the most preferred media type from a list of available media types.
  35. ##### mediaTypes()
  36. Returns an array of preferred media types ordered by the client preference.
  37. ##### mediaTypes(availableMediaTypes)
  38. Returns an array of preferred media types ordered by priority from a list of
  39. available media types.
  40. ### Accept-Language Negotiation
  41. ```js
  42. negotiator = new Negotiator(request)
  43. availableLanguages = ['en', 'es', 'fr']
  44. // Let's say Accept-Language header is 'en;q=0.8, es, pt'
  45. negotiator.languages()
  46. // -> ['es', 'pt', 'en']
  47. negotiator.languages(availableLanguages)
  48. // -> ['es', 'en']
  49. language = negotiator.language(availableLanguages)
  50. // -> 'es'
  51. ```
  52. You can check a working example at `examples/language.js`.
  53. #### Methods
  54. ##### language()
  55. Returns the most preferred language from the client.
  56. ##### language(availableLanguages)
  57. Returns the most preferred language from a list of available languages.
  58. ##### languages()
  59. Returns an array of preferred languages ordered by the client preference.
  60. ##### languages(availableLanguages)
  61. Returns an array of preferred languages ordered by priority from a list of
  62. available languages.
  63. ### Accept-Charset Negotiation
  64. ```js
  65. availableCharsets = ['utf-8', 'iso-8859-1', 'iso-8859-5']
  66. negotiator = new Negotiator(request)
  67. // Let's say Accept-Charset header is 'utf-8, iso-8859-1;q=0.8, utf-7;q=0.2'
  68. negotiator.charsets()
  69. // -> ['utf-8', 'iso-8859-1', 'utf-7']
  70. negotiator.charsets(availableCharsets)
  71. // -> ['utf-8', 'iso-8859-1']
  72. negotiator.charset(availableCharsets)
  73. // -> 'utf-8'
  74. ```
  75. You can check a working example at `examples/charset.js`.
  76. #### Methods
  77. ##### charset()
  78. Returns the most preferred charset from the client.
  79. ##### charset(availableCharsets)
  80. Returns the most preferred charset from a list of available charsets.
  81. ##### charsets()
  82. Returns an array of preferred charsets ordered by the client preference.
  83. ##### charsets(availableCharsets)
  84. Returns an array of preferred charsets ordered by priority from a list of
  85. available charsets.
  86. ### Accept-Encoding Negotiation
  87. ```js
  88. availableEncodings = ['identity', 'gzip']
  89. negotiator = new Negotiator(request)
  90. // Let's say Accept-Encoding header is 'gzip, compress;q=0.2, identity;q=0.5'
  91. negotiator.encodings()
  92. // -> ['gzip', 'identity', 'compress']
  93. negotiator.encodings(availableEncodings)
  94. // -> ['gzip', 'identity']
  95. negotiator.encoding(availableEncodings)
  96. // -> 'gzip'
  97. ```
  98. You can check a working example at `examples/encoding.js`.
  99. #### Methods
  100. ##### encoding()
  101. Returns the most preferred encoding from the client.
  102. ##### encoding(availableEncodings)
  103. Returns the most preferred encoding from a list of available encodings.
  104. ##### encodings()
  105. Returns an array of preferred encodings ordered by the client preference.
  106. ##### encodings(availableEncodings)
  107. Returns an array of preferred encodings ordered by priority from a list of
  108. available encodings.
  109. ## See Also
  110. The [accepts](https://npmjs.org/package/accepts#readme) module builds on
  111. this module and provides an alternative interface, mime type validation,
  112. and more.
  113. ## License
  114. [MIT](LICENSE)
  115. [npm-image]: https://img.shields.io/npm/v/negotiator.svg
  116. [npm-url]: https://npmjs.org/package/negotiator
  117. [node-version-image]: https://img.shields.io/node/v/negotiator.svg
  118. [node-version-url]: https://nodejs.org/en/download/
  119. [coveralls-image]: https://img.shields.io/coveralls/jshttp/negotiator/master.svg
  120. [coveralls-url]: https://coveralls.io/r/jshttp/negotiator?branch=master
  121. [downloads-image]: https://img.shields.io/npm/dm/negotiator.svg
  122. [downloads-url]: https://npmjs.org/package/negotiator
  123. [github-actions-ci-image]: https://img.shields.io/github/workflow/status/jshttp/negotiator/ci/master?label=ci
  124. [github-actions-ci-url]: https://github.com/jshttp/negotiator/actions/workflows/ci.yml