0
# Core Filesystem Operations
1

2
Fundamental file system operations providing the foundation for all file management functionality in Theia applications. This includes reading, writing, watching, metadata access, and streaming operations with full encoding support.
3

4
## Capabilities
5

6
### FileSystemProvider Interface
7

8
The core abstraction for all filesystem implementations, providing standardized CRUD operations across different storage backends.
9

10
```typescript { .api }
11
/**
12
 * Core filesystem provider interface with all CRUD operations
13
 */
14
interface FileSystemProvider {
15
  /** Provider capability flags indicating supported operations */
16
  readonly capabilities: FileSystemProviderCapabilities;
17
  
18
  /** Event fired when provider capabilities change */
19
  readonly onDidChangeCapabilities: Event<void>;
20
  
21
  /** Event fired when watched files change */
22
  readonly onDidChangeFile: Event<readonly FileChange[]>;
23
  
24
  /** Event fired when file watching encounters errors */
25
  readonly onFileWatchError: Event<void>;
26
  
27
  /** Watch for file system changes */
28
  watch(resource: URI, opts: WatchOptions): Disposable;
29
  
30
  /** Get file/directory metadata and statistics */
31
  stat(resource: URI): Promise<Stat>;
32
  
33
  /** Create directory, including parent directories if needed */
34
  mkdir(resource: URI): Promise<void>;
35
  
36
  /** Read directory contents as name/type pairs */
37
  readdir(resource: URI): Promise<[string, FileType][]>;
38
  
39
  /** Delete file or directory */
40
  delete(resource: URI, opts: FileDeleteOptions): Promise<void>;
41
  
42
  /** Rename/move file or directory */
43
  rename(from: URI, to: URI, opts: FileOverwriteOptions): Promise<void>;
44
  
45
  /** Copy file or directory (optional capability) */
46
  copy?(from: URI, to: URI, opts: FileOverwriteOptions): Promise<void>;
47
  
48
  /** Read entire file contents as binary data (optional capability) */
49
  readFile?(resource: URI): Promise<Uint8Array>;
50
  
51
  /** Write binary data to file with options (optional capability) */
52
  writeFile?(resource: URI, content: Uint8Array, opts: FileWriteOptions): Promise<void>;
53
}
54

55
enum FileSystemProviderCapabilities {
56
  FileReadWrite = 2,
57
  FileOpenReadWriteClose = 4,
58
  FileReadStream = 16,
59
  FileFolderCopy = 8,
60
  PathCaseSensitive = 1024,
61
  Readonly = 2048,
62
  Trash = 4096
63
}
64
```
65

66
### FileStat Interface
67

68
Complete file metadata including type information, timestamps, size, and URI reference.
69

70
```typescript { .api }
71
/**
72
 * Complete file metadata with type information
73
 */
74
interface FileStat extends BaseStat {
75
  /** True if this represents a file */
76
  isFile: boolean;
77
  
78
  /** True if this represents a directory */
79
  isDirectory: boolean;
80
  
81
  /** True if this represents a symbolic link */
82
  isSymbolicLink: boolean;
83
  
84
  /** True if this resource is read-only */
85
  isReadonly: boolean;
86
  
87
  /** Child file stats for directories (when resolved) */
88
  children?: FileStat[];
89
}
90

91
interface BaseStat {
92
  /** File system resource URI */
93
  resource: URI;
94
  
95
  /** File name (last segment of path) */
96
  name: string;
97
  
98
  /** File size in bytes (optional) */
99
  size?: number;
100
  
101
  /** Last modification time in millis from Unix epoch (optional) */
102
  mtime?: number;
103
  
104
  /** Creation time in millis from Unix epoch (optional) */
105
  ctime?: number;
106
  
107
  /** Unique identifier representing current state (optional) */
108
  etag?: string;
109
}
110

111
enum FileType {
112
  Unknown = 0,
113
  File = 1,
114
  Directory = 2,
115
  SymbolicLink = 64
116
}
117

118
enum FilePermission {
119
  Readonly = 1
120
}
121
```
122

123
### File Operations and Events
124

125
Event system for tracking file system changes and operations.
126

127
```typescript { .api }
128
/**
129
 * Collection of file changes with filtering and query methods
130
 */
131
interface FileChangesEvent {
132
  /** Array of all file changes in this event */
133
  readonly changes: readonly FileChange[];
134
  
135
  /** Check if event contains changes for a specific resource */
136
  contains(resource: URI, type?: FileChangeType): boolean;
137
  
138
  /** Check if event affects a specific resource or its children */
139
  affects(resource: URI, type?: FileChangeType): boolean;
140
  
141
  /** Get all added file changes */
142
  getAdded(): FileChange[];
143
  
144
  /** Get all updated file changes */
145
  getUpdated(): FileChange[];
146
  
147
  /** Get all deleted file changes */
148
  getDeleted(): FileChange[];
149
}
150

151
interface FileChange {
152
  /** Type of change (added, updated, deleted) */
153
  readonly type: FileChangeType;
154
  
155
  /** Resource that changed */
156
  readonly resource: URI;
157
}
158

159
enum FileChangeType {
160
  UPDATED = 0,
161
  ADDED = 1,
162
  DELETED = 2
163
}
164

165
/**
166
 * File operation event information
167
 */
168
interface FileOperationEvent {
169
  /** Type of operation performed */
170
  readonly operation: FileOperation;
171
  
172
  /** Target resource */
173
  readonly target: URI;
174
  
175
  /** Source resource (for move/copy operations) */
176
  readonly source?: URI;
177
}
178

179
enum FileOperation {
180
  CREATE,
181
  DELETE,
182
  MOVE,
183
  COPY
184
}
185
```
186

187
### File Operation Options
188

189
Configuration options for various file operations.
190

191
```typescript { .api }
192
interface FileWriteOptions {
193
  /** Whether to create file if it doesn't exist */
194
  create?: boolean;
195
  
196
  /** Whether to overwrite existing file */
197
  overwrite?: boolean;
198
  
199
  /** Whether to unlock readonly files */
200
  unlock?: boolean;
201
  
202
  /** Atomic write operations */
203
  atomic?: boolean;
204
}
205

206
interface FileDeleteOptions {
207
  /** Delete recursively for directories */
208
  recursive?: boolean;
209
  
210
  /** Move to trash instead of permanent deletion */
211
  useTrash?: boolean;
212
}
213

214
interface FileOverwriteOptions {
215
  /** Whether to overwrite existing target */
216
  overwrite?: boolean;
217
}
218

219
interface WatchOptions {
220
  /** Whether to watch recursively */
221
  recursive?: boolean;
222
  
223
  /** Glob patterns to exclude from watching */
224
  excludes?: string[];
225
}
226
```
227

228
### Streaming Operations
229

230
High-performance streaming operations for large files.
231

232
```typescript { .api }
233
/**
234
 * Provider with streaming capabilities for large files
235
 */
236
interface FileSystemProviderWithOpenReadWriteCloseCapability extends FileSystemProvider {
237
  /** Open file for reading/writing */
238
  open(resource: URI, opts: FileOpenOptions): Promise<number>;
239
  
240
  /** Close previously opened file */
241
  close(fd: number): Promise<void>;
242
  
243
  /** Read data from opened file */
244
  read(fd: number, pos: number, data: Uint8Array, offset: number, length: number): Promise<number>;
245
  
246
  /** Write data to opened file */  
247
  write(fd: number, pos: number, data: Uint8Array, offset: number, length: number): Promise<number>;
248
}
249

250
interface FileOpenOptions {
251
  /** Open for read access */
252
  read?: boolean;
253
  
254
  /** Open for write access */
255
  write?: boolean;
256
  
257
  /** Create file if it doesn't exist */
258
  create?: boolean;
259
}
260

261
/**
262
 * Stream file content with transformations
263
 */
264
function readFileIntoStream<T>(
265
  provider: FileSystemProviderWithOpenReadWriteCloseCapability,
266
  resource: URI,
267
  target: WriteableStream<T>,
268
  transformer: DataTransformer<BinaryBuffer, T>,
269
  options: CreateReadStreamOptions,
270
  token: CancellationToken
271
): Promise<void>;
272

273
interface CreateReadStreamOptions extends FileReadStreamOptions {
274
  /** Size of each read chunk */
275
  bufferSize?: number;
276
  
277
  /** Total bytes to read */
278
  length?: number;
279
  
280
  /** Starting position for reading */
281
  position?: number;
282
}
283
```
284

285
**Usage Examples:**
286

287
```typescript
288
import { FileSystemProvider, FileStat, URI } from "@theia/filesystem/lib/common";
289

290
// Basic file operations
291
const provider: FileSystemProvider = container.get(FileSystemProvider);
292

293
// Read file contents
294
const content = await provider.readFile(URI.parse('file:///path/to/file.txt'));
295
const text = content.toString();
296

297
// Write file contents  
298
const data = new TextEncoder().encode('Hello World');
299
await provider.writeFile(URI.parse('file:///path/to/output.txt'), data, {
300
  create: true,
301
  overwrite: true
302
});
303

304
// Get file metadata
305
const stat = await provider.stat(URI.parse('file:///path/to/file.txt'));
306
console.log(`File size: ${stat.size} bytes`);
307
console.log(`Last modified: ${new Date(stat.mtime)}`);
308
console.log(`Is file: ${stat.isFile}`);
309

310
// List directory contents
311
const entries = await provider.readdir(URI.parse('file:///path/to/directory'));
312
for (const [name, type] of entries) {
313
  console.log(`${name}: ${FileType[type]}`);
314
}
315

316
// Watch for changes
317
const watcher = provider.watch(URI.parse('file:///path/to/watch'), {
318
  recursive: true,
319
  excludes: ['node_modules/**', '.git/**']
320
});
321

322
provider.onDidChangeFile(changes => {
323
  for (const change of changes) {
324
    console.log(`${FileChangeType[change.type]}: ${change.resource.toString()}`);
325
  }
326
});
327

328
// Clean up watcher
329
watcher.dispose();
330
```