0
# Path Utilities
1
2
POSIX-compatible path manipulation utilities for working with URI paths. All operations use forward slashes and follow POSIX path semantics regardless of platform, making them ideal for cross-platform URI path operations.
3
4
## Capabilities
5
6
### Utils Namespace
7
8
The Utils namespace provides path manipulation functions that work with URI instances.
9
10
```typescript { .api }
11
/**
12
* Path manipulation utilities using POSIX semantics
13
* All functions preserve URI components other than path
14
*/
15
namespace Utils {
16
/** Join one or more paths to a URI's path */
17
function joinPath(uri: URI, ...paths: string[]): URI;
18
/** Resolve paths against a URI's path */
19
function resolvePath(uri: URI, ...paths: string[]): URI;
20
/** Get directory name of URI's path */
21
function dirname(uri: URI): URI;
22
/** Get base name of URI's path */
23
function basename(uri: URI): string;
24
/** Get extension name of URI's path */
25
function extname(uri: URI): string;
26
}
27
```
28
29
### Path Joining
30
31
Join one or more paths to a URI's existing path with normalization.
32
33
```typescript { .api }
34
/**
35
* Joins one or more input paths to the path of URI
36
* Uses '/' as directory separator and normalizes the result
37
* @param uri - Base URI to join paths to
38
* @param paths - Path segments to join
39
* @returns New URI with joined path, preserving other components
40
*/
41
function joinPath(uri: URI, ...paths: string[]): URI;
42
```
43
44
**Usage Examples:**
45
46
```typescript
47
import { URI, Utils } from "vscode-uri";
48
49
const baseUri = URI.parse('https://example.com/api/v1');
50
51
// Join single path
52
const singleJoin = Utils.joinPath(baseUri, 'users');
53
console.log(singleJoin.toString()); // 'https://example.com/api/v1/users'
54
55
// Join multiple paths
56
const multiJoin = Utils.joinPath(baseUri, 'users', '123', 'profile');
57
console.log(multiJoin.toString()); // 'https://example.com/api/v1/users/123/profile'
58
59
// Join with leading/trailing slashes (normalized)
60
const normalized = Utils.joinPath(baseUri, '/users/', '/123/');
61
console.log(normalized.path); // '/api/v1/users/123'
62
63
// Join with relative paths
64
const relative = Utils.joinPath(baseUri, 'users', '..', 'admin');
65
console.log(relative.path); // '/api/v1/admin'
66
67
// File URI example
68
const fileUri = URI.file('/home/user/project');
69
const joined = Utils.joinPath(fileUri, 'src', 'main.ts');
70
console.log(joined.fsPath); // '/home/user/project/src/main.ts'
71
```
72
73
### Path Resolution
74
75
Resolve paths against a URI's path, similar to Node.js path.resolve().
76
77
```typescript { .api }
78
/**
79
* Resolves one or more paths against the path of a URI
80
* Uses '/' as directory separator and normalizes the result
81
* @param uri - Base URI to resolve paths against
82
* @param paths - Path segments to resolve
83
* @returns New URI with resolved path, preserving other components
84
*/
85
function resolvePath(uri: URI, ...paths: string[]): URI;
86
```
87
88
**Usage Examples:**
89
90
```typescript
91
import { URI, Utils } from "vscode-uri";
92
93
const baseUri = URI.parse('file:///home/user/project/src');
94
95
// Resolve relative path
96
const relative = Utils.resolvePath(baseUri, '../config/settings.json');
97
console.log(relative.path); // '/home/user/project/config/settings.json'
98
99
// Resolve absolute path
100
const absolute = Utils.resolvePath(baseUri, '/etc/hosts');
101
console.log(absolute.path); // '/etc/hosts'
102
103
// Resolve complex relative path
104
const complex = Utils.resolvePath(baseUri, '../..', 'other-project', 'file.txt');
105
console.log(complex.path); // '/home/user/other-project/file.txt'
106
107
// HTTP URI example
108
const httpUri = URI.parse('https://api.example.com/v1/users');
109
const resolved = Utils.resolvePath(httpUri, '../admin/settings');
110
console.log(resolved.toString()); // 'https://api.example.com/v1/admin/settings'
111
```
112
113
### Directory Name
114
115
Get the directory name of a URI's path, similar to Unix dirname command.
116
117
```typescript { .api }
118
/**
119
* Returns a URI where the path is the directory name of the input URI
120
* Similar to Unix dirname command, ignoring trailing separators
121
* @param uri - Input URI
122
* @returns New URI with directory path, or original URI if path is empty
123
*/
124
function dirname(uri: URI): URI;
125
```
126
127
**Usage Examples:**
128
129
```typescript
130
import { URI, Utils } from "vscode-uri";
131
132
// File path
133
const fileUri = URI.file('/home/user/documents/file.txt');
134
const dir = Utils.dirname(fileUri);
135
console.log(dir.fsPath); // '/home/user/documents'
136
137
// HTTP path
138
const httpUri = URI.parse('https://example.com/api/v1/users/123');
139
const httpDir = Utils.dirname(httpUri);
140
console.log(httpDir.path); // '/api/v1/users'
141
142
// Root directory
143
const rootUri = URI.file('/file.txt');
144
const rootDir = Utils.dirname(rootUri);
145
console.log(rootDir.path); // '/'
146
147
// Already directory (with trailing slash)
148
const dirUri = URI.parse('https://example.com/path/');
149
const dirParent = Utils.dirname(dirUri);
150
console.log(dirParent.path); // '/path' (same as input without trailing slash)
151
```
152
153
### Base Name
154
155
Get the base name (filename) of a URI's path, similar to Unix basename command.
156
157
```typescript { .api }
158
/**
159
* Returns the last segment of the path of a URI
160
* Similar to Unix basename command, ignoring trailing separators
161
* @param uri - Input URI
162
* @returns Base name of the URI's path, or empty string if no segments
163
*/
164
function basename(uri: URI): string;
165
```
166
167
**Usage Examples:**
168
169
```typescript
170
import { URI, Utils } from "vscode-uri";
171
172
// File with extension
173
const fileUri = URI.file('/home/user/documents/report.pdf');
174
const filename = Utils.basename(fileUri);
175
console.log(filename); // 'report.pdf'
176
177
// Directory path
178
const dirUri = URI.parse('https://example.com/api/v1/users');
179
const dirname = Utils.basename(dirUri);
180
console.log(dirname); // 'users'
181
182
// Path with trailing slash
183
const trailingUri = URI.parse('file:///home/user/folder/');
184
const folderName = Utils.basename(trailingUri);
185
console.log(folderName); // 'folder'
186
187
// Root path
188
const rootUri = URI.file('/');
189
const rootName = Utils.basename(rootUri);
190
console.log(rootName); // '' (empty string)
191
192
// Single segment
193
const singleUri = URI.parse('file:///filename.txt');
194
const single = Utils.basename(singleUri);
195
console.log(single); // 'filename.txt'
196
```
197
198
### Extension Name
199
200
Get the extension of a URI's path, similar to Unix extname.
201
202
```typescript { .api }
203
/**
204
* Returns the extension name of the path of a URI
205
* Similar to Unix extname command, including the leading dot
206
* @param uri - Input URI
207
* @returns Extension name including dot, or empty string if no extension
208
*/
209
function extname(uri: URI): string;
210
```
211
212
**Usage Examples:**
213
214
```typescript
215
import { URI, Utils } from "vscode-uri";
216
217
// File with extension
218
const jsFile = URI.file('/project/src/main.js');
219
const jsExt = Utils.extname(jsFile);
220
console.log(jsExt); // '.js'
221
222
// File with multiple dots
223
const configFile = URI.file('/project/config.prod.json');
224
const configExt = Utils.extname(configFile);
225
console.log(configExt); // '.json'
226
227
// File without extension
228
const noExt = URI.file('/project/README');
229
const emptyExt = Utils.extname(noExt);
230
console.log(emptyExt); // ''
231
232
// Hidden file with extension
233
const hiddenFile = URI.file('/home/user/.gitignore');
234
const hiddenExt = Utils.extname(hiddenFile);
235
console.log(hiddenExt); // ''
236
237
// Directory path
238
const dirUri = URI.parse('https://example.com/api/v1');
239
const dirExt = Utils.extname(dirUri);
240
console.log(dirExt); // ''
241
242
// Complex file path
243
const complexFile = URI.file('/path/file.backup.2023.tar.gz');
244
const complexExt = Utils.extname(complexFile);
245
console.log(complexExt); // '.gz'
246
```
247
248
## Path Normalization
249
250
All path utilities automatically normalize paths by:
251
252
- Resolving `.` and `..` segments
253
- Collapsing multiple consecutive `/` characters into single `/`
254
- Preserving trailing separators where semantically meaningful
255
- Using POSIX path semantics regardless of platform
256
257
**Example:**
258
259
```typescript
260
import { URI, Utils } from "vscode-uri";
261
262
const messy = URI.parse('file:///project//src/./components/../utils//file.js');
263
const clean = Utils.joinPath(messy); // Normalize by joining with no additional paths
264
console.log(clean.path); // '/project/src/utils/file.js'
265
```