/**
* The `OpenApiGenerator` module orchestrates converting OpenAPI and Swagger
* documents into generated Effect source.
*
* It normalizes Swagger 2.0 input, resolves local references, builds the
* parsed operation model, registers request and response schemas, applies
* HttpApi-specific adaptations such as multipart helpers and security metadata,
* emits warnings for unsupported or lossy OpenAPI features, and then delegates
* final rendering to the HttpClient or HttpApi code generators.
*
* @since 4.0.0
*/
import * as Context from "effect/Context"
import * as Effect from "effect/Effect"
import type { OpenAPISecurityScheme, OpenAPISpec, OpenAPISpecOperation } from "effect/http-api/OpenApi"
import type { HttpMethod } from "effect/http/HttpMethod"
import * as JsonPointer from "effect/JsonPointer"
import type * as JsonSchema from "effect/JsonSchema"
import * as Layer from "effect/Layer"
import * as Predicate from "effect/Predicate"
import * as Rec from "effect/Record"
import * as String from "effect/String"
import SwaggerToOpenApi from "swagger2openapi"
import * as HttpApiTransformer from "./HttpApiTransformer.ts"
import * as JsonSchemaGenerator from "./JsonSchemaGenerator.ts"
import * as OpenApiTransformer from "./OpenApiTransformer.ts"
import * as ParsedOperation from "./ParsedOperation.ts"
import * as Utils from "./Utils.ts"
/**
* Service for turning OpenAPI or Swagger specifications into generated Effect
* HTTP client or HttpApi source code.
*
* @category services
* @since 4.0.0
*/
export class OpenApiGenerator extends Context.Service<
OpenApiGenerator,
{ readonly generate: (spec: OpenAPISpec, options: OpenApiGenerateOptions) => Effect.Effect<string> }
>()("OpenApiGenerator") {}
/**
* Output targets supported by the OpenAPI generator.
*
* **Details**
*
* The `httpclient` and `httpclient-type-only` formats support non-security
* cookie parameters with primitive schemas, which generated clients send in
* the request `Cookie` header. Cookie parameters with structured schemas, such
* as objects or arrays, are dropped with a `cookie-parameter-dropped` warning.
* The `httpapi` format drops all non-security cookie parameters.
*
* The `Cookie` header is set before the request reaches the supplied
* `HttpClient`, so it is subject to that client's request transformations.
* Browsers manage the `Cookie` header themselves and ignore explicit values,
* and `HttpClient.withCookiesRef` replaces the header whenever its cookie jar
* is non-empty.
*
* @category models
* @since 4.0.0
*/
export type OpenApiGeneratorFormat = "httpclient" | "httpclient-type-only" | "httpapi"
/**
* Stable identifiers for non-fatal OpenAPI generation warnings.
*
* @category models
* @since 4.0.0
*/
export type OpenApiGeneratorWarningCode =
| "cookie-parameter-dropped"
| "additional-tags-dropped"
| "sse-operation-skipped"
| "response-headers-ignored"
| "optional-request-body-approximated"
| "default-response-remapped"
| "security-and-downgraded"
| "no-body-method-request-body-skipped"
| "streaming-request-body-skipped"
| "naming-collision"
/**
* Describes a non-fatal issue encountered while mapping an OpenAPI operation to
* generated Effect source.
*
* @category models
* @since 4.0.0
*/
export interface OpenApiGeneratorWarning {
readonly code: OpenApiGeneratorWarningCode
readonly message: string
readonly path?: string | undefined
readonly method?: Lowercase<HttpMethod> | undefined
readonly operationId?: string | undefined
}
/**
* Formats a generation warning as a single human-readable line.
*
* **Details**
*
* The line starts with `WARNING [code]`, followed by the HTTP method, path and
* operation id when the warning carries them, then the warning message.
*
* **Example** (Formatting an operation warning)
*
* ```ts import.meta.vitest
* import { formatWarning } from "@effect/openapi-generator/OpenApiGenerator"
*
* formatWarning({
* code: "cookie-parameter-dropped",
* message: "Cookie parameter was dropped.",
* path: "/items",
* method: "get",
* operationId: "listItems"
* }) // => "WARNING [cookie-parameter-dropped] GET /items (listItems): Cookie parameter was dropped."
* ```
*
* @category formatting
* @since 4.0.0
*/
export const formatWarning = (warning: OpenApiGeneratorWarning): string => {
const context = [
warning.method?.toUpperCase(),
warning.path,
warning.operationId ? `(${warning.operationId})` : undefined
].filter((value): value is string => value !== undefined)
return context.length > 0
? `WARNING [${warning.code}] ${context.join(" ")}: ${warning.message}`
: `WARNING [${warning.code}] ${warning.message}`
}
/**
* Options that control one OpenAPI generation run.
*
* @category options
* @since 4.0.0
*/
export interface OpenApiGenerateOptions {
/**
* The name to give to the generated output.
*/
readonly name: string
/**
* The output format to generate.
*/
readonly format: OpenApiGeneratorFormat
/**
* Hook to transform each JSON Schema node before processing.
*/
readonly onEnter?: ((js: JsonSchema.JsonSchema) => JsonSchema.JsonSchema) | undefined
/**
* Component schemas to generate even when no operation references them.
*/
readonly includeSchemas?: ReadonlyArray<string> | undefined
/**
* Callback to receive non-fatal generation warnings.
*/
readonly onWarning?: ((warning: OpenApiGeneratorWarning) => void) | undefined
}
interface HttpApiMultipartSchemaRefs {
readonly kind: "httpapi"
readonly singleFile: string
readonly files: string
}
type MultipartSchemaRefs = HttpApiMultipartSchemaRefs | { readonly kind: "client"; readonly singleFile: string }
const methodNames: ReadonlyArray<Lowercase<HttpMethod>> = [
"get",
"put",
"post",
"delete",
"options",
"head",
"patch",
"trace",
"query"
]
/**
* Constructs the OpenAPI generator service implementation.
*
* @category constructors
* @since 4.0.0
*/
export const make = Effect.gen(function*() {
const generate = Effect.fn(
function*(spec: OpenAPISpec, options: OpenApiGenerateOptions) {
const generator = JsonSchemaGenerator.make()
const openApiTransformer = yield* OpenApiTransformer.OpenApiTransformer
const emitWarning = makeWarningEmitter(options)
if (isSwaggerSpec(spec)) {
spec = yield* convertSwaggerSpec(spec)
}
function resolveRef(ref: string) {
const parts = ref.split("/").slice(1).map(JsonPointer.unescapeToken)
let current: any = spec
for (const part of parts) {
current = current[part]
}
return current
}
const multipart = makeMultipartSchemas(spec, options.format, resolveRef)
const parsed = parseOpenApi(spec, generator, resolveRef, options.format, emitWarning, multipart.transform)
multipart.finish(generator.schemas)
// TODO: make a CLI option ?
const importName = "Schema"
const source = getDialect(spec)
const schemaOptions = {
onEnter: options.onEnter,
multipartSchemaRefs: multipart.refs,
includeSchemas: options.includeSchemas
}
const generation = options.format === "httpapi"
? generator.generateHttpApi(source, multipart.definitions, schemaOptions)
: generator.generate(source, multipart.definitions, options.format === "httpclient-type-only", schemaOptions)
if (options.format === "httpapi") {
const needsMultipartImport = generation.includes("Multipart.")
return String.stripMargin(
`|${HttpApiTransformer.imports(importName, { multipart: needsMultipartImport })}
|${generation}
|${HttpApiTransformer.toImplementation(importName, options.name, parsed)}`
)
}
return String.stripMargin(
`|${openApiTransformer.imports(importName, parsed)}
|${generation}
|${openApiTransformer.toImplementation(importName, options.name, parsed)}
|
|${openApiTransformer.toTypes(importName, options.name, parsed)}`
)
},
(effect, _, options) =>
Effect.provideServiceEffect(
effect,
OpenApiTransformer.OpenApiTransformer,
options.format === "httpclient-type-only"
? Effect.sync(OpenApiTransformer.makeTransformerTs)
: Effect.sync(OpenApiTransformer.makeTransformerSchema)
)
)
return { generate } as const
})
type WarningEmitter = (warning: OpenApiGeneratorWarning) => void
const makeWarningEmitter = (options: OpenApiGenerateOptions): WarningEmitter => (warning) => {
options.onWarning?.(warning)
}
const parseOpenApi = (
spec: OpenAPISpec,
generator: ReturnType<typeof JsonSchemaGenerator.make>,
resolveRef: (ref: string) => unknown,
format: OpenApiGeneratorFormat,
emitWarning: WarningEmitter,
transformMultipart: (schema: JsonSchema.JsonSchema) => JsonSchema.JsonSchema
): ParsedOperation.ParsedOpenApi => {
const operations: Array<ParsedOperation.ParsedOperation> = []
const reservedSchemaNames = new Set<string>(Object.keys(spec.components?.schemas ?? {}))
const isHttpApi = format === "httpapi"
const securitySchemes = isHttpApi ? parseSecuritySchemes(spec, resolveRef) : []
const addSchema = (
baseName: string,
schema: JsonSchema.JsonSchema,
operation: ParsedOperation.ParsedOperation
): string => {
let candidate = baseName
let index = 2
while (reservedSchemaNames.has(candidate)) {
candidate = `${baseName}${index}`
index += 1
}
if (candidate !== baseName) {
warnForOperation(emitWarning, operation, {
code: "naming-collision",
message: `Schema name "${baseName}" collided with an existing name and was renamed to "${candidate}".`
})
}
reservedSchemaNames.add(candidate)
return generator.addSchema(candidate, schema)
}
for (const [path, methods] of Object.entries(spec.paths)) {
const pathItem: Partial<Record<Lowercase<HttpMethod>, OpenAPISpecOperation>> = methods
for (const method of methodNames) {
const operation = method === "query"
? pathItem.query ?? methods["x-oai-additionalOperations"]?.QUERY
: pathItem[method]
if (Predicate.isUndefined(operation)) {
continue
}
const id = operation.operationId
? Utils.camelize(operation.operationId)
: `${method.toUpperCase()}${path}`
const description = Utils.nonEmptyString(operation.description) ?? Utils.nonEmptyString(operation.summary)
const { pathIds, pathTemplate } = processPath(path)
const op = ParsedOperation.makeDeepMutable({
id,
method,
description,
pathIds,
pathTemplate
})
const httpClientResponses = op.httpClientResponses
op.path = path
op.operationId = Utils.nonEmptyString(operation.operationId)
op.tags = [...(operation.tags ?? [])]
if (isHttpApi && op.tags.length > 1) {
warnForOperation(emitWarning, op, {
code: "additional-tags-dropped",
message: `Additional tags (${op.tags.slice(1).join(", ")}) were dropped. Only the first tag ("${
op.tags[0]
}") is used for grouping.`
})
}
op.metadata = {
summary: Utils.nonEmptyString(operation.summary),
description: Utils.nonEmptyString(operation.description),
deprecated: operation.deprecated === true,
externalDocs: operation.externalDocs
}
op.effectiveSecurity = cloneSecurityRequirements(operation.security ?? spec.security ?? [])
if (isHttpApi) {
warnForAndSecurityRequirements(emitWarning, op)
}
const schemaId = Utils.identifier(operation.operationId ?? path)
const pathParameters = Array.isArray(methods.parameters)
? methods.parameters
: undefined
const parameters = resolveOperationParameters(
pathParameters,
Array.isArray(operation.parameters) ? operation.parameters : undefined,
resolveRef
)
const droppedCookies = new Set<OpenApiParameter>()
for (const parameter of parameters) {
const parsedParameter: ParsedOperation.ParsedOperationParameter = {
name: parameter.name,
in: parameter.in,
required: parameter.required === true,
description: Utils.nonEmptyString(parameter.description),
schema: parameter.schema
}
switch (parameter.in) {
case "path": {
op.parameters.path.push(parsedParameter)
break
}
case "query": {
op.parameters.query.push(parsedParameter)
if ((parameter.style ?? "form") === "form" && parameter.explode === false) {
op.commaUrlParams.push(parameter.name)
}
break
}
case "header": {
op.parameters.header.push(parsedParameter)
break
}
case "cookie": {
op.parameters.cookie.push(parsedParameter)
const dropReason = isHttpApi
? "non-security cookie parameters are not supported"
: isPrimitiveSchema(parameter.schema, resolveRef)
? undefined
: "only primitive cookie parameter schemas are supported"
if (dropReason !== undefined) {
droppedCookies.add(parameter)
warnForOperation(emitWarning, op, {
code: "cookie-parameter-dropped",
message: `Cookie parameter "${parameter.name}" was dropped because ${dropReason}.`
})
}
break
}
}
}
const requestBody = resolveReference(operation.requestBody, resolveRef)
if (isHttpApi && !methodSupportsRequestBody(op.method) && Predicate.isObject(requestBody)) {
warnForOperation(emitWarning, op, {
code: "no-body-method-request-body-skipped",
message: `Operation was skipped because ${op.method.toUpperCase()} does not support request bodies.`
})
continue
}
const resolvedResponses = Object.entries(operation.responses ?? {})
.filter(([status]) => isResponseStatus(status))
.map(([status, response]) => [status, resolveReference(response, resolveRef)] as const)
const hasExplicitSuccessResponse = resolvedResponses.some(([status]) => {
if (!/^\d{3}$/.test(status)) {
return false
}
return Number(status) < 400
})
if (isHttpApi && hasUnsupportedSuccessfulSseResponse(resolvedResponses, hasExplicitSuccessResponse)) {
warnForOperation(emitWarning, op, {
code: "sse-operation-skipped",
message:
"Operation was skipped because a successful SSE response is missing x-effect-stream metadata required for HttpApi generation."
})
continue
}
const validParameters = parameters.filter((parameter) =>
parameter.in !== "path" && !droppedCookies.has(parameter)
)
const combinedParameterSchema = buildParameterSchema(validParameters, (parameter, added) => {
if (parameter.in === "query") {
Utils.spreadElementsInto(added, op.urlParams)
} else if (parameter.in === "header") {
Utils.spreadElementsInto(added, op.headers)
} else if (parameter.in === "cookie") {
Utils.spreadElementsInto(added, op.cookies)
}
})
if (combinedParameterSchema !== undefined) {
op.params = addSchema(`${schemaId}Params`, combinedParameterSchema.schema, op)
op.paramsOptional = combinedParameterSchema.optional
}
if (isHttpApi) {
const pathParameterSchema = buildParameterSchema(op.parameters.path)
if (pathParameterSchema !== undefined) {
op.pathSchema = addSchema(`${schemaId}PathParams`, pathParameterSchema.schema, op)
}
const queryParameterSchema = buildParameterSchema(op.parameters.query)
if (queryParameterSchema !== undefined) {
op.querySchema = addSchema(`${schemaId}Query`, queryParameterSchema.schema, op)
op.querySchemaOptional = queryParameterSchema.optional
}
const headerParameterSchema = buildParameterSchema(op.parameters.header)
if (headerParameterSchema !== undefined) {
op.headersSchema = addSchema(`${schemaId}Headers`, headerParameterSchema.schema, op)
op.headersSchemaOptional = headerParameterSchema.optional
}
}
if (Predicate.isNotUndefined(requestBody) && Predicate.isObject(requestBody)) {
const content = Predicate.isObject(requestBody.content)
? requestBody.content as Record<string, any>
: {}
const requestSchemaNames = new Map<string, string>()
op.requestBody = {
required: requestBody.required === true,
contentTypes: Object.keys(content)
}
if (isHttpApi && requestBody.required === false) {
warnForOperation(emitWarning, op, {
code: "optional-request-body-approximated",
message: "Optional request body was approximated by adding a no-content payload alternative."
})
}
if (Predicate.isNotUndefined(content["application/json"]?.schema)) {
op.payload = addSchema(`${schemaId}RequestJson`, content["application/json"].schema, op)
requestSchemaNames.set("application/json", op.payload)
}
if (
Predicate.isNotUndefined(content["multipart/form-data"]?.schema) &&
!(isHttpApi && getEffectStreamEncoding(content["multipart/form-data"]) === "ndjson")
) {
op.payload = addSchema(
`${schemaId}RequestFormData`,
transformMultipart(content["multipart/form-data"].schema),
op
)
op.payloadFormData = true
requestSchemaNames.set("multipart/form-data", op.payload)
}
if (Predicate.isNotUndefined(content["application/x-www-form-urlencoded"]?.schema)) {
op.payload = addSchema(
`${schemaId}RequestFormUrlEncoded`,
content["application/x-www-form-urlencoded"].schema,
op
)
op.payloadFormUrlEncoded = true
requestSchemaNames.set("application/x-www-form-urlencoded", op.payload)
}
if (isHttpApi) {
const representableRequestBody: Array<ParsedOperation.ParsedOperationMediaTypeSchema> = []
for (const [contentType, mediaType] of Object.entries(content)) {
if (!Predicate.isObject(mediaType)) {
continue
}
const streamEncoding = getEffectStreamEncoding(mediaType)
if (
streamEncoding !== "ndjson" &&
unsupportedStreamingRequestMediaTypes.has(normalizeMediaType(contentType))
) {
warnForOperation(emitWarning, op, {
code: "streaming-request-body-skipped",
message: `Request body media type ${contentType} was skipped because HttpApi cannot stream it.`
})
continue
}
if (streamEncoding === "uint8array") {
representableRequestBody.push({
contentType,
encoding: "binary",
effectStream: "uint8array"
})
continue
}
const ndjsonSchema = getNdjsonElementSchema(contentType, mediaType)
if (Predicate.isNotUndefined(ndjsonSchema)) {
representableRequestBody.push({
contentType,
encoding: "json",
effectStream: "ndjson",
schema: requestSchemaNames.get(contentType) ?? addSchema(
`${schemaId}Request${mediaTypeToSuffix(contentType)}`,
ndjsonSchema,
op
)
})
continue
}
if (Predicate.isUndefined(mediaType.schema)) {
continue
}
const encoding = getRequestMediaTypeEncoding(contentType)
if (encoding === undefined) {
continue
}
let schemaName = requestSchemaNames.get(contentType)
if (schemaName === undefined) {
const schema = encoding === "multipart"
? transformMultipart(mediaType.schema as JsonSchema.JsonSchema)
: mediaType.schema as JsonSchema.JsonSchema
schemaName = addSchema(
`${schemaId}Request${mediaTypeToSuffix(contentType)}`,
schema,
op
)
requestSchemaNames.set(contentType, schemaName)
}
representableRequestBody.push({
contentType,
encoding,
schema: schemaName
})
}
op.requestBodyRepresentable = representableRequestBody
}
}
let defaultSchema: string | undefined
for (const [status, response] of resolvedResponses) {
if (!Predicate.isObject(response)) {
continue
}
const parsedStatus = isHttpApi
? remapDefaultResponseStatusForHttpApi(status, hasExplicitSuccessResponse)
: status
if (isHttpApi && status === "default") {
warnForOperation(emitWarning, op, {
code: "default-response-remapped",
message: `Default response was remapped to status ${parsedStatus} for HttpApi generation.`
})
}
const content = Predicate.isObject(response.content)
? response.content as Record<string, any>
: undefined
if (isHttpApi && Predicate.isNotUndefined(response.headers)) {
warnForOperation(emitWarning, op, {
code: "response-headers-ignored",
message: `Response headers on status ${status} were ignored in HttpApi generation.`
})
}
const representable: Array<ParsedOperation.ParsedOperationMediaTypeSchema> = []
let jsonSchemaName: string | undefined
let jsonResponseContentType: string | undefined
if (isHttpApi) {
const jsonResponseEntries = Object.entries(content ?? {}).filter(([contentType, mediaType]) =>
isJsonMediaType(normalizeMediaType(contentType)) &&
Predicate.isObject(mediaType) &&
Predicate.isNotUndefined(mediaType.schema) &&
!(isSuccessStatus(parsedStatus) && getEffectStreamEncoding(mediaType) === "ndjson")
)
const jsonResponseEntry = jsonResponseEntries.find(([contentType]) =>
normalizeMediaType(contentType) === "application/json"
) ?? jsonResponseEntries[0]
if (Predicate.isNotUndefined(jsonResponseEntry)) {
const [contentType, mediaType] = jsonResponseEntry
jsonResponseContentType = contentType
jsonSchemaName = addSchema(`${schemaId}${status}`, mediaType.schema as JsonSchema.JsonSchema, op)
representable.push({
contentType,
encoding: "json",
schema: jsonSchemaName
})
}
} else {
const jsonSchemas = Object.entries(content ?? {}).flatMap(([contentType, mediaType]) =>
isJsonMediaType(normalizeMediaType(contentType)) &&
Predicate.isObject(mediaType) &&
Predicate.isNotUndefined(mediaType.schema)
? [mediaType.schema as JsonSchema.JsonSchema]
: []
)
if (jsonSchemas.length > 0) {
jsonSchemaName = addSchema(
`${schemaId}${status}`,
jsonSchemas.length === 1 ? jsonSchemas[0] : { anyOf: jsonSchemas },
op
)
}
}
if (isHttpApi) {
for (const [contentType, mediaType] of Object.entries(content ?? {})) {
if (contentType === jsonResponseContentType) {
continue
}
if (!Predicate.isObject(mediaType)) {
continue
}
const streamEncoding = isSuccessStatus(parsedStatus)
? getEffectStreamEncoding(mediaType)
: undefined
if (streamEncoding === "uint8array") {
representable.push({
contentType,
encoding: "binary",
effectStream: "uint8array"
})
continue
}
const ndjsonSchema = isSuccessStatus(parsedStatus)
? getNdjsonElementSchema(contentType, mediaType)
: undefined
if (Predicate.isNotUndefined(ndjsonSchema)) {
representable.push({
contentType,
encoding: "json",
effectStream: "ndjson",
schema: addSchema(
`${schemaId}${status}${mediaTypeToSuffix(contentType)}`,
ndjsonSchema,
op
)
})
continue
}
if (streamEncoding === "sse") {
const errorSchema = getEffectStreamErrorSchema(mediaType)
if (Predicate.isUndefined(mediaType.schema) || Predicate.isUndefined(errorSchema)) {
continue
}
representable.push({
contentType,
encoding: "text",
effectStream: "sse",
schema: addSchema(
`${schemaId}${status}Sse`,
mediaType.schema as JsonSchema.JsonSchema,
op
),
errorSchema: addSchema(
`${schemaId}${status}SseError`,
errorSchema,
op
)
})
continue
}
if (Predicate.isUndefined(mediaType.schema)) {
continue
}
const encoding = getResponseMediaTypeEncoding(contentType)
if (encoding === undefined) {
continue
}
const schemaName = addSchema(
`${schemaId}${status}${mediaTypeToSuffix(contentType)}`,
mediaType.schema as JsonSchema.JsonSchema,
op
)
representable.push({
contentType,
encoding,
schema: schemaName
})
}
}
const isEmptyResponse = Predicate.isUndefined(content) || Object.keys(content).length === 0
const parsedResponse = {
status: parsedStatus,
description: Utils.nonEmptyString(response.description),
contentTypes: Predicate.isNotUndefined(content) ? Object.keys(content) : [],
hasHeaders: Predicate.isNotUndefined(response.headers),
isEmpty: isEmptyResponse,
representable
}
op.responses.push(parsedResponse)
if (status === "default") {
op.defaultResponse = parsedResponse
}
const normalizedStatus = parsedStatus.toLowerCase()
const hasBinaryResponse = Object.entries(content ?? {}).some(([contentType, mediaType]) =>
Predicate.isObject(mediaType) &&
(isBinaryMediaType(normalizeMediaType(contentType)) || isBinarySchema(mediaType.schema))
)
if (hasBinaryResponse && isSuccessStatus(parsedStatus)) {
httpClientResponses.binarySuccessStatuses.add(normalizedStatus)
}
if (Predicate.isNotUndefined(jsonSchemaName)) {
if (status === "default" && !isHttpApi) {
defaultSchema = jsonSchemaName
continue
}
if (Number.isNaN(Number(parsedStatus[0]))) {
continue
}
if (isSuccessStatus(parsedStatus)) {
if (!httpClientResponses.binarySuccessStatuses.has(normalizedStatus)) {
httpClientResponses.successSchemas.set(normalizedStatus, jsonSchemaName)
}
} else {
httpClientResponses.errorSchemas.set(normalizedStatus, jsonSchemaName)
}
}
const sseMediaType = content?.["text/event-stream"]
const sseResponseSchema = sseMediaType?.schema
if (
!isHttpApi && Predicate.isUndefined(httpClientResponses.sseSchema) &&
Predicate.isNotUndefined(sseResponseSchema) &&
isSuccessStatus(parsedStatus)
) {
const effectStream = sseMediaType["x-effect-stream"]
httpClientResponses.sseSchemaMode = getEffectStreamEncoding(sseMediaType) === "sse" ? "event" : "data"
httpClientResponses.sseSchema = addSchema(
`${schemaId}${status}Sse`,
httpClientResponses.sseSchemaMode === "event"
? makeSseEventSchema(
resolveReference(sseResponseSchema, resolveRef),
effectStream?.encoding === "sse" ? effectStream.failureEvent : undefined
)
: sseResponseSchema,
op
)
}
if (isEmptyResponse && parsedStatus !== "default") {
if (isSuccessStatus(normalizedStatus)) {
httpClientResponses.voidSuccessStatuses.add(normalizedStatus)
} else {
httpClientResponses.voidErrorStatuses.add(normalizedStatus)
}
}
}
if (
!isHttpApi && httpClientResponses.successSchemas.size === 0 && Predicate.isNotUndefined(defaultSchema)
) {
httpClientResponses.successSchemas.set("2xx", defaultSchema)
warnForOperation(emitWarning, op, {
code: "default-response-remapped",
message: "Default response was remapped to 2xx for the current HttpClient outputs."
})
}
operations.push(op)
}
}
return {
metadata: {
title: spec.info.title,
version: spec.info.version,
summary: Utils.nonEmptyString(spec.info.summary),
description: Utils.nonEmptyString(spec.info.description),
license: spec.info.license,
servers: spec.servers
},
tags: (spec.tags ?? []).map((tag) => ({
name: tag.name,
description: Utils.nonEmptyString(tag.description),
externalDocs: tag.externalDocs
})),
securitySchemes,
operations
}
}
interface OpenApiParameter {
readonly name: string
readonly in: "path" | "query" | "header" | "cookie"
readonly required: boolean
readonly schema: {}
readonly description?: string | undefined
readonly style?: string | undefined
readonly explode?: boolean | undefined
}
const isOpenApiParameter = (parameter: unknown): parameter is OpenApiParameter => {
if (!Predicate.isObject(parameter)) {
return false
}
return (
typeof parameter.name === "string" &&
(parameter.in === "path" || parameter.in === "query" || parameter.in === "header" || parameter.in === "cookie")
)
}
const resolveOperationParameters = (
pathParameters: ReadonlyArray<unknown> | undefined,
operationParameters: ReadonlyArray<unknown> | undefined,
resolveRef: (ref: string) => unknown
): Array<OpenApiParameter> => {
const resolved = new Map<string, OpenApiParameter>()
const add = (parameter: unknown): void => {
const current = resolveReference(parameter, resolveRef)
if (!isOpenApiParameter(current)) {
return
}
const key = `${current.in}:${current.name}`
if (resolved.has(key)) {
resolved.delete(key)
}
resolved.set(key, current)
}
for (const parameter of pathParameters ?? []) {
add(parameter)
}
for (const parameter of operationParameters ?? []) {
add(parameter)
}
return [...resolved.values()]
}
const buildParameterSchema = <
Parameter extends {
readonly name: string
readonly required: boolean
readonly schema: {}
readonly in?: "path" | "query" | "header" | "cookie" | undefined
}
>(
parameters: ReadonlyArray<Parameter>,
onAdded?: ((parameter: Parameter, added: Array<string>) => void) | undefined
): {
readonly schema: JsonSchema.JsonSchema
readonly optional: boolean
} | undefined => {
if (parameters.length === 0) {
return
}
const schema = {
type: "object" as JsonSchema.Type,
properties: {} as Record<string, JsonSchema.JsonSchema>,
required: [] as Array<string>,
additionalProperties: false
}
for (const parameter of parameters) {
const paramSchema = parameter.schema as any
const added: Array<string> = []
if (
Predicate.isObject(paramSchema) &&
"properties" in paramSchema &&
Predicate.isObject(paramSchema.properties)
) {
const required = "required" in paramSchema
? paramSchema.required as Array<string>
: []
for (const [name, propertySchema] of Object.entries(paramSchema.properties)) {
const adjustedName = `${parameter.name}[${name}]`
Rec.assignProperty(schema.properties, adjustedName, propertySchema as JsonSchema.JsonSchema)
if (required.includes(name)) {
schema.required.push(adjustedName)
}
added.push(adjustedName)
}
} else {
Rec.assignProperty(schema.properties, parameter.name, parameter.schema as JsonSchema.JsonSchema)
if (parameter.required) {
schema.required.push(parameter.name)
}
added.push(parameter.name)
}
onAdded?.(parameter, added)
}
return {
schema,
optional: schema.required.length === 0
}
}
const mediaTypeToSuffix = (contentType: string): string => {
const normalized = contentType.toLowerCase()
switch (normalized) {
case "application/json":
return "Json"
case "multipart/form-data":
return "FormData"
case "application/x-www-form-urlencoded":
return "FormUrlEncoded"
case "text/plain":
return "Text"
case "application/octet-stream":
return "Binary"
}
const suffix = Utils.identifier(contentType)
return suffix.length > 0 ? suffix : "Body"
}
const makeMultipartSchemas = (
spec: OpenAPISpec,
format: OpenApiGeneratorFormat,
resolveRef: (ref: string) => unknown
) => {
const definitions = spec.components?.schemas ?? {}
const names = new Set(Object.keys(definitions))
const allocate = (base: string): string => {
let candidate = base
let index = 2
while (names.has(candidate)) {
candidate = `${base}${index}`
index += 1
}
names.add(candidate)
return candidate
}
const output = { ...definitions }
const refs: MultipartSchemaRefs = format === "httpapi"
? {
kind: "httpapi",
singleFile: allocate("__HttpApiMultipartSingleFile"),
files: allocate("__HttpApiMultipartFiles")
}
: { kind: "client", singleFile: allocate("__ClientMultipartFile") }
const singleFileRef = toDefinitionRef(refs.singleFile)
const filesRef = refs.kind === "httpapi" ? toDefinitionRef(refs.files) : undefined
Rec.assignProperty(output, refs.singleFile, { type: "string", format: "binary" })
if (refs.kind === "httpapi") {
Rec.assignProperty(output, refs.files, { type: "array", items: { $ref: singleFileRef } })
}
const binaryComponents = new Map<string, boolean>()
const copies = new Map<string, string>()
const inlining = new Set<string>()
// Components reachable from a schema that is not a multipart body, filled in by `finish`.
let shared: ReadonlySet<string> = new Set()
const hasBinary = (value: unknown, seen: Set<string>): boolean => {
if (Array.isArray(value)) return value.some((item) => hasBinary(item, seen))
if (!Predicate.isObject(value)) return false
if (isMultipartBinaryFile(value)) return true
if (isComponentRef(value.$ref) && !seen.has(value.$ref)) {
seen.add(value.$ref)
if (hasBinary(resolveRef(value.$ref), seen)) return true
}
return Object.values(value).some((item) => hasBinary(item, seen))
}
const isBinaryComponent = ($ref: string): boolean => {
let binary = binaryComponents.get($ref)
if (binary === undefined) {
binary = hasBinary(resolveRef($ref), new Set([$ref]))
binaryComponents.set($ref, binary)
}
return binary
}
// Copies a binary-bearing component to `<Name>Multipart`, leaving the original for JSON payloads.
const copyComponent = ($ref: string): string => {
let name = copies.get($ref)
if (name === undefined) {
name = allocate(`${JsonPointer.unescapeToken($ref.slice(componentRefPrefix.length))}Multipart`)
copies.set($ref, name)
Rec.assignProperty(output, name, visit(resolveRef($ref)))
}
return name
}
// The httpapi format inlines components that only multipart bodies use; reference siblings still apply.
const inlineComponent = (value: Record<string, unknown>, $ref: string): unknown => {
const { $ref: _, ...siblings } = value
inlining.add($ref)
const inlined = visit(resolveRef($ref))
inlining.delete($ref)
return Object.keys(siblings).length === 0 ? inlined : { allOf: [inlined, visit(siblings)] }
}
// Follows component aliases so a reference to a binary string maps to the file schema too.
const isBinaryFile = (value: unknown, seen: Set<string> = new Set()): boolean => {
if (isMultipartBinaryFile(value)) return true
if (!Predicate.isObject(value) || !isComponentRef(value.$ref) || seen.has(value.$ref)) return false
seen.add(value.$ref)
return isBinaryFile(resolveRef(value.$ref), seen)
}
const visit = (value: unknown): unknown => {
if (Array.isArray(value)) return value.map(visit)
if (!Predicate.isObject(value)) return value
if (isBinaryFile(value)) return { $ref: singleFileRef }
if (
filesRef !== undefined && isComponentRef(value.$ref) && !shared.has(value.$ref) && !inlining.has(value.$ref)
) {
return inlineComponent(value, value.$ref)
}
const out = Rec.map(value, visit)
if (isComponentRef(value.$ref) && isBinaryComponent(value.$ref)) {
out.$ref = toDefinitionRef(copyComponent(value.$ref))
}
if (filesRef !== undefined && isMultipartBinaryFiles(out, singleFileRef)) return { $ref: filesRef }
return out
}
// Whether a component is shared is only known once every schema is registered, so `transform` hands
// out a placeholder that `finish` fills in after parsing.
const pending = new Map<JsonSchema.JsonSchema, JsonSchema.JsonSchema>()
const transform = (schema: JsonSchema.JsonSchema): JsonSchema.JsonSchema => {
const placeholder: JsonSchema.JsonSchema = {}
pending.set(placeholder, schema)
return placeholder
}
const finish = (schemas: Readonly<Record<string, JsonSchema.JsonSchema>>): void => {
shared = collectComponentRefs(Object.values(schemas).filter((schema) => !pending.has(schema)), resolveRef)
for (const [placeholder, schema] of pending) {
Object.assign(placeholder, visit(schema))
}
}
return { refs, definitions: output, transform, finish }
}
const toDefinitionRef = (name: string): string => `#/$defs/${name.replaceAll("~", "~0").replaceAll("/", "~1")}`
// Collects every component reachable from the schemas, following references through other components.
// Only JSON Schema keywords that hold subschemas are walked, so a `$ref` inside `default`, `const` or
// `examples` is treated as data.
const collectComponentRefs = (
schemas: ReadonlyArray<JsonSchema.JsonSchema>,
resolveRef: (ref: string) => unknown
): ReadonlySet<string> => {
const seen = new Set<string>()
const visit = (schema: unknown): void => {
if (Array.isArray(schema)) {
for (const item of schema) visit(item)
return
}
if (!Predicate.isObject(schema)) return
if (isComponentRef(schema.$ref) && !seen.has(schema.$ref)) {
seen.add(schema.$ref)
visit(resolveRef(schema.$ref))
}
for (const key of subschemaKeywords) {
visit(schema[key])
}
for (const key of subschemaMapKeywords) {
const map = schema[key]
if (Predicate.isObject(map)) visit(Object.values(map))
}
}
for (const schema of schemas) visit(schema)
return seen
}
const subschemaKeywords = [
"items",
"prefixItems",
"additionalItems",
"additionalProperties",
"unevaluatedItems",
"unevaluatedProperties",
"contains",
"propertyNames",
"contentSchema",
"allOf",
"anyOf",
"oneOf",
"not",
"if",
"then",
"else"
] as const
const subschemaMapKeywords = ["properties", "patternProperties", "dependentSchemas", "$defs", "definitions"] as const
const componentRefPrefix = "#/components/schemas/"
const isComponentRef = (value: unknown): value is string =>
typeof value === "string" && value.startsWith(componentRefPrefix)
const isMultipartBinaryFile = (value: unknown): boolean =>
Predicate.isObject(value) &&
value.type === "string" &&
(
(typeof value.format === "string" && value.format.toLowerCase() === "binary") ||
(typeof value.contentEncoding === "string" && value.contentEncoding.toLowerCase() === "binary")
)
const isMultipartBinaryFiles = (value: Record<string, unknown>, singleFileRef: string): boolean => {
if (value.type !== "array") {
return false
}
const items = value.items
return isMultipartBinaryFile(items) || (Predicate.isObject(items) && items.$ref === singleFileRef)
}
const isJsonMediaType = (contentType: string): boolean =>
contentType === "application/json" ||
(contentType.startsWith("application/") && contentType.endsWith("+json"))
const normalizeMediaType = (contentType: string): string => contentType.toLowerCase().split(";", 1)[0].trim()
const isTextMediaType = (contentType: string): boolean => contentType.startsWith("text/")
const binaryMediaTypes = new Set([
"application/octet-stream",
"application/pdf",
"application/zip",
"application/gzip",
"application/x-gzip",
"application/x-tar",
"application/x-zip-compressed"
])
const binaryMediaTypePrefixes = ["image/", "audio/", "video/", "font/"]
const isBinaryMediaType = (contentType: string): boolean =>
binaryMediaTypes.has(contentType) ||
binaryMediaTypePrefixes.some((prefix) => contentType.startsWith(prefix)) ||
(contentType.startsWith("application/") &&
(contentType.includes("binary") ||
contentType.endsWith("+octet-stream") ||
contentType.endsWith("+zip") ||
contentType.endsWith("+gzip")))
const isBinarySchema = (schema: unknown): boolean =>
Predicate.isObject(schema) &&
(
(typeof schema.format === "string" && schema.format.toLowerCase() === "binary") ||
(typeof schema.contentEncoding === "string" && schema.contentEncoding.toLowerCase() === "binary")
)
const isSuccessStatus = (status: string): boolean => {
const statusMajorNumber = Number(status[0])
return !Number.isNaN(statusMajorNumber) && statusMajorNumber < 4
}
// Response keys are emitted into generated identifiers, so anything other than
// a status code, status range or `default` (such as `x-` extensions) is skipped.
const isResponseStatus = (status: string): boolean => /^(?:[1-5]\d\d|[1-5]xx|default)$/i.test(status)
const getRequestMediaTypeEncoding = (
contentType: string
): ParsedOperation.ParsedOperationMediaTypeEncoding | undefined => {
const normalized = normalizeMediaType(contentType)
if (isJsonMediaType(normalized)) {
return "json"
}
if (normalized === "multipart/form-data") {
return "multipart"
}
if (normalized === "application/x-www-form-urlencoded") {
return "form-url-encoded"
}
if (isTextMediaType(normalized)) {
return "text"
}
if (isBinaryMediaType(normalized)) {
return "binary"
}
return
}
const getResponseMediaTypeEncoding = (
contentType: string
): ParsedOperation.ParsedOperationMediaTypeEncoding | undefined => {
const normalized = normalizeMediaType(contentType)
if (isJsonMediaType(normalized)) {
return "json"
}
if (normalized === "application/x-www-form-urlencoded") {
return "form-url-encoded"
}
if (isTextMediaType(normalized)) {
return "text"
}
if (isBinaryMediaType(normalized)) {
return "binary"
}
return
}
const getEffectStreamEncoding = (mediaType: object): "uint8array" | "sse" | "ndjson" | undefined => {
const stream = (mediaType as Record<string, unknown>)["x-effect-stream"]
if (!Predicate.isObject(stream)) {
return
}
return stream.encoding === "uint8array" || stream.encoding === "sse" || stream.encoding === "ndjson"
? stream.encoding
: undefined
}
const ndjsonMediaTypes = new Set(["application/x-ndjson", "application/jsonl"])
const unsupportedStreamingRequestMediaTypes = new Set(["application/json-seq", "text/event-stream"])
// Effect specs mark NDJSON with x-effect-stream on any content type. Other specs
// use an OpenAPI 3.2 itemSchema on an NDJSON or JSONL content type.
const getNdjsonElementSchema = (contentType: string, mediaType: object): JsonSchema.JsonSchema | undefined => {
const record = mediaType as Record<string, unknown>
if (getEffectStreamEncoding(mediaType) === "ndjson") {
return Predicate.isObject(record.schema) ? record.schema as JsonSchema.JsonSchema : undefined
}
if (
Predicate.isUndefined(record["x-effect-stream"]) &&
ndjsonMediaTypes.has(normalizeMediaType(contentType)) &&
Predicate.isObject(record.itemSchema)
) {
return record.itemSchema as JsonSchema.JsonSchema
}
return
}
const getEffectStreamErrorSchema = (mediaType: object): JsonSchema.JsonSchema | undefined => {
const stream = (mediaType as Record<string, unknown>)["x-effect-stream"]
if (!Predicate.isObject(stream) || !Predicate.isObject(stream.errorSchema)) {
return
}
return stream.errorSchema as JsonSchema.JsonSchema
}
const makeSseEventSchema = (
input: JsonSchema.JsonSchema,
failureEvent: string | undefined
): JsonSchema.JsonSchema => {
const eventSchema = normalizeSseEventSchema(input)
if (failureEvent === undefined) {
return eventSchema
}
return {
anyOf: [
eventSchema,
{
type: "object",
properties: {
id: { type: "string" },
event: { const: failureEvent },
data: { type: "string" }
},
required: ["event", "data"],
additionalProperties: false
}
]
}
}
const normalizeSseEventSchema = (input: JsonSchema.JsonSchema): JsonSchema.JsonSchema => {
const schema = { ...input } as Record<string, any>
for (const key of ["allOf", "anyOf", "oneOf"] as const) {
if (Array.isArray(schema[key])) {
schema[key] = schema[key].map(normalizeSseEventSchema)
}
}
if (
schema.type !== "object" ||
!Predicate.isObject(schema.properties) ||
!Object.hasOwn(schema.properties, "id") ||
!Object.hasOwn(schema.properties, "event") ||
!Object.hasOwn(schema.properties, "data")
) {
return schema as JsonSchema.JsonSchema
}
// OpenAPI represents `undefined` as required nullable; restore the SSE parser's optional wire field.
schema.properties = {
...schema.properties,
id: { type: "string" }
}
if (Array.isArray(schema.required)) {
schema.required = schema.required.filter((name: unknown) => name !== "id")
}
return schema as JsonSchema.JsonSchema
}
const primitiveSchemaTypes = new Set(["string", "number", "integer", "boolean", "null"])
const isPrimitiveValue = (value: unknown): boolean =>
value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean"
// Cookie values are serialized with `String(value)`, so only schemas whose
// values are always primitives can be represented.
const isPrimitiveSchema = (
input: unknown,
resolveRef: (ref: string) => unknown,
ancestors: Set<unknown> = new Set()
): boolean => {
const schema = resolveReference(input, resolveRef)
if (!Predicate.isObject(schema) || ancestors.has(schema)) {
return false
}
ancestors.add(schema)
const members = [schema.anyOf, schema.oneOf, schema.allOf].filter(Array.isArray).flat()
const membersArePrimitive = members.every((member) => isPrimitiveSchema(member, resolveRef, ancestors))
ancestors.delete(schema)
if (!membersArePrimitive) {
return false
}
if (schema.type !== undefined) {
const types: ReadonlyArray<unknown> = Array.isArray(schema.type) ? schema.type : [schema.type]
return types.every((type) => primitiveSchemaTypes.has(type as string))
}
if (Array.isArray(schema.enum)) {
return schema.enum.every(isPrimitiveValue)
}
if ("const" in schema) {
return isPrimitiveValue(schema.const)
}
return members.length > 0
}
const resolveReference = (input: unknown, resolveRef: (ref: string) => unknown): any => {
let current = input
while (Predicate.isObject(current) && typeof current.$ref === "string") {
current = resolveRef(current.$ref)
}
return current
}
const cloneSecurityRequirements = (
security: ReadonlyArray<Record<string, ReadonlyArray<string>>>
): Array<ParsedOperation.ParsedOperationSecurityRequirement> =>
security.map((requirement) =>
Object.fromEntries(
Object.entries(requirement).map(([name, scopes]) => [name, [...scopes]])
)
)
const parseSecuritySchemes = (
spec: OpenAPISpec,
resolveRef: (ref: string) => unknown
): Array<ParsedOperation.ParsedOpenApiSecurityScheme> => {
const securitySchemes = spec.components?.securitySchemes ?? {}
const parsed: Array<ParsedOperation.ParsedOpenApiSecurityScheme> = []
for (const [name, value] of Object.entries(securitySchemes)) {
const scheme = resolveReference(value, resolveRef) as OpenAPISecurityScheme | undefined
if (!Predicate.isObject(scheme)) {
continue
}
if (scheme.type === "http" && typeof scheme.scheme === "string") {
const normalizedScheme = scheme.scheme.toLowerCase()
if (normalizedScheme === "basic") {
parsed.push({
name,
type: "basic",
description: Utils.nonEmptyString(scheme.description),
bearerFormat: undefined,
scheme: undefined,
key: undefined,
in: undefined
})
} else if (normalizedScheme === "bearer") {
parsed.push({
name,
type: "bearer",
description: Utils.nonEmptyString(scheme.description),
bearerFormat: Utils.nonEmptyString(scheme.bearerFormat),
scheme: undefined,
key: undefined,
in: undefined
})
} else {
parsed.push({
name,
type: "http",
description: Utils.nonEmptyString(scheme.description),
bearerFormat: Utils.nonEmptyString(scheme.bearerFormat),
scheme: scheme.scheme,
key: undefined,
in: undefined
})
}
continue
}
if (
scheme.type === "apiKey" &&
(scheme.in === "header" || scheme.in === "query" || scheme.in === "cookie") &&
typeof scheme.name === "string"
) {
parsed.push({
name,
type: "apiKey",
description: Utils.nonEmptyString(scheme.description),
bearerFormat: undefined,
scheme: undefined,
key: scheme.name,
in: scheme.in
})
}
}
return parsed
}
const warnForAndSecurityRequirements = (
emitWarning: WarningEmitter,
operation: ParsedOperation.ParsedOperation
): void => {
if (operation.effectiveSecurity.some((requirement) => Object.keys(requirement).length === 0)) {
return
}
for (const requirement of operation.effectiveSecurity) {
const schemes = Object.keys(requirement)
if (schemes.length <= 1) {
continue
}
warnForOperation(emitWarning, operation, {
code: "security-and-downgraded",
message: `Security requirement requiring all of [${
schemes.join(", ")
}] was downgraded to a placeholder middleware.`
})
}
}
const hasUnsupportedSuccessfulSseResponse = (
responses: ReadonlyArray<readonly [string, unknown]>,
hasExplicitSuccessResponse: boolean
): boolean => {
for (const [status, response] of responses) {
if (!Predicate.isObject(response)) {
continue
}
const remappedStatus = remapDefaultResponseStatusForHttpApi(status, hasExplicitSuccessResponse)
const statusCode = Number(remappedStatus)
if (Number.isNaN(statusCode) || statusCode >= 400) {
continue
}
const content = Predicate.isObject(response.content)
? response.content as Record<string, any>
: undefined
if (Predicate.isUndefined(content)) {
continue
}
for (const [contentType, mediaType] of Object.entries(content)) {
if (!Predicate.isObject(mediaType)) {
continue
}
const streamEncoding = getEffectStreamEncoding(mediaType)
if (streamEncoding === "sse") {
if (Predicate.isUndefined(mediaType.schema) || Predicate.isUndefined(getEffectStreamErrorSchema(mediaType))) {
return true
}
continue
}
if (contentType === "text/event-stream" && streamEncoding !== "ndjson") {
return true
}
}
}
return false
}
const remapDefaultResponseStatusForHttpApi = (status: string, hasExplicitSuccessResponse: boolean): string =>
status === "default" ? (hasExplicitSuccessResponse ? "500" : "200") : status
const methodSupportsRequestBody = (method: Lowercase<HttpMethod>): boolean =>
method !== "get" && method !== "head" && method !== "options" && method !== "trace"
const warnForOperation = (
emitWarning: WarningEmitter,
operation: ParsedOperation.ParsedOperation,
warning: {
readonly code: OpenApiGeneratorWarningCode
readonly message: string
}
): void => {
emitWarning({
...warning,
path: operation.path,
method: operation.method,
operationId: operation.operationId
})
}
function getDialect(spec: OpenAPISpec): "openapi-3.0" | "openapi-3.1" {
return spec.openapi.trim().startsWith("3.0") ? "openapi-3.0" : "openapi-3.1"
}
/**
* Layer providing an OpenAPI generator for Schema-backed HTTP client and HttpApi output.
*
* @category layers
* @since 4.0.0
*/
export const layerTransformerSchema: Layer.Layer<OpenApiGenerator> = Layer.effect(OpenApiGenerator, make)
/**
* Layer providing an OpenAPI generator for type-only HTTP client output.
*
* @category layers
* @since 4.0.0
*/
export const layerTransformerTs: Layer.Layer<OpenApiGenerator> = Layer.effect(OpenApiGenerator, make)
const isSwaggerSpec = (spec: OpenAPISpec) => "swagger" in spec
const convertSwaggerSpec = Effect.fn((spec: OpenAPISpec) =>
Effect.callback<OpenAPISpec>((resume) => {
SwaggerToOpenApi.convertObj(
spec as any,
{ laxDefaults: true, laxurls: true, patch: true, warnOnly: true },
(err, result) => {
if (err) {
resume(Effect.die(err))
} else {
resume(Effect.succeed(result.openapi as any))
}
}
)
}).pipe(Effect.withSpan("OpenApi.convertSwaggerSpec"))
)
const processPath = (path: string): {
readonly pathIds: Array<string>
readonly pathTemplate: string
} => {
const pathIds: Array<string> = []
const fragments: Array<string> = []
let offset = 0
for (const match of path.matchAll(/{([^}]+)}/g)) {
fragments.push(JSON.stringify(path.slice(offset, match.index)))
const id = Utils.camelize(match[1])
pathIds.push(id)
fragments.push(`__encodePathParam(${id})`)
offset = match.index + match[0].length
}
fragments.push(JSON.stringify(path.slice(offset)))
const pathTemplate = fragments.join(" + ")
return { pathIds, pathTemplate } as const
}