0
# Path
1

2
Path is an exact copy of Node.js's built-in path module published as a standalone npm package. It provides comprehensive utilities for working with file and directory paths in a cross-platform manner, handling platform-specific differences between Windows and POSIX systems including path separators, drive letters, and UNC paths.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
ES6 imports:
18

19
```javascript
20
import * as path from "path";
21
```
22

23
Individual function imports:
24

25
```javascript
26
const { resolve, join, dirname, basename, extname } = require("path");
27
```
28

29
TypeScript imports (when using @types/node):
30

31
```typescript
32
import * as path from "path";
33
import { resolve, join, dirname, basename, extname } from "path";
34
```
35

36
## Basic Usage
37

38
```javascript
39
const path = require("path");
40

41
// Join paths
42
const fullPath = path.join("/users", "john", "documents", "file.txt");
43
// Result: "/users/john/documents/file.txt" (on POSIX)
44
// Result: "\\users\\john\\documents\\file.txt" (on Windows)
45

46
// Resolve absolute path
47
const absolutePath = path.resolve("../docs", "readme.md");
48
// Result: absolute path based on current working directory
49

50
// Extract path components
51
const filePath = "/home/user/project/index.js";
52
console.log(path.dirname(filePath));  // "/home/user/project"
53
console.log(path.basename(filePath)); // "index.js"
54
console.log(path.extname(filePath));  // ".js"
55

56
// Parse path into components
57
const parsed = path.parse(filePath);
58
// Result: { root: "/", dir: "/home/user/project", base: "index.js", ext: ".js", name: "index" }
59
```
60

61
## Architecture
62

63
The path module provides platform-aware path utilities through a conditional export system:
64

65
- **Platform Detection**: Automatically exports Windows or POSIX implementation based on `process.platform`
66
- **Cross-Platform Access**: Both `path.win32` and `path.posix` are always available regardless of platform
67
- **String Manipulation**: Pure string operations with no filesystem access
68
- **Consistent API**: Identical function signatures across both Windows and POSIX implementations
69

70
## Capabilities
71

72
### Path Resolution
73

74
Core path resolution functionality for converting relative paths to absolute paths and normalizing path structures.
75

76
```javascript { .api }
77
function resolve(...paths: string[]): string;
78
function normalize(path: string): string;
79
function isAbsolute(path: string): boolean;
80
```
81

82
[Path Resolution](./path-resolution.md)
83

84
### Path Manipulation
85

86
Essential path manipulation operations for joining paths and computing relative paths between locations.
87

88
```javascript { .api }
89
function join(...paths: string[]): string;
90
function relative(from: string, to: string): string;
91
```
92

93
[Path Manipulation](./path-manipulation.md)
94

95
### Path Parsing
96

97
Path parsing utilities for extracting components from file paths and reconstructing paths from components.
98

99
```javascript { .api }
100
function dirname(path: string): string;
101
function basename(path: string, ext?: string): string;
102
function extname(path: string): string;
103
function parse(pathString: string): ParsedPath;
104
function format(pathObject: PathObject): string;
105
```
106

107
[Path Parsing](./path-parsing.md)
108

109
### Platform-Specific Operations
110

111
Platform-specific path operations and constants for Windows and POSIX systems.
112

113
```javascript { .api }
114
function _makeLong(path: string): string;
115
const sep: string;
116
const delimiter: string;
117
```
118

119
[Platform Operations](./platform-operations.md)
120

121
## Cross-Platform Usage
122

123
```javascript { .api }
124
// Access platform-specific implementations
125
const posix: typeof path;
126
const win32: typeof path;
127
```
128

129
Access both Windows and POSIX implementations regardless of current platform:
130

131
```javascript
132
const path = require("path");
133

134
// Force POSIX behavior on any platform
135
const posixPath = path.posix.join("/usr", "local", "bin");
136
// Always results in: "/usr/local/bin"
137

138
// Force Windows behavior on any platform  
139
const windowsPath = path.win32.join("C:", "Users", "John");
140
// Always results in: "C:\\Users\\John"
141
```
142

143
## Types
144

145
```javascript { .api }
146
interface ParsedPath {
147
  /** Root portion of path (e.g., '/', 'C:\\') */
148
  root: string;
149
  /** Directory portion of path */
150
  dir: string;
151
  /** File name including extension */
152
  base: string;
153
  /** File extension including leading dot */
154
  ext: string;
155
  /** File name without extension */
156
  name: string;
157
}
158

159
interface PathObject {
160
  /** Root portion of path */
161
  root?: string;
162
  /** Directory portion of path */
163
  dir?: string;
164
  /** File name including extension */
165
  base?: string;
166
}
167
```