1 | URI validation functions
|
2 | ==
|
3 | [![Build Status](https://travis-ci.org/ogt/valid-url.png)](https://travis-ci.org/ogt/valid-url)
|
4 |
|
5 | ## Synopsis
|
6 |
|
7 | Common url validation methods
|
8 | ```
|
9 | var validUrl = require('valid-url');
|
10 |
|
11 | if (validUrl.isUri(suspect)){
|
12 | console.log('Looks like an URI');
|
13 | } else {
|
14 | console.log('Not a URI');
|
15 | }
|
16 | ```
|
17 |
|
18 | Replicates the functionality of Richard Sonnen <sonnen@richardsonnen.com> perl module :
|
19 | http://search.cpan.org/~sonnen/Data-Validate-URI-0.01/lib/Data/Validate/URI.pm [full code here](http://anonscm.debian.org/gitweb/?p=users/dom/libdata-validate-uri-perl.git)
|
20 | into a nodejs module. Translated practically line by line from perl.
|
21 | It passes all the original tests.
|
22 |
|
23 | ## Description
|
24 |
|
25 | (copied from original perl module)
|
26 |
|
27 | > This module collects common URI validation routines to make input validation, and untainting easier and more readable.
|
28 | > All functions return an untainted value if the test passes, and undef if it fails. This means that you should always check for a defined status explicitly. Don't assume the return will be true.
|
29 | > The value to test is always the first (and often only) argument.
|
30 | > There are a number of other URI validation modules out there as well (see below.) This one focuses on being fast, lightweight, and relatively 'real-world'. i.e. it's good if you want to check user input, and don't need to parse out the URI/URL into chunks.
|
31 | > Right now the module focuses on HTTP URIs, since they're arguably the most common. If you have a specialized scheme you'd like to have supported, let me know.
|
32 |
|
33 | ## Installation
|
34 |
|
35 | ```
|
36 | npm install valid-url
|
37 | ```
|
38 |
|
39 | ## Methods
|
40 | ```javascript
|
41 | /*
|
42 | * @Function isUri(value)
|
43 | *
|
44 | * @Synopsis is the value a well-formed uri?
|
45 | * @Description
|
46 | Returns the untainted URI if the test value appears to be well-formed. Note that
|
47 | you may really want one of the more practical methods like is_http_uri or is_https_uri,
|
48 | since the URI standard (RFC 3986) allows a lot of things you probably don't want.
|
49 | * @Arguments
|
50 | * value The potential URI to test.
|
51 | *
|
52 | * @Returns The untainted RFC 3986 URI on success, undefined on failure.
|
53 | * @Notes
|
54 | This function does not make any attempt to check whether the URI is accessible
|
55 | or 'makes sense' in any meaningful way. It just checks that it is formatted
|
56 | correctly.
|
57 | *
|
58 | */
|
59 |
|
60 |
|
61 | /*
|
62 | * @Function isHttpUri(value)
|
63 | * @Synopsis is the value a well-formed HTTP uri?
|
64 | * @Description
|
65 | Specialized version of isUri() that only likes http:// urls. As a result, it can
|
66 | also do a much more thorough job validating. Also, unlike isUri() it is more
|
67 | concerned with only allowing real-world URIs through. Things like relative
|
68 | hostnames are allowed by the standards, but probably aren't wise. Conversely,
|
69 | null paths aren't allowed per RFC 2616 (should be '/' instead), but are allowed
|
70 | by this function.
|
71 |
|
72 | This function only works for fully-qualified URIs. /bob.html won't work.
|
73 | See RFC 3986 for the appropriate method to turn a relative URI into an absolute
|
74 | one given its context.
|
75 |
|
76 | Returns the untainted URI if the test value appears to be well-formed.
|
77 |
|
78 | Note that you probably want to either call this in combo with is_https_uri(). i.e.
|
79 |
|
80 | if(isHttpUri(uri) || isHttpsUri(uri)) console.log('Good');
|
81 |
|
82 | or use the convenience method isWebUri which is equivalent.
|
83 |
|
84 | * @Arguments
|
85 | * value The potential URI to test.
|
86 | *
|
87 | * @Returns The untainted RFC 3986 URI on success, undefined on failure.
|
88 | * @Notes
|
89 | This function does not make any attempt to check whether the URI is accessible
|
90 | or 'makes sense' in any meaningful way. It just checks that it is formatted
|
91 | correctly.
|
92 | */
|
93 |
|
94 |
|
95 |
|
96 | /*
|
97 | * @Function isHttpsUri(value)
|
98 | * @Synopsis is the value a well-formed HTTPS uri?
|
99 | * @Description
|
100 | See is_http_uri() for details. This version only likes the https URI scheme.
|
101 | Otherwise it's identical to is_http_uri()
|
102 | * @Arguments
|
103 | * value The potential URI to test.
|
104 | *
|
105 | * @Returns The untainted RFC 3986 URI on success, undefined on failure.
|
106 | * @Notes
|
107 | This function does not make any attempt to check whether the URI is accessible
|
108 | or 'makes sense' in any meaningful way. It just checks that it is formatted
|
109 | correctly.
|
110 | */
|
111 |
|
112 |
|
113 | /*
|
114 | * @Function isWebUri(value)
|
115 | * @Synopsis is the value a well-formed HTTP or HTTPS uri?
|
116 | * @Description
|
117 | This is just a convenience method that combines isHttpUri and isHttpsUri
|
118 | to accept most common real-world URLs.
|
119 | * @Arguments
|
120 | * value The potential URI to test.
|
121 | *
|
122 | * @Returns The untainted RFC 3986 URI on success, undefined on failure.
|
123 | * @Notes
|
124 | This function does not make any attempt to check whether the URI is accessible
|
125 | or 'makes sense' in any meaningful way. It just checks that it is formatted
|
126 | correctly.
|
127 | */
|
128 |
|
129 | ```
|
130 |
|
131 | ## See also
|
132 |
|
133 | RFC 3986, RFC 3966, RFC 4694, RFC 4759, RFC 4904
|
134 |
|