0
# URL Class (Deprecated)
1

2
Legacy URL class implementation provided for backward compatibility. **This class is deprecated** - new projects should use the native URL constructor or the functional parseURL API for better performance and standards compliance.
3

4
## Capabilities
5

6
### $URL Class
7

8
Object-oriented URL manipulation class with automatic parsing and property access.
9

10
```typescript { .api }
11
/**
12
 * @deprecated Use native URL with `new URL(input)` or `ufo.parseURL(input)`
13
 */
14
class $URL implements URL {
15
  protocol: string;
16
  host: string;
17
  auth: string;
18
  pathname: string;
19
  query: QueryObject;
20
  hash: string;
21

22
  /**
23
   * Creates a new $URL instance from a URL string
24
   * @param input - URL string to parse (defaults to empty string)
25
   * @throws TypeError if input is not a string
26
   */
27
  constructor(input?: string);
28

29
  // Computed properties
30
  readonly hostname: string;
31
  readonly port: string;
32
  readonly username: string;
33
  readonly password: string;
34
  readonly hasProtocol: boolean;
35
  readonly isAbsolute: boolean;
36
  readonly search: string;
37
  readonly searchParams: URLSearchParams;
38
  readonly origin: string;
39
  readonly fullpath: string;
40
  readonly encodedAuth: string;
41
  readonly href: string;
42

43
  /**
44
   * Appends another $URL to this one
45
   * @param url - $URL instance to append
46
   * @throws Error if the URL to append has a protocol
47
   */
48
  append(url: $URL): void;
49

50
  /**
51
   * Returns the URL as a JSON string
52
   * @returns URL string
53
   */
54
  toJSON(): string;
55

56
  /**
57
   * Returns the URL as a string
58
   * @returns URL string
59
   */
60
  toString(): string;
61
}
62

63
type QueryObject = Record<string, QueryValue | QueryValue[]>;
64
type QueryValue = string | number | undefined | null | boolean | Array<QueryValue> | Record<string, any>;
65
```
66

67
### Create URL Function
68

69
Factory function for creating $URL instances.
70

71
```typescript { .api }
72
/**
73
 * @deprecated Use native URL with `new URL(input)` or `ufo.parseURL(input)`
74
 */
75
function createURL(input: string): $URL;
76
```
77

78
## Usage Examples
79

80
⚠️ **Warning**: These examples show deprecated functionality. Use native URL or parseURL instead.
81

82
```typescript
83
import { $URL, createURL } from "ufo";
84

85
// Creating URL instances (DEPRECATED)
86
const url = new $URL("https://user:pass@example.com:8080/path?foo=bar#section");
87

88
// Accessing properties
89
console.log(url.protocol);   // "https:"
90
console.log(url.hostname);   // "example.com"
91
console.log(url.port);       // "8080"
92
console.log(url.username);   // "user"
93
console.log(url.password);   // "pass"
94
console.log(url.pathname);   // "/path"
95
console.log(url.search);     // "?foo=bar"
96
console.log(url.hash);       // "#section"
97

98
// Query object access
99
console.log(url.query);      // { foo: "bar" }
100
url.query.newParam = "value";
101
console.log(url.search);     // "?foo=bar&newParam=value"
102

103
// Computed properties
104
console.log(url.origin);     // "https://example.com:8080"
105
console.log(url.href);       // "https://user:pass@example.com:8080/path?foo=bar&newParam=value#section"
106
console.log(url.isAbsolute); // true
107
console.log(url.hasProtocol);// true
108

109
// URL manipulation
110
const base = new $URL("https://api.example.com/v1/");
111
const path = new $URL("users/123?active=true");
112
base.append(path);
113
console.log(base.href); // "https://api.example.com/v1/users/123?active=true"
114

115
// Factory function (DEPRECATED)
116
const url2 = createURL("https://example.com/path");
117
console.log(url2.pathname); // "/path"
118
```
119

120
## Modern Alternatives
121

122
Instead of using the deprecated $URL class, use these modern approaches:
123

124
### Native URL (Recommended)
125

126
```typescript
127
// Modern approach using native URL
128
const url = new URL("https://example.com/path?foo=bar#section");
129

130
console.log(url.protocol);   // "https:"
131
console.log(url.hostname);   // "example.com"
132
console.log(url.pathname);   // "/path"
133
console.log(url.search);     // "?foo=bar"
134
console.log(url.hash);       // "#section"
135

136
// Modify query parameters
137
url.searchParams.set("newParam", "value");
138
console.log(url.href); // "https://example.com/path?foo=bar&newParam=value#section"
139
```
140

141
### UFO Functional API (Recommended)
142

143
```typescript
144
import { parseURL, stringifyParsedURL, withQuery } from "ufo";
145

146
// Parse URL functionally
147
const parsed = parseURL("https://example.com/path?foo=bar#section");
148
console.log(parsed.protocol);  // "https:"
149
console.log(parsed.hostname);  // "example.com" (need to use parseHost)
150
console.log(parsed.pathname);  // "/path"
151

152
// Modify and reconstruct
153
const modified = {
154
  ...parsed,
155
  pathname: "/newpath"
156
};
157
const newUrl = stringifyParsedURL(modified);
158

159
// Add query parameters functionally
160
const withParams = withQuery("/path", { foo: "bar", newParam: "value" });
161
// "/path?foo=bar&newParam=value"
162
```
163

164
## Migration Guide
165

166
### From $URL to Native URL
167

168
```typescript
169
// OLD (deprecated)
170
const oldUrl = new $URL("https://example.com/path?foo=bar");
171
oldUrl.query.newParam = "value";
172
const result = oldUrl.href;
173

174
// NEW (recommended)
175
const newUrl = new URL("https://example.com/path?foo=bar");
176
newUrl.searchParams.set("newParam", "value");
177
const result = newUrl.href;
178
```
179

180
### From $URL to UFO Functional API
181

182
```typescript
183
// OLD (deprecated)
184
const oldUrl = new $URL("https://example.com/path?foo=bar");
185
oldUrl.pathname = "/newpath";
186
const result = oldUrl.href;
187

188
// NEW (recommended)
189
import { parseURL, stringifyParsedURL } from "ufo";
190

191
const parsed = parseURL("https://example.com/path?foo=bar");
192
const modified = { ...parsed, pathname: "/newpath" };
193
const result = stringifyParsedURL(modified);
194
```
195

196
### URL Joining Migration
197

198
```typescript
199
// OLD (deprecated)
200
const base = new $URL("https://api.example.com/v1/");
201
const path = new $URL("users/123");
202
base.append(path);
203
const result = base.href;
204

205
// NEW (recommended)
206
import { joinURL } from "ufo";
207

208
const result = joinURL("https://api.example.com/v1/", "users/123");
209
```
210

211
## Why This API is Deprecated
212

213
1. **Performance**: Native URL is faster and more memory efficient
214
2. **Standards Compliance**: Native URL follows web standards exactly
215
3. **Bundle Size**: Using native URL reduces bundle size
216
4. **Maintenance**: Less custom code to maintain and debug
217
5. **Ecosystem**: Better integration with other tools and libraries
218
6. **Type Safety**: Native URL has better TypeScript support
219

220
The functional approach using parseURL and utility functions provides more flexibility and composability for URL manipulation tasks.