Open History to see the last commit
1/**
2 * Generate TypeScript source for JSON Schema declarations extracted from
3 * OpenAPI documents.
4 *
5 * This module is the schema-rendering stage of the OpenAPI generator. Callers
6 * register named OpenAPI 3.0 or 3.1 schemas, provide the reusable component
7 * definitions for the document, and receive source text containing exported
8 * TypeScript aliases plus Effect Schema runtime values. The generator first
9 * normalizes OpenAPI-specific schema shapes into Effect's JSON Schema model,
10 * then delegates recursive analysis and runtime expression construction to
11 * `SchemaRepresentation`.
12 *
13 * The renderer keeps the emitted module usable for both human maintainers and
14 * automated code-generation consumers by grouping recursive declarations,
15 * reusable references, and locally registered schemas. It also contains the
16 * HttpApi-specific multipart file substitutions that map generated schemas to
17 * Effect's multipart runtime types.
18 *
19 * @since 4.0.0
20 */
21import * as Arr from "effect/Array"
22import * as JsonSchema from "effect/JsonSchema"
23import * as Rec from "effect/Record"
24import * as Schema from "effect/Schema"
25import * as SchemaRepresentation from "effect/SchemaRepresentation"
26
27type Source = "openapi-3.0" | "openapi-3.1"
28interface GenerateOptions {
29 readonly onEnter?: ((js: JsonSchema.JsonSchema) => JsonSchema.JsonSchema) | undefined
30 readonly multipartSchemaRefs?: MultipartSchemaRefs | undefined
31 readonly includeSchemas?: ReadonlyArray<string> | undefined
32}
33
34interface HttpApiMultipartSchemaRefs {
35 readonly kind: "httpapi"
36 readonly singleFile: string
37 readonly files: string
38}
39
40type MultipartSchemaRefs = HttpApiMultipartSchemaRefs | { readonly kind: "client"; readonly singleFile: string }
41
42/**
43 * Create a stateful JSON Schema code generator for OpenAPI-derived schemas.
44 *
45 * **Details**
46 *
47 * Schemas registered with the returned generator are converted into TypeScript
48 * type aliases and Effect Schema runtime declarations, with reusable OpenAPI
49 * component definitions supplied at generation time.
50 *
51 * @category code generation
52 * @since 4.0.0
53 */
54export function make() {
55 return makeWithRepresentation()
56}
57
58function makeWithRepresentation() {
59 const store = Object.create(null) as Record<string, JsonSchema.JsonSchema>
60
61 function addSchema(name: string, schema: JsonSchema.JsonSchema): string {
62 if (Object.hasOwn(store, name)) {
63 throw new Error(`Schema ${name} already exists`)
64 }
65 store[name] = schema
66 return name
67 }
68
69 function generate(
70 source: Source,
71 components: JsonSchema.Definitions,
72 typeOnly: boolean,
73 options?: GenerateOptions
74 ) {
75 const generated = makeCodeDocument(source, components, options)
76 if (generated === undefined) {
77 return ""
78 }
79
80 const nonRecursiveReferences = generated.codeDocument.references.nonRecursives
81 const recursiveReferences = Object.entries(generated.codeDocument.references.recursives)
82
83 const nonRecursives = nonRecursiveReferences.map(({ $ref, code }) =>
84 renderSchemaTypeAndRuntime($ref, code, typeOnly, options)
85 )
86
87 const recursiveDeclarations: Array<string> = []
88 const recursives: Array<string> = []
89
90 if (typeOnly) {
91 for (const [$ref, code] of recursiveReferences) {
92 recursives.push(renderSchemaTypeAndRuntime($ref, code, true, options))
93 }
94 } else {
95 const recursivelyForwardReferenced = collectForwardReferencedRecursives(
96 nonRecursiveReferences,
97 recursiveReferences
98 )
99 const recursiveInternalNames = makeRecursiveInternalNameMap(
100 recursivelyForwardReferenced,
101 [
102 ...nonRecursiveReferences.map(({ $ref }) => $ref),
103 ...recursiveReferences.map(([$ref]) => $ref),
104 ...generated.nameMap
105 ]
106 )
107
108 for (const [$ref, code] of recursiveReferences) {
109 if (recursivelyForwardReferenced.has($ref)) {
110 const internalName = recursiveInternalNames.get($ref)!
111 recursiveDeclarations.push(renderRecursiveReferenceDeclaration($ref, code, internalName))
112 recursives.push(`const ${internalName} = ${code.runtime}`)
113 continue
114 }
115
116 recursives.push(renderSchemaTypeAndRuntime($ref, code, false, options))
117 }
118 }
119
120 const codes = generated.nameMap.map((name, i) =>
121 renderSchemaTypeAndRuntime(name, generated.codeDocument.codes[i], typeOnly, options)
122 )
123
124 return renderImportArtifacts(generated.codeDocument, !typeOnly) +
125 render("recursive declarations", recursiveDeclarations) +
126 render("non-recursive definitions", nonRecursives) +
127 render("recursive definitions", recursives) +
128 render("schemas", codes)
129 }
130
131 function generateHttpApi(
132 source: Source,
133 components: JsonSchema.Definitions,
134 options?: GenerateOptions
135 ) {
136 const generated = makeCodeDocument(source, components, options)
137 if (generated === undefined) {
138 return ""
139 }
140
141 const nonRecursiveReferences = generated.codeDocument.references.nonRecursives
142 const recursiveReferences = Object.entries(generated.codeDocument.references.recursives)
143
144 const nonRecursives = nonRecursiveReferences.map(({ $ref, code }) =>
145 renderSchemaTypeAndRuntime($ref, code, false, options)
146 )
147
148 const recursivelyForwardReferenced = collectForwardReferencedRecursives(nonRecursiveReferences, recursiveReferences)
149 const recursiveInternalNames = makeRecursiveInternalNameMap(
150 recursivelyForwardReferenced,
151 [
152 ...nonRecursiveReferences.map(({ $ref }) => $ref),
153 ...recursiveReferences.map(([$ref]) => $ref),
154 ...generated.nameMap
155 ]
156 )
157
158 const recursiveDeclarations: Array<string> = []
159 const recursives: Array<string> = []
160
161 for (const [$ref, code] of recursiveReferences) {
162 if (recursivelyForwardReferenced.has($ref)) {
163 const internalName = recursiveInternalNames.get($ref)!
164 recursiveDeclarations.push(renderRecursiveReferenceDeclaration($ref, code, internalName))
165 recursives.push(`const ${internalName} = ${code.runtime}`)
166 continue
167 }
168
169 recursives.push(renderSchemaTypeAndRuntime($ref, code, false, options))
170 }
171
172 const codes = generated.nameMap.map((name, i) =>
173 renderSchemaTypeAndRuntime(name, generated.codeDocument.codes[i], false, options)
174 )
175
176 return renderImportArtifacts(generated.codeDocument, true) +
177 render("recursive declarations", recursiveDeclarations) +
178 render("non-recursive definitions", nonRecursives) +
179 render("recursive definitions", recursives) +
180 render("schemas", codes)
181 }
182
183 function makeCodeDocument(
184 source: Source,
185 components: JsonSchema.Definitions,
186 options?: GenerateOptions
187 ): {
188 readonly nameMap: Array<string>
189 readonly codeDocument: SchemaRepresentation.CodeDocument
190 } | undefined {
191 const nameMap: Array<string> = []
192 const schemas: Array<JsonSchema.JsonSchema> = []
193
194 const definitions: JsonSchema.Definitions = Rec.map(
195 components,
196 (js) => fromSchemaOpenApi(source, js).schema
197 )
198
199 for (const [name, js] of Object.entries(store)) {
200 nameMap.push(name)
201 schemas.push(fromSchemaOpenApi(source, js).schema)
202 }
203 // Unnamed roots, so included components are emitted as definitions without an alias
204 for (const name of options?.includeSchemas ?? []) {
205 if (!Object.hasOwn(components, name)) {
206 throw new Error(`Included schema ${name} is not a component`)
207 }
208 schemas.push(fromSchemaOpenApi(source, { $ref: `#/components/schemas/${name}` }).schema)
209 }
210
211 if (!Arr.isArrayNonEmpty(schemas)) {
212 return
213 }
214
215 const document = {
216 dialect: "draft-2020-12" as const,
217 schemas,
218 definitions
219 }
220 const schemasWithExamples: Array<JsonSchema.JsonSchema> = []
221 const preparedSchemas = new WeakMap<JsonSchema.JsonSchema, JsonSchema.JsonSchema>()
222 const preparedOutputs = new WeakSet<JsonSchema.JsonSchema>()
223 const importerOptions: SchemaRepresentation.FromJsonSchemaOptions = {
224 patterns: "apply",
225 onEnter(js: JsonSchema.JsonSchema) {
226 if (preparedOutputs.has(js)) return js
227 const cached = preparedSchemas.get(js)
228 if (cached !== undefined) return cached
229
230 const out = { ...js }
231 const transformed = { ...(options?.onEnter === undefined ? out : options.onEnter(out)) }
232 preparedSchemas.set(js, transformed)
233 preparedOutputs.add(transformed)
234 if (Array.isArray(transformed.examples)) {
235 schemasWithExamples.push(transformed)
236 }
237 return transformed
238 }
239 }
240 let rootSchemas = SchemaRepresentation.fromJsonSchemaMultiDocument(document, importerOptions)
241 if (Arr.isArrayNonEmpty(schemasWithExamples)) {
242 const exampleSchemas = SchemaRepresentation.fromJsonSchemaMultiDocument(
243 { ...document, schemas: schemasWithExamples },
244 importerOptions
245 )
246 for (let i = 0; i < schemasWithExamples.length; i++) {
247 const node = schemasWithExamples[i]
248 const examples = node.examples as ReadonlyArray<unknown>
249 const validExamples = examples.filter(Schema.is(exampleSchemas[i]))
250 if (validExamples.length === examples.length) continue
251 if (validExamples.length === 0) {
252 delete node.examples
253 } else {
254 node.examples = validExamples
255 }
256 }
257 rootSchemas = SchemaRepresentation.fromJsonSchemaMultiDocument(document, importerOptions)
258 }
259 const codeDocument = SchemaRepresentation.toCodeDocument(
260 SchemaRepresentation.toRepresentations(Arr.map(rootSchemas, (schema) => schema.ast))
261 )
262
263 return {
264 nameMap,
265 codeDocument
266 }
267 }
268
269 return {
270 addSchema,
271 generate,
272 generateHttpApi,
273 schemas: store as Readonly<Record<string, JsonSchema.JsonSchema>>
274 } as const
275}
276
277function fromSchemaOpenApi(source: Source, jsonSchema: JsonSchema.JsonSchema) {
278 switch (source) {
279 case "openapi-3.1":
280 return JsonSchema.fromSchemaOpenApi3_1(jsonSchema)
281 case "openapi-3.0":
282 return JsonSchema.fromSchemaOpenApi3_0(jsonSchema)
283 }
284}
285
286function renderSchemaTypeAndRuntime(
287 $ref: string,
288 code: SchemaRepresentation.Code,
289 typeOnly: boolean,
290 options?: GenerateOptions
291) {
292 code = multipartCode($ref, options?.multipartSchemaRefs) ?? code
293 const strings = [`export type ${$ref} = ${code.Type}`]
294 if (!typeOnly) {
295 strings.push(`export const ${$ref} = ${code.runtime}`)
296 }
297 return strings.join("\n")
298}
299
300function multipartCode(
301 $ref: string,
302 refs: MultipartSchemaRefs | undefined
303): SchemaRepresentation.Code | undefined {
304 if (refs === undefined) {
305 return undefined
306 }
307 if ($ref === refs.singleFile) {
308 return refs.kind === "httpapi"
309 ? { Type: "Multipart.PersistedFile", runtime: "Multipart.SingleFileSchema" }
310 : {
311 Type: "globalThis.File | globalThis.Blob",
312 runtime: `Schema.instanceOf(globalThis.Blob, { expected: "File | Blob" })`
313 }
314 }
315 if (refs.kind === "httpapi" && $ref === refs.files) {
316 return { Type: "ReadonlyArray<Multipart.PersistedFile>", runtime: "Multipart.FilesSchema" }
317 }
318 return undefined
319}
320
321function renderRecursiveReferenceDeclaration(
322 $ref: string,
323 code: SchemaRepresentation.Code,
324 internalName: string
325): string {
326 return [
327 `export type ${$ref} = ${code.Type}`,
328 `export const ${$ref} = Schema.suspend((): Schema.Codec<${$ref}> => ${internalName})`
329 ].join("\n")
330}
331
332function render(title: string, as: ReadonlyArray<string>) {
333 if (as.length === 0) return ""
334 return "// " + title + "\n" + as.join("\n") + "\n"
335}
336
337function renderImportArtifacts(codeDocument: SchemaRepresentation.CodeDocument, enabled: boolean): string {
338 if (!enabled) return ""
339 const imports = codeDocument.artifacts.flatMap((artifact) =>
340 artifact._tag === "Import" ? [artifact.importDeclaration] : []
341 )
342 return imports.length === 0 ? "" : imports.join("\n") + "\n"
343}
344
345const tokenPattern = /[A-Za-z_$][A-Za-z0-9_$]*/g
346
347function collectForwardReferencedRecursives(
348 nonRecursives: ReadonlyArray<{
349 readonly $ref: string
350 readonly code: SchemaRepresentation.Code
351 }>,
352 recursives: ReadonlyArray<readonly [string, SchemaRepresentation.Code]>
353): Set<string> {
354 const recursiveNames = new Set(recursives.map(([name]) => name))
355 const recursiveIndexes = new Map(recursives.map(([name], index) => [name, index]))
356 const referenced = new Set<string>()
357
358 for (const { code } of nonRecursives) {
359 for (const token of code.runtime.matchAll(tokenPattern)) {
360 const identifier = token[0]
361 if (recursiveNames.has(identifier)) {
362 referenced.add(identifier)
363 }
364 }
365 }
366
367 for (let index = 0; index < recursives.length; index++) {
368 const [, code] = recursives[index]
369 for (const token of code.runtime.matchAll(tokenPattern)) {
370 const identifier = token[0]
371 const referencedIndex = recursiveIndexes.get(identifier)
372 if (referencedIndex !== undefined && referencedIndex > index) {
373 referenced.add(identifier)
374 }
375 }
376 }
377
378 return referenced
379}
380
381function makeRecursiveInternalNameMap(
382 recursiveNames: ReadonlySet<string>,
383 existingNames: ReadonlyArray<string>
384): Map<string, string> {
385 const usedNames = new Set(existingNames)
386 const internalNames = new Map<string, string>()
387
388 for (const name of recursiveNames) {
389 let candidate = `__recursive_${name}`
390 while (usedNames.has(candidate)) {
391 candidate = `_${candidate}`
392 }
393 usedNames.add(candidate)
394 internalNames.set(name, candidate)
395 }
396
397 return internalNames
398}