0
# @yarnpkg/fslib
1

2
A comprehensive filesystem abstraction library that provides cross-platform filesystem operations with support for virtual filesystems, path utilities, and filesystem compositions. This library is the foundation for Yarn's filesystem operations and offers a unified API for working with different filesystem implementations.
3

4
## Package Information
5

6
- **Name**: @yarnpkg/fslib
7
- **Type**: TypeScript Library
8
- **Language**: TypeScript
9
- **Installation**: `npm install @yarnpkg/fslib` or `yarn add @yarnpkg/fslib`
10

11
## Core Imports
12

13
The package provides several key entry points for different functionalities:
14

15
```typescript { .api }
16
// Main filesystem abstractions and implementations
17
import {
18
  FakeFS, BasePortableFakeFS,
19
  NodeFS, NodePathFS, VirtualFS, JailFS, CwdFS, 
20
  MountFS, AliasFS, LazyFS, PosixFS, ProxiedFS, NoFS
21
} from '@yarnpkg/fslib';
22

23
// Extended filesystem with temporary file operations
24
import { xfs, type XFS } from '@yarnpkg/fslib';
25

26
// Path utilities for cross-platform path handling
27
import { 
28
  npath, ppath,
29
  type PortablePath, type NativePath, type Filename, type Path, type FSPath
30
} from '@yarnpkg/fslib';
31

32
// Constants, errors, and statistics utilities
33
import { constants, errors, statUtils } from '@yarnpkg/fslib';
34

35
// Algorithm utilities and filesystem patching
36
import { 
37
  setupCopyIndex, opendir, CustomDir,
38
  watchFile, unwatchFile, unwatchAllFiles,
39
  patchFs, extendFs
40
} from '@yarnpkg/fslib';
41
```
42

43
## Basic Usage
44

45
### Working with the Extended Filesystem (XFS)
46

47
The most common entry point is the `xfs` instance, which provides all standard filesystem operations plus temporary file management:
48

49
```typescript { .api }
50
import { xfs, ppath } from '@yarnpkg/fslib';
51

52
// Read and write files
53
const content = await xfs.readFilePromise('/path/to/file.txt', 'utf8');
54
await xfs.writeFilePromise('/path/to/output.txt', content);
55

56
// Work with directories
57
await xfs.mkdirPromise('/new/directory', { recursive: true });
58
const files = await xfs.readdirPromise('/directory');
59

60
// Temporary file operations
61
const tempDir = await xfs.mktempPromise();
62
await xfs.writeFilePromise(ppath.join(tempDir, 'temp.txt'), 'data');
63
await xfs.rmtempPromise(); // Clean up all temp directories
64
```
65

66
### Cross-Platform Path Handling
67

68
Use `ppath` for portable paths and `npath` for platform-native paths:
69

70
```typescript { .api }
71
import { ppath, npath, type PortablePath } from '@yarnpkg/fslib';
72

73
// Portable paths (always use forward slashes)
74
const portablePath = ppath.join('/base' as PortablePath, 'sub/file.txt');
75
const resolved = ppath.resolve('/current' as PortablePath, '../relative/path');
76

77
// Convert between portable and native paths
78
const nativePath = npath.fromPortablePath(portablePath);
79
const backToPortable = npath.toPortablePath(nativePath);
80
```
81

82
### Virtual Filesystem Operations
83

84
Create in-memory filesystems for testing or isolated operations:
85

86
```typescript { .api }
87
import { VirtualFS, ppath } from '@yarnpkg/fslib';
88

89
const vfs = new VirtualFS();
90
await vfs.mkdirPromise('/virtual' as PortablePath, { recursive: true });
91
await vfs.writeFilePromise('/virtual/file.txt' as PortablePath, 'content');
92
const content = await vfs.readFilePromise('/virtual/file.txt' as PortablePath, 'utf8');
93
```
94

95
## Architecture
96

97
The library is built around several key concepts:
98

99
### Filesystem Abstractions
100
- **FakeFS**: Abstract base class providing the complete filesystem interface
101
- **BasePortableFakeFS**: Base class for portable path filesystems
102
- **ProxiedFS**: Base for filesystem decorators that proxy to other filesystems
103

104
### Filesystem Implementations
105
- **NodeFS**: Direct interface to Node.js filesystem
106
- **VirtualFS**: In-memory filesystem implementation  
107
- **JailFS**: Security-focused filesystem restricting access to a specific directory
108
- **CwdFS**: Filesystem operating relative to a specific working directory
109
- **MountFS**: Combines multiple filesystems into a unified view
110

111
### Path System
112
- **Portable Paths**: Cross-platform paths using forward slashes
113
- **Native Paths**: Platform-specific paths
114
- **Path Utilities**: Comprehensive path manipulation functions
115

116
## Capabilities
117

118
### Path Handling and Utilities
119

120
Cross-platform path manipulation with type safety and conversion utilities.
121

122
**Key APIs:**
123
```typescript { .api }
124
// Join and resolve paths
125
const joined = ppath.join('/base' as PortablePath, 'sub', 'file.txt');
126
const resolved = ppath.resolve('/current' as PortablePath, '../file.txt');
127

128
// Path analysis
129
const isAbs = ppath.isAbsolute('/absolute/path' as PortablePath);
130
const relative = ppath.relative('/from' as PortablePath, '/to/file.txt' as PortablePath);
131
const dirname = ppath.dirname('/path/to/file.txt' as PortablePath);
132
```
133

134
**Detailed documentation:** [Path Handling](./path-handling.md)
135

136
### Filesystem Abstractions and Interfaces
137

138
Core filesystem interfaces and base classes for building filesystem implementations.
139

140
**Key APIs:**
141
```typescript { .api }
142
import { FakeFS, type Stats, type Dirent } from '@yarnpkg/fslib';
143

144
// Standard filesystem operations available on all implementations
145
abstract class FakeFS<P extends Path> {
146
  abstract readFilePromise(p: P, encoding?: BufferEncoding): Promise<string | Buffer>;
147
  abstract writeFilePromise(p: P, content: string | Buffer): Promise<void>;
148
  abstract mkdirPromise(p: P, options?: MkdirOptions): Promise<void>;
149
  abstract readdirPromise(p: P, options?: ReaddirOptions): Promise<string[] | Dirent<P>[]>;
150
}
151
```
152

153
**Detailed documentation:** [Filesystem Abstractions](./filesystem-abstractions.md)
154

155
### Filesystem Implementations
156

157
Concrete filesystem implementations for different use cases.
158

159
**Key APIs:**
160
```typescript { .api }
161
// Real filesystem access
162
import { NodeFS } from '@yarnpkg/fslib';
163
const nodeFs = new NodeFS();
164

165
// Virtual in-memory filesystem
166
import { VirtualFS } from '@yarnpkg/fslib';
167
const virtualFs = new VirtualFS();
168

169
// Security-restricted filesystem
170
import { JailFS } from '@yarnpkg/fslib';
171
const jailedFs = new JailFS('/safe/directory' as PortablePath, { baseFs: nodeFs });
172
```
173

174
**Detailed documentation:** [Filesystem Implementations](./filesystem-implementations.md)
175

176
### Constants, Errors, and Utilities
177

178
File mode constants, error factories, and statistics utilities.
179

180
**Key APIs:**
181
```typescript { .api }
182
import { constants, errors, statUtils } from '@yarnpkg/fslib';
183

184
// File mode constants
185
const isDirectory = (mode: number) => (mode & constants.S_IFMT) === constants.S_IFDIR;
186

187
// Error creation
188
throw errors.ENOENT('File not found: /missing/file.txt');
189

190
// Statistics utilities
191
const stats = statUtils.makeDefaultStats();
192
const areEqual = statUtils.areStatsEqual(stats1, stats2);
193
```
194

195
**Detailed documentation:** [Constants and Utilities](./constants-and-utilities.md)
196

197
### Advanced Features and Algorithms
198

199
Advanced filesystem operations, patching, and algorithm utilities.
200

201
**Key APIs:**
202
```typescript { .api }
203
// Filesystem patching
204
import { patchFs, extendFs } from '@yarnpkg/fslib';
205
import * as fs from 'fs';
206
const patchedFs = patchFs(fs, customFileSystem);
207

208
// Extended filesystem with temp file management
209
import { xfs } from '@yarnpkg/fslib';
210
const tempDir = await xfs.mktempPromise();
211
await xfs.rmtempPromise();
212

213
// Directory operations
214
import { opendir, CustomDir } from '@yarnpkg/fslib';
215
const dir = await opendir(filesystem, '/path' as PortablePath);
216
```
217

218
**Detailed documentation:** [Advanced Features](./advanced-features.md)
219

220
## Related Documentation
221

222
- [Path Handling](./path-handling.md) - Path utilities and cross-platform path management
223
- [Filesystem Abstractions](./filesystem-abstractions.md) - Core interfaces and base classes  
224
- [Filesystem Implementations](./filesystem-implementations.md) - Concrete filesystem implementations
225
- [Constants and Utilities](./constants-and-utilities.md) - Constants, errors, and statistics utilities
226
- [Advanced Features](./advanced-features.md) - Algorithms, patching, and extended functionality