0
# path-parse
1

2
path-parse is a Node.js ponyfill for the `path.parse()` method, providing cross-platform path parsing functionality. It parses file paths into their constituent parts (root, directory, base filename, extension, and name) with automatic platform detection and explicit platform-specific parsers.
3

4
## Package Information
5

6
- **Package Name**: path-parse
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install path-parse`
10

11
## Core Imports
12

13
```javascript
14
const pathParse = require("path-parse");
15
```
16

17
For ES modules (if supported by your environment):
18

19
```javascript
20
import pathParse from "path-parse";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const pathParse = require("path-parse");
27

28
// Parse a POSIX path (automatic platform detection)
29
const result = pathParse("/home/user/documents/file.txt");
30
console.log(result);
31
// {
32
//   root: "/",
33
//   dir: "/home/user/documents",
34
//   base: "file.txt",
35
//   ext: ".txt",
36
//   name: "file"
37
// }
38

39
// Parse a Windows path (automatic platform detection)
40
const winResult = pathParse("C:\\Users\\user\\Documents\\file.txt");
41
console.log(winResult);
42
// {
43
//   root: "C:\\",
44
//   dir: "C:\\Users\\user\\Documents",
45
//   base: "file.txt",
46
//   ext: ".txt",
47
//   name: "file"
48
// }
49

50
// Use platform-specific parsers explicitly
51
const posixResult = pathParse.posix("/home/user/file.txt");
52
const win32Result = pathParse.win32("C:\\Users\\user\\file.txt");
53
```
54

55
## Capabilities
56

57
### Default Path Parser
58

59
Parses file paths using automatic platform detection based on `process.platform`.
60

61
```javascript { .api }
62
/**
63
 * Parse a file path into its constituent parts using platform-aware logic
64
 * @param {string} pathString - The file path to parse
65
 * @returns {ParsedPath} Object containing parsed path components
66
 * @throws {TypeError} If pathString is not a string or is invalid
67
 */
68
function pathParse(pathString);
69
```
70

71
### POSIX Path Parser
72

73
Explicitly parses paths using POSIX (Unix/Linux/macOS) conventions.
74

75
```javascript { .api }
76
/**
77
 * Parse a file path using POSIX conventions
78
 * @param {string} pathString - The file path to parse  
79
 * @returns {ParsedPath} Object containing parsed path components
80
 * @throws {TypeError} If pathString is not a string or is invalid
81
 */
82
pathParse.posix(pathString);
83
```
84

85
### Windows Path Parser
86

87
Explicitly parses paths using Windows conventions.
88

89
```javascript { .api }
90
/**
91
 * Parse a file path using Windows conventions
92
 * @param {string} pathString - The file path to parse
93
 * @returns {ParsedPath} Object containing parsed path components  
94
 * @throws {TypeError} If pathString is not a string or is invalid
95
 */
96
pathParse.win32(pathString);
97
```
98

99
## Types
100

101
```javascript { .api }
102
/**
103
 * Parsed path object returned by all parse functions
104
 */
105
interface ParsedPath {
106
  /** The root portion of the path (e.g., "/" on POSIX, "C:\\" on Windows) */
107
  root: string;
108
  /** The directory path without trailing separator */
109
  dir: string;
110
  /** The filename including extension */
111
  base: string;
112
  /** The file extension including the dot (e.g., ".txt") */
113
  ext: string;
114
  /** The filename without extension */
115
  name: string;
116
}
117
```
118

119
## Error Handling
120

121
All parse functions validate input and throw `TypeError` in the following cases:
122

123
- **Invalid input type**: When `pathString` is not a string (null, undefined, number, object, boolean)
124
- **Invalid path format**: When the path doesn't match expected format patterns
125

126
```javascript
127
// Examples that throw TypeError
128
try {
129
  pathParse(null); // TypeError: Parameter 'pathString' must be a string, not object
130
  pathParse(123); // TypeError: Parameter 'pathString' must be a string, not number
131
  pathParse(undefined); // TypeError: Parameter 'pathString' must be a string, not undefined
132
} catch (err) {
133
  console.error(err.message);
134
}
135
```
136

137
## Platform Behavior
138

139
- **Automatic Detection**: The default export automatically detects the platform using `process.platform === 'win32'`
140
- **Windows Behavior**: Recognizes drive letters, UNC paths, and Windows path separators (`\\`)
141
- **POSIX Behavior**: Uses forward slashes (`/`) as path separators
142
- **Cross-Platform**: Platform-specific methods allow parsing paths from different systems regardless of current platform
143

144
## Usage Examples
145

146
### Parsing Different Path Types
147

148
```javascript
149
const pathParse = require("path-parse");
150

151
// File with extension
152
pathParse("/path/to/file.html");
153
// { root: "/", dir: "/path/to", base: "file.html", ext: ".html", name: "file" }
154

155
// File without extension  
156
pathParse("/path/to/README");
157
// { root: "/", dir: "/path/to", base: "README", ext: "", name: "README" }
158

159
// Directory path (trailing slash ignored)
160
pathParse("/path/to/directory/");
161
// { root: "/", dir: "/path/to", base: "directory", ext: "", name: "directory" }
162

163
// Root directory
164
pathParse("/");
165
// { root: "/", dir: "/", base: "", ext: "", name: "" }
166

167
// Windows UNC path
168
pathParse.win32("\\\\server\\share\\file.txt");
169
// { root: "\\\\server\\share\\", dir: "\\\\server\\share", base: "file.txt", ext: ".txt", name: "file" }
170
```
171

172
### Cross-Platform Path Parsing
173

174
```javascript
175
const pathParse = require("path-parse");
176

177
// Parse Windows path on any platform
178
const winPath = pathParse.win32("C:\\Users\\john\\Desktop\\document.pdf");
179
console.log(winPath.name); // "document"
180

181
// Parse POSIX path on any platform  
182
const posixPath = pathParse.posix("/home/john/Desktop/document.pdf");
183
console.log(posixPath.dir); // "/home/john/Desktop"
184
```