@effect/openapi-generator 4.0.0-beta.8 → 4.0.0-beta.81

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"
@@ -26,12 +26,15 @@ import * as Yaml from "yaml"
 /**
  * Error thrown when parsing a JSON Patch input fails.
  *
+ * **Details**
+ *
  * This error occurs when:
  * - A patch file cannot be read
  * - 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,10 +47,10 @@ 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")({
+export class JsonPatchParseError extends Schema.ErrorClass<JsonPatchParseError>("JsonPatchParseError")({
   _tag: Schema.tag("JsonPatchParseError"),
   source: Schema.String,
   reason: Schema.String
@@ -60,13 +63,16 @@ export class JsonPatchParseError extends Schema.ErrorClass("JsonPatchParseError"
 /**
  * Error thrown when a parsed value does not conform to the JSON Patch schema.
  *
+ * **Details**
+ *
  * This error occurs when:
  * - The patch is not an array
  * - An operation is missing required fields (op, path)
  * - 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,10 +85,10 @@ 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")({
+export class JsonPatchValidationError extends Schema.ErrorClass<JsonPatchValidationError>("JsonPatchValidationError")({
   _tag: Schema.tag("JsonPatchValidationError"),
   source: Schema.String,
   reason: Schema.String
@@ -95,12 +101,15 @@ export class JsonPatchValidationError extends Schema.ErrorClass("JsonPatchValida
 /**
  * Error thrown when applying a JSON Patch operation fails.
  *
+ * **Details**
+ *
  * This error occurs when:
  * - A path does not exist for remove/replace operations
  * - 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,17 +125,19 @@ export class JsonPatchValidationError extends Schema.ErrorClass("JsonPatchValida
  * // "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")({
-  _tag: Schema.tag("JsonPatchApplicationError"),
-  source: Schema.String,
-  operationIndex: Schema.Number,
-  operation: Schema.String,
-  path: Schema.String,
-  reason: Schema.String
-}) {
+export class JsonPatchApplicationError
+  extends Schema.ErrorClass<JsonPatchApplicationError>("JsonPatchApplicationError")({
+    _tag: Schema.tag("JsonPatchApplicationError"),
+    source: Schema.String,
+    operationIndex: Schema.Number,
+    operation: Schema.String,
+    path: Schema.String,
+    reason: Schema.String
+  })
+{
   override get message() {
     return `Failed to apply patch from ${this.source}: operation ${this.operationIndex} ` +
       `(${this.operation} at ${this.path}): ${this.reason}`
@@ -136,10 +147,13 @@ export class JsonPatchApplicationError extends Schema.ErrorClass("JsonPatchAppli
 /**
  * Error thrown when multiple JSON Patch operations fail.
  *
+ * **Details**
+ *
  * 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"
  *
@@ -166,10 +180,10 @@ export class JsonPatchApplicationError extends Schema.ErrorClass("JsonPatchAppli
  * // "2 patch operations failed:\n  1. ..."
  * ```
  *
- * @since 1.0.0
  * @category errors
+ * @since 4.0.0
  */
-export class JsonPatchAggregateError extends Schema.ErrorClass("JsonPatchAggregateError")({
+export class JsonPatchAggregateError extends Schema.ErrorClass<JsonPatchAggregateError>("JsonPatchAggregateError")({
   _tag: Schema.tag("JsonPatchAggregateError"),
   errors: Schema.Array(Schema.Unknown)
 }) {
@@ -191,8 +205,8 @@ export class JsonPatchAggregateError extends Schema.ErrorClass("JsonPatchAggrega
 /**
  * Schema for a JSON Patch "add" operation.
  *
- * @since 1.0.0
  * @category schemas
+ * @since 4.0.0
  */
 export const JsonPatchAdd: Schema.Codec<
   Extract<
@@ -209,8 +223,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<
@@ -226,8 +240,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<
@@ -244,11 +258,13 @@ export const JsonPatchReplace: Schema.Codec<
 /**
  * Schema for a single JSON Patch operation.
  *
+ * **Details**
+ *
  * 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,
@@ -259,11 +275,14 @@ export const JsonPatchOperation: Schema.Codec<JsonPatch.JsonPatchOperation> = Sc
 /**
  * Schema for a JSON Patch document (array of operations).
  *
+ * **Details**
+ *
  * A JSON Patch document is an ordered list of operations to apply to a JSON
  * 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"
@@ -275,16 +294,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
 
@@ -407,11 +426,14 @@ const parseInlinePatch = Effect.fn("parseInlinePatch")(function*(input: string)
 /**
  * Parse a JSON Patch from either a file path or inline JSON string.
  *
+ * **Details**
+ *
  * The input is first checked as a file path. If the file exists, it is read
  * 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"
@@ -431,8 +453,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)) {
@@ -451,11 +473,14 @@ export const parsePatchInput = Effect.fn("parsePatchInput")(function*(input: str
 /**
  * Apply a sequence of JSON patches to a document.
  *
+ * **Details**
+ *
  * Patches are applied in order, with each patch operating on the result of
  * 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"
@@ -475,8 +500,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,15 +1,40 @@
+/**
+ * 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 * as ServiceMap from "effect/ServiceMap"
-import type { ParsedOperation } from "./ParsedOperation.ts"
+import type { ParsedOpenApi, ParsedOperation } from "./ParsedOperation.ts"
 import * as Utils from "./Utils.ts"
 
-export class OpenApiTransformer extends ServiceMap.Service<
+/**
+ * Service used by the OpenAPI generator to render parsed operations as an
+ * Effect HttpClient module.
+ *
+ * **Details**
+ *
+ * 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,
   {
-    readonly imports: (importName: string, operations: ReadonlyArray<ParsedOperation>) => string
-    readonly toTypes: (importName: string, name: string, operations: ReadonlyArray<ParsedOperation>) => string
-    readonly toImplementation: (importName: string, name: string, operations: ReadonlyArray<ParsedOperation>) => string
+    readonly imports: (importName: string, parsed: ParsedOpenApi) => string
+    readonly toTypes: (importName: string, name: string, parsed: ParsedOpenApi) => string
+    readonly toImplementation: (importName: string, name: string, parsed: ParsedOpenApi) => string
   }
 >()("OpenApiTransformer") {}
 
@@ -35,6 +60,18 @@ const computeImportRequirements = (operations: ReadonlyArray<ParsedOperation>):
 const requiresStreaming = (requirements: ImportRequirements): boolean =>
   requirements.eventStream || requirements.octetStream
 
+/**
+ * Create the transformer used for schema-backed HttpClient output.
+ *
+ * **Details**
+ *
+ * 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,
@@ -269,6 +306,8 @@ export const make = (
     const payloadVarName = "options.payload"
     if (operation.payloadFormData) {
       pipeline.push(`HttpClientRequest.bodyFormData(${payloadVarName} as any)`)
+    } else if (operation.payloadFormUrlEncoded) {
+      pipeline.push(`HttpClientRequest.bodyUrlParams(${payloadVarName} as any)`)
     } else if (operation.payload) {
       pipeline.push(`HttpClientRequest.bodyJsonUnsafe(${payloadVarName})`)
     }
@@ -382,7 +421,8 @@ export const make = (
   }
 
   return OpenApiTransformer.of({
-    imports: (importName, operations) => {
+    imports: (importName, parsed) => {
+      const operations = parsed.operations
       const requirements = computeImportRequirements(operations)
       const imports = [
         `import * as Data from "effect/Data"`,
@@ -409,16 +449,40 @@ export const make = (
       )
       return imports.join("\n")
     },
-    toTypes: operationsToInterface,
-    toImplementation: operationsToImpl
+    toTypes: (importName, name, parsed) => operationsToInterface(importName, name, parsed.operations),
+    toImplementation: (importName, name, parsed) => operationsToImpl(importName, name, parsed.operations)
   })
 }
 
+/**
+ * Layer that provides the schema-backed OpenApiTransformer service.
+ *
+ * **When to use**
+ *
+ * Use when you 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.
+ *
+ * **Details**
+ *
+ * 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,
@@ -777,7 +841,8 @@ export const make = (
   }
 
   return OpenApiTransformer.of({
-    imports: (_importName, operations) => {
+    imports: (_importName, parsed) => {
+      const operations = parsed.operations
       const requirements = computeImportRequirements(operations)
       const imports = [
         `import * as Data from "effect/Data"`,
@@ -794,11 +859,23 @@ export const make = (
       )
       return imports.join("\n")
     },
-    toTypes: operationsToInterface,
-    toImplementation: operationsToImpl
+    toTypes: (importName, name, parsed) => operationsToInterface(importName, name, parsed.operations),
+    toImplementation: (importName, name, parsed) => operationsToImpl(importName, name, parsed.operations)
   })
 }
 
+/**
+ * Layer that provides the type-only OpenApiTransformer service.
+ *
+ * **When to use**
+ *
+ * Use when you 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,9 +1,204 @@
+/**
+ * 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 { OpenAPISpecMethodName } from "effect/unstable/httpapi/OpenApi"
+import type {
+  OpenAPISecurityRequirement,
+  OpenAPISpecExternalDocs,
+  OpenAPISpecLicense,
+  OpenAPISpecMethodName,
+  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
+  readonly summary: string | undefined
+  readonly description: string | undefined
+  readonly license: OpenAPISpecLicense | undefined
+  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" | "http"
+  readonly description: string | undefined
+  readonly bearerFormat: string | undefined
+  readonly scheme: string | undefined
+  readonly key: string | undefined
+  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>
+  readonly securitySchemes: ReadonlyArray<ParsedOpenApiSecurityScheme>
+  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
+  readonly deprecated: boolean
+  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"
+  readonly required: boolean
+  readonly description: string | undefined
+  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"
+  | "form-url-encoded"
+  | "text"
+  | "binary"
+
+/**
+ * Media type whose schema can be represented in generated Effect code.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export type ParsedOperationMediaTypeSchema =
+  | {
+    readonly contentType: string
+    readonly encoding: ParsedOperationMediaTypeEncoding
+    readonly schema: string
+    readonly effectStream?: undefined
+  }
+  | {
+    readonly contentType: string
+    readonly encoding: "text"
+    readonly schema: string
+    readonly effectStream: "sse"
+    readonly errorSchema: string
+  }
+  | {
+    readonly contentType: string
+    readonly encoding: "binary"
+    readonly schema?: undefined
+    readonly effectStream: "uint8array"
+  }
+
+/**
+ * Parsed response metadata together with generated schema references.
+ *
+ * @category models
+ * @since 4.0.0
+ */
+export interface ParsedOperationResponse {
+  readonly status: string
+  readonly description: string | undefined
+  readonly contentTypes: Array<string>
+  readonly hasHeaders: boolean
+  readonly isEmpty: boolean
+  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
+  readonly path: string
   readonly method: OpenAPISpecMethodName
+  readonly tags: ReadonlyArray<string>
+  readonly metadata: ParsedOperationMetadata
+  readonly parameters: {
+    readonly path: ReadonlyArray<ParsedOperationParameter>
+    readonly query: ReadonlyArray<ParsedOperationParameter>
+    readonly header: ReadonlyArray<ParsedOperationParameter>
+    readonly cookie: ReadonlyArray<ParsedOperationParameter>
+  }
+  readonly requestBody: ParsedOperationRequestBody | undefined
+  readonly responses: ReadonlyArray<ParsedOperationResponse>
+  readonly defaultResponse: ParsedOperationResponse | undefined
+  readonly effectiveSecurity: ReadonlyArray<ParsedOperationSecurityRequirement>
   readonly description: string | undefined
   readonly params?: string
   readonly paramsOptional: boolean
@@ -12,6 +207,13 @@ export interface ParsedOperation {
   readonly cookies: ReadonlyArray<string>
   readonly payload?: string
   readonly payloadFormData: boolean
+  readonly payloadFormUrlEncoded: boolean
+  readonly pathSchema: string | undefined
+  readonly querySchema: string | undefined
+  readonly querySchemaOptional: boolean
+  readonly headersSchema: string | undefined
+  readonly headersSchemaOptional: boolean
+  readonly requestBodyRepresentable: ReadonlyArray<ParsedOperationMediaTypeSchema>
   readonly pathIds: ReadonlyArray<string>
   readonly pathTemplate: string
   readonly successSchemas: ReadonlyMap<string, string>
@@ -23,6 +225,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
@@ -31,10 +239,36 @@ export const makeDeepMutable = (options: {
   readonly description: string | undefined
 }): Types.DeepMutable<ParsedOperation> => ({
   ...options,
+  operationId: undefined,
+  path: "",
+  tags: [],
+  metadata: {
+    summary: undefined,
+    description: options.description,
+    deprecated: false,
+    externalDocs: undefined
+  },
+  parameters: {
+    path: [],
+    query: [],
+    header: [],
+    cookie: []
+  },
+  requestBody: undefined,
+  responses: [],
+  defaultResponse: undefined,
+  effectiveSecurity: [],
   urlParams: [],
   headers: [],
   cookies: [],
   payloadFormData: false,
+  payloadFormUrlEncoded: false,
+  pathSchema: undefined,
+  querySchema: undefined,
+  querySchemaOptional: true,
+  headersSchema: undefined,
+  headersSchemaOptional: true,
+  requestBodyRepresentable: [],
   successSchemas: new Map(),
   errorSchemas: new Map(),
   voidSchemas: new Set(),