0
# path-scurry
1

2
path-scurry is a high-performance utility for building tools that read the file system, designed to minimize filesystem operations and path string manipulations. It provides intelligent caching mechanisms, cross-platform path handling, and multiple interfaces including streaming, async/await, and traditional callback patterns for maximum flexibility and performance.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { PathScurry, Path } from "path-scurry";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { PathScurry, Path } = require("path-scurry");
21
```
22

23
Platform-specific imports:
24

25
```typescript
26
import { PathScurryWin32, PathScurryPosix, PathScurryDarwin } from "path-scurry";
27
import { PathWin32, PathPosix } from "path-scurry";
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { PathScurry } from "path-scurry";
34

35
// Create a path walker for the current directory
36
const pw = new PathScurry(process.cwd());
37

38
// Simple directory traversal
39
for await (const entry of pw) {
40
  if (entry.isFile() && entry.name.endsWith(".js")) {
41
    console.log(entry.fullpath());
42
  }
43
}
44

45
// Path resolution with caching
46
const resolved = pw.resolve("./src/index.ts");
47
console.log(resolved); // Fully resolved absolute path
48

49
// Directory reading
50
const children = await pw.readdir("./src");
51
console.log(children.map(child => child.name));
52
```
53

54
## Architecture
55

56
Path-scurry is built around several key components:
57

58
- **PathScurry Classes**: Main interface providing filesystem operations and path resolution with intelligent caching
59
- **Path Objects**: Represent individual filesystem entries with lazy-loaded metadata and cached operations
60
- **Caching System**: LRU caches for path resolution, directory contents, and filesystem metadata to minimize syscalls
61
- **Cross-Platform Support**: Platform-specific implementations handling Windows UNC paths, drive letters, and POSIX paths
62
- **Multiple APIs**: Traditional fs-like methods, streaming interfaces, async iterators, and callback patterns
63

64
## Capabilities
65

66
### Path Resolution and Navigation
67

68
Core path resolution functionality with intelligent caching, supporting both relative and absolute paths across platforms.
69

70
```typescript { .api }
71
class PathScurry {
72
  constructor(cwd?: URL | string, opts?: PathScurryOpts);
73
  resolve(...paths: string[]): string;
74
  resolvePosix(...paths: string[]): string;
75
  relative(entry?: PathBase | string): string;
76
  relativePosix(entry?: PathBase | string): string;
77
  basename(entry?: PathBase | string): string;
78
  dirname(entry?: PathBase | string): string;
79
  depth(path?: Path | string): number;
80
  chdir(path: string | Path): void;
81
}
82

83
interface PathScurryOpts {
84
  nocase?: boolean;
85
  childrenCacheSize?: number;
86
  fs?: FSOption;
87
}
88
```
89

90
[Path Resolution](./path-resolution.md)
91

92
### Directory Operations
93

94
High-performance directory reading and traversal with caching and multiple output formats.
95

96
```typescript { .api }
97
// Directory reading
98
readdir(): Promise<PathBase[]>;
99
readdir(opts: { withFileTypes: false }): Promise<string[]>;
100
readdir(entry: PathBase | string): Promise<PathBase[]>;
101
readdir(entry: PathBase | string, opts: { withFileTypes: false }): Promise<string[]>;
102

103
readdirSync(): PathBase[];
104
readdirSync(opts: { withFileTypes: false }): string[];
105
readdirSync(entry: PathBase | string): PathBase[];
106
readdirSync(entry: PathBase | string, opts: { withFileTypes: false }): string[];
107
```
108

109
[Directory Operations](./directory-operations.md)
110

111
### File System Metadata
112

113
Cached filesystem metadata operations including lstat, readlink, and realpath with error handling.
114

115
```typescript { .api }
116
lstat(entry?: string | PathBase): Promise<PathBase | undefined>;
117
lstatSync(entry?: string | PathBase): PathBase | undefined;
118

119
readlink(entry?: string | PathBase): Promise<string | undefined>;
120
readlink(entry: string | PathBase, opt: { withFileTypes: true }): Promise<PathBase | undefined>;
121
readlinkSync(entry?: string | PathBase): string | undefined;
122
readlinkSync(entry: string | PathBase, opt: { withFileTypes: true }): PathBase | undefined;
123

124
realpath(entry?: string | PathBase): Promise<string | undefined>;
125
realpath(entry: string | PathBase, opt: { withFileTypes: true }): Promise<PathBase | undefined>;
126
realpathSync(entry?: string | PathBase): string | undefined;
127
realpathSync(entry: string | PathBase, opt: { withFileTypes: true }): PathBase | undefined;
128
```
129

130
[File System Metadata](./filesystem-metadata.md)
131

132
### Directory Walking and Traversal
133

134
Multiple interfaces for directory tree traversal including async/await, streaming, and synchronous options with filtering and symlink following.
135

136
```typescript { .api }
137
// Async array-based walking
138
walk(): Promise<PathBase[]>;
139
walk(opts: WalkOptions): Promise<PathBase[] | string[]>;
140
walk(entry: string | PathBase, opts?: WalkOptions): Promise<PathBase[] | string[]>;
141

142
walkSync(): PathBase[];
143
walkSync(opts: WalkOptions): PathBase[] | string[];
144
walkSync(entry: string | PathBase, opts?: WalkOptions): PathBase[] | string[];
145

146
// Streaming interfaces
147
stream(): Minipass<PathBase>;
148
stream(opts: WalkOptions): Minipass<PathBase | string>;
149
streamSync(): Minipass<PathBase>;
150

151
// Async iteration
152
iterate(): AsyncGenerator<PathBase, void, void>;
153
iterate(opts: WalkOptions): AsyncGenerator<PathBase | string, void, void>;
154
iterateSync(): Generator<PathBase, void, void>;
155

156
interface WalkOptions {
157
  withFileTypes?: boolean;
158
  follow?: boolean;
159
  filter?: (entry: PathBase) => boolean;
160
  walkFilter?: (entry: PathBase) => boolean;
161
}
162
```
163

164
[Directory Walking](./directory-walking.md)
165

166
### Path Objects
167

168
Individual filesystem entry objects with lazy-loaded metadata, type checking, and path manipulation methods.
169

170
```typescript { .api }
171
abstract class PathBase implements Dirent {
172
  name: string;
173
  isCWD: boolean;
174
  readonly parentPath: string;
175
  readonly path: string; // deprecated
176

177
  // Path navigation
178
  resolve(path?: string): PathBase;
179
  relative(): string;
180
  relativePosix(): string;
181
  fullpath(): string;
182
  fullpathPosix(): string;
183
  depth(): number;
184

185
  // Type checking
186
  isFile(): boolean;
187
  isDirectory(): boolean;
188
  isSymbolicLink(): boolean;
189
  isUnknown(): boolean;
190
  isType(type: Type): boolean;
191
  getType(): Type;
192
  isNamed(name: string): boolean;
193

194
  // Filesystem operations
195
  readdir(): Promise<PathBase[]>;
196
  readdirSync(): PathBase[];
197
  lstat(): Promise<PathBase | undefined>;
198
  lstatSync(): PathBase | undefined;
199
  readlink(): Promise<PathBase | undefined>;
200
  readlinkSync(): PathBase | undefined;
201
  realpath(): Promise<PathBase | undefined>;
202
  realpathSync(): PathBase | undefined;
203
}
204

205
type Type = 'Unknown' | 'FIFO' | 'CharacterDevice' | 'Directory' | 
206
           'BlockDevice' | 'File' | 'SymbolicLink' | 'Socket';
207
```
208

209
[Path Objects](./path-objects.md)
210

211
## Types
212

213
```typescript { .api }
214
type Path = PathBase | InstanceType<typeof Path>;
215
type PathScurry = PathScurryBase | InstanceType<typeof PathScurry>;
216

217
// Internal types also exported
218
type Children = PathBase[] & { provisional: number };
219

220
interface PathOpts {
221
  fullpath?: string;
222
  relative?: string;
223
  relativePosix?: string;
224
  parent?: PathBase;
225
  fs?: FSOption;
226
}
227

228
interface FSOption {
229
  lstatSync?: (path: string) => Stats;
230
  readdir?: (path: string, options: { withFileTypes: true }, 
231
            cb: (er: NodeJS.ErrnoException | null, entries?: Dirent[]) => any) => void;
232
  readdirSync?: (path: string, options: { withFileTypes: true }) => Dirent[];
233
  readlinkSync?: (path: string) => string;
234
  realpathSync?: (path: string) => string;
235
  promises?: {
236
    lstat?: (path: string) => Promise<Stats>;
237
    readdir?: (path: string, options: { withFileTypes: true }) => Promise<Dirent[]>;
238
    readlink?: (path: string) => Promise<string>;
239
    realpath?: (path: string) => Promise<string>;
240
  };
241
}
242

243
// Internal cache classes (exported but advanced usage)
244
class ResolveCache extends LRUCache<string, string> {
245
  constructor();
246
}
247

248
class ChildrenCache extends LRUCache<PathBase, Children> {
249
  constructor(maxSize?: number);
250
}
251
```