0
# AutoRest Core
1

2
AutoRest Core is the foundational module of the AutoRest code generation tool, which generates client libraries for accessing RESTful web services from OpenAPI specifications. This package provides the core functionality for parsing, validating, and transforming OpenAPI specs into code generation artifacts, serving as the central processing engine that coordinates with language-specific generators.
3

4
## Package Information
5

6
- **Package Name**: @microsoft.azure/autorest-core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @microsoft.azure/autorest-core`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  AutoRest, 
16
  ConfigurationView, 
17
  IFileSystem, 
18
  Message, 
19
  Channel, 
20
  Artifact,
21
  IdentifyDocument,
22
  LiterateToJson,
23
  IsConfigurationDocument,
24
  IsOpenApiDocument,
25
  IsConfigurationExtension,
26
  IsOpenApiExtension,
27
  DocumentType,
28
  DocumentFormat,
29
  DocumentExtension,
30
  DocumentPatterns
31
} from "@microsoft.azure/autorest-core";
32

33
// File system implementations (not re-exported from main, import directly)
34
import { RealFileSystem, MemoryFileSystem, EnhancedFileSystem } from "@microsoft.azure/autorest-core/lib/file-system";
35
```
36

37
For CommonJS:
38

39
```javascript
40
const { 
41
  AutoRest, 
42
  ConfigurationView, 
43
  IFileSystem, 
44
  Message, 
45
  Channel, 
46
  Artifact 
47
} = require("@microsoft.azure/autorest-core");
48
```
49

50
## Basic Usage
51

52
```typescript
53
import { AutoRest } from "@microsoft.azure/autorest-core";
54
import { RealFileSystem } from "@microsoft.azure/autorest-core/lib/file-system";
55

56
// Create AutoRest instance with file system
57
const autorest = new AutoRest(new RealFileSystem(), "./autorest-config.json");
58

59
// Add configuration
60
autorest.AddConfiguration({
61
  "input-file": "swagger.json",
62
  "output-folder": "./generated",
63
  "namespace": "MyClient"
64
});
65

66
// Listen to events  
67
const unsubscribeGenerated = autorest.GeneratedFile.Subscribe((autorest, artifact) => {
68
  console.log(`Generated: ${artifact.uri}`);
69
});
70

71
const unsubscribeMessage = autorest.Message.Subscribe((autorest, message) => {
72
  console.log(`${message.Channel}: ${message.Text}`);
73
});
74

75
// Start processing
76
const { finish, cancel } = autorest.Process();
77
const result = await finish;
78
```
79

80
## Architecture
81

82
AutoRest Core is built around several key components:
83

84
- **AutoRest Class**: Main generator instance that orchestrates the entire process
85
- **File System Abstraction**: Pluggable file system implementations (Real, Memory, Enhanced)
86
- **Configuration System**: Hierarchical configuration loading and management
87
- **Message System**: Event-driven communication with detailed logging and error reporting  
88
- **Pipeline System**: Extensible processing pipeline with plugin support
89
- **Document Processing**: OpenAPI and configuration document identification and parsing
90
- **Type System**: Complete TypeScript integration with full type definitions
91

92
## Capabilities
93

94
### AutoRest Generator
95

96
Main generator class that coordinates the entire code generation process with event-driven architecture and configuration management.
97

98
```typescript { .api }
99
class AutoRest {
100
  constructor(fileSystem?: IFileSystem, configFileOrFolderUri?: string);
101
  view: Promise<ConfigurationView>;
102
  AddConfiguration(configuration: any): void;
103
  ResetConfiguration(): Promise<void>;
104
  Process(): { finish: Promise<boolean | Error>, cancel: () => void };
105
  
106
  // Events
107
  Finished: IEvent<AutoRest, boolean | Error>;
108
  GeneratedFile: IEvent<AutoRest, Artifact>;
109
  ClearFolder: IEvent<AutoRest, string>;
110
  Message: IEvent<AutoRest, Message>;
111
}
112
```
113

114
[AutoRest Generator](./autorest-generator.md)
115

116
### File System Operations
117

118
File system abstraction providing pluggable implementations for different environments, including real file system, in-memory operations, and GitHub integration.
119

120
```typescript { .api }
121
interface IFileSystem {
122
  EnumerateFileUris(folderUri: string): Promise<Array<string>>;
123
  ReadFile(uri: string): Promise<string>;
124
}
125

126
class RealFileSystem implements IFileSystem {
127
  constructor();
128
  EnumerateFileUris(folderUri: string): Promise<string[]>;
129
  ReadFile(uri: string): Promise<string>;
130
  WriteFile(uri: string, content: string): Promise<void>;
131
}
132

133
class MemoryFileSystem implements IFileSystem {
134
  constructor(files: Map<string, string>);
135
  readonly Outputs: Map<string, string>;
136
  ReadFile(uri: string): Promise<string>;
137
  EnumerateFileUris(folderUri?: string): Promise<Array<string>>;
138
  WriteFile(uri: string, content: string): Promise<void>;
139
}
140

141
class EnhancedFileSystem implements IFileSystem {
142
  constructor(githubAuthToken?: string);
143
  EnumerateFileUris(folderUri: string): Promise<string[]>;
144
  ReadFile(uri: string): Promise<string>;
145
  WriteFile(uri: string, content: string): Promise<void>;
146
}
147
```
148

149
[File System Operations](./file-system.md)
150

151
### Document Processing
152

153
Document type identification and format detection for OpenAPI specifications and configuration files.
154

155
```typescript { .api }
156
function IdentifyDocument(content: string): Promise<DocumentType>;
157
function LiterateToJson(content: string): Promise<string>;
158
function IsConfigurationDocument(content: string): Promise<boolean>;
159
function IsOpenApiDocument(content: string): Promise<boolean>;
160
function IsConfigurationExtension(extension: string): Promise<boolean>;
161
function IsOpenApiExtension(extension: string): Promise<boolean>;
162

163
enum DocumentType {
164
  OpenAPI2 = "OpenAPI2",
165
  OpenAPI3 = "OpenAPI3", 
166
  LiterateConfiguration = "LiterateConfiguration",
167
  Unknown = "Unknown"
168
}
169

170
enum DocumentFormat {
171
  Markdown = "markdown",
172
  Yaml = "yaml",
173
  Json = "json", 
174
  Unknown = "unknown"
175
}
176

177
const DocumentExtension: {
178
  yaml: DocumentFormat.Yaml;
179
  yml: DocumentFormat.Yaml;
180
  json: DocumentFormat.Json;
181
  md: DocumentFormat.Markdown;
182
  markdown: DocumentFormat.Markdown;
183
};
184

185
const DocumentPatterns: {
186
  yaml: string[];
187
  json: string[];
188
  markdown: string[];
189
  all: string[];
190
};
191
```
192

193
[Document Processing](./document-processing.md)
194

195
### Configuration Management
196

197
Hierarchical configuration system with support for multiple configuration sources and view-based access patterns.
198

199
```typescript { .api }
200
class ConfigurationView {
201
  // Configuration access and management methods
202
}
203

204
interface AutoRestConfigurationImpl {
205
  // Core processing options
206
  "input-file"?: string | string[];
207
  "output-folder"?: string;
208
  "base-folder"?: string;
209
  
210
  // Processing flags
211
  "debug"?: boolean;
212
  "verbose"?: boolean;
213
  "message-format"?: string;
214
  
215
  // Plugin options
216
  "use-extension"?: string | string[];
217
  "require"?: string | string[];
218
  "directive"?: any[];
219
  
220
  // Language-specific options
221
  "namespace"?: string;
222
  "package-name"?: string;
223
}
224
```
225

226
[Configuration Management](./configuration.md)
227

228
### Message System
229

230
Event-driven messaging system with structured logging, error reporting, and multi-channel communication.
231

232
```typescript { .api }
233
interface Message {
234
  Channel: Channel;
235
  Key?: Iterable<string>;
236
  Details?: any;
237
  Text: string;
238
  Source?: Array<SourceLocation>;
239
  Range?: Iterable<Range>;
240
  Plugin?: string;
241
  FormattedMessage?: string;
242
}
243

244
enum Channel {
245
  Information = "information",
246
  Warning = "warning", 
247
  Error = "error",
248
  Debug = "debug",
249
  Verbose = "verbose",
250
  Fatal = "fatal",
251
  Hint = "hint",
252
  File = "file",
253
  Configuration = "configuration"
254
}
255

256
interface Artifact {
257
  uri: string;
258
  type: string;
259
  content: string;
260
}
261
```
262

263
[Message System](./messaging.md)
264

265
## Binary Entry Points
266

267
The package provides two CLI tools:
268

269
- **autorest-core**: Main CLI for processing OpenAPI specifications (`dist/app.js`)
270
- **autorest-language-service**: Language service for editor integration (`dist/language-service/language-service.js`)
271

272

273
## Types
274

275
```typescript { .api }
276
interface SourceLocation {
277
  document: string;
278
  Position: EnhancedPosition;
279
}
280

281
interface Range {
282
  document: string;
283
  start: Position;
284
  end: Position;
285
}
286

287
interface Position {
288
  line: number;
289
  column: number;
290
}
291

292
interface IEvent<TSender, TArgs> {
293
  Subscribe(fn: (sender: TSender, args: TArgs) => void): () => void;
294
  Unsubscribe(fn: (sender: TSender, args: TArgs) => void): void;
295
  Dispatch(args: TArgs): void;
296
}
297
```