0
# URI Operations
1

2
Complete URI parsing, creation, and manipulation functionality following RFC 3986 standards. The URI class provides comprehensive support for parsing URIs from strings, creating URIs from filesystem paths, building URIs from components, and manipulating existing URIs.
3

4
## Capabilities
5

6
### URI Class
7

8
The main URI class implementing RFC 3986 URI specification with all standard components.
9

10
```typescript { .api }
11
/**
12
 * Uniform Resource Identifier (URI) implementation following RFC 3986
13
 * Provides parsing, creation, and manipulation of URI components
14
 */
15
class URI {
16
  /** The scheme component (e.g., 'http', 'file', 'https') */
17
  readonly scheme: string;
18
  /** The authority component (e.g., 'www.example.com', 'localhost:8080') */
19
  readonly authority: string;
20
  /** The path component (e.g., '/some/path', '/file.txt') */
21
  readonly path: string;
22
  /** The query component (e.g., 'param=value&other=data') */
23
  readonly query: string;
24
  /** The fragment component (e.g., 'section', 'line-42') */
25
  readonly fragment: string;
26
  /** Filesystem path representation with platform-specific separators */
27
  readonly fsPath: string;
28

29
  /** Create new URI with modified components */
30
  with(change: {
31
    scheme?: string;
32
    authority?: string | null;
33
    path?: string | null;
34
    query?: string | null;
35
    fragment?: string | null;
36
  }): URI;
37

38
  /** Convert URI to string representation */
39
  toString(skipEncoding?: boolean): string;
40

41
  /** Convert URI to JSON-serializable object */
42
  toJSON(): UriComponents;
43
}
44
```
45

46
### URI Parsing
47

48
Parse URI from string representation with optional strict validation.
49

50
```typescript { .api }
51
/**
52
 * Creates a new URI from a string representation
53
 * @param value - String representation of URI (e.g., 'http://example.com/path')
54
 * @param strict - Enable strict validation (default: false)
55
 * @returns Parsed URI instance
56
 */
57
static parse(value: string, strict?: boolean): URI;
58
```
59

60
**Usage Examples:**
61

62
```typescript
63
import { URI } from "vscode-uri";
64

65
// Parse HTTP URI
66
const httpUri = URI.parse('https://code.visualstudio.com/docs/extensions/overview#frag');
67
console.log(httpUri.scheme);    // 'https'
68
console.log(httpUri.authority); // 'code.visualstudio.com'
69
console.log(httpUri.path);      // '/docs/extensions/overview'
70
console.log(httpUri.query);     // ''
71
console.log(httpUri.fragment);  // 'frag'
72

73
// Parse file URI
74
const fileUri = URI.parse('file:///c:/Users/name/file.txt');
75
console.log(fileUri.scheme);    // 'file'
76
console.log(fileUri.path);      // '/c:/Users/name/file.txt'
77

78
// Parse with query parameters
79
const queryUri = URI.parse('http://api.example.com/search?q=test&limit=10');
80
console.log(queryUri.query);    // 'q=test&limit=10'
81
```
82

83
### File URI Creation
84

85
Create URI from filesystem path with proper encoding and platform handling.
86

87
```typescript { .api }
88
/**
89
 * Creates a new URI from a file system path
90
 * Handles platform-specific path conventions and UNC paths
91
 * @param path - Filesystem path (e.g., '/usr/local/file.txt', 'C:\\Windows\\file.txt')
92
 * @returns URI with 'file' scheme
93
 */
94
static file(path: string): URI;
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import { URI } from "vscode-uri";
101

102
// Unix-style path
103
const unixUri = URI.file('/usr/local/bin/code');
104
console.log(unixUri.toString()); // 'file:///usr/local/bin/code'
105
console.log(unixUri.fsPath);     // '/usr/local/bin/code'
106

107
// Windows-style path
108
const winUri = URI.file('C:\\Users\\name\\file.txt');
109
console.log(winUri.toString()); // 'file:///c%3A/Users/name/file.txt'
110

111
// UNC path
112
const uncUri = URI.file('\\\\server\\share\\file.txt');
113
console.log(uncUri.authority);  // 'server'
114
console.log(uncUri.path);       // '/share/file.txt'
115

116
// Paths with special characters
117
const specialUri = URI.file('/path with spaces/file#with-hash.txt');
118
console.log(specialUri.toString()); // Properly encoded URI
119
```
120

121
### Component-Based Creation
122

123
Create URI from individual components with validation.
124

125
```typescript { .api }
126
/**
127
 * Creates a new URI from component object with validation
128
 * @param components - Object containing URI components
129
 * @returns New URI instance
130
 */
131
static from(components: UriComponents): URI;
132

133
interface UriComponents {
134
  scheme: string;
135
  authority: string;
136
  path: string;
137
  query: string;
138
  fragment: string;
139
}
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
import { URI, UriComponents } from "vscode-uri";
146

147
// Create HTTP URI from components
148
const httpUri = URI.from({
149
  scheme: 'https',
150
  authority: 'api.example.com',
151
  path: '/v1/users',
152
  query: 'limit=50',
153
  fragment: ''
154
});
155
console.log(httpUri.toString()); // 'https://api.example.com/v1/users?limit=50'
156

157
// Create file URI from components
158
const fileComponents: UriComponents = {
159
  scheme: 'file',
160
  authority: '',
161
  path: '/home/user/document.txt',
162
  query: '',
163
  fragment: ''
164
};
165
const fileUri = URI.from(fileComponents);
166
```
167

168
### URI Type Checking
169

170
Type guard function to check if object is URI instance.
171

172
```typescript { .api }
173
/**
174
 * Type guard to check if object is a URI instance
175
 * @param thing - Object to check
176
 * @returns True if object is URI instance
177
 */
178
static isUri(thing: any): thing is URI;
179
```
180

181
### URI Serialization and Deserialization
182

183
Revive URI from serialized data or handle null/undefined values.
184

185
```typescript { .api }
186
/**
187
 * Revive URI from serialized data with null/undefined handling
188
 * @param data - Serialized URI data or URI instance
189
 * @returns Revived URI instance or original value if null/undefined
190
 */
191
static revive(data: UriComponents | URI | undefined | null): URI | undefined | null;
192
```
193

194
### URI Modification
195

196
Create new URI with modified components while preserving others.
197

198
```typescript { .api }
199
/**
200
 * Create new URI with modified components
201
 * @param change - Object specifying which components to change
202
 * @returns New URI instance with modifications
203
 */
204
with(change: {
205
  scheme?: string;
206
  authority?: string | null;
207
  path?: string | null;
208
  query?: string | null;
209
  fragment?: string | null;
210
}): URI;
211
```
212

213
**Usage Examples:**
214

215
```typescript
216
import { URI } from "vscode-uri";
217

218
const original = URI.parse('https://example.com/path?query=value');
219

220
// Change only the path
221
const withNewPath = original.with({ path: '/new/path' });
222
console.log(withNewPath.toString()); // 'https://example.com/new/path?query=value'
223

224
// Change multiple components
225
const modified = original.with({
226
  scheme: 'http',
227
  query: 'updated=true',
228
  fragment: 'section1'
229
});
230
console.log(modified.toString()); // 'http://example.com/path?updated=true#section1'
231

232
// Clear components by setting to null
233
const cleared = original.with({ query: null, fragment: null });
234
console.log(cleared.toString()); // 'https://example.com/path'
235
```
236

237
### String Conversion
238

239
Convert URI to string representation with optional encoding control.
240

241
```typescript { .api }
242
/**
243
 * Creates string representation of URI
244
 * @param skipEncoding - Skip URI encoding (default: false)
245
 * @returns String representation of URI
246
 */
247
toString(skipEncoding?: boolean): string;
248
```
249

250
**Usage Examples:**
251

252
```typescript
253
import { URI } from "vscode-uri";
254

255
const uri = URI.file('/path with spaces/file#name.txt');
256

257
// Normal encoding (default)
258
console.log(uri.toString()); // Encoded URI string
259

260
// Skip encoding for display purposes
261
console.log(uri.toString(true)); // Human-readable URI string
262
```