@effect/openapi-generator 4.0.0-beta.9 → 4.0.0-beta.90

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(),

package/src/Utils.ts

@@ -1,6 +1,27 @@
+/**
+ * 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.
+ *
+ * **Details**
+ *
+ * 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 +45,26 @@ 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.
+ *
+ * **Details**
+ *
+ * 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 +74,17 @@ export const nonEmptyString = (a: unknown): string | undefined => {
   }
 }
 
+/**
+ * Renders an optional description as a JSDoc block for generated TypeScript.
+ *
+ * **Details**
+ *
+ * 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 +93,17 @@ export const toComment = UndefinedOr.match({
 */\n`
 })
 
+/**
+ * Appends every element from `source` into `destination` in order.
+ *
+ * **Details**
+ *
+ * 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])

package/src/main.ts

@@ -1,3 +1,13 @@
+/**
+ * Command-line entry point for generating Effect HTTP clients or HttpApi
+ * definitions from an OpenAPI specification.
+ *
+ * The CLI reads a spec file, optionally applies JSON patches in order, selects
+ * the generator layer for the requested output format, reports generation
+ * warnings to stderr, and writes the generated source to stdout.
+ *
+ * @since 4.0.0
+ */
 import * as Console from "effect/Console"
 import * as Effect from "effect/Effect"
 import type * as Schema from "effect/Schema"
@@ -10,18 +20,21 @@ import * as OpenApiPatch from "./OpenApiPatch.ts"
 
 const spec = Flag.fileParse("spec").pipe(
   Flag.withAlias("s"),
-  Flag.withDescription("The OpenAPI spec file to generate the client from")
+  Flag.withDescription("The OpenAPI spec file to generate output from")
 )
 
 const name = Flag.string("name").pipe(
   Flag.withAlias("n"),
-  Flag.withDescription("The name of the generated client"),
+  Flag.withDescription("The name of the generated output"),
   Flag.withDefault("Client")
 )
 
-const typeOnly = Flag.boolean("type-only").pipe(
-  Flag.withAlias("t"),
-  Flag.withDescription("Generate a type-only client without schemas")
+const format = Flag.choice("format", ["httpclient", "httpclient-type-only", "httpapi"] as const).pipe(
+  Flag.withAlias("f"),
+  Flag.withDescription(
+    "Output format to generate: httpclient | httpclient-type-only | httpapi (default: httpclient)"
+  ),
+  Flag.withDefault("httpclient")
 )
 
 const patch = Flag.string("patch").pipe(
@@ -34,8 +47,8 @@ const patch = Flag.string("patch").pipe(
   Flag.between(0, Infinity)
 )
 
-const root = Command.make("openapigen", { spec, typeOnly, name, patch }).pipe(
-  Command.withHandler(Effect.fnUntraced(function*({ name, spec, typeOnly, patch }) {
+const root = Command.make("openapigen", { spec, format, name, patch }).pipe(
+  Command.withHandler(Effect.fnUntraced(function*({ name, spec, format, patch }) {
     let patchedSpec: Schema.Json = spec as Schema.Json
 
     if (patch.length > 0) {
@@ -53,16 +66,51 @@ const root = Command.make("openapigen", { spec, typeOnly, name, patch }).pipe(
     }
 
     const generator = yield* OpenApiGenerator.OpenApiGenerator
-    const source = yield* generator.generate(patchedSpec as unknown as OpenAPISpec, { name, typeOnly })
+    const warnings: Array<OpenApiGenerator.OpenApiGeneratorWarning> = []
+    const source = yield* generator.generate(patchedSpec as unknown as OpenAPISpec, {
+      name,
+      format,
+      onWarning: (warning) => {
+        warnings.push(warning)
+      }
+    })
+    yield* Effect.forEach(
+      warnings,
+      (warning) => Console.error(formatWarning(warning)),
+      { discard: true }
+    )
     return yield* Console.log(source)
   })),
-  Command.provide(({ typeOnly }) =>
-    typeOnly
+  Command.provide(({ format }) =>
+    format === "httpclient-type-only"
       ? OpenApiGenerator.layerTransformerTs
       : OpenApiGenerator.layerTransformerSchema
   )
 )
 
+/**
+ * Runs the OpenAPI generator command-line program.
+ *
+ * **Details**
+ *
+ * The command reads an OpenAPI specification, optionally applies JSON patches,
+ * generates source code in the selected format, writes any generation warnings
+ * to stderr, and prints the generated source to stdout.
+ *
+ * @category running
+ * @since 4.0.0
+ */
 export const run: Effect.Effect<void, CliError.CliError, Command.Environment> = Command.run(root, {
   version: "0.0.0"
 })
+
+const formatWarning = (warning: OpenApiGenerator.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}`
+}