0
# UFO
1

2
UFO is a comprehensive URL utility library for JavaScript and TypeScript that provides over 40 utility functions for parsing, manipulating, encoding, and normalizing URLs and their components. It features zero dependencies, full TypeScript support, and cross-platform compatibility for both browser and Node.js environments.
3

4
## Package Information
5

6
- **Package Name**: ufo
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install ufo`
10

11
## Core Imports
12

13
```typescript
14
import { parseURL, joinURL, normalizeURL, withQuery } from "ufo";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { parseURL, joinURL, normalizeURL, withQuery } = require("ufo");
21
```
22

23
For specific functionality:
24

25
```typescript
26
// URL parsing
27
import { parseURL, parsePath, parseQuery } from "ufo";
28
// Encoding/decoding
29
import { encode, decode, encodePath, decodePath } from "ufo";
30
// URL manipulation
31
import { joinURL, withBase, withQuery, normalizeURL } from "ufo";
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { parseURL, joinURL, withQuery, normalizeURL } from "ufo";
38

39
// Parse URLs into components
40
const parsed = parseURL("https://example.com/path?foo=bar#section");
41
// { protocol: 'https:', host: 'example.com', pathname: '/path', search: '?foo=bar', hash: '#section' }
42

43
// Join URL segments
44
const fullUrl = joinURL("https://api.example.com", "v1", "users", "123");
45
// "https://api.example.com/v1/users/123"
46

47
// Add query parameters
48
const urlWithQuery = withQuery("/search", { q: "javascript", page: 2 });
49
// "/search?q=javascript&page=2"
50

51
// Normalize URLs for consistency
52
const normalized = normalizeURL("//example.com//path//to//resource");
53
// "//example.com/path/to/resource"
54
```
55

56
## Architecture
57

58
UFO is organized into several functional modules:
59

60
- **Parsing Engine**: Core URL parsing with support for various URL formats and edge cases
61
- **Encoding System**: Safe encoding/decoding for different URL components (path, query, hash, host)
62
- **Query Handler**: Complete query string parsing with array support and type preservation
63
- **Path Utilities**: Comprehensive path manipulation with relative path resolution
64
- **Protocol Management**: Add, remove, or change URL protocols with validation
65
- **Cross-platform Support**: Works consistently across browsers and Node.js environments
66

67
## Capabilities
68

69
### URL Parsing & Stringification
70

71
Complete URL parsing into structured components with support for various formats, protocols, and edge cases. Handles everything from simple paths to complex URLs with authentication and international domains.
72

73
```typescript { .api }
74
function parseURL(input?: string, defaultProto?: string): ParsedURL;
75
function parsePath(input?: string): ParsedURL;
76
function parseAuth(input?: string): ParsedAuth;
77
function parseHost(input?: string): ParsedHost;
78
function stringifyParsedURL(parsed: Partial<ParsedURL>): string;
79
function parseFilename(input?: string, opts?: { strict?: boolean }): string | undefined;
80
```
81

82
[URL Parsing & Stringification](./parsing.md)
83

84
### URL Encoding & Decoding
85

86
Safe encoding and decoding functions for different URL components with proper handling of special characters, spaces, and international characters. Includes punycode support for international domain names.
87

88
```typescript { .api }
89
function encode(text: string | number): string;
90
function decode(text?: string | number): string;
91
function encodePath(text: string | number): string;
92
function decodePath(text: string): string;
93
function encodeQueryValue(input: QueryValue): string;
94
function decodeQueryValue(text: string): string;
95
function encodeHost(name?: string): string;
96
```
97

98
[URL Encoding & Decoding](./encoding.md)
99

100
### Query String Handling
101

102
Comprehensive query string parsing and manipulation with support for arrays, nested objects, and complex data types. Includes protection against prototype pollution and flexible serialization options.
103

104
```typescript { .api }
105
function parseQuery<T extends ParsedQuery = ParsedQuery>(parametersString?: string): T;
106
function stringifyQuery(query: QueryObject): string;
107
function encodeQueryItem(key: string, value: QueryValue | QueryValue[]): string;
108
function getQuery<T extends ParsedQuery = ParsedQuery>(input: string): T;
109
```
110

111
[Query String Handling](./query.md)
112

113
### URL Utilities
114

115
Extensive collection of utility functions for URL manipulation including path joining, protocol management, slash handling, base URL operations, and URL comparison with flexible options.
116

117
```typescript { .api }
118
function joinURL(base: string, ...input: string[]): string;
119
function joinRelativeURL(...input: string[]): string;
120
function resolveURL(base?: string, ...inputs: string[]): string;
121
function normalizeURL(input: string): string;
122
function withBase(input: string, base: string): string;
123
function withQuery(input: string, query: QueryObject): string;
124
function hasProtocol(inputString: string, opts?: HasProtocolOptions): boolean;
125
```
126

127
[URL Utilities](./utilities.md)
128

129
### URL Class (Deprecated)
130

131
Legacy URL class implementation provided for backward compatibility. New projects should use native URL constructor or the functional parseURL API.
132

133
```typescript { .api }
134
class $URL implements URL {
135
  constructor(input?: string);
136
  readonly hostname: string;
137
  readonly port: string;
138
  readonly hasProtocol: boolean;
139
  readonly isAbsolute: boolean;
140
  append(url: $URL): void;
141
  toString(): string;
142
}
143

144
function createURL(input: string): $URL;
145
```
146

147
[URL Class (Deprecated)](./url-class.md)
148

149
## Types
150

151
```typescript { .api }
152
interface ParsedURL {
153
  protocol?: string;
154
  host?: string;
155
  auth?: string;
156
  href?: string;
157
  pathname: string;
158
  hash: string;
159
  search: string;
160
  [protocolRelative]?: boolean;
161
}
162

163
interface ParsedAuth {
164
  username: string;
165
  password: string;
166
}
167

168
interface ParsedHost {
169
  hostname: string;
170
  port: string;
171
}
172

173
type QueryValue = string | number | undefined | null | boolean | Array<QueryValue> | Record<string, any>;
174
type QueryObject = Record<string, QueryValue | QueryValue[]>;
175
type ParsedQuery = Record<string, string | string[]>;
176

177
interface HasProtocolOptions {
178
  acceptRelative?: boolean;
179
  strict?: boolean;
180
}
181

182
interface CompareURLOptions {
183
  trailingSlash?: boolean;
184
  leadingSlash?: boolean;
185
  encoding?: boolean;
186
}
187
```