0
# is-absolute-url
1

2
Check if a URL is absolute. A lightweight utility function that determines whether a given URL string contains a protocol scheme, following RFC 3986 standards with special handling for Windows file path edge cases.
3

4
## Package Information
5

6
- **Package Name**: is-absolute-url
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install is-absolute-url`
10

11
## Core Imports
12

13
```javascript
14
import isAbsoluteUrl from 'is-absolute-url';
15
```
16

17
This package is ES module only and does not support CommonJS `require()`.
18

19
## Basic Usage
20

21
```javascript
22
import isAbsoluteUrl from 'is-absolute-url';
23

24
// Absolute URLs (contain protocol scheme)
25
isAbsoluteUrl('https://sindresorhus.com/foo/bar');
26
//=> true
27

28
isAbsoluteUrl('http://example.com');
29
//=> true
30

31
isAbsoluteUrl('file://path/to/file');
32
//=> true
33

34
isAbsoluteUrl('mailto:someone@example.com');
35
//=> true
36

37
isAbsoluteUrl('data:text/plain;base64,SGVsbG8sIFdvcmxkIQ%3D%3D');
38
//=> true
39

40
// Case insensitive scheme matching
41
isAbsoluteUrl('httpS://example.com');
42
//=> true
43

44
// Relative URLs (no protocol scheme)
45
isAbsoluteUrl('//sindresorhus.com');
46
//=> false
47

48
isAbsoluteUrl('/foo/bar');
49
//=> false
50

51
isAbsoluteUrl('foo/bar');
52
//=> false
53

54
// Windows paths are handled as non-absolute
55
isAbsoluteUrl('c:\\Windows\\System32');
56
//=> false
57

58
// Invalid scheme characters
59
isAbsoluteUrl('ht,tp://example.com');
60
//=> false
61
```
62

63
## Capabilities
64

65
### URL Validation
66

67
Determines if a URL string is absolute by checking for a valid protocol scheme.
68

69
```javascript { .api }
70
/**
71
 * Check if a URL is absolute
72
 * @param {string} url - The URL string to check
73
 * @returns {boolean} true if the URL is absolute, false otherwise
74
 * @throws {TypeError} if url parameter is not a string
75
 */
76
export default function isAbsoluteUrl(url) {}
77
```
78

79
**Parameters:**
80
- `url` (string): The URL string to validate
81

82
**Returns:**
83
- `boolean`: `true` if the URL contains a valid protocol scheme, `false` otherwise
84

85
**Throws:**
86
- `TypeError`: If the `url` parameter is not a string
87

88
**Implementation Details:**
89
- Uses RFC 3986 compliant regex pattern for scheme validation
90
- Scheme must start with a letter followed by letters, digits, `+`, `-`, or `.`
91
- Explicitly rejects Windows file paths (e.g., `c:\`) to avoid false positives
92
- Case-insensitive scheme matching
93

94
**Supported URL Schemes:**
95
All RFC 3986 compliant schemes are supported, including but not limited to:
96
- `http://` and `https://`
97
- `file://`
98
- `mailto:`
99
- `data:`
100
- `ftp://`
101
- `ldap://`
102
- Custom schemes following the RFC pattern
103

104
**Edge Cases:**
105
- Protocol-relative URLs (`//example.com`) return `false`
106
- Windows file paths (`c:\`, `C:\Dev\`) return `false`
107
- Invalid scheme characters (`ht,tp://`) return `false`
108
- Empty strings return `false`
109

110
## Error Handling
111

112
The function validates input types and throws a descriptive error for non-string inputs:
113

114
```javascript
115
try {
116
  isAbsoluteUrl(123);
117
} catch (error) {
118
  console.log(error.message);
119
  // "Expected a `string`, got `number`"
120
}
121
```