0
# URL Polyfill
1

2
URL Polyfill provides polyfill implementations for the `URL` and `URLSearchParams` web APIs to ensure compatibility with older browsers that don't support these standards. It implements the WHATWG URL specification to provide consistent URL parsing and manipulation capabilities across different browser environments, specifically tested on IE 10+.
3

4
## Package Information
5

6
- **Package Name**: url-polyfill
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install url-polyfill --save`
10

11
## Core Imports
12

13
Include the polyfill script to automatically add support for URL and URLSearchParams:
14

15
```html
16
<script src="node_modules/url-polyfill/url-polyfill.js"></script>
17
```
18

19
Or in Node.js:
20

21
```javascript
22
require('url-polyfill');
23
```
24

25
The polyfill automatically detects missing or incomplete URL/URLSearchParams support and adds the functionality to the global scope.
26

27
## Basic Usage
28

29
```javascript
30
// URL API usage
31
const url = new URL('https://www.example.com:8080/?fr=yset_ie_syc_oracle&type=orcl_hpset#page0');
32

33
console.log(url.hash);       // "#page0"
34
console.log(url.host);       // "www.example.com:8080"
35
console.log(url.hostname);   // "www.example.com"
36
console.log(url.href);       // "https://www.example.com:8080/?fr=yset_ie_syc_oracle&type=orcl_hpset#page0"
37
console.log(url.origin);     // "https://www.example.com:8080"
38
console.log(url.pathname);   // "/"
39
console.log(url.port);       // "8080"
40
console.log(url.protocol);   // "https:"
41
console.log(url.search);     // "?fr=yset_ie_syc_oracle&type=orcl_hpset"
42

43
// URLSearchParams API usage
44
url.searchParams.append('page', 0);
45
console.log(url.toString()); // "https://www.example.com:8080/?fr=yset_ie_syc_oracle&type=orcl_hpset&page=0#page0"
46

47
// Standalone URLSearchParams usage
48
const params = new URLSearchParams('a=1&b=2&a=3');
49
console.log(params.get('a'));    // "1"
50
console.log(params.getAll('a')); // ["1", "3"]
51
console.log(params.has('b'));    // true
52
params.set('c', '4');
53
console.log(params.toString());  // "a=1&b=2&a=3&c=4"
54
```
55

56
## Capabilities
57

58
### URL Constructor
59

60
Creates a new URL instance for parsing and manipulating URLs.
61

62
```javascript { .api }
63
/**
64
 * Creates a new URL object
65
 * @param {string} url - The URL string to parse
66
 * @param {string} [base] - Base URL for relative URLs
67
 * @throws {TypeError} When URL is invalid
68
 */
69
new URL(url, base);
70
```
71

72
### URL Instance Properties
73

74
Properties for accessing and modifying URL components.
75

76
```javascript { .api }
77
/**
78
 * Gets/sets the fragment identifier including the '#'
79
 * @type {string}
80
 */
81
url.hash;
82

83
/**
84
 * Gets/sets the host (hostname + port)
85
 * @type {string}
86
 */
87
url.host;
88

89
/**
90
 * Gets/sets the hostname without port
91
 * @type {string}
92
 */
93
url.hostname;
94

95
/**
96
 * Gets/sets the complete URL string
97
 * @type {string}
98
 */
99
url.href;
100

101
/**
102
 * Gets the origin (protocol + hostname + port) - read-only
103
 * @type {string}
104
 */
105
url.origin;
106

107
/**
108
 * Gets/sets the path portion of the URL
109
 * @type {string}
110
 */
111
url.pathname;
112

113
/**
114
 * Gets/sets the port number
115
 * @type {string}
116
 */
117
url.port;
118

119
/**
120
 * Gets/sets the protocol scheme including ':'
121
 * @type {string}
122
 */
123
url.protocol;
124

125
/**
126
 * Gets/sets the query string including '?'
127
 * @type {string}
128
 */
129
url.search;
130

131
/**
132
 * Gets URLSearchParams object linked to the URL's query string - read-only
133
 * @type {URLSearchParams}
134
 */
135
url.searchParams;
136

137
/**
138
 * Gets/sets the username (not fully implemented - always returns empty string)
139
 * @type {string}
140
 */
141
url.username;
142

143
/**
144
 * Gets/sets the password (not fully implemented - always returns empty string)
145
 * @type {string}
146
 */
147
url.password;
148
```
149

150
### URL Instance Methods
151

152
Methods for URL string conversion and manipulation.
153

154
```javascript { .api }
155
/**
156
 * Returns the complete URL as a string
157
 * @returns {string} The complete URL
158
 */
159
url.toString();
160
```
161

162
### URL Static Methods
163

164
Static utility methods for blob URL management.
165

166
```javascript { .api }
167
/**
168
 * Creates an object URL for a blob (delegates to native implementation)
169
 * @param {Blob} blob - The blob object
170
 * @returns {string} Object URL string
171
 */
172
URL.createObjectURL(blob);
173

174
/**
175
 * Revokes an object URL (delegates to native implementation)  
176
 * @param {string} url - Object URL string to revoke
177
 * @returns {void}
178
 */
179
URL.revokeObjectURL(url);
180
```
181

182
### URLSearchParams Constructor
183

184
Creates a new URLSearchParams instance for working with URL search parameters.
185

186
```javascript { .api }
187
/**
188
 * Creates a new URLSearchParams object
189
 * @param {string|URLSearchParams|Array|Object} [init] - Initial search parameters
190
 * @throws {TypeError} When input type is unsupported
191
 */
192
new URLSearchParams(init);
193
```
194

195
**Constructor Examples:**
196

197
```javascript
198
// From string
199
const params1 = new URLSearchParams('a=1&b=2&a=3');
200

201
// From another URLSearchParams instance
202
const params2 = new URLSearchParams(params1);
203

204
// From array of key-value pairs
205
const params3 = new URLSearchParams([['a', '1'], ['b', '2'], ['a', '3']]);
206

207
// From object
208
const params4 = new URLSearchParams({ a: '1', b: '2' });
209

210
// Empty
211
const params5 = new URLSearchParams();
212
```
213

214
### URLSearchParams Instance Methods
215

216
Methods for manipulating search parameters.
217

218
```javascript { .api }
219
/**
220
 * Appends a key/value pair to the search parameters
221
 * @param {string} name - Parameter name
222
 * @param {string} value - Parameter value
223
 * @returns {void}
224
 */
225
searchParams.append(name, value);
226

227
/**
228
 * Deletes all entries with the given name
229
 * @param {string} name - Parameter name to delete
230
 * @returns {void}
231
 */
232
searchParams.delete(name);
233

234
/**
235
 * Gets the first value associated with the given name
236
 * @param {string} name - Parameter name
237
 * @returns {string|null} The first value or null if not found
238
 */
239
searchParams.get(name);
240

241
/**
242
 * Gets all values associated with the given name
243
 * @param {string} name - Parameter name
244
 * @returns {Array<string>} Array of all values
245
 */
246
searchParams.getAll(name);
247

248
/**
249
 * Checks if a parameter with the given name exists
250
 * @param {string} name - Parameter name
251
 * @returns {boolean} True if parameter exists
252
 */
253
searchParams.has(name);
254

255
/**
256
 * Sets the value for the given name, replacing any existing values
257
 * @param {string} name - Parameter name
258
 * @param {string} value - Parameter value
259
 * @returns {void}
260
 */
261
searchParams.set(name, value);
262

263
/**
264
 * Sorts all parameters by name
265
 * @returns {void}
266
 */
267
searchParams.sort();
268

269
/**
270
 * Returns the search parameters as a URL-encoded string
271
 * @returns {string} URL-encoded parameter string
272
 */
273
searchParams.toString();
274

275
/**
276
 * Executes callback for each parameter
277
 * @param {function} callback - Function called for each parameter (value, name, searchParams)
278
 * @param {any} [thisArg] - Value to use as 'this' when executing callback
279
 * @returns {void}
280
 */
281
searchParams.forEach(callback, thisArg);
282

283
/**
284
 * Returns an iterator for parameter names
285
 * @returns {Iterator<string>} Iterator for names
286
 */
287
searchParams.keys();
288

289
/**
290
 * Returns an iterator for parameter values
291
 * @returns {Iterator<string>} Iterator for values
292
 */
293
searchParams.values();
294

295
/**
296
 * Returns an iterator for [name, value] pairs
297
 * @returns {Iterator<Array<string>>} Iterator for key-value pairs
298
 */
299
searchParams.entries();
300
```
301

302
### URLSearchParams Iterator Support
303

304
When Symbol.iterator is supported, URLSearchParams provides iteration capability.
305

306
```javascript { .api }
307
/**
308
 * Returns an iterator for [name, value] pairs (same as entries())
309
 * Available when Symbol.iterator is supported
310
 * @returns {Iterator<Array<string>>} Iterator for key-value pairs
311
 */
312
searchParams[Symbol.iterator]();
313
```
314

315
**Iterator Usage Examples:**
316

317
```javascript
318
const params = new URLSearchParams('a=1&b=2&a=3');
319

320
// Using for...of (when Symbol.iterator is supported)
321
for (const [name, value] of params) {
322
  console.log(name, value);
323
}
324

325
// Using entries() explicitly
326
for (const [name, value] of params.entries()) {
327
  console.log(name, value);
328
}
329

330
// Using keys()
331
for (const name of params.keys()) {
332
  console.log(name);
333
}
334

335
// Using values()
336
for (const value of params.values()) {
337
  console.log(value);
338
}
339
```
340

341
### URLSearchParams Instance Properties
342

343
Properties providing information about the search parameters.
344

345
```javascript { .api }
346
/**
347
 * Gets the number of parameter names - read-only
348
 * @type {number}
349
 */
350
searchParams.size;
351
```
352

353
## Error Handling
354

355
The polyfill throws standard web API errors:
356

357
- **TypeError**: Thrown for invalid URLs in URL constructor
358
- **TypeError**: Thrown for unsupported URLSearchParams input types
359
- **Error**: Thrown for invalid base URLs
360

361
**Error Examples:**
362

363
```javascript
364
try {
365
  const url = new URL('invalid-url');
366
} catch (error) {
367
  console.log(error instanceof TypeError); // true
368
}
369

370
try {
371
  const params = new URLSearchParams(123); // Unsupported type
372
} catch (error) {
373
  console.log(error instanceof TypeError); // true
374
}
375
```
376

377
## Special Behavior
378

379
### Parameter Encoding
380

381
The polyfill follows WHATWG URL specification for parameter encoding:
382

383
- Spaces are encoded as `+` in search parameters
384
- Special characters are properly percent-encoded
385
- Decoding handles both `+` and `%20` for spaces
386

387
```javascript
388
const params = new URLSearchParams();
389
params.append('query', 'hello world');
390
console.log(params.toString()); // "query=hello+world"
391

392
const decoded = new URLSearchParams('query=hello+world');
393
console.log(decoded.get('query')); // "hello world"
394

395
const encoded = new URLSearchParams('query=hello%20world');
396
console.log(encoded.get('query')); // "hello world"
397
```
398

399
### Conditional Polyfilling
400

401
The library only applies polyfills when native implementations are missing or incomplete:
402

403
- Tests for proper URL support with searchParams integration
404
- Tests for complete URLSearchParams functionality
405
- Preserves native implementations when they work correctly
406

407
### Legacy Browser Support
408

409
Designed specifically for IE 10+ and other legacy browsers:
410

411
- Handles missing Symbol.iterator gracefully
412
- Provides fallback iterator implementations
413
- Uses DOM elements for URL parsing in older browsers
414

415
### Global Location Enhancement
416

417
The polyfill also enhances the global `location` object:
418

419
- Adds `origin` property to `location` when missing
420
- Provides proper origin calculation for legacy browsers