0
# quicktype-core
1

2
quicktype-core is the core TypeScript library that powers the quicktype code generation tool. It provides a comprehensive engine for generating strongly-typed models and serializers from JSON, JSON Schema, TypeScript, and GraphQL queries across multiple programming languages. The library exposes a programmatic API that allows developers to integrate quicktype's functionality into their own applications, offering fine-grained control over code generation through customizable options, target language selection, and input data processing.
3

4
## Package Information
5

6
- **Package Name**: quicktype-core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install quicktype-core`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  quicktype, 
16
  quicktypeMultiFile,
17
  InputData,
18
  JSONInput,
19
  jsonInputForTargetLanguage,
20
  JSONSchemaInput,
21
  getTargetLanguage,
22
  type Options 
23
} from "quicktype-core";
24
```
25

26
For CommonJS:
27

28
```javascript
29
const { 
30
  quicktype, 
31
  quicktypeMultiFile,
32
  InputData,
33
  JSONInput,
34
  jsonInputForTargetLanguage
35
} = require("quicktype-core");
36
```
37

38
## Basic Usage
39

40
```typescript
41
import { quicktype, InputData, jsonInputForTargetLanguage } from "quicktype-core";
42

43
// Create input data container
44
const inputData = new InputData();
45

46
// Add JSON sample data  
47
const jsonInput = jsonInputForTargetLanguage("typescript");
48
await jsonInput.addSource({
49
  name: "Person",
50
  samples: ['{"name": "John", "age": 30, "active": true}']
51
});
52
inputData.addInput(jsonInput);
53

54
// Generate TypeScript code
55
const result = await quicktype({
56
  lang: "typescript",
57
  inputData,
58
  outputFilename: "Person.ts"
59
});
60

61
console.log(result.lines.join('\n'));
62
```
63

64
## Architecture
65

66
quicktype-core is built around several key components:
67

68
- **Core Generation Engine**: Primary `quicktype()` functions that orchestrate the entire code generation process
69
- **Input System**: Flexible input handling supporting JSON samples, JSON Schema, and other formats
70
- **Type System**: Comprehensive type representation with inference, transformation, and graph-based processing
71
- **Target Language System**: Extensible rendering system supporting 20+ programming languages
72
- **Options & Configuration**: Fine-grained control over generation behavior through options and inference flags
73

74
## Capabilities
75

76
### Core Code Generation
77

78
Primary functions for generating strongly-typed code from various input formats, with support for single-file and multi-file output scenarios.
79

80
```typescript { .api }
81
function quicktype(options: Partial<Options>): Promise<SerializedRenderResult>;
82
function quicktypeMultiFile(options: Partial<Options>): Promise<MultiFileRenderResult>;
83
function quicktypeMultiFileSync(options: Partial<Options>): MultiFileRenderResult;
84

85
interface Options extends NonInferenceOptions, InferenceFlags {
86
  lang: string | TargetLanguage;
87
  inputData: InputData;
88
  outputFilename: string;
89
  rendererOptions: RendererOptions;
90
  alphabetizeProperties: boolean;
91
  allPropertiesOptional: boolean;
92
}
93

94
interface SerializedRenderResult {
95
  lines: string[];
96
  annotations: Annotation[];
97
}
98

99
type MultiFileRenderResult = ReadonlyMap<string, SerializedRenderResult>;
100
```
101

102
[Core Generation](./core-generation.md)
103

104
### Input Data Management
105

106
Comprehensive input handling system supporting JSON samples, JSON Schema, and other data formats with flexible source management.
107

108
```typescript { .api }
109
class InputData {
110
  addInput<T>(input: Input<T>): void;
111
  addSource<T>(kind: string, source: T, makeInput: () => Input<T>): Promise<void>;
112
  addSourceSync<T>(kind: string, source: T, makeInput: () => Input<T>): void;
113
}
114

115
function jsonInputForTargetLanguage(
116
  targetLanguage: string | TargetLanguage,
117
  languages?: TargetLanguage[],
118
  handleJSONRefs?: boolean
119
): JSONInput<string>;
120

121
interface JSONSourceData<T> {
122
  name: string;
123
  samples: T[];
124
  description?: string;
125
}
126
```
127

128
[Input Management](./input-management.md)
129

130
### JSON Schema Support
131

132
Dedicated support for JSON Schema input with reference resolution, schema validation, and comprehensive type attribute handling.
133

134
```typescript { .api }
135
class JSONSchemaInput {
136
  constructor(
137
    schemaStore?: JSONSchemaStore,
138
    additionalAttributeProducers?: JSONSchemaAttributeProducer[],
139
    additionalSchemaAddresses?: readonly string[]
140
  );
141
  addSource(source: JSONSchemaSourceData): Promise<void>;
142
}
143

144
interface JSONSchemaSourceData {
145
  name: string;
146
  uris?: string[];
147
  schema?: string;
148
  isConverted?: boolean;
149
}
150

151
class Ref {
152
  static root(address?: string): Ref;
153
  static parse(ref: string): Ref;
154
  push(...keys: string[]): Ref;
155
  resolveAgainst(base?: Ref): Ref;
156
}
157
```
158

159
[JSON Schema](./json-schema.md)
160

161
### Type System
162

163
Advanced type system with comprehensive type representation, inference capabilities, and graph-based type processing for accurate code generation.
164

165
```typescript { .api }
166
abstract class Type {
167
  readonly kind: TypeKind;
168
  readonly typeRef: TypeRef;
169
  getChildren(): ReadonlySet<Type>;
170
  getAttributes(): TypeAttributes;
171
  getNames(): TypeNames;
172
  structurallyCompatible(other: Type, conflateNumbers?: boolean): boolean;
173
}
174

175
class TypeBuilder {
176
  constructor(
177
    stringTypeMapping: StringTypeMapping,
178
    canonicalOrder: boolean,
179
    allPropertiesOptional: boolean,
180
    addProvenanceAttributes: boolean,
181
    inheritsProvenanceAttributes: boolean
182
  );
183
  getPrimitiveType(kind: PrimitiveTypeKind, attributes?: TypeAttributes): TypeRef;
184
  getArrayType(attributes: TypeAttributes, items: TypeRef): TypeRef;
185
  getClassType(attributes: TypeAttributes, properties: ReadonlyMap<string, ClassProperty>): TypeRef;
186
  getEnumType(attributes: TypeAttributes, cases: ReadonlySet<string>): TypeRef;
187
  getUnionType(attributes: TypeAttributes, members: ReadonlySet<TypeRef>): TypeRef;
188
  finish(): TypeGraph;
189
}
190

191
type TypeKind = PrimitiveTypeKind | ObjectTypeKind | "array" | "enum" | "union" | "intersection";
192
type PrimitiveTypeKind = "none" | "any" | "null" | "bool" | "integer" | "double" | "string" | "date-time" | "uuid" | "uri" | "integer-string" | "bool-string";
193
```
194

195
[Type System](./type-system.md)
196

197
### Target Languages & Rendering
198

199
Extensible target language system supporting code generation for 20+ programming languages with customizable rendering options.
200

201
```typescript { .api }
202
abstract class TargetLanguage {
203
  readonly displayName: string;
204
  readonly names: readonly string[];
205
  readonly extension: string;
206
  readonly stringTypeMapping: StringTypeMapping;
207
  readonly supportsOptionalClassProperties: boolean;
208
  abstract makeRenderer(renderContext: RenderContext, optionValues: RendererOptions): Renderer;
209
  renderGraphAndSerialize(
210
    typeGraph: TypeGraph,
211
    outputFilename: string,
212
    alphabetizeProperties: boolean,
213
    leadingComments?: Comment[],
214
    rendererOptions: RendererOptions,
215
    indentation?: string
216
  ): MultiFileRenderResult;
217
}
218

219
function getTargetLanguage(nameOrInstance: string | TargetLanguage): TargetLanguage;
220
```
221

222
[Target Languages](./target-languages.md)
223

224
### Configuration & Options
225

226
Comprehensive configuration system with inference flags, renderer options, and debugging capabilities for fine-tuned code generation control.
227

228
```typescript { .api }
229
interface InferenceFlags {
230
  inferMaps: boolean;
231
  inferEnums: boolean;
232
  inferUuids: boolean;
233
  inferDateTimes: boolean;
234
  inferIntegerStrings: boolean;
235
  inferBooleanStrings: boolean;
236
  combineClasses: boolean;
237
  ignoreJsonRefs: boolean;
238
}
239

240
const defaultInferenceFlags: InferenceFlags;
241
const inferenceFlags: Record<InferenceFlagName, InferenceFlag>;
242

243
class Option<Name, T> {
244
  definition: OptionDefinition<Name, T>;
245
}
246

247
interface OptionDefinition<Name, T> {
248
  name: Name;
249
  type: OptionType<T>;
250
  defaultValue: T;
251
  description: string;
252
  typeLabel?: string;
253
}
254
```
255

256
[Configuration](./configuration.md)
257

258
### Utilities & Support
259

260
Essential utility functions for string processing, JSON parsing, error handling, and various support operations used throughout the library.
261

262
```typescript { .api }
263
// Core utilities
264
function panic(message: string): never;
265
function assert(condition: boolean, message?: string): void;
266
function defined<T>(value: T | undefined): T;
267
function parseJSON(text: string, description: string, address?: string): any;
268

269
// String utilities  
270
function splitIntoWords(str: string): string[];
271
function capitalize(str: string): string;
272
function combineWords(words: string[]): string;
273
function firstUpperWordStyle(words: string[]): string;
274
function allUpperWordStyle(words: string[]): string;
275
function legalizeCharacters(str: string, isLegal: (char: string) => boolean): string;
276

277
// Type utilities
278
function removeNullFromUnion(t: Type): Type;
279
function matchType<T>(t: Type, matchers: Record<TypeKind, (t: Type) => T>): T;
280
function nullableFromUnion(t: Type): Type | null;
281
```
282

283
[Utilities](./utilities.md)