@effect/openapi-generator 4.0.0-beta.66 → 4.0.0-beta.68

package/src/JsonSchemaGenerator.ts

@@ -1,3 +1,23 @@
+/**
+ * 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"
@@ -16,6 +36,16 @@ interface GenerateHttpApiOptions extends GenerateOptions {
   } | undefined
 }
 
+/**
+ * Create a stateful JSON Schema code generator for OpenAPI-derived schemas.
+ *
+ * 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() {
   const store: Record<string, JsonSchema.JsonSchema> = {}
 

package/src/OpenApiGenerator.ts

@@ -1,3 +1,15 @@
+/**
+ * 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 * as JsonSchema from "effect/JsonSchema"
@@ -12,13 +24,32 @@ 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.
+ *
+ * @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"
@@ -30,6 +61,13 @@ export type OpenApiGeneratorWarningCode =
   | "no-body-method-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
@@ -38,6 +76,12 @@ export interface OpenApiGeneratorWarning {
   readonly operationId?: string | undefined
 }
 
+/**
+ * Options that control one OpenAPI generation run.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface OpenApiGenerateOptions {
   /**
    * The name to give to the generated output.
@@ -73,6 +117,12 @@ const methodNames: ReadonlyArray<OpenAPISpecMethodName> = [
   "trace"
 ]
 
+/**
+ * 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) {
@@ -1018,8 +1068,20 @@ 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

package/src/OpenApiPatch.ts

@@ -7,7 +7,7 @@
  * - YAML files (.yaml, .yml)
  * - Inline JSON strings
  *
- * @module OpenApiPatch
+ * @since 4.0.0
  */
 
 import * as Effect from "effect/Effect"
@@ -31,7 +31,8 @@ import * as Yaml from "yaml"
  * - JSON or YAML syntax is invalid
  * - The file format is unsupported
  *
- * @example
+ * **Example** (Creating a parse error)
+ *
  * ```ts
  * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
  *
@@ -44,8 +45,8 @@ import * as Yaml from "yaml"
  * // "Failed to parse patch from ./patches/fix.json: Unexpected token at position 42"
  * ```
  *
- * @since 1.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class JsonPatchParseError extends Schema.ErrorClass<JsonPatchParseError>("JsonPatchParseError")({
   _tag: Schema.tag("JsonPatchParseError"),
@@ -66,7 +67,8 @@ export class JsonPatchParseError extends Schema.ErrorClass<JsonPatchParseError>(
  * - An operation has an unsupported op value
  * - An add/replace operation is missing the value field
  *
- * @example
+ * **Example** (Creating a validation error)
+ *
  * ```ts
  * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
  *
@@ -79,8 +81,8 @@ export class JsonPatchParseError extends Schema.ErrorClass<JsonPatchParseError>(
  * // "Invalid JSON Patch from inline: Expected 'add' | 'remove' | 'replace' at [0].op, got 'copy'"
  * ```
  *
- * @since 1.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class JsonPatchValidationError extends Schema.ErrorClass<JsonPatchValidationError>("JsonPatchValidationError")({
   _tag: Schema.tag("JsonPatchValidationError"),
@@ -100,7 +102,8 @@ export class JsonPatchValidationError extends Schema.ErrorClass<JsonPatchValidat
  * - An array index is out of bounds
  * - The target location is not a valid container
  *
- * @example
+ * **Example** (Creating an application error)
+ *
  * ```ts
  * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
  *
@@ -116,8 +119,8 @@ export class JsonPatchValidationError extends Schema.ErrorClass<JsonPatchValidat
  * // "Failed to apply patch from ./patches/fix.json: operation 2 (remove at /paths/~1users): Property \"users\" does not exist"
  * ```
  *
- * @since 1.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class JsonPatchApplicationError
   extends Schema.ErrorClass<JsonPatchApplicationError>("JsonPatchApplicationError")({
@@ -141,7 +144,8 @@ export class JsonPatchApplicationError
  * This error aggregates all application errors so users can see every
  * failing operation at once instead of fixing them one at a time.
  *
- * @example
+ * **Example** (Creating an aggregate error)
+ *
  * ```ts
  * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
  *
@@ -168,8 +172,8 @@ export class JsonPatchApplicationError
  * // "2 patch operations failed:\n  1. ..."
  * ```
  *
- * @since 1.0.0
  * @category errors
+ * @since 4.0.0
  */
 export class JsonPatchAggregateError extends Schema.ErrorClass<JsonPatchAggregateError>("JsonPatchAggregateError")({
   _tag: Schema.tag("JsonPatchAggregateError"),
@@ -193,8 +197,8 @@ export class JsonPatchAggregateError extends Schema.ErrorClass<JsonPatchAggregat
 /**
  * Schema for a JSON Patch "add" operation.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const JsonPatchAdd: Schema.Codec<
   Extract<
@@ -211,8 +215,8 @@ export const JsonPatchAdd: Schema.Codec<
 /**
  * Schema for a JSON Patch "remove" operation.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const JsonPatchRemove: Schema.Codec<
   Extract<
@@ -228,8 +232,8 @@ export const JsonPatchRemove: Schema.Codec<
 /**
  * Schema for a JSON Patch "replace" operation.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const JsonPatchReplace: Schema.Codec<
   Extract<
@@ -249,8 +253,8 @@ export const JsonPatchReplace: Schema.Codec<
  * Supports the subset of RFC 6902 operations that Effect's JsonPatch module
  * implements: `add`, `remove`, and `replace`.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const JsonPatchOperation: Schema.Codec<JsonPatch.JsonPatchOperation> = Schema.Union([
   JsonPatchAdd,
@@ -265,7 +269,8 @@ export const JsonPatchOperation: Schema.Codec<JsonPatch.JsonPatchOperation> = Sc
  * document. Operations are applied in sequence, with each operation seeing
  * the result of previous operations.
  *
- * @example
+ * **Example** (Decoding a patch document)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
@@ -277,16 +282,16 @@ export const JsonPatchOperation: Schema.Codec<JsonPatch.JsonPatchOperation> = Sc
  * ])
  * ```
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const JsonPatchDocument = Schema.Array(JsonPatchOperation)
 
 /**
  * Type for a JSON Patch document.
  *
- * @since 1.0.0
  * @category types
+ * @since 4.0.0
  */
 export type JsonPatchDocument = typeof JsonPatchDocument.Type
 
@@ -413,7 +418,8 @@ const parseInlinePatch = Effect.fn("parseInlinePatch")(function*(input: string)
  * and parsed based on its extension (.json, .yaml, .yml). Otherwise, the
  * input is parsed as inline JSON.
  *
- * @example
+ * **Example** (Parsing patch input)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
@@ -433,8 +439,8 @@ const parseInlinePatch = Effect.fn("parseInlinePatch")(function*(input: string)
  * })
  * ```
  *
- * @since 1.0.0
  * @category parsing
+ * @since 4.0.0
  */
 export const parsePatchInput = Effect.fn("parsePatchInput")(function*(input: string) {
   if (looksLikeFilePath(input)) {
@@ -457,7 +463,8 @@ export const parsePatchInput = Effect.fn("parsePatchInput")(function*(input: str
  * the previous one. All operations are attempted, and if any fail, the errors
  * are accumulated and reported together so users can fix all issues at once.
  *
- * @example
+ * **Example** (Applying patches)
+ *
  * ```ts
  * import { Effect } from "effect"
  * import * as OpenApiPatch from "@effect/openapi-generator/OpenApiPatch"
@@ -477,8 +484,8 @@ export const parsePatchInput = Effect.fn("parsePatchInput")(function*(input: str
  * })
  * ```
  *
- * @since 1.0.0
  * @category application
+ * @since 4.0.0
  */
 export const applyPatches = Effect.fn("applyPatches")(function*(
   patches: ReadonlyArray<{ readonly source: string; readonly patch: JsonPatchDocument }>,

package/src/OpenApiTransformer.ts

@@ -1,9 +1,32 @@
+/**
+ * OpenAPI-to-HttpClient code generation for the OpenAPI generator.
+ *
+ * This module defines the `OpenApiTransformer` service used to render parsed
+ * OpenAPI operations into Effect `HttpClient` modules. It provides both
+ * schema-backed and type-only transformer implementations, including generated
+ * imports, public client interfaces, operation implementations, typed API
+ * errors, optional response handling, and helpers for server-sent events and
+ * binary response streams.
+ *
+ * @since 4.0.0
+ */
 import * as Context from "effect/Context"
 import * as Layer from "effect/Layer"
 import * as Predicate from "effect/Predicate"
 import type { ParsedOpenApi, ParsedOperation } from "./ParsedOperation.ts"
 import * as Utils from "./Utils.ts"
 
+/**
+ * Service used by the OpenAPI generator to render parsed operations as an
+ * Effect HttpClient module.
+ *
+ * A transformer owns the code-generation dialect for imports, public client
+ * types, and the implementation body. The generator swaps implementations to
+ * choose between schema-backed clients and type-only clients.
+ *
+ * @category code generation
+ * @since 4.0.0
+ */
 export class OpenApiTransformer extends Context.Service<
   OpenApiTransformer,
   {
@@ -35,6 +58,16 @@ const computeImportRequirements = (operations: ReadonlyArray<ParsedOperation>):
 const requiresStreaming = (requirements: ImportRequirements): boolean =>
   requirements.eventStream || requirements.octetStream
 
+/**
+ * Create the transformer used for schema-backed HttpClient output.
+ *
+ * Generated clients import Effect Schema values and use them at runtime to
+ * decode successful responses and typed API errors. Request parameters and
+ * payloads are typed against each schema's encoded representation.
+ *
+ * @category code generation
+ * @since 4.0.0
+ */
 export const makeTransformerSchema = () => {
   const operationsToInterface = (
     _importName: string,
@@ -417,11 +450,31 @@ export const make = (
   })
 }
 
+/**
+ * Layer that provides the schema-backed OpenApiTransformer service.
+ *
+ * Use this layer when generated HttpClient code should perform runtime response
+ * decoding with generated Effect Schema values.
+ *
+ * @category code generation
+ * @since 4.0.0
+ */
 export const layerTransformerSchema = Layer.sync(
   OpenApiTransformer,
   makeTransformerSchema
 )
 
+/**
+ * Create the transformer used for type-only HttpClient output.
+ *
+ * Generated clients reference emitted TypeScript types directly and do not
+ * import schema decoders for JSON response bodies. Responses are typed as the
+ * declared operation result while preserving generated error and stream method
+ * shapes.
+ *
+ * @category code generation
+ * @since 4.0.0
+ */
 export const makeTransformerTs = () => {
   const operationsToInterface = (
     _importName: string,
@@ -803,6 +856,16 @@ export const make = (
   })
 }
 
+/**
+ * Layer that provides the type-only OpenApiTransformer service.
+ *
+ * Use this layer for the `httpclient-type-only` generator format, where the
+ * generated client relies on TypeScript types instead of runtime Schema
+ * decoding.
+ *
+ * @category code generation
+ * @since 4.0.0
+ */
 export const layerTransformerTs = Layer.sync(
   OpenApiTransformer,
   makeTransformerTs

package/src/ParsedOperation.ts

@@ -1,3 +1,15 @@
+/**
+ * Normalized OpenAPI operation model shared by the generator pipeline.
+ *
+ * This module records the shape produced after an OpenAPI document is resolved
+ * into stable generator inputs: document metadata, tags, security schemes,
+ * per-operation parameters, request bodies, response media types, derived
+ * schema references, path templates, and streaming capabilities. Renderers
+ * consume this representation to emit HttpClient or HttpApi modules without
+ * reinterpreting raw OpenAPI path-item structures.
+ *
+ * @since 4.0.0
+ */
 import type * as Types from "effect/Types"
 import type {
   OpenAPISecurityRequirement,
@@ -7,6 +19,12 @@ import type {
   OpenAPISpecServer
 } from "effect/unstable/httpapi/OpenApi"
 
+/**
+ * Root OpenAPI metadata preserved for generated client and HttpApi output.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface ParsedOpenApiMetadata {
   readonly title: string
   readonly version: string
@@ -16,12 +34,24 @@ export interface ParsedOpenApiMetadata {
   readonly servers: ReadonlyArray<OpenAPISpecServer> | undefined
 }
 
+/**
+ * Tag metadata used to group and annotate generated operations.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface ParsedOpenApiTag {
   readonly name: string
   readonly description: string | undefined
   readonly externalDocs: OpenAPISpecExternalDocs | undefined
 }
 
+/**
+ * Supported security scheme extracted from an OpenAPI components section.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface ParsedOpenApiSecurityScheme {
   readonly name: string
   readonly type: "basic" | "bearer" | "apiKey"
@@ -31,6 +61,12 @@ export interface ParsedOpenApiSecurityScheme {
   readonly in: "header" | "query" | "cookie" | undefined
 }
 
+/**
+ * Normalized OpenAPI document consumed by the generator renderers.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface ParsedOpenApi {
   readonly metadata: ParsedOpenApiMetadata
   readonly tags: ReadonlyArray<ParsedOpenApiTag>
@@ -38,6 +74,12 @@ export interface ParsedOpenApi {
   readonly operations: ReadonlyArray<ParsedOperation>
 }
 
+/**
+ * Documentation and lifecycle metadata associated with an operation.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface ParsedOperationMetadata {
   readonly summary: string | undefined
   readonly description: string | undefined
@@ -45,6 +87,12 @@ export interface ParsedOperationMetadata {
   readonly externalDocs: OpenAPISpecExternalDocs | undefined
 }
 
+/**
+ * Resolved OpenAPI parameter grouped by where it appears in the request.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface ParsedOperationParameter {
   readonly name: string
   readonly in: "path" | "query" | "header" | "cookie"
@@ -53,11 +101,23 @@ export interface ParsedOperationParameter {
   readonly schema: {}
 }
 
+/**
+ * Summary of the request body declaration before per-media schemas are rendered.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface ParsedOperationRequestBody {
   readonly required: boolean
   readonly contentTypes: Array<string>
 }
 
+/**
+ * Encoding strategy the generator can use for a request or response media type.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export type ParsedOperationMediaTypeEncoding =
   | "json"
   | "multipart"
@@ -65,12 +125,24 @@ export type ParsedOperationMediaTypeEncoding =
   | "text"
   | "binary"
 
+/**
+ * Media type whose schema can be represented in generated Effect code.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface ParsedOperationMediaTypeSchema {
   readonly contentType: string
   readonly encoding: ParsedOperationMediaTypeEncoding
   readonly schema: string
 }
 
+/**
+ * Parsed response metadata together with generated schema references.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface ParsedOperationResponse {
   readonly status: string
   readonly description: string | undefined
@@ -80,8 +152,20 @@ export interface ParsedOperationResponse {
   readonly representable: ReadonlyArray<ParsedOperationMediaTypeSchema>
 }
 
+/**
+ * Resolved security requirement applied to a parsed operation.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export type ParsedOperationSecurityRequirement = Readonly<OpenAPISecurityRequirement>
 
+/**
+ * Normalized operation model shared by all OpenAPI generator backends.
+ *
+ * @category models
+ * @since 4.0.0
+ */
 export interface ParsedOperation {
   readonly id: string
   readonly operationId: string | undefined
@@ -125,6 +209,12 @@ export interface ParsedOperation {
   readonly binaryResponse: boolean
 }
 
+/**
+ * Creates a mutable operation accumulator populated with parser defaults.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
 export const makeDeepMutable = (options: {
   readonly id: string
   readonly method: OpenAPISpecMethodName

package/src/Utils.ts

@@ -1,6 +1,25 @@
+/**
+ * Shared utility helpers for the OpenAPI generator.
+ *
+ * This module centralizes the small transformations used while rendering
+ * generated TypeScript, including operation-name normalization, optional
+ * description handling, safe JSDoc comment emission, and direct array merging
+ * for code-generation accumulators.
+ *
+ * @since 4.0.0
+ */
 import * as String from "effect/String"
 import * as UndefinedOr from "effect/UndefinedOr"
 
+/**
+ * Converts an OpenAPI name into the generator's camel-case form.
+ *
+ * Separators are removed, leading digits are ignored, and letters following a
+ * separator or digit are upper-cased without otherwise changing letter casing.
+ *
+ * @category converting
+ * @since 4.0.0
+ */
 export const camelize = (self: string): string => {
   let str = ""
   let hadSymbol = false
@@ -24,8 +43,24 @@ export const camelize = (self: string): string => {
   return str
 }
 
+/**
+ * Converts an OpenAPI operation id into the exported operation identifier used
+ * by generated TypeScript modules.
+ *
+ * @category converting
+ * @since 4.0.0
+ */
 export const identifier = (operationId: string) => String.capitalize(camelize(operationId))
 
+/**
+ * Extracts a trimmed, non-empty string from an unknown value.
+ *
+ * Returns `undefined` for non-string values and for strings containing only
+ * whitespace.
+ *
+ * @category filtering
+ * @since 4.0.0
+ */
 export const nonEmptyString = (a: unknown): string | undefined => {
   if (typeof a === "string") {
     const trimmed = String.trim(a)
@@ -35,6 +70,15 @@ export const nonEmptyString = (a: unknown): string | undefined => {
   }
 }
 
+/**
+ * Renders an optional description as a JSDoc block for generated TypeScript.
+ *
+ * Returns an empty string when the description is absent and escapes any
+ * closing comment marker so generated source remains syntactically valid.
+ *
+ * @category converting
+ * @since 4.0.0
+ */
 export const toComment = UndefinedOr.match({
   onUndefined: () => "",
   onDefined: (description: string) =>
@@ -43,6 +87,15 @@ export const toComment = UndefinedOr.match({
 */\n`
 })
 
+/**
+ * Appends every element from `source` into `destination` in order.
+ *
+ * This mutates `destination` directly, which avoids allocating an intermediate
+ * array when generator code needs to merge collections.
+ *
+ * @category concatenating
+ * @since 4.0.0
+ */
 export const spreadElementsInto = <A>(source: Array<A>, destination: Array<A>): void => {
   for (let i = 0; i < source.length; i++) {
     destination.push(source[i])