0
# Parse URL
1
2
Parse URL is an advanced URL parser supporting both standard URLs and Git URLs. It provides comprehensive URL parsing capabilities beyond the native URL API, with special handling for Git repository URLs commonly used in development workflows.
3
4
## Package Information
5
6
- **Package Name**: parse-url
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install parse-url`
10
- **Module Support**: Dual CommonJS and ES modules support
11
12
## Core Imports
13
14
```typescript
15
import parseUrl from "parse-url";
16
```
17
18
For CommonJS:
19
20
```javascript
21
const parseUrl = require("parse-url");
22
```
23
24
## Basic Usage
25
26
```typescript
27
import parseUrl from "parse-url";
28
29
// Parse a standard HTTP URL
30
const httpUrl = parseUrl("http://ionicabizau.net/blog");
31
console.log(httpUrl);
32
// {
33
// protocols: ["http"],
34
// protocol: "http",
35
// port: "",
36
// resource: "ionicabizau.net",
37
// host: "ionicabizau.net",
38
// user: "",
39
// password: "",
40
// pathname: "/blog",
41
// hash: "",
42
// search: "",
43
// href: "http://ionicabizau.net/blog",
44
// query: {},
45
// parse_failed: false
46
// }
47
48
// Parse a Git SSH URL
49
const gitUrl = parseUrl("git@github.com:IonicaBizau/parse-url.git");
50
console.log(gitUrl);
51
// {
52
// protocols: ["ssh"],
53
// protocol: "ssh",
54
// port: "",
55
// resource: "github.com",
56
// host: "github.com",
57
// user: "git",
58
// password: "",
59
// pathname: "/IonicaBizau/parse-url.git",
60
// hash: "",
61
// search: "",
62
// href: "git@github.com:IonicaBizau/parse-url.git",
63
// query: {},
64
// parse_failed: false
65
// }
66
67
// Parse with URL normalization
68
const normalizedUrl = parseUrl("http://example.com//path", true);
69
```
70
71
## Capabilities
72
73
### URL Parsing
74
75
Parses input URLs and returns detailed information about their components with special handling for Git URLs.
76
77
```typescript { .api }
78
/**
79
* Parses the input url and returns detailed component information
80
* @param url - The input URL to parse
81
* @param normalize - Whether to normalize the URL. If true, normalizes using default options. If object, uses as normalize-url options
82
* @returns Parsed URL object with detailed component information
83
* @throws ParsingError if URL is invalid or parsing fails
84
*/
85
function parseUrl(url: string, normalize?: boolean | NormalizeOptions): ParsedUrl;
86
87
interface ParsedUrl {
88
/** Array of URL protocols (usually contains one element) */
89
protocols: string[];
90
/** The first protocol, "ssh" for SSH URLs, or "file" for file URLs */
91
protocol: string;
92
/** The domain port as a string */
93
port: string;
94
/** The URL domain including subdomains */
95
resource: string;
96
/** The fully qualified domain name or IP address */
97
host: string;
98
/** The authentication user (typically for SSH URLs) */
99
user: string;
100
/** The authentication password */
101
password: string;
102
/** The URL pathname */
103
pathname: string;
104
/** The URL hash fragment */
105
hash: string;
106
/** The URL query string value */
107
search: string;
108
/** The original input URL */
109
href: string;
110
/** The URL query string parsed as an object */
111
query: Record<string, any>;
112
/** Whether the URL parsing failed */
113
parse_failed: boolean;
114
}
115
116
/**
117
* Normalization options from the normalize-url package
118
* See normalize-url documentation for complete options
119
*/
120
type NormalizeOptions = {
121
/** Whether to strip the hash fragment during normalization */
122
stripHash?: boolean;
123
/** Additional normalize-url package options */
124
[key: string]: any;
125
};
126
127
interface ParsingError extends Error {
128
/** The URL that failed to parse */
129
readonly subject_url: string;
130
}
131
```
132
133
### Maximum Input Length Constant
134
135
Maximum allowed length for input URLs to prevent performance issues with extremely long URLs.
136
137
```typescript { .api }
138
/** Maximum allowed input URL length (2048 characters) */
139
const MAX_INPUT_LENGTH: 2048;
140
```
141
142
## URL Format Support
143
144
Parse URL supports various URL formats:
145
146
- **HTTP/HTTPS URLs**: `http://domain.com/path`, `https://example.com/api`
147
- **Protocol-relative URLs**: `//domain.com/path`
148
- **Git SSH URLs**: `git@github.com:user/repo.git`
149
- **Git+SSH URLs**: `git+ssh://git@host.xz/path/name.git`
150
- **File URLs**: `file:///path/to/file`
151
- **URLs with query strings**: `http://domain.com/path?foo=bar&baz=42`
152
- **URLs with hash fragments**: `http://domain.com/path#section`
153
154
## Special Features
155
156
### Git URL Parsing
157
Parse URL includes specialized logic for handling Git repository URLs that don't follow standard URL format:
158
159
```typescript
160
// SSH-style Git URLs are automatically detected and parsed
161
const gitSshUrl = parseUrl("git@github.com:user/repo.git");
162
// Returns protocol: "ssh", user: "git", resource: "github.com"
163
164
// Git+SSH URLs with full protocol
165
const gitPlusSchUrl = parseUrl("git+ssh://git@host.xz/path/name.git");
166
// Returns protocols: ["git", "ssh"], protocol: "git"
167
```
168
169
### URL Normalization
170
Optional URL normalization using the `normalize-url` package:
171
172
```typescript
173
// Basic normalization
174
parseUrl("HTTP://EXAMPLE.COM//path", true);
175
176
// Custom normalization options
177
parseUrl("http://example.com/path#hash", {
178
stripHash: false,
179
stripWWW: true
180
});
181
```
182
183
### Error Handling
184
The function throws `ParsingError` in these cases:
185
186
```typescript
187
try {
188
parseUrl(""); // Empty URL
189
} catch (error: ParsingError) {
190
console.log(error.subject_url); // The URL that failed
191
}
192
193
try {
194
parseUrl("a".repeat(3000)); // URL too long
195
} catch (error: ParsingError) {
196
console.log("URL exceeds maximum length");
197
}
198
199
try {
200
parseUrl("invalid-url-format"); // Unparseable URL
201
} catch (error: ParsingError) {
202
console.log("URL parsing failed");
203
}
204
```
205
206
## Type Information
207
208
The parse-url package uses TypeScript definitions that reference types from its dependencies:
209
210
- **ParsedUrl**: The return type comes from the `parse-path` package
211
- **NormalizeOptions**: The normalization options come from the `normalize-url` package
212
- **ParsingError**: A custom error type with the `subject_url` property
213
214
These types are automatically available when using TypeScript with proper type inference from the function signatures above.