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

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}`
+}