1 | export type Options = {
|
2 | /**
|
3 | @default 'http'
|
4 | */
|
5 | readonly defaultProtocol?: 'https' | 'http';
|
6 |
|
7 | /**
|
8 | Prepends `defaultProtocol` to the URL if it's protocol-relative.
|
9 |
|
10 | @default true
|
11 |
|
12 | @example
|
13 | ```
|
14 | normalizeUrl('//sindresorhus.com');
|
15 | //=> 'http://sindresorhus.com'
|
16 |
|
17 | normalizeUrl('//sindresorhus.com', {normalizeProtocol: false});
|
18 | //=> '//sindresorhus.com'
|
19 | ```
|
20 | */
|
21 | readonly normalizeProtocol?: boolean;
|
22 |
|
23 | /**
|
24 | Normalizes HTTPS URLs to HTTP.
|
25 |
|
26 | @default false
|
27 |
|
28 | @example
|
29 | ```
|
30 | normalizeUrl('https://sindresorhus.com');
|
31 | //=> 'https://sindresorhus.com'
|
32 |
|
33 | normalizeUrl('https://sindresorhus.com', {forceHttp: true});
|
34 | //=> 'http://sindresorhus.com'
|
35 | ```
|
36 | */
|
37 | readonly forceHttp?: boolean;
|
38 |
|
39 | /**
|
40 | Normalizes HTTP URLs to HTTPS.
|
41 |
|
42 | This option cannot be used with the `forceHttp` option at the same time.
|
43 |
|
44 | @default false
|
45 |
|
46 | @example
|
47 | ```
|
48 | normalizeUrl('http://sindresorhus.com');
|
49 | //=> 'http://sindresorhus.com'
|
50 |
|
51 | normalizeUrl('http://sindresorhus.com', {forceHttps: true});
|
52 | //=> 'https://sindresorhus.com'
|
53 | ```
|
54 | */
|
55 | readonly forceHttps?: boolean;
|
56 |
|
57 | /**
|
58 | Strip the [authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) part of a URL.
|
59 |
|
60 | @default true
|
61 |
|
62 | @example
|
63 | ```
|
64 | normalizeUrl('https://user:password@sindresorhus.com');
|
65 | //=> 'https://sindresorhus.com'
|
66 |
|
67 | normalizeUrl('https://user:password@sindresorhus.com', {stripAuthentication: false});
|
68 | //=> 'https://user:password@sindresorhus.com'
|
69 | ```
|
70 | */
|
71 | readonly stripAuthentication?: boolean;
|
72 |
|
73 | /**
|
74 | Removes hash from the URL.
|
75 |
|
76 | @default false
|
77 |
|
78 | @example
|
79 | ```
|
80 | normalizeUrl('sindresorhus.com/about.html#contact');
|
81 | //=> 'http://sindresorhus.com/about.html#contact'
|
82 |
|
83 | normalizeUrl('sindresorhus.com/about.html#contact', {stripHash: true});
|
84 | //=> 'http://sindresorhus.com/about.html'
|
85 | ```
|
86 | */
|
87 | readonly stripHash?: boolean;
|
88 |
|
89 | /**
|
90 | Remove the protocol from the URL: `http://sindresorhus.com` → `sindresorhus.com`.
|
91 |
|
92 | It will only remove `https://` and `http://` protocols.
|
93 |
|
94 | @default false
|
95 |
|
96 | @example
|
97 | ```
|
98 | normalizeUrl('https://sindresorhus.com');
|
99 | //=> 'https://sindresorhus.com'
|
100 |
|
101 | normalizeUrl('sindresorhus.com', {stripProtocol: true});
|
102 | //=> 'sindresorhus.com'
|
103 | ```
|
104 | */
|
105 | readonly stripProtocol?: boolean;
|
106 |
|
107 | /**
|
108 | Strip the [text fragment](https://web.dev/text-fragments/) part of the URL
|
109 |
|
110 | __Note:__ The text fragment will always be removed if the `stripHash` option is set to `true`, as the hash contains the text fragment.
|
111 |
|
112 | @default true
|
113 |
|
114 | @example
|
115 | ```
|
116 | normalizeUrl('http://sindresorhus.com/about.html#:~:text=hello');
|
117 | //=> 'http://sindresorhus.com/about.html#'
|
118 |
|
119 | normalizeUrl('http://sindresorhus.com/about.html#section:~:text=hello');
|
120 | //=> 'http://sindresorhus.com/about.html#section'
|
121 |
|
122 | normalizeUrl('http://sindresorhus.com/about.html#:~:text=hello', {stripTextFragment: false});
|
123 | //=> 'http://sindresorhus.com/about.html#:~:text=hello'
|
124 |
|
125 | normalizeUrl('http://sindresorhus.com/about.html#section:~:text=hello', {stripTextFragment: false});
|
126 | //=> 'http://sindresorhus.com/about.html#section:~:text=hello'
|
127 | ```
|
128 | */
|
129 | readonly stripTextFragment?: boolean;
|
130 |
|
131 | /**
|
132 | Removes `www.` from the URL.
|
133 |
|
134 | @default true
|
135 |
|
136 | @example
|
137 | ```
|
138 | normalizeUrl('http://www.sindresorhus.com');
|
139 | //=> 'http://sindresorhus.com'
|
140 |
|
141 | normalizeUrl('http://www.sindresorhus.com', {stripWWW: false});
|
142 | //=> 'http://www.sindresorhus.com'
|
143 | ```
|
144 | */
|
145 | readonly stripWWW?: boolean;
|
146 |
|
147 | /**
|
148 | Removes query parameters that matches any of the provided strings or regexes.
|
149 |
|
150 | @default [/^utm_\w+/i]
|
151 |
|
152 | @example
|
153 | ```
|
154 | normalizeUrl('www.sindresorhus.com?foo=bar&ref=test_ref', {
|
155 | removeQueryParameters: ['ref']
|
156 | });
|
157 | //=> 'http://sindresorhus.com/?foo=bar'
|
158 | ```
|
159 |
|
160 | If a boolean is provided, `true` will remove all the query parameters.
|
161 |
|
162 | ```
|
163 | normalizeUrl('www.sindresorhus.com?foo=bar', {
|
164 | removeQueryParameters: true
|
165 | });
|
166 | //=> 'http://sindresorhus.com'
|
167 | ```
|
168 |
|
169 | `false` will not remove any query parameter.
|
170 |
|
171 | ```
|
172 | normalizeUrl('www.sindresorhus.com?foo=bar&utm_medium=test&ref=test_ref', {
|
173 | removeQueryParameters: false
|
174 | });
|
175 | //=> 'http://www.sindresorhus.com/?foo=bar&ref=test_ref&utm_medium=test'
|
176 | ```
|
177 | */
|
178 | readonly removeQueryParameters?: ReadonlyArray<RegExp | string> | boolean;
|
179 |
|
180 | /**
|
181 | Keeps only query parameters that matches any of the provided strings or regexes.
|
182 |
|
183 | __Note__: It overrides the `removeQueryParameters` option.
|
184 |
|
185 | @default undefined
|
186 |
|
187 | @example
|
188 | ```
|
189 | normalizeUrl('https://sindresorhus.com?foo=bar&ref=unicorn', {
|
190 | keepQueryParameters: ['ref']
|
191 | });
|
192 | //=> 'https://sindresorhus.com/?ref=unicorn'
|
193 | ```
|
194 | */
|
195 | readonly keepQueryParameters?: ReadonlyArray<RegExp | string>;
|
196 |
|
197 | /**
|
198 | Removes trailing slash.
|
199 |
|
200 | __Note__: Trailing slash is always removed if the URL doesn't have a pathname unless the `removeSingleSlash` option is set to `false`.
|
201 |
|
202 | @default true
|
203 |
|
204 | @example
|
205 | ```
|
206 | normalizeUrl('http://sindresorhus.com/redirect/');
|
207 | //=> 'http://sindresorhus.com/redirect'
|
208 |
|
209 | normalizeUrl('http://sindresorhus.com/redirect/', {removeTrailingSlash: false});
|
210 | //=> 'http://sindresorhus.com/redirect/'
|
211 |
|
212 | normalizeUrl('http://sindresorhus.com/', {removeTrailingSlash: false});
|
213 | //=> 'http://sindresorhus.com'
|
214 | ```
|
215 | */
|
216 | readonly removeTrailingSlash?: boolean;
|
217 |
|
218 | /**
|
219 | Remove a sole `/` pathname in the output. This option is independent of `removeTrailingSlash`.
|
220 |
|
221 | @default true
|
222 |
|
223 | @example
|
224 | ```
|
225 | normalizeUrl('https://sindresorhus.com/');
|
226 | //=> 'https://sindresorhus.com'
|
227 |
|
228 | normalizeUrl('https://sindresorhus.com/', {removeSingleSlash: false});
|
229 | //=> 'https://sindresorhus.com/'
|
230 | ```
|
231 | */
|
232 | readonly removeSingleSlash?: boolean;
|
233 |
|
234 | /**
|
235 | Removes the default directory index file from path that matches any of the provided strings or regexes.
|
236 | When `true`, the regex `/^index\.[a-z]+$/` is used.
|
237 |
|
238 | @default false
|
239 |
|
240 | @example
|
241 | ```
|
242 | normalizeUrl('www.sindresorhus.com/foo/default.php', {
|
243 | removeDirectoryIndex: [/^default\.[a-z]+$/]
|
244 | });
|
245 | //=> 'http://sindresorhus.com/foo'
|
246 | ```
|
247 | */
|
248 | readonly removeDirectoryIndex?: boolean | ReadonlyArray<RegExp | string>;
|
249 |
|
250 | /**
|
251 | Removes an explicit port number from the URL.
|
252 |
|
253 | Port 443 is always removed from HTTPS URLs and 80 is always removed from HTTP URLs regardless of this option.
|
254 |
|
255 | @default false
|
256 |
|
257 | @example
|
258 | ```
|
259 | normalizeUrl('sindresorhus.com:123', {
|
260 | removeExplicitPort: true
|
261 | });
|
262 | //=> 'http://sindresorhus.com'
|
263 | ```
|
264 | */
|
265 | readonly removeExplicitPort?: boolean;
|
266 |
|
267 | /**
|
268 | Sorts the query parameters alphabetically by key.
|
269 |
|
270 | @default true
|
271 |
|
272 | @example
|
273 | ```
|
274 | normalizeUrl('www.sindresorhus.com?b=two&a=one&c=three', {
|
275 | sortQueryParameters: false
|
276 | });
|
277 | //=> 'http://sindresorhus.com/?b=two&a=one&c=three'
|
278 | ```
|
279 | */
|
280 | readonly sortQueryParameters?: boolean;
|
281 | };
|
282 |
|
283 | /**
|
284 | [Normalize](https://en.wikipedia.org/wiki/URL_normalization) a URL.
|
285 |
|
286 | URLs with custom protocols are not normalized and just passed through by default. Supported protocols are: `https`, `http`, `file`, and `data`.
|
287 |
|
288 | Human-friendly URLs with basic auth (for example, `user:password@sindresorhus.com`) are not handled because basic auth conflicts with custom protocols. [Basic auth URLs are also deprecated.](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#access_using_credentials_in_the_url)
|
289 |
|
290 | @param url - URL to normalize, including [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs).
|
291 |
|
292 | @example
|
293 | ```
|
294 | import normalizeUrl from 'normalize-url';
|
295 |
|
296 | normalizeUrl('sindresorhus.com');
|
297 | //=> 'http://sindresorhus.com'
|
298 |
|
299 | normalizeUrl('//www.sindresorhus.com:80/../baz?b=bar&a=foo');
|
300 | //=> 'http://sindresorhus.com/baz?a=foo&b=bar'
|
301 | ```
|
302 | */
|
303 | export default function normalizeUrl(url: string, options?: Options): string;
|