0
# Path Resolution
1

2
Core path resolution functionality providing intelligent caching and cross-platform path handling. Significantly faster than Node's built-in `path.resolve()` for repeated operations due to comprehensive caching mechanisms.
3

4
## Capabilities
5

6
### PathScurry Constructor
7

8
Creates a new PathScurry instance with specified working directory and options.
9

10
```typescript { .api }
11
/**
12
 * Create a new PathScurry instance
13
 * @param cwd - Starting working directory (defaults to process.cwd())
14
 * @param opts - Configuration options
15
 */
16
constructor(cwd?: URL | string, opts?: PathScurryOpts);
17

18
interface PathScurryOpts {
19
  /** Perform case-insensitive path matching (default: true on Windows/macOS, false elsewhere) */
20
  nocase?: boolean;
21
  /** Number of child entries to cache (default: 16384) */
22
  childrenCacheSize?: number;
23
  /** Override default filesystem methods */
24
  fs?: FSOption;
25
}
26
```
27

28
**Usage Example:**
29

30
```typescript
31
import { PathScurry } from "path-scurry";
32

33
// Default (current working directory)
34
const pw1 = new PathScurry();
35

36
// Specific directory
37
const pw2 = new PathScurry("/home/user/project");
38

39
// With options
40
const pw3 = new PathScurry("/project", {
41
  nocase: true,
42
  childrenCacheSize: 8192
43
});
44
```
45

46
### Path Resolution
47

48
Resolve one or more path segments to an absolute path with intelligent caching.
49

50
```typescript { .api }
51
/**
52
 * Resolve path segments to absolute path
53
 * @param paths - Path segments to resolve
54
 * @returns Fully resolved absolute path
55
 */
56
resolve(...paths: string[]): string;
57

58
/**
59
 * Resolve path segments to absolute POSIX path
60
 * @param paths - Path segments to resolve  
61
 * @returns Fully resolved absolute path using forward slashes
62
 */
63
resolvePosix(...paths: string[]): string;
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
const pw = new PathScurry("/project");
70

71
// Basic resolution
72
const resolved = pw.resolve("src", "index.ts");
73
console.log(resolved); // "/project/src/index.ts"
74

75
// Absolute path handling
76
const abs = pw.resolve("/etc", "hosts");
77
console.log(abs); // "/etc/hosts"
78

79
// POSIX-style resolution (always forward slashes)
80
const posix = pw.resolvePosix("src\\utils\\helper.js");
81
console.log(posix); // "/project/src/utils/helper.js"
82
```
83

84
### Relative Path Calculation
85

86
Calculate relative paths from the current working directory to target paths.
87

88
```typescript { .api }
89
/**
90
 * Get relative path from current working directory
91
 * @param entry - Target path (string or Path object)
92
 * @returns Relative path string
93
 */
94
relative(entry?: PathBase | string): string;
95

96
/**
97
 * Get relative path using POSIX separators
98
 * @param entry - Target path (string or Path object)
99
 * @returns Relative path string with forward slashes
100
 */
101
relativePosix(entry?: PathBase | string): string;
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
const pw = new PathScurry("/home/user");
108

109
// Relative path calculation
110
const rel = pw.relative("/home/user/projects/app/src");
111
console.log(rel); // "projects/app/src"
112

113
// POSIX relative paths
114
const relPosix = pw.relativePosix("C:\\Users\\data\\file.txt");
115
console.log(relPosix); // "../../data/file.txt" (on Windows)
116
```
117

118
### Path Component Extraction
119

120
Extract basename and dirname components from paths.
121

122
```typescript { .api }
123
/**
124
 * Get basename of path
125
 * @param entry - Path to analyze (defaults to current working directory)
126
 * @returns Base filename or directory name
127
 */
128
basename(entry?: PathBase | string): string;
129

130
/**
131
 * Get parent directory path
132
 * @param entry - Path to analyze (defaults to current working directory)
133
 * @returns Parent directory path
134
 */
135
dirname(entry?: PathBase | string): string;
136
```
137

138
**Usage Examples:**
139

140
```typescript
141
const pw = new PathScurry();
142

143
const base = pw.basename("/path/to/file.txt");
144
console.log(base); // "file.txt"
145

146
const dir = pw.dirname("/path/to/file.txt");
147
console.log(dir); // "/path/to"
148
```
149

150
### Working Directory Management
151

152
Change the effective working directory and calculate path depths.
153

154
```typescript { .api }
155
/**
156
 * Change current working directory
157
 * @param path - New working directory path
158
 */
159
chdir(path: string | Path): void;
160

161
/**
162
 * Calculate depth of path within directory tree
163
 * @param path - Path to analyze (defaults to current working directory)
164
 * @returns Depth level (root = 0)
165
 */
166
depth(path?: Path | string): number;
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
const pw = new PathScurry("/home");
173

174
// Change working directory
175
pw.chdir("user/projects");
176
console.log(pw.cwd.fullpath()); // "/home/user/projects"
177

178
// Calculate depth
179
const depth1 = pw.depth("/");           // 0 (root)
180
const depth2 = pw.depth("/home/user");  // 2
181
```
182

183
### Platform-Specific Classes
184

185
Use specific implementations for cross-platform development or testing.
186

187
```typescript { .api }
188
/**
189
 * Windows-specific PathScurry implementation
190
 */
191
class PathScurryWin32 extends PathScurryBase {
192
  constructor(cwd?: URL | string, opts?: PathScurryOpts);
193
  sep: '\\';
194
}
195

196
/**
197
 * POSIX-specific PathScurry implementation  
198
 */
199
class PathScurryPosix extends PathScurryBase {
200
  constructor(cwd?: URL | string, opts?: PathScurryOpts);
201
  sep: '/';
202
}
203

204
/**
205
 * Darwin (macOS) specific implementation with case-insensitive defaults
206
 */
207
class PathScurryDarwin extends PathScurryPosix {
208
  constructor(cwd?: URL | string, opts?: PathScurryOpts);
209
}
210
```
211

212
**Usage Example:**
213

214
```typescript
215
import { PathScurryWin32, PathScurryPosix } from "path-scurry";
216

217
// Force Windows behavior regardless of platform
218
const winPw = new PathScurryWin32("/project");
219
console.log(winPw.resolve("src", "file.js")); // "C:\\project\\src\\file.js"
220

221
// Force POSIX behavior
222
const posixPw = new PathScurryPosix("/project");  
223
console.log(posixPw.resolve("src", "file.js")); // "/project/src/file.js"
224
```