0
# URL Parsing & Stringification
1

2
Complete URL parsing functionality that breaks down URLs into structured components and reconstructs them back to strings. Handles various URL formats, protocols, and edge cases including special protocols, authentication, and international domains.
3

4
## Capabilities
5

6
### Parse URL
7

8
Parses a complete URL string into structured components.
9

10
```typescript { .api }
11
/**
12
 * Takes a URL string and returns an object with the URL's components
13
 * @param input - The URL string to parse
14
 * @param defaultProto - Default protocol to use if input doesn't have one
15
 * @returns Parsed URL object with protocol, host, auth, pathname, search, hash
16
 */
17
function parseURL(input?: string, defaultProto?: string): ParsedURL;
18

19
interface ParsedURL {
20
  protocol?: string;
21
  host?: string;
22
  auth?: string;
23
  href?: string;
24
  pathname: string;
25
  hash: string;
26
  search: string;
27
  [protocolRelative]?: boolean;
28
}
29
```
30

31
**Usage Examples:**
32

33
```typescript
34
import { parseURL } from "ufo";
35

36
// Parse complete URL
37
const parsed = parseURL("http://foo.com/foo?test=123#token");
38
// { protocol: 'http:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }
39

40
// Parse URL without protocol
41
const pathOnly = parseURL("foo.com/foo?test=123#token");
42
// { pathname: 'foo.com/foo', search: '?test=123', hash: '#token' }
43

44
// Parse with default protocol
45
const withDefault = parseURL("foo.com/foo?test=123#token", "https://");
46
// { protocol: 'https:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }
47

48
// Special protocols
49
const blob = parseURL("blob:data-content");
50
// { protocol: 'blob:', pathname: 'data-content', href: 'blob:data-content', auth: '', host: '', search: '', hash: '' }
51
```
52

53
### Parse Path
54

55
Splits a path string into pathname, search, and hash components.
56

57
```typescript { .api }
58
/**
59
 * Splits the input string into pathname, search, and hash parts
60
 * @param input - The path string to parse
61
 * @returns Object with pathname, search, and hash properties
62
 */
63
function parsePath(input?: string): ParsedURL;
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
import { parsePath } from "ufo";
70

71
const pathParts = parsePath("/users/123?active=true#profile");
72
// { pathname: '/users/123', search: '?active=true', hash: '#profile' }
73

74
const simple = parsePath("/api/data");
75
// { pathname: '/api/data', search: '', hash: '' }
76
```
77

78
### Parse Authentication
79

80
Parses authentication string into username and password components.
81

82
```typescript { .api }
83
/**
84
 * Parses a string of the form 'username:password' into components
85
 * @param input - Authentication string to parse
86
 * @returns Object with decoded username and password
87
 */
88
function parseAuth(input?: string): ParsedAuth;
89

90
interface ParsedAuth {
91
  username: string;
92
  password: string;
93
}
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
import { parseAuth } from "ufo";
100

101
const auth = parseAuth("john:secret123");
102
// { username: 'john', password: 'secret123' }
103

104
const encoded = parseAuth("user%40domain:pass%20word");
105
// { username: 'user@domain', password: 'pass word' }
106
```
107

108
### Parse Host
109

110
Extracts hostname and port from a host string.
111

112
```typescript { .api }
113
/**
114
 * Parses a host string into hostname and port components
115
 * @param input - Host string to parse
116
 * @returns Object with decoded hostname and port
117
 */
118
function parseHost(input?: string): ParsedHost;
119

120
interface ParsedHost {
121
  hostname: string;
122
  port: string;
123
}
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
import { parseHost } from "ufo";
130

131
const host = parseHost("example.com:8080");
132
// { hostname: 'example.com', port: '8080' }
133

134
const hostOnly = parseHost("api.example.com");
135
// { hostname: 'api.example.com', port: undefined }
136

137
const encoded = parseHost("xn--e1afmkfd.xn--p1ai:3000");
138
// { hostname: 'пример.рф', port: '3000' }
139
```
140

141
### Stringify Parsed URL
142

143
Converts a ParsedURL object back into a URL string.
144

145
```typescript { .api }
146
/**
147
 * Takes a ParsedURL object and returns the stringified URL
148
 * @param parsed - Parsed URL object to stringify
149
 * @returns Complete URL string
150
 */
151
function stringifyParsedURL(parsed: Partial<ParsedURL>): string;
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
import { parseURL, stringifyParsedURL } from "ufo";
158

159
const parsed = parseURL("http://foo.com/foo?test=123#token");
160
parsed.host = "bar.com";
161
parsed.pathname = "/updated";
162

163
const newUrl = stringifyParsedURL(parsed);
164
// "http://bar.com/updated?test=123#token"
165

166
// Build URL from parts
167
const custom = stringifyParsedURL({
168
  protocol: "https:",
169
  host: "api.example.com",
170
  pathname: "/v1/users",
171
  search: "?limit=10",
172
  hash: "#results"
173
});
174
// "https://api.example.com/v1/users?limit=10#results"
175
```
176

177
### Parse Filename
178

179
Extracts filename from URL path with optional strict mode.
180

181
```typescript { .api }
182
/**
183
 * Parses a URL and returns last segment in path as filename
184
 * @param input - URL string to parse
185
 * @param opts - Options including strict mode for extension requirement
186
 * @returns Filename string or undefined if not found
187
 */
188
function parseFilename(input?: string, opts?: { strict?: boolean }): string | undefined;
189
```
190

191
**Usage Examples:**
192

193
```typescript
194
import { parseFilename } from "ufo";
195

196
// Extract filename with extension
197
const filename = parseFilename("http://example.com/path/to/document.pdf");
198
// "document.pdf"
199

200
// Extract last segment (non-strict)
201
const segment = parseFilename("/api/users/profile");
202
// "profile"
203

204
// Strict mode requires extension
205
const strict = parseFilename("/path/to/.hidden-file", { strict: true });
206
// undefined
207

208
const strictValid = parseFilename("/path/to/image.jpg", { strict: true });
209
// "image.jpg"
210
```