0
# memfs
1
2
memfs is a comprehensive in-memory file system implementation that mimics Node.js's native fs API, enabling developers to create virtual file systems entirely in memory for testing, mocking, and development purposes. It offers full compatibility with Node.js filesystem operations while also providing browser compatibility through File System Access API adapters and OPFS (Origin Private File System) support.
3
4
## Package Information
5
6
- **Package Name**: memfs
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install memfs`
10
11
## Core Imports
12
13
```typescript
14
import { fs, vol, memfs, Volume } from "memfs";
15
```
16
17
For individual components:
18
19
```typescript
20
import {
21
fs, // Default file system instance
22
vol, // Default volume instance
23
Volume, // Volume class
24
memfs, // Factory function
25
createFsFromVolume, // Factory function
26
DirectoryJSON, // JSON structure type
27
NestedDirectoryJSON, // Nested JSON structure type
28
IFs, // File system interface type
29
IFsWithVolume // File system with volume type
30
} from "memfs";
31
```
32
33
CommonJS:
34
35
```javascript
36
const { fs, vol, memfs, Volume } = require("memfs");
37
```
38
39
## Basic Usage
40
41
```typescript
42
import { fs, memfs } from "memfs";
43
44
// Use the default file system
45
fs.writeFileSync("/hello.txt", "Hello World!");
46
const content = fs.readFileSync("/hello.txt", "utf8");
47
console.log(content); // "Hello World!"
48
49
// Create a new file system from JSON
50
const { fs: customFs } = memfs({
51
"/app": {
52
"package.json": '{"name": "my-app"}',
53
"src": {
54
"index.js": "console.log('Hello');"
55
}
56
}
57
});
58
59
// Read from the custom file system
60
const packageJson = customFs.readFileSync("/app/package.json", "utf8");
61
console.log(JSON.parse(packageJson).name); // "my-app"
62
```
63
64
## Architecture
65
66
memfs is built around several key components:
67
68
- **Volume System**: Core file system management with complete Node.js fs API compatibility
69
- **File System Access API**: Modern browser-compatible FSA implementation for web environments
70
- **Bridge Adapters**: Bidirectional compatibility layers between Node.js fs and FSA APIs
71
- **Snapshot System**: File system serialization/deserialization for persistence and testing
72
- **Core Primitives**: Low-level file system components (Node, Link, File, Superblock)
73
- **Utility Libraries**: Tree printing, encoding helpers, and testing utilities
74
75
## Capabilities
76
77
### Core File System API
78
79
Complete Node.js fs API implementation with synchronous, callback, and promise-based methods. Provides drop-in replacement for Node.js fs module with full compatibility.
80
81
```typescript { .api }
82
// Main exports
83
export const fs: IFs;
84
export const vol: Volume;
85
export function memfs(json?: NestedDirectoryJSON, cwd?: string): { fs: IFs; vol: Volume };
86
export function createFsFromVolume(vol: Volume): IFs;
87
88
// Core volume class providing complete Node.js fs API
89
export class Volume {
90
static fromJSON(json: DirectoryJSON, cwd?: string): Volume;
91
static fromNestedJSON(json: NestedDirectoryJSON, cwd?: string): Volume;
92
93
// File operations (synchronous)
94
readFileSync(path: PathLike, options?: any): string | Buffer;
95
writeFileSync(path: PathLike, data: any, options?: any): void;
96
appendFileSync(path: PathLike, data: any, options?: any): void;
97
copyFileSync(src: PathLike, dest: PathLike, mode?: number): void;
98
unlinkSync(path: PathLike): void;
99
existsSync(path: PathLike): boolean;
100
accessSync(path: PathLike, mode?: number): void;
101
102
// File descriptor operations (synchronous)
103
openSync(path: PathLike, flags: TFlags, mode?: TMode): number;
104
closeSync(fd: number): void;
105
readSync(fd: number, buffer: Buffer, offset: number, length: number, position: number | null): number;
106
writeSync(fd: number, buffer: Buffer, offset?: number, length?: number, position?: number): number;
107
108
// Directory operations (synchronous)
109
mkdirSync(path: PathLike, options?: any): string | undefined;
110
readdirSync(path: PathLike, options?: any): string[] | Dirent[];
111
rmdirSync(path: PathLike, options?: any): void;
112
rmSync(path: PathLike, options?: any): void;
113
114
// File status operations (synchronous)
115
statSync(path: PathLike, options?: any): Stats;
116
lstatSync(path: PathLike, options?: any): Stats;
117
fstatSync(fd: number, options?: any): Stats;
118
119
// Link operations (synchronous)
120
linkSync(existingPath: PathLike, newPath: PathLike): void;
121
symlinkSync(target: PathLike, path: PathLike, type?: string): void;
122
readlinkSync(path: PathLike, options?: any): string | Buffer;
123
124
// Async callback API (all Node.js fs methods available)
125
readFile(path: PathLike, options: any, callback: (err: Error | null, data?: any) => void): void;
126
writeFile(path: PathLike, data: any, options: any, callback: (err: Error | null) => void): void;
127
// ... all Node.js fs callback methods
128
129
// Stream operations
130
createReadStream(path: PathLike, options?: any): ReadStream;
131
createWriteStream(path: PathLike, options?: any): WriteStream;
132
133
// Promise API
134
promises: FsPromisesApi;
135
136
// Watchers
137
StatWatcher: new () => StatWatcher;
138
FSWatcher: new () => FSWatcher;
139
ReadStream: new (...args: any[]) => ReadStream;
140
WriteStream: new (...args: any[]) => WriteStream;
141
}
142
143
// Core interfaces
144
export interface IFs extends Volume {
145
constants: typeof constants;
146
Stats: new (...args: any[]) => Stats;
147
Dirent: new (...args: any[]) => Dirent;
148
}
149
150
// JSON structure types
151
export type NestedDirectoryJSON = { [key: string]: string | Buffer | NestedDirectoryJSON | null };
152
export type DirectoryJSON = { [key: string]: string | Buffer | null };
153
154
// Common types used throughout the API
155
export type PathLike = string | Buffer | URL;
156
export type TFlags = string | number;
157
export type TMode = string | number;
158
```
159
160
[Core File System API](./core-filesystem.md)
161
162
163
164
165
### Helper Classes and Utilities
166
167
File statistics, directory entries, and other utility classes available through the fs object.
168
169
```typescript { .api }
170
// Accessible through fs.Stats constructor
171
interface Stats {
172
isFile(): boolean;
173
isDirectory(): boolean;
174
isSymbolicLink(): boolean;
175
size: number;
176
mode: number;
177
mtime: Date;
178
ctime: Date;
179
// ... other stat properties
180
}
181
182
// Accessible through fs.Dirent constructor
183
interface Dirent {
184
name: string;
185
isFile(): boolean;
186
isDirectory(): boolean;
187
isSymbolicLink(): boolean;
188
}
189
190
// Access via fs.Stats and fs.Dirent constructors
191
const stats = new fs.Stats(/* ... */);
192
const dirent = new fs.Dirent(/* ... */);
193
```
194
195
[Helper Classes and Utilities](./helpers.md)
196
197
### Constants
198
199
File system constants compatible with Node.js fs.constants, accessible through the fs object.
200
201
```typescript { .api }
202
// Access file system constants through fs object
203
fs.constants.F_OK; // File existence check
204
fs.constants.R_OK; // Read permission check
205
fs.constants.W_OK; // Write permission check
206
fs.constants.X_OK; // Execute permission check
207
208
// Open flags
209
fs.constants.O_RDONLY; // Read-only
210
fs.constants.O_WRONLY; // Write-only
211
fs.constants.O_RDWR; // Read-write
212
fs.constants.O_CREAT; // Create if not exists
213
fs.constants.O_EXCL; // Exclusive create
214
fs.constants.O_TRUNC; // Truncate to zero
215
fs.constants.O_APPEND; // Append mode
216
217
// File types and permissions
218
fs.constants.S_IFMT; // File type mask
219
fs.constants.S_IFREG; // Regular file
220
fs.constants.S_IFDIR; // Directory
221
fs.constants.S_IFLNK; // Symbolic link
222
// ... all standard Node.js fs constants available
223
```
224
225
## Error Handling
226
227
memfs follows Node.js error handling conventions with full error type compatibility:
228
229
```typescript { .api }
230
// Error interface matching Node.js
231
export interface IError extends Error {
232
code?: string;
233
errno?: number;
234
syscall?: string;
235
path?: string;
236
}
237
238
// Common error patterns
239
export interface ErrorPatterns {
240
// Synchronous methods throw errors
241
syncError: () => never;
242
243
// Callback methods pass errors as first argument
244
callbackError: (err: IError | null, result?: any) => void;
245
246
// Promise methods reject with error objects
247
promiseError: () => Promise<never>;
248
}
249
```
250
251
### Error Handling Patterns:
252
253
**Synchronous API:**
254
```typescript
255
try {
256
const content = fs.readFileSync('/nonexistent.txt', 'utf8');
257
} catch (error) {
258
console.log(error.code); // 'ENOENT'
259
console.log(error.path); // '/nonexistent.txt'
260
console.log(error.syscall); // 'open'
261
}
262
```
263
264
**Callback API:**
265
```typescript
266
fs.readFile('/nonexistent.txt', 'utf8', (err, data) => {
267
if (err) {
268
console.log(err.code); // 'ENOENT'
269
return;
270
}
271
console.log(data);
272
});
273
```
274
275
**Promise API:**
276
```typescript
277
try {
278
const content = await fs.promises.readFile('/nonexistent.txt', 'utf8');
279
} catch (error) {
280
console.log(error.code); // 'ENOENT'
281
}
282
```
283
284
### Error Code Reference:
285
286
| Code | Description | Common Scenarios |
287
|------|-------------|------------------|
288
| `ENOENT` | File or directory not found | Reading non-existent files, accessing missing directories |
289
| `EEXIST` | File or directory already exists | Creating files/directories that exist with exclusive flags |
290
| `EISDIR` | Expected file but found directory | Reading directory as file, writing to directory path |
291
| `ENOTDIR` | Expected directory but found file | Directory operations on file paths |
292
| `EACCES` | Permission denied | Accessing files without proper permissions |
293
| `EMFILE` | Too many open files | Exceeding file descriptor limits |
294
| `EBADF` | Bad file descriptor | Using invalid or closed file descriptors |
295
| `EINVAL` | Invalid argument | Invalid parameters or options |
296
| `EPERM` | Operation not permitted | System-level permission restrictions |