0
# Path Manipulation
1

2
Essential path manipulation operations for joining path segments and computing relative paths between locations.
3

4
## Capabilities
5

6
### Join
7

8
Joins all given path segments together using the platform-specific separator as a delimiter, then normalizes the resulting path. Zero-length path segments are ignored.
9

10
```javascript { .api }
11
/**
12
 * Joins path segments using platform-specific separator
13
 * @param {...string} paths - Path segments to join
14
 * @returns {string} Joined and normalized path
15
 * @throws {TypeError} If any argument is not a string
16
 */
17
function join(...paths: string[]): string;
18
```
19

20
**Usage Examples:**
21

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

25
// Basic path joining
26
path.join("users", "john", "documents");
27
// POSIX: "users/john/documents"
28
// Windows: "users\\john\\documents"
29

30
// Handle leading/trailing separators
31
path.join("/users", "john/", "/documents");
32
// POSIX: "/users/john/documents"
33
// Windows: "\\users\\john\\documents"
34

35
// Skip empty segments
36
path.join("users", "", "john", "documents");
37
// Result: "users/john/documents"
38

39
// Handle relative path segments
40
path.join("users", "../admin", "config");
41
// Result: "admin/config"
42

43
// Single argument normalization
44
path.join("/users//john/");
45
// POSIX: "/users/john/"
46
// Windows: "\\users\\john\\"
47
```
48

49
**Platform Differences:**
50

51
```javascript
52
// Windows-specific joining
53
path.win32.join("C:", "Users", "John");
54
// Result: "C:\\Users\\John"
55

56
path.win32.join("//server", "share", "file.txt");
57
// Result: "\\\\server\\share\\file.txt"
58

59
// POSIX joining
60
path.posix.join("/usr", "local", "bin");
61
// Result: "/usr/local/bin"
62
```
63

64
**Error Handling:**
65

66
```javascript
67
// Throws TypeError for non-string arguments
68
try {
69
  path.join("users", 123, "documents");
70
} catch (error) {
71
  console.log(error.message); // "Arguments to path.join must be strings"
72
}
73
```
74

75
### Relative
76

77
Returns the relative path from `from` to `to` based on the current working directory. If `from` and `to` each resolve to the same path (after calling `resolve()` on each), a zero-length string is returned.
78

79
```javascript { .api }
80
/**
81
 * Returns relative path from 'from' to 'to'
82
 * @param {string} from - Source path
83
 * @param {string} to - Target path  
84
 * @returns {string} Relative path from source to target
85
 */
86
function relative(from: string, to: string): string;
87
```
88

89
**Usage Examples:**
90

91
```javascript
92
const path = require("path");
93

94
// Basic relative path calculation
95
path.relative("/users/john", "/users/jane");
96
// Result: "../jane"
97

98
path.relative("/users/john/docs", "/users/john/images");
99
// Result: "../images"
100

101
// Same path returns empty string
102
path.relative("/users/john", "/users/john");
103
// Result: ""
104

105
// Different drives on Windows
106
path.win32.relative("C:\\users\\john", "D:\\data");
107
// Result: "D:\\data" (absolute path when no common root)
108

109
// Nested directory navigation
110
path.relative("/a/b/c/d", "/a/b/x/y");
111
// Result: "../../x/y"
112

113
// Relative to parent
114
path.relative("/users/john/docs", "/users/john");
115
// Result: ".."
116

117
// Relative to subdirectory
118
path.relative("/users/john", "/users/john/docs");
119
// Result: "docs"
120
```
121

122
**Platform Differences:**
123

124
```javascript
125
// Windows relative paths (case-insensitive)
126
path.win32.relative("C:\\Users\\John", "C:\\users\\jane");
127
// Result: "..\\jane"
128

129
// POSIX relative paths (case-sensitive)
130
path.posix.relative("/Users/John", "/users/jane");
131
// Result: "../../users/jane"
132

133
// UNC paths on Windows
134
path.win32.relative("\\\\server\\share\\folder", "\\\\server\\share\\other");
135
// Result: "..\\other"
136
```
137

138
**Working with Current Directory:**
139

140
```javascript
141
// Relative from current working directory
142
const cwd = process.cwd(); // e.g., "/home/user/project"
143
path.relative(cwd, "/home/user/docs");
144
// Result: "../docs"
145

146
// Resolve first, then calculate relative
147
path.relative(path.resolve("./src"), path.resolve("./docs"));
148
// Calculates relative path between resolved absolute paths
149
```