/**
* Generate TypeScript source for JSON Schema declarations extracted from
* OpenAPI documents.
*
* This module is the schema-rendering stage of the OpenAPI generator. Callers
* register named OpenAPI 3.0 or 3.1 schemas, provide the reusable component
* definitions for the document, and receive source text containing exported
* TypeScript aliases plus Effect Schema runtime values. The generator first
* normalizes OpenAPI-specific schema shapes into Effect's JSON Schema model,
* then delegates recursive analysis and runtime expression construction to
* `SchemaRepresentation`.
*
* The renderer keeps the emitted module usable for both human maintainers and
* automated code-generation consumers by grouping recursive declarations,
* reusable references, and locally registered schemas. It also contains the
* HttpApi-specific multipart file substitutions that map generated schemas to
* Effect's multipart runtime types.
*
* @since 4.0.0
*/
import * as Arr from "effect/Array"
import * as JsonSchema from "effect/JsonSchema"
import * as Rec from "effect/Record"
import * as Schema from "effect/Schema"
import * as SchemaRepresentation from "effect/SchemaRepresentation"
type Source = "openapi-3.0" | "openapi-3.1"
interface GenerateOptions {
readonly onEnter?: ((js: JsonSchema.JsonSchema) => JsonSchema.JsonSchema) | undefined
readonly multipartSchemaRefs?: MultipartSchemaRefs | undefined
readonly includeSchemas?: ReadonlyArray<string> | undefined
}
interface HttpApiMultipartSchemaRefs {
readonly kind: "httpapi"
readonly singleFile: string
readonly files: string
}
type MultipartSchemaRefs = HttpApiMultipartSchemaRefs | { readonly kind: "client"; readonly singleFile: string }
/**
* Create a stateful JSON Schema code generator for OpenAPI-derived schemas.
*
* **Details**
*
* Schemas registered with the returned generator are converted into TypeScript
* type aliases and Effect Schema runtime declarations, with reusable OpenAPI
* component definitions supplied at generation time.
*
* @category code generation
* @since 4.0.0
*/
export function make() {
return makeWithRepresentation()
}
function makeWithRepresentation() {
const store = Object.create(null) as Record<string, JsonSchema.JsonSchema>
function addSchema(name: string, schema: JsonSchema.JsonSchema): string {
if (Object.hasOwn(store, name)) {
throw new Error(`Schema ${name} already exists`)
}
store[name] = schema
return name
}
function generate(
source: Source,
components: JsonSchema.Definitions,
typeOnly: boolean,
options?: GenerateOptions
) {
const generated = makeCodeDocument(source, components, options)
if (generated === undefined) {
return ""
}
const nonRecursiveReferences = generated.codeDocument.references.nonRecursives
const recursiveReferences = Object.entries(generated.codeDocument.references.recursives)
const nonRecursives = nonRecursiveReferences.map(({ $ref, code }) =>
renderSchemaTypeAndRuntime($ref, code, typeOnly, options)
)
const recursiveDeclarations: Array<string> = []
const recursives: Array<string> = []
if (typeOnly) {
for (const [$ref, code] of recursiveReferences) {
recursives.push(renderSchemaTypeAndRuntime($ref, code, true, options))
}
} else {
const recursivelyForwardReferenced = collectForwardReferencedRecursives(
nonRecursiveReferences,
recursiveReferences
)
const recursiveInternalNames = makeRecursiveInternalNameMap(
recursivelyForwardReferenced,
[
...nonRecursiveReferences.map(({ $ref }) => $ref),
...recursiveReferences.map(([$ref]) => $ref),
...generated.nameMap
]
)
for (const [$ref, code] of recursiveReferences) {
if (recursivelyForwardReferenced.has($ref)) {
const internalName = recursiveInternalNames.get($ref)!
recursiveDeclarations.push(renderRecursiveReferenceDeclaration($ref, code, internalName))
recursives.push(`const ${internalName} = ${code.runtime}`)
continue
}
recursives.push(renderSchemaTypeAndRuntime($ref, code, false, options))
}
}
const codes = generated.nameMap.map((name, i) =>
renderSchemaTypeAndRuntime(name, generated.codeDocument.codes[i], typeOnly, options)
)
return renderImportArtifacts(generated.codeDocument, !typeOnly) +
render("recursive declarations", recursiveDeclarations) +
render("non-recursive definitions", nonRecursives) +
render("recursive definitions", recursives) +
render("schemas", codes)
}
function generateHttpApi(
source: Source,
components: JsonSchema.Definitions,
options?: GenerateOptions
) {
const generated = makeCodeDocument(source, components, options)
if (generated === undefined) {
return ""
}
const nonRecursiveReferences = generated.codeDocument.references.nonRecursives
const recursiveReferences = Object.entries(generated.codeDocument.references.recursives)
const nonRecursives = nonRecursiveReferences.map(({ $ref, code }) =>
renderSchemaTypeAndRuntime($ref, code, false, options)
)
const recursivelyForwardReferenced = collectForwardReferencedRecursives(nonRecursiveReferences, recursiveReferences)
const recursiveInternalNames = makeRecursiveInternalNameMap(
recursivelyForwardReferenced,
[
...nonRecursiveReferences.map(({ $ref }) => $ref),
...recursiveReferences.map(([$ref]) => $ref),
...generated.nameMap
]
)
const recursiveDeclarations: Array<string> = []
const recursives: Array<string> = []
for (const [$ref, code] of recursiveReferences) {
if (recursivelyForwardReferenced.has($ref)) {
const internalName = recursiveInternalNames.get($ref)!
recursiveDeclarations.push(renderRecursiveReferenceDeclaration($ref, code, internalName))
recursives.push(`const ${internalName} = ${code.runtime}`)
continue
}
recursives.push(renderSchemaTypeAndRuntime($ref, code, false, options))
}
const codes = generated.nameMap.map((name, i) =>
renderSchemaTypeAndRuntime(name, generated.codeDocument.codes[i], false, options)
)
return renderImportArtifacts(generated.codeDocument, true) +
render("recursive declarations", recursiveDeclarations) +
render("non-recursive definitions", nonRecursives) +
render("recursive definitions", recursives) +
render("schemas", codes)
}
function makeCodeDocument(
source: Source,
components: JsonSchema.Definitions,
options?: GenerateOptions
): {
readonly nameMap: Array<string>
readonly codeDocument: SchemaRepresentation.CodeDocument
} | undefined {
const nameMap: Array<string> = []
const schemas: Array<JsonSchema.JsonSchema> = []
const definitions: JsonSchema.Definitions = Rec.map(
components,
(js) => fromSchemaOpenApi(source, js).schema
)
for (const [name, js] of Object.entries(store)) {
nameMap.push(name)
schemas.push(fromSchemaOpenApi(source, js).schema)
}
// Unnamed roots, so included components are emitted as definitions without an alias
for (const name of options?.includeSchemas ?? []) {
if (!Object.hasOwn(components, name)) {
throw new Error(`Included schema ${name} is not a component`)
}
schemas.push(fromSchemaOpenApi(source, { $ref: `#/components/schemas/${name}` }).schema)
}
if (!Arr.isArrayNonEmpty(schemas)) {
return
}
const document = {
dialect: "draft-2020-12" as const,
schemas,
definitions
}
const schemasWithExamples: Array<JsonSchema.JsonSchema> = []
const preparedSchemas = new WeakMap<JsonSchema.JsonSchema, JsonSchema.JsonSchema>()
const preparedOutputs = new WeakSet<JsonSchema.JsonSchema>()
const importerOptions: SchemaRepresentation.FromJsonSchemaOptions = {
patterns: "apply",
onEnter(js: JsonSchema.JsonSchema) {
if (preparedOutputs.has(js)) return js
const cached = preparedSchemas.get(js)
if (cached !== undefined) return cached
const out = { ...js }
const transformed = { ...(options?.onEnter === undefined ? out : options.onEnter(out)) }
preparedSchemas.set(js, transformed)
preparedOutputs.add(transformed)
if (Array.isArray(transformed.examples)) {
schemasWithExamples.push(transformed)
}
return transformed
}
}
let rootSchemas = SchemaRepresentation.fromJsonSchemaMultiDocument(document, importerOptions)
if (Arr.isArrayNonEmpty(schemasWithExamples)) {
const exampleSchemas = SchemaRepresentation.fromJsonSchemaMultiDocument(
{ ...document, schemas: schemasWithExamples },
importerOptions
)
for (let i = 0; i < schemasWithExamples.length; i++) {
const node = schemasWithExamples[i]
const examples = node.examples as ReadonlyArray<unknown>
const validExamples = examples.filter(Schema.is(exampleSchemas[i]))
if (validExamples.length === examples.length) continue
if (validExamples.length === 0) {
delete node.examples
} else {
node.examples = validExamples
}
}
rootSchemas = SchemaRepresentation.fromJsonSchemaMultiDocument(document, importerOptions)
}
const codeDocument = SchemaRepresentation.toCodeDocument(
SchemaRepresentation.toRepresentations(Arr.map(rootSchemas, (schema) => schema.ast))
)
return {
nameMap,
codeDocument
}
}
return {
addSchema,
generate,
generateHttpApi,
schemas: store as Readonly<Record<string, JsonSchema.JsonSchema>>
} as const
}
function fromSchemaOpenApi(source: Source, jsonSchema: JsonSchema.JsonSchema) {
switch (source) {
case "openapi-3.1":
return JsonSchema.fromSchemaOpenApi3_1(jsonSchema)
case "openapi-3.0":
return JsonSchema.fromSchemaOpenApi3_0(jsonSchema)
}
}
function renderSchemaTypeAndRuntime(
$ref: string,
code: SchemaRepresentation.Code,
typeOnly: boolean,
options?: GenerateOptions
) {
code = multipartCode($ref, options?.multipartSchemaRefs) ?? code
const strings = [`export type ${$ref} = ${code.Type}`]
if (!typeOnly) {
strings.push(`export const ${$ref} = ${code.runtime}`)
}
return strings.join("\n")
}
function multipartCode(
$ref: string,
refs: MultipartSchemaRefs | undefined
): SchemaRepresentation.Code | undefined {
if (refs === undefined) {
return undefined
}
if ($ref === refs.singleFile) {
return refs.kind === "httpapi"
? { Type: "Multipart.PersistedFile", runtime: "Multipart.SingleFileSchema" }
: {
Type: "globalThis.File | globalThis.Blob",
runtime: `Schema.instanceOf(globalThis.Blob, { expected: "File | Blob" })`
}
}
if (refs.kind === "httpapi" && $ref === refs.files) {
return { Type: "ReadonlyArray<Multipart.PersistedFile>", runtime: "Multipart.FilesSchema" }
}
return undefined
}
function renderRecursiveReferenceDeclaration(
$ref: string,
code: SchemaRepresentation.Code,
internalName: string
): string {
return [
`export type ${$ref} = ${code.Type}`,
`export const ${$ref} = Schema.suspend((): Schema.Codec<${$ref}> => ${internalName})`
].join("\n")
}
function render(title: string, as: ReadonlyArray<string>) {
if (as.length === 0) return ""
return "// " + title + "\n" + as.join("\n") + "\n"
}
function renderImportArtifacts(codeDocument: SchemaRepresentation.CodeDocument, enabled: boolean): string {
if (!enabled) return ""
const imports = codeDocument.artifacts.flatMap((artifact) =>
artifact._tag === "Import" ? [artifact.importDeclaration] : []
)
return imports.length === 0 ? "" : imports.join("\n") + "\n"
}
const tokenPattern = /[A-Za-z_$][A-Za-z0-9_$]*/g
function collectForwardReferencedRecursives(
nonRecursives: ReadonlyArray<{
readonly $ref: string
readonly code: SchemaRepresentation.Code
}>,
recursives: ReadonlyArray<readonly [string, SchemaRepresentation.Code]>
): Set<string> {
const recursiveNames = new Set(recursives.map(([name]) => name))
const recursiveIndexes = new Map(recursives.map(([name], index) => [name, index]))
const referenced = new Set<string>()
for (const { code } of nonRecursives) {
for (const token of code.runtime.matchAll(tokenPattern)) {
const identifier = token[0]
if (recursiveNames.has(identifier)) {
referenced.add(identifier)
}
}
}
for (let index = 0; index < recursives.length; index++) {
const [, code] = recursives[index]
for (const token of code.runtime.matchAll(tokenPattern)) {
const identifier = token[0]
const referencedIndex = recursiveIndexes.get(identifier)
if (referencedIndex !== undefined && referencedIndex > index) {
referenced.add(identifier)
}
}
}
return referenced
}
function makeRecursiveInternalNameMap(
recursiveNames: ReadonlySet<string>,
existingNames: ReadonlyArray<string>
): Map<string, string> {
const usedNames = new Set(existingNames)
const internalNames = new Map<string, string>()
for (const name of recursiveNames) {
let candidate = `__recursive_${name}`
while (usedNames.has(candidate)) {
candidate = `_${candidate}`
}
usedNames.add(candidate)
internalNames.set(name, candidate)
}
return internalNames
}