0
# Resources and Files
1

2
Theia's resource system provides unified abstraction for files, URIs, and virtual resources with versioning, encoding support, and multiple resolvers for flexible file system integration.
3

4
## Capabilities
5

6
### Resource Interface
7

8
Base abstraction for any resource that can be read or modified.
9

10
```typescript { .api }
11
/**
12
 * Abstract resource interface
13
 */
14
interface Resource {
15
    /** Resource URI */
16
    readonly uri: URI;
17
    
18
    /** Optional version information */
19
    readonly version?: ResourceVersion;
20
    
21
    /** Optional encoding information */
22
    readonly encoding?: string;
23
    
24
    /**
25
     * Read resource contents
26
     * @param options - Read options
27
     * @returns Promise resolving to resource content
28
     */
29
    readContents(options?: ResourceReadOptions): Promise<string>;
30
    
31
    /**
32
     * Save resource contents (if supported)
33
     * @param content - Content to save
34
     * @param options - Save options
35
     * @returns Promise that resolves when save completes
36
     */
37
    saveContents?(content: string, options?: ResourceSaveOptions): Promise<void>;
38
    
39
    /**
40
     * Get resource stat information
41
     * @returns Promise resolving to stat info
42
     */
43
    stat?(): Promise<ResourceStat>;
44
    
45
    /**
46
     * Delete the resource (if supported)
47
     * @returns Promise that resolves when delete completes
48
     */
49
    delete?(): Promise<void>;
50
}
51

52
/**
53
 * Resource version for tracking changes
54
 */
55
interface ResourceVersion {
56
    /** Version identifier */
57
    readonly id: string;
58
    
59
    /** Last modification timestamp */
60
    readonly mtime?: number;
61
    
62
    /** Content hash */
63
    readonly etag?: string;
64
}
65
```
66

67
### URI System
68

69
Universal Resource Identifier handling with cross-platform path support.
70

71
```typescript { .api }
72
/**
73
 * URI class for resource identification
74
 */
75
class URI {
76
    /** URI scheme (file, http, theia, etc.) */
77
    readonly scheme: string;
78
    
79
    /** URI authority (hostname, etc.) */
80
    readonly authority: string;
81
    
82
    /** URI path */
83
    readonly path: string;
84
    
85
    /** URI query string */
86
    readonly query: string;
87
    
88
    /** URI fragment */
89
    readonly fragment: string;
90
    
91
    /**
92
     * Create file URI from file system path
93
     * @param path - File system path
94
     * @returns File URI
95
     */
96
    static file(path: string): URI;
97
    
98
    /**
99
     * Parse URI from string
100
     * @param value - URI string
101
     * @returns Parsed URI
102
     */
103
    static parse(value: string): URI;
104
    
105
    /**
106
     * Resolve relative URI against this URI
107
     * @param relative - Relative URI or path
108
     * @returns Resolved URI
109
     */
110
    resolve(relative: string | URI): URI;
111
    
112
    /**
113
     * Get relative path from this URI to target
114
     * @param target - Target URI
115
     * @returns Relative path or undefined
116
     */
117
    relative(target: URI): string | undefined;
118
    
119
    /**
120
     * Create new URI with modified properties
121
     * @param change - Properties to change
122
     * @returns New URI with changes
123
     */
124
    with(change: {
125
        scheme?: string;
126
        authority?: string;
127
        path?: string;
128
        query?: string;
129
        fragment?: string;
130
    }): URI;
131
    
132
    /**
133
     * Convert to string representation
134
     * @returns URI string
135
     */
136
    toString(): string;
137
    
138
    /**
139
     * Convert to file system path (file URIs only)
140
     * @returns File system path
141
     */
142
    fsPath: string;
143
}
144
```
145

146
**Usage Example:**
147

148
```typescript
149
import { URI } from "@theia/core";
150

151
// Create file URI
152
const fileUri = URI.file('/home/user/document.txt');
153
console.log(fileUri.toString()); // file:///home/user/document.txt
154

155
// Parse URI from string
156
const httpUri = URI.parse('https://example.com/api/data?format=json');
157
console.log(httpUri.scheme); // https
158
console.log(httpUri.authority); // example.com
159
console.log(httpUri.path); // /api/data
160
console.log(httpUri.query); // format=json
161

162
// Resolve relative paths
163
const baseUri = URI.file('/home/user/');
164
const resolvedUri = baseUri.resolve('documents/file.txt');
165
console.log(resolvedUri.fsPath); // /home/user/documents/file.txt
166

167
// Modify URI
168
const modifiedUri = httpUri.with({ 
169
    query: 'format=xml&limit=10' 
170
});
171
console.log(modifiedUri.toString()); // https://example.com/api/data?format=xml&limit=10
172
```
173

174
### Resource Provider
175

176
Service for obtaining resources from URIs with caching and resolution.
177

178
```typescript { .api }
179
/**
180
 * Provider for creating/obtaining resources
181
 */
182
interface ResourceProvider {
183
    /**
184
     * Get resource for URI
185
     * @param uri - Resource URI
186
     * @returns Promise resolving to resource
187
     */
188
    get(uri: URI): Promise<Resource>;
189
    
190
    /**
191
     * Check if provider can handle URI scheme
192
     * @param uri - URI to check
193
     * @returns True if provider can handle URI
194
     */
195
    canHandle(uri: URI): boolean;
196
}
197

198
/**
199
 * Service token for ResourceProvider
200
 */
201
const ResourceProvider: symbol;
202
```
203

204
### Resource Resolver
205

206
Lower-level interface for resolving URIs to resources.
207

208
```typescript { .api }
209
/**
210
 * Resolver for specific URI schemes
211
 */
212
interface ResourceResolver {
213
    /**
214
     * Resolve URI to resource
215
     * @param uri - URI to resolve
216
     * @returns Promise resolving to resource
217
     */
218
    resolve(uri: URI): Promise<Resource>;
219
    
220
    /**
221
     * Check if resolver supports URI
222
     * @param uri - URI to check
223
     * @returns True if resolver supports URI
224
     */
225
    canResolve(uri: URI): boolean;
226
}
227

228
/**
229
 * Service token for ResourceResolver
230
 */
231
const ResourceResolver: symbol;
232
```
233

234
### In-Memory Resources
235

236
In-memory resource implementations for virtual files and temporary content.
237

238
```typescript { .api }
239
/**
240
 * In-memory resource implementation
241
 */
242
class InMemoryResource implements Resource {
243
    readonly uri: URI;
244
    readonly version?: ResourceVersion;
245
    
246
    constructor(uri: URI, content?: string, version?: ResourceVersion);
247
    
248
    readContents(): Promise<string>;
249
    saveContents(content: string): Promise<void>;
250
    delete(): Promise<void>;
251
}
252

253
/**
254
 * In-memory text resource with encoding support
255
 */
256
class InMemoryTextResource extends InMemoryResource {
257
    readonly encoding: string;
258
    
259
    constructor(uri: URI, content?: string, encoding?: string);
260
}
261

262
/**
263
 * Collection of in-memory resources
264
 */
265
class InMemoryResources {
266
    /**
267
     * Add resource to collection
268
     * @param resource - Resource to add
269
     */
270
    add(resource: InMemoryResource): void;
271
    
272
    /**
273
     * Get resource by URI
274
     * @param uri - Resource URI
275
     * @returns Resource or undefined
276
     */
277
    get(uri: URI): InMemoryResource | undefined;
278
    
279
    /**
280
     * Remove resource from collection
281
     * @param uri - Resource URI to remove
282
     */
283
    delete(uri: URI): boolean;
284
    
285
    /**
286
     * Get all resources
287
     * @returns Array of all resources
288
     */
289
    getAll(): InMemoryResource[];
290
}
291
```
292

293
### Untitled Resources
294

295
Support for untitled/temporary files that haven't been saved to disk.
296

297
```typescript { .api }
298
/**
299
 * Resolver for untitled resources
300
 */
301
class UntitledResourceResolver implements ResourceResolver {
302
    resolve(uri: URI): Promise<UntitledResource>;
303
    canResolve(uri: URI): boolean;
304
}
305

306
/**
307
 * Untitled resource implementation
308
 */
309
class UntitledResource implements Resource {
310
    readonly uri: URI;
311
    readonly version?: ResourceVersion;
312
    
313
    constructor(uri: URI, content?: string);
314
    
315
    readContents(): Promise<string>;
316
    saveContents(content: string): Promise<void>;
317
    
318
    /**
319
     * Save to actual file URI
320
     * @param uri - Target file URI
321
     * @returns Promise that resolves when saved
322
     */
323
    saveAs(uri: URI): Promise<void>;
324
}
325

326
/**
327
 * URI scheme for untitled resources
328
 */
329
const UNTITLED_SCHEME = 'untitled';
330
```
331

332
## File System Integration
333

334
### File URI Utilities
335

336
Utilities for working with file system URIs.
337

338
```typescript { .api }
339
/**
340
 * File URI utilities
341
 */
342
class FileUri {
343
    /**
344
     * Create file URI from path
345
     * @param path - File system path
346
     * @returns File URI
347
     */
348
    static create(path: string): URI;
349
    
350
    /**
351
     * Get file system path from URI
352
     * @param uri - File URI
353
     * @returns File system path
354
     */
355
    static fsPath(uri: URI): string;
356
    
357
    /**
358
     * Check if URI is file URI
359
     * @param uri - URI to check
360
     * @returns True if file URI
361
     */
362
    static is(uri: URI): boolean;
363
}
364
```
365

366
### Resource Options
367

368
Configuration options for resource operations.
369

370
```typescript { .api }
371
/**
372
 * Options for reading resources
373
 */
374
interface ResourceReadOptions {
375
    /** Text encoding */
376
    encoding?: string;
377
    
378
    /** Expected version */
379
    version?: ResourceVersion;
380
    
381
    /** Byte range to read */
382
    range?: {
383
        start: number;
384
        end: number;
385
    };
386
}
387

388
/**
389
 * Options for saving resources
390
 */
391
interface ResourceSaveOptions {
392
    /** Text encoding */
393
    encoding?: string;
394
    
395
    /** Expected current version */
396
    version?: ResourceVersion;
397
    
398
    /** Create parent directories */
399
    createParents?: boolean;
400
    
401
    /** Overwrite existing */
402
    overwrite?: boolean;
403
}
404

405
/**
406
 * Resource stat information
407
 */
408
interface ResourceStat {
409
    /** Resource URI */
410
    readonly uri: URI;
411
    
412
    /** Last modification time */
413
    readonly mtime?: number;
414
    
415
    /** File size in bytes */
416
    readonly size?: number;
417
    
418
    /** True if resource is directory */
419
    readonly isDirectory: boolean;
420
    
421
    /** True if resource is read-only */
422
    readonly readonly?: boolean;
423
}
424
```
425

426
## Error Handling
427

428
### Resource Errors
429

430
Standardized error types for resource operations.
431

432
```typescript { .api }
433
/**
434
 * Resource error namespace
435
 */
436
namespace ResourceError {
437
    /**
438
     * Error when resource is not found
439
     */
440
    class NotFound extends Error {
441
        constructor(uri: URI);
442
        readonly uri: URI;
443
    }
444
    
445
    /**
446
     * Error when resource is out of sync
447
     */
448
    class OutOfSync extends Error {
449
        constructor(uri: URI, expectedVersion: ResourceVersion, actualVersion: ResourceVersion);
450
        readonly uri: URI;
451
        readonly expectedVersion: ResourceVersion;
452
        readonly actualVersion: ResourceVersion;
453
    }
454
    
455
    /**
456
     * Error when operation is not supported
457
     */
458
    class NotSupported extends Error {
459
        constructor(operation: string, uri: URI);
460
        readonly operation: string;
461
        readonly uri: URI;
462
    }
463
}
464
```
465

466
## Types
467

468
```typescript { .api }
469
/**
470
 * URI scheme constants
471
 */
472
const FILE_SCHEME = 'file';
473
const HTTP_SCHEME = 'http';
474
const HTTPS_SCHEME = 'https';
475
const MEMORY_TEXT = 'mem-txt';
476
const UNTITLED_SCHEME = 'untitled';
477

478
/**
479
 * Resource-related type aliases
480
 */
481
type ResourceChangeType = 'added' | 'updated' | 'deleted';
482

483
interface ResourceChange {
484
    readonly uri: URI;
485
    readonly type: ResourceChangeType;
486
}
487

488
type ResourceWatcher = {
489
    readonly onDidChange: Event<ResourceChange[]>;
490
    dispose(): void;
491
};
492
```