node_modules/encodeurl/README.md

   1 # encodeurl
   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 Encode a URL to a percent-encoded form, excluding already-encoded sequences
  10
  11 ## Installation
  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 encodeurl
  19 ```
  20
  21 ## API
  22
  23 ```js
  24 var encodeUrl = require('encodeurl')
  25 ```
  26
  27 ### encodeUrl(url)
  28
  29 Encode a URL to a percent-encoded form, excluding already-encoded sequences.
  30
  31 This function will take an already-encoded URL and encode all the non-URL
  32 code points (as UTF-8 byte sequences). This function will not encode the
  33 "%" character unless it is not part of a valid sequence (`%20` will be
  34 left as-is, but `%foo` will be encoded as `%25foo`).
  35
  36 This encode is meant to be "safe" and does not throw errors. It will try as
  37 hard as it can to properly encode the given URL, including replacing any raw,
  38 unpaired surrogate pairs with the Unicode replacement character prior to
  39 encoding.
  40
  41 This function is _similar_ to the intrinsic function `encodeURI`, except it
  42 will not encode the `%` character if that is part of a valid sequence, will
  43 not encode `[` and `]` (for IPv6 hostnames) and will replace raw, unpaired
  44 surrogate pairs with the Unicode replacement character (instead of throwing).
  45
  46 ## Examples
  47
  48 ### Encode a URL containing user-controled data
  49
  50 ```js
  51 var encodeUrl = require('encodeurl')
  52 var escapeHtml = require('escape-html')
  53
  54 http.createServer(function onRequest (req, res) {
  55   // get encoded form of inbound url
  56   var url = encodeUrl(req.url)
  57
  58   // create html message
  59   var body = '<p>Location ' + escapeHtml(url) + ' not found</p>'
  60
  61   // send a 404
  62   res.statusCode = 404
  63   res.setHeader('Content-Type', 'text/html; charset=UTF-8')
  64   res.setHeader('Content-Length', String(Buffer.byteLength(body, 'utf-8')))
  65   res.end(body, 'utf-8')
  66 })
  67 ```
  68
  69 ### Encode a URL for use in a header field
  70
  71 ```js
  72 var encodeUrl = require('encodeurl')
  73 var escapeHtml = require('escape-html')
  74 var url = require('url')
  75
  76 http.createServer(function onRequest (req, res) {
  77   // parse inbound url
  78   var href = url.parse(req)
  79
  80   // set new host for redirect
  81   href.host = 'localhost'
  82   href.protocol = 'https:'
  83   href.slashes = true
  84
  85   // create location header
  86   var location = encodeUrl(url.format(href))
  87
  88   // create html message
  89   var body = '<p>Redirecting to new site: ' + escapeHtml(location) + '</p>'
  90
  91   // send a 301
  92   res.statusCode = 301
  93   res.setHeader('Content-Type', 'text/html; charset=UTF-8')
  94   res.setHeader('Content-Length', String(Buffer.byteLength(body, 'utf-8')))
  95   res.setHeader('Location', location)
  96   res.end(body, 'utf-8')
  97 })
  98 ```
  99
 100 ## Testing
 101
 102 ```sh
 103 $ npm test
 104 $ npm run lint
 105 ```
 106
 107 ## References
 108
 109 - [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax][rfc-3986]
 110 - [WHATWG URL Living Standard][whatwg-url]
 111
 112 [rfc-3986]: https://tools.ietf.org/html/rfc3986
 113 [whatwg-url]: https://url.spec.whatwg.org/
 114
 115 ## License
 116
 117 [MIT](LICENSE)
 118
 119 [npm-image]: https://img.shields.io/npm/v/encodeurl.svg
 120 [npm-url]: https://npmjs.org/package/encodeurl
 121 [node-version-image]: https://img.shields.io/node/v/encodeurl.svg
 122 [node-version-url]: https://nodejs.org/en/download
 123 [travis-image]: https://img.shields.io/travis/pillarjs/encodeurl.svg
 124 [travis-url]: https://travis-ci.org/pillarjs/encodeurl
 125 [coveralls-image]: https://img.shields.io/coveralls/pillarjs/encodeurl.svg
 126 [coveralls-url]: https://coveralls.io/r/pillarjs/encodeurl?branch=master
 127 [downloads-image]: https://img.shields.io/npm/dm/encodeurl.svg
 128 [downloads-url]: https://npmjs.org/package/encodeurl