0
# File System Operations
1

2
AutoRest Core provides a pluggable file system abstraction that supports different environments and use cases. This includes real file system access, in-memory operations for testing, and enhanced GitHub integration with authentication.
3

4
## Capabilities
5

6
### File System Interface
7

8
Base interface that all file system implementations must provide.
9

10
```typescript { .api }
11
/**
12
 * Interface for file system operations used by AutoRest
13
 */
14
interface IFileSystem {
15
  /**
16
   * Enumerates all file URIs in a given folder
17
   * @param folderUri - URI of the folder to enumerate
18
   * @returns Promise resolving to array of file URIs
19
   */
20
  EnumerateFileUris(folderUri: string): Promise<Array<string>>;
21

22
  /**
23
   * Reads the content of a file
24
   * @param uri - URI of the file to read
25
   * @returns Promise resolving to file content as string
26
   */
27
  ReadFile(uri: string): Promise<string>;
28
}
29
```
30

31
### Real File System
32

33
Implementation for accessing the actual file system of the host machine.
34

35
```typescript { .api }
36
/**
37
 * Real file system implementation for accessing actual files
38
 */
39
class RealFileSystem implements IFileSystem {
40
  /**
41
   * Creates a new RealFileSystem instance
42
   */
43
  constructor();
44

45
  /**
46
   * Enumerates file URIs in a folder, filtering for configuration files
47
   * @param folderUri - URI of the folder to enumerate
48
   * @returns Promise resolving to array of file URIs
49
   */
50
  EnumerateFileUris(folderUri: string): Promise<string[]>;
51

52
  /**
53
   * Reads content from a file URI
54
   * @param uri - URI of the file to read
55
   * @returns Promise resolving to file content
56
   */
57
  ReadFile(uri: string): Promise<string>;
58

59
  /**
60
   * Writes content to a file URI
61
   * @param uri - URI of the file to write
62
   * @param content - Content to write
63
   * @returns Promise that resolves when write completes
64
   */
65
  WriteFile(uri: string, content: string): Promise<void>;
66
}
67
```
68

69
**Usage Examples:**
70

71
```typescript
72
import { RealFileSystem } from "@microsoft.azure/autorest-core/lib/file-system";
73

74
const fs = new RealFileSystem();
75

76
// Read a configuration file
77
const config = await fs.ReadFile("file:///path/to/autorest.json");
78
console.log("Config:", JSON.parse(config));
79

80
// List files in a directory
81
const files = await fs.EnumerateFileUris("file:///path/to/specs/");
82
console.log("Spec files:", files);
83

84
// Write generated output
85
await fs.WriteFile(
86
  "file:///output/generated-client.ts", 
87
  "// Generated client code here"
88
);
89
```
90

91
### Memory File System
92

93
In-memory file system implementation useful for testing and scenarios where file operations should not touch the actual file system.
94

95
```typescript { .api }
96
/**
97
 * In-memory file system implementation for testing and isolated operations
98
 */
99
class MemoryFileSystem implements IFileSystem {
100
  /** Default virtual root URI for memory file system */
101
  static readonly DefaultVirtualRootUri: string = "file:///";
102

103
  /**
104
   * Creates a new MemoryFileSystem with initial files
105
   * @param files - Map of relative paths to file contents
106
   */
107
  constructor(files: Map<string, string>);
108

109
  /**
110
   * Output files written during processing
111
   */
112
  readonly Outputs: Map<string, string>;
113

114
  /**
115
   * Reads content from a memory file
116
   * @param uri - URI of the file to read
117
   * @returns Promise resolving to file content
118
   * @throws Error if file doesn't exist
119
   */
120
  ReadFile(uri: string): Promise<string>;
121

122
  /**
123
   * Enumerates files in a virtual folder
124
   * @param folderUri - URI of the folder (defaults to root)
125
   * @returns Promise resolving to array of file URIs
126
   */
127
  EnumerateFileUris(folderUri?: string): Promise<Array<string>>;
128

129
  /**
130
   * Writes content to memory (stored in Outputs map)
131
   * @param uri - URI of the file to write
132
   * @param content - Content to write
133
   * @returns Promise that resolves when write completes
134
   */
135
  WriteFile(uri: string, content: string): Promise<void>;
136
}
137
```
138

139
**Usage Examples:**
140

141
```typescript
142
import { MemoryFileSystem } from "@microsoft.azure/autorest-core/lib/file-system";
143

144
// Create with initial files
145
const initialFiles = new Map([
146
  ["swagger.json", JSON.stringify({ swagger: "2.0", info: { title: "Test API" } })],
147
  ["config.json", JSON.stringify({ "output-folder": "./generated" })]
148
]);
149

150
const memFs = new MemoryFileSystem(initialFiles);
151

152
// Read existing file
153
const swagger = await memFs.ReadFile("file:///swagger.json");
154
console.log("Swagger spec:", JSON.parse(swagger));
155

156
// List all files  
157
const files = await memFs.EnumerateFileUris();
158
console.log("Available files:", files);
159

160
// Write new file (goes to Outputs)
161
await memFs.WriteFile("file:///generated/client.ts", "export class ApiClient {}");
162

163
// Check outputs
164
console.log("Generated files:", Array.from(memFs.Outputs.keys()));
165
console.log("Client content:", memFs.Outputs.get("file:///generated/client.ts"));
166
```
167

168
### Enhanced File System
169

170
Enhanced file system with GitHub integration and authentication support.
171

172
```typescript { .api }
173
/**
174
 * Enhanced file system with GitHub URI adjustment and authentication
175
 */
176
class EnhancedFileSystem implements IFileSystem {
177
  /**
178
   * Creates enhanced file system with optional GitHub authentication
179
   * @param githubAuthToken - Optional GitHub OAuth token for private repos
180
   */
181
  constructor(githubAuthToken?: string);
182

183
  /**
184
   * Enumerates file URIs in a folder, filtering for configuration files
185
   * @param folderUri - URI of the folder to enumerate
186
   * @returns Promise resolving to array of file URIs
187
   */
188
  EnumerateFileUris(folderUri: string): Promise<string[]>;
189

190
  /**
191
   * Reads content from URI with GitHub authentication support
192
   * @param uri - URI of the file to read (automatically converts GitHub URLs to raw format)
193
   * @returns Promise resolving to file content
194
   */
195
  ReadFile(uri: string): Promise<string>;
196

197
  /**
198
   * Writes content to a file URI
199
   * @param uri - URI of the file to write
200
   * @param content - Content to write
201
   * @returns Promise that resolves when write completes
202
   */  
203
  WriteFile(uri: string, content: string): Promise<void>;
204
}
205
```
206

207
**Usage Examples:**
208

209
```typescript
210
import { EnhancedFileSystem } from "@microsoft.azure/autorest-core/lib/file-system";
211

212
// Create with GitHub token for private repositories
213
const enhancedFs = new EnhancedFileSystem("ghp_your_github_token_here");
214

215
// Read from GitHub (automatically converts to raw URL and adds auth)
216
const spec = await enhancedFs.ReadFile(
217
  "https://github.com/myorg/private-specs/blob/main/api.json"
218
);
219

220
// Read from public GitHub repo (no auth needed)
221
const publicSpec = await enhancedFs.ReadFile(
222
  "https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/TextAnalytics/preview/v3.1/TextAnalytics.json"
223
);
224

225
// Enumerate files in a local folder
226
const localFiles = await enhancedFs.EnumerateFileUris("file:///specs/");
227
```
228

229
## File System Utilities
230

231
The file system implementations work with various URI formats and provide automatic conversion for GitHub URLs.
232

233
### Supported URI Formats
234

235
- **File URIs**: `file:///absolute/path/to/file.json`
236
- **HTTP/HTTPS**: `https://example.com/api.json`  
237
- **GitHub URLs**: Automatically converted from blob URLs to raw URLs
238
- **Relative paths**: Resolved against base URIs
239

240
### GitHub Integration Features
241

242
- Automatic URL conversion from GitHub blob URLs to raw content URLs
243
- OAuth token authentication for private repositories  
244
- Standard GitHub API rate limiting support
245
- Proper header handling for authenticated requests