0
# Path Parsing
1

2
Path parsing utilities for extracting components from file paths and reconstructing paths from components.
3

4
## Capabilities
5

6
### Dirname
7

8
Returns the directory name of a path, similar to the Unix `dirname` command. Trailing directory separators are ignored.
9

10
```javascript { .api }
11
/**
12
 * Returns the directory portion of a path
13
 * @param {string} path - Path to extract directory from
14
 * @returns {string} Directory portion of path
15
 */
16
function dirname(path: string): string;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const path = require("path");
23

24
// Extract directory from file path
25
path.dirname("/users/john/document.txt");
26
// Result: "/users/john"
27

28
path.dirname("/users/john/");
29
// Result: "/users"
30

31
// Handle relative paths
32
path.dirname("docs/readme.md");
33
// Result: "docs"
34

35
// No directory returns "."
36
path.dirname("file.txt");
37
// Result: "."
38

39
// Root directory
40
path.dirname("/");
41
// Result: "/"
42
```
43

44
**Platform Differences:**
45

46
```javascript
47
// Windows paths
48
path.win32.dirname("C:\\Users\\John\\file.txt");
49
// Result: "C:\\Users\\John"
50

51
path.win32.dirname("C:\\");
52
// Result: "C:\\"
53

54
// UNC paths
55
path.win32.dirname("\\\\server\\share\\file.txt");
56
// Result: "\\\\server\\share"
57
```
58

59
### Basename
60

61
Returns the last portion of a path, similar to the Unix `basename` command. If `ext` is provided and matches the end of the basename, it is removed.
62

63
```javascript { .api }
64
/**
65
 * Returns the last portion of a path
66
 * @param {string} path - Path to extract basename from
67
 * @param {string} [ext] - Optional extension to remove
68
 * @returns {string} Basename of path
69
 */
70
function basename(path: string, ext?: string): string;
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
const path = require("path");
77

78
// Extract filename from path
79
path.basename("/users/john/document.txt");
80
// Result: "document.txt"
81

82
// Remove specific extension
83
path.basename("/users/john/document.txt", ".txt");
84
// Result: "document"
85

86
// Extension must match exactly
87
path.basename("/users/john/document.txt", ".md");
88
// Result: "document.txt" (extension doesn't match)
89

90
// Directory paths
91
path.basename("/users/john/");
92
// Result: "john"
93

94
// Handle relative paths
95
path.basename("docs/readme.md");
96
// Result: "readme.md"
97

98
// Root path
99
path.basename("/");
100
// Result: ""
101
```
102

103
**Platform Differences:**
104

105
```javascript
106
// Windows paths
107
path.win32.basename("C:\\Users\\John\\file.txt");
108
// Result: "file.txt"
109

110
path.win32.basename("C:\\Users\\John\\", ".John");
111
// Result: "John" (if extension matches)
112
```
113

114
### Extname
115

116
Returns the extension of the path, from the last occurrence of the `.` character to end of string in the last portion of the path. If there is no `.` in the last portion, or if there are no `.` characters other than the first character, then it returns an empty string.
117

118
```javascript { .api }
119
/**
120
 * Returns the extension of a path
121
 * @param {string} path - Path to extract extension from
122
 * @returns {string} Extension including leading dot, or empty string
123
 */
124
function extname(path: string): string;
125
```
126

127
**Usage Examples:**
128

129
```javascript
130
const path = require("path");
131

132
// Extract file extension
133
path.extname("document.txt");
134
// Result: ".txt"
135

136
path.extname("archive.tar.gz");
137
// Result: ".gz"
138

139
// No extension
140
path.extname("readme");
141
// Result: ""
142

143
// Hidden files starting with dot
144
path.extname(".gitignore");
145
// Result: ""
146

147
path.extname(".config.json");
148
// Result: ".json"
149

150
// Directory paths
151
path.extname("/users/john/");
152
// Result: ""
153

154
// Complex paths
155
path.extname("/users/john.doe/document.pdf");
156
// Result: ".pdf"
157
```
158

159
### Parse
160

161
Parses a path string into an object with `root`, `dir`, `base`, `ext`, and `name` properties.
162

163
```javascript { .api }
164
/**
165
 * Parses a path string into components
166
 * @param {string} pathString - Path to parse
167
 * @returns {ParsedPath} Object with path components
168
 * @throws {TypeError} If pathString is not a string
169
 */
170
function parse(pathString: string): ParsedPath;
171

172
interface ParsedPath {
173
  /** Root portion of path (e.g., '/', 'C:\\') */
174
  root: string;
175
  /** Directory portion of path */
176
  dir: string;
177
  /** File name including extension */
178
  base: string;
179
  /** File extension including leading dot */
180
  ext: string;
181
  /** File name without extension */
182
  name: string;
183
}
184
```
185

186
**Usage Examples:**
187

188
```javascript
189
const path = require("path");
190

191
// Parse a complete file path
192
const parsed = path.parse("/users/john/document.txt");
193
console.log(parsed);
194
// Result: {
195
//   root: "/",
196
//   dir: "/users/john", 
197
//   base: "document.txt",
198
//   ext: ".txt",
199
//   name: "document"
200
// }
201

202
// Parse relative path
203
const relative = path.parse("docs/readme.md");
204
// Result: {
205
//   root: "",
206
//   dir: "docs",
207
//   base: "readme.md", 
208
//   ext: ".md",
209
//   name: "readme"
210
// }
211

212
// Parse directory path
213
const directory = path.parse("/users/john/");
214
// Result: {
215
//   root: "/",
216
//   dir: "/users",
217
//   base: "john",
218
//   ext: "",
219
//   name: "john"
220
// }
221
```
222

223
**Platform Differences:**
224

225
```javascript
226
// Windows path parsing
227
const winParsed = path.win32.parse("C:\\Users\\John\\file.txt");
228
// Result: {
229
//   root: "C:\\",
230
//   dir: "C:\\Users\\John",
231
//   base: "file.txt",
232
//   ext: ".txt", 
233
//   name: "file"
234
// }
235

236
// UNC path parsing
237
const uncParsed = path.win32.parse("\\\\server\\share\\file.txt");
238
// Result: {
239
//   root: "\\\\server\\share\\",
240
//   dir: "\\\\server\\share",
241
//   base: "file.txt",
242
//   ext: ".txt",
243
//   name: "file"
244
// }
245
```
246

247
### Format
248

249
Formats a path object into a path string. This is the opposite of `parse()`. When providing properties to the pathObject, precedence is given to properties in the following order: `dir` over `root`, `base` over `name` + `ext`.
250

251
```javascript { .api }
252
/**
253
 * Formats a path object into a path string
254
 * @param {PathObject} pathObject - Object with path components
255
 * @returns {string} Formatted path string
256
 * @throws {TypeError} If pathObject is not an object or if root is not string/undefined
257
 */
258
function format(pathObject: PathObject): string;
259

260
interface PathObject {
261
  /** Root portion of path */
262
  root?: string;
263
  /** Directory portion of path */
264
  dir?: string;
265
  /** File name including extension */
266
  base?: string;
267
  /** File name without extension (used with ext if base not provided) */
268
  name?: string;
269
  /** File extension (used with name if base not provided) */
270
  ext?: string;
271
}
272
```
273

274
**Usage Examples:**
275

276
```javascript
277
const path = require("path");
278

279
// Format with dir and base
280
path.format({
281
  dir: "/users/john",
282
  base: "document.txt"
283
});
284
// Result: "/users/john/document.txt"
285

286
// Format with root, name, and ext
287
path.format({
288
  root: "/",
289
  name: "document",
290
  ext: ".txt"
291
});
292
// Result: "/document.txt"
293

294
// Dir takes precedence over root
295
path.format({
296
  root: "/usr",
297
  dir: "/users/john",
298
  base: "file.txt"
299
});
300
// Result: "/users/john/file.txt"
301

302
// Base takes precedence over name + ext
303
path.format({
304
  dir: "/users",
305
  base: "document.txt",
306
  name: "readme",
307
  ext: ".md"
308
});
309
// Result: "/users/document.txt"
310

311
// Minimal object
312
path.format({
313
  base: "file.txt"
314
});
315
// Result: "file.txt"
316
```
317

318
**Platform Differences:**
319

320
```javascript
321
// Windows formatting
322
path.win32.format({
323
  root: "C:\\",
324
  dir: "C:\\Users\\John", 
325
  base: "file.txt"
326
});
327
// Result: "C:\\Users\\John\\file.txt"
328

329
// POSIX formatting
330
path.posix.format({
331
  root: "/",
332
  dir: "/usr/local",
333
  base: "bin"
334
});
335
// Result: "/usr/local/bin"
336
```
337

338
**Error Handling:**
339

340
```javascript
341
// Throws TypeError for invalid pathObject
342
try {
343
  path.format("not an object");
344
} catch (error) {
345
  console.log(error.message); // "Parameter 'pathObject' must be an object..."
346
}
347

348
// Throws TypeError for invalid root type
349
try {
350
  path.format({ root: 123 });
351
} catch (error) {
352
  console.log(error.message); // "'pathObject.root' must be a string or undefined..."
353
}
354
```