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.