@effect/openapi-generator 4.0.0-beta.1 → 4.0.0-beta.100

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,16 +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 { OpenAPISpecMethodName } from "effect/unstable/httpapi/OpenApi"
-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") {}
 
@@ -36,17 +60,18 @@ const computeImportRequirements = (operations: ReadonlyArray<ParsedOperation>):
 const requiresStreaming = (requirements: ImportRequirements): boolean =>
   requirements.eventStream || requirements.octetStream
 
-const httpClientMethodNames: Record<OpenAPISpecMethodName, string> = {
-  get: "get",
-  put: "put",
-  post: "post",
-  delete: "del",
-  options: "options",
-  head: "head",
-  patch: "patch",
-  trace: `make("TRACE")`
-}
-
+/**
+ * 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,
@@ -238,11 +263,11 @@ export const make = (
 ): ${name} => {
   ${helpers.join("\n  ")}
   const decodeSuccess =
-    <Schema extends ${importName}.Top>(schema: Schema) =>
+    <Schema extends ${importName}.Constraint>(schema: Schema) =>
     (response: HttpClientResponse.HttpClientResponse) =>
       HttpClientResponse.schemaBodyJson(schema)(response)
   const decodeError =
-    <const Tag extends string, Schema extends ${importName}.Top>(tag: Tag, schema: Schema) =>
+    <const Tag extends string, Schema extends ${importName}.Constraint>(tag: Tag, schema: Schema) =>
     (response: HttpClientResponse.HttpClientResponse) =>
       Effect.flatMap(
         HttpClientResponse.schemaBodyJson(schema)(response),
@@ -281,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})`)
     }
@@ -306,7 +333,7 @@ export const make = (
 
     return (
       `"${operation.id}": (${params}) => ` +
-      `HttpClientRequest.${httpClientMethodNames[operation.method]}(${operation.pathTemplate})` +
+      `HttpClientRequest.${operation.method}(${operation.pathTemplate})` +
       `.pipe(\n    ${pipeline.join(",\n    ")}\n  )`
     )
   }
@@ -347,7 +374,7 @@ export const make = (
 
     return (
       `"${operation.id}Sse": (${params}) => ` +
-      `HttpClientRequest.${httpClientMethodNames[operation.method]}(${operation.pathTemplate})` +
+      `HttpClientRequest.${operation.method}(${operation.pathTemplate})` +
       `.pipe(\n      ${pipeline.join(",\n      ")}\n    )`
     )
   }
@@ -388,13 +415,14 @@ export const make = (
 
     return (
       `"${operation.id}Stream": (${params}) => ` +
-      `HttpClientRequest.${httpClientMethodNames[operation.method]}(${operation.pathTemplate})` +
+      `HttpClientRequest.${operation.method}(${operation.pathTemplate})` +
       `.pipe(\n      ${pipeline.join(",\n      ")}\n    )`
     )
   }
 
   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"`,
@@ -421,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,
@@ -701,7 +753,7 @@ export const make = (
 
     return (
       `"${operation.id}": (${params}) => ` +
-      `HttpClientRequest.${httpClientMethodNames[operation.method]}(${operation.pathTemplate})` +
+      `HttpClientRequest.${operation.method}(${operation.pathTemplate})` +
       `.pipe(\n    ${pipeline.join(",\n    ")}\n  )`
     )
   }
@@ -742,7 +794,7 @@ export const make = (
 
     return (
       `"${operation.id}Sse": (${params}) => ` +
-      `HttpClientRequest.${httpClientMethodNames[operation.method]}(${operation.pathTemplate})` +
+      `HttpClientRequest.${operation.method}(${operation.pathTemplate})` +
       `.pipe(\n      ${pipeline.join(",\n      ")}\n    )`
     )
   }
@@ -783,13 +835,14 @@ export const make = (
 
     return (
       `"${operation.id}Stream": (${params}) => ` +
-      `HttpClientRequest.${httpClientMethodNames[operation.method]}(${operation.pathTemplate})` +
+      `HttpClientRequest.${operation.method}(${operation.pathTemplate})` +
       `.pipe(\n      ${pipeline.join(",\n      ")}\n    )`
     )
   }
 
   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"`,
@@ -806,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
@@ -852,7 +917,7 @@ const sseRequestSource = (_importName: string) =>
      Type,
      DecodingServices
     >(
-      schema: Schema.Decoder<Type, DecodingServices>
+      schema: Schema.ConstraintDecoder<Type, DecodingServices>
     ) =>
     (
       request: HttpClientRequest.HttpClientRequest