@let-aurn/swagger-client 0.4.0 → 0.5.0

package/README.md

@@ -24,6 +24,63 @@ npx swagger-client generate --config=swagger-client.json
 
 `client` can be `angular` or `react`.
 
+`enum-style` is optional and accepts `"union"` (the default) or `"enum"`:
+
+```json
+{
+  "enum-style": "enum"
+}
+```
+
+Union style emits literal types such as `"PENDING" | "IN_PROGRESS"`.
+Enum style emits exported runtime TypeScript enums in `api-models.ts` and uses
+them in model properties and endpoint request/response types:
+
+```ts
+export enum TaskState {
+  PENDING = "PENDING",
+  IN_PROGRESS = "IN_PROGRESS",
+  COMPLETED = "COMPLETED",
+}
+
+export interface Task {
+  state?: TaskState;
+}
+```
+
+Standalone enum schemas keep their generated schema names. Inline enums use
+the enclosing model name plus the property path; array items add `Item`, and
+dictionary values add `Value`. Endpoint enums use the endpoint name followed
+by `Path`, `Query`, `Header`, `Body`, or `Response` and the nested property path.
+Declaration and member name collisions receive numeric suffixes. Identical
+inline enums in different locations remain separate declarations; use a shared
+schema with `$ref` to share a single enum.
+
+String values retain valid member names such as `PENDING`; invalid identifier
+characters are removed, leading digits receive a `Value` prefix, and reserved
+names are adjusted. Numeric members use names such as `Value_0` and
+`Value_Minus_1`. Every member has an explicit initializer that preserves its
+original JSON value. Duplicate values are emitted once. String, numeric, and
+mixed string/numeric enums are supported; enums containing boolean or structured
+values remain literal unions because TypeScript enums cannot represent them.
+Null values and `nullable: true` become `EnumName | null`. Nullable standalone
+enum schemas emit an `EnumNameValue` enum plus an `EnumName` type alias.
+
+When enabling enum style, use enum members instead of assigning raw strings:
+
+```ts
+import { TaskState } from './api-models';
+import type { Task } from './api-models';
+
+const task: Task = {
+  state: TaskState.PENDING,
+};
+```
+
+Enums exist at runtime; serialized request values are still the original strings
+or numbers. This option changes generated types only and does not validate or
+convert server responses at runtime.
+
 `swaggers-directory` accepts a directory (all JSON files recursively), a file
 glob, or an array of include/exclude glob patterns. Paths are relative to the
 command's working directory; absolute paths also work. Use forward slashes in

package/dist/core/enums.d.ts

@@ -0,0 +1,12 @@
+import type { EnumStyle, OpenApiSchema, SchemaModel } from "./types.js";
+export declare function validateEnumStyle(style: EnumStyle | undefined, source: string): void;
+/** Extracts inline enums before endpoint schemas are converted to type strings. */
+export declare class EnumCollector {
+    private readonly schemas;
+    private readonly usedNames;
+    private readonly style;
+    constructor(schemas: SchemaModel[], usedNames: Set<string>, style: EnumStyle);
+    addModel(name: string, schema: OpenApiSchema): void;
+    normalize(schema: OpenApiSchema, context: string): OpenApiSchema;
+}
+export declare function emitEnum(name: string, values: (string | number)[]): string;

package/dist/core/enums.js

@@ -0,0 +1,77 @@
+import { ensureIdentifier, toPascalCase, uniqueName } from "./names.js";
+export function validateEnumStyle(style, source) {
+    if (style !== undefined && style !== "union" && style !== "enum") {
+        throw new Error(`${source}: "enum-style" must be "union" or "enum".`);
+    }
+}
+function enumValues(schema) {
+    if (schema.$ref || !schema.enum?.length)
+        return undefined;
+    const values = schema.enum.filter((value) => value !== null);
+    if (!values.length || !values.every((value) => typeof value === "string" || (typeof value === "number" && Number.isFinite(value)))) {
+        return undefined;
+    }
+    return [...new Set(values)];
+}
+/** Extracts inline enums before endpoint schemas are converted to type strings. */
+export class EnumCollector {
+    schemas;
+    usedNames;
+    style;
+    constructor(schemas, usedNames, style) {
+        this.schemas = schemas;
+        this.usedNames = usedNames;
+        this.style = style;
+    }
+    addModel(name, schema) {
+        const values = this.style === "enum" ? enumValues(schema) : undefined;
+        if (values && !schema.nullable && !schema.enum.includes(null)) {
+            this.schemas.push({ name, schema, enumValues: values });
+        }
+        else {
+            this.schemas.push({ name, schema: this.normalize(schema, values ? `${name}Value` : name) });
+        }
+    }
+    normalize(schema, context) {
+        if (this.style === "union")
+            return schema;
+        const values = enumValues(schema);
+        if (values) {
+            const name = uniqueName(toPascalCase(context), this.usedNames);
+            this.schemas.push({ name, schema: { enum: values }, enumValues: values });
+            return {
+                $ref: `#/components/schemas/${name}`,
+                nullable: schema.nullable === true || schema.enum.includes(null)
+            };
+        }
+        const result = { ...schema };
+        if (schema.properties) {
+            result.properties = Object.fromEntries(Object.entries(schema.properties).map(([key, child]) => [key, this.normalize(child, `${context}${toPascalCase(key)}`)]));
+        }
+        if (schema.items)
+            result.items = this.normalize(schema.items, `${context}Item`);
+        if (typeof schema.additionalProperties === "object") {
+            result.additionalProperties = this.normalize(schema.additionalProperties, `${context}Value`);
+        }
+        for (const kind of ["allOf", "oneOf", "anyOf"]) {
+            if (schema[kind]) {
+                result[kind] = schema[kind].map((child, index) => this.normalize(child, `${context}${toPascalCase(kind)}${index + 1}`));
+            }
+        }
+        return result;
+    }
+}
+export function emitEnum(name, values) {
+    const usedNames = new Set();
+    const members = values.map((value) => {
+        const preferred = typeof value === "number" ? `Value_${String(value).replace(/-/g, "Minus_").replace(/\./g, "_")}` : value;
+        const identifier = ensureIdentifier(preferred || "Value", "Value");
+        // These names conflict with the enum object's prototype or its JS setter.
+        const safeIdentifier = identifier === "prototype" || identifier === "__proto__"
+            ? `${identifier}Value`
+            : identifier;
+        const member = uniqueName(safeIdentifier, usedNames);
+        return `  ${member} = ${JSON.stringify(value)},`;
+    });
+    return [`export enum ${name} {`, ...members, "}"].join("\n");
+}

package/dist/core/generate.js

@@ -13,7 +13,7 @@ import { emitReactClient } from "../generators/react-client.js";
  * @throws Error when OpenAPI files cannot be read or generated files cannot be written.
  */
 export async function generate(config) {
-    const project = await readOpenApiProject(config["swaggers-directory"], config["endpoint-name-strategy"], config["endpoint-namespace"], config.serverUrlIndex);
+    const project = await readOpenApiProject(config["swaggers-directory"], config["endpoint-name-strategy"], config["endpoint-namespace"], config.serverUrlIndex, config["enum-style"]);
     const modelsPath = config.output["api-models.ts"];
     const endpointsPath = config.output["api-endpoints.ts"];
     const clientPath = config.output["client.ts"];

package/dist/core/load-config.js

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { validateEndpointNamespace } from "./endpoint-namespace.js";
 import { validateServerUrlIndex } from "./server-url.js";
 import { resolveSwaggerInput, validateSwaggerInput } from "./swagger-files.js";
+import { validateEnumStyle } from "./enums.js";
 /**
  * Loads and validates a swagger-client configuration file.
  *
@@ -26,6 +27,7 @@ export async function loadConfig(configPath) {
     };
 }
 function validateConfig(config, configPath) {
+    validateEnumStyle(config["enum-style"], configPath);
     validateServerUrlIndex(config.serverUrlIndex, configPath);
     if (config.client !== "angular" && config.client !== "react") {
         throw new Error(`${configPath}: "client" must be "angular" or "react".`);

package/dist/core/read-openapi.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointNameStrategy, EndpointNamespaceConfig, ProjectModel } from "./types.js";
+import type { EndpointNameStrategy, EnumStyle, EndpointNamespaceConfig, ProjectModel } from "./types.js";
 /**
  * Reads selected OpenAPI JSON files and converts them to the generator project model.
  *
@@ -6,7 +6,8 @@ import type { EndpointNameStrategy, EndpointNamespaceConfig, ProjectModel } from
  * @param endpointNameStrategy The strategy used to name generated endpoint constants.
  * @param endpointNamespace Configurable document field and optional namespace extraction regex.
  * @param serverUrlIndex Optional document server URL index to prefix endpoint paths with.
+ * @param enumStyle Emit literal unions (default) or named runtime enums.
  * @returns The normalized schemas and endpoints discovered in the OpenAPI files.
  * @throws Error when a JSON file cannot be read or parsed.
  */
-export declare function readOpenApiProject(swaggerDirectory: string | string[], endpointNameStrategy?: EndpointNameStrategy, endpointNamespace?: EndpointNamespaceConfig, serverUrlIndex?: number): Promise<ProjectModel>;
+export declare function readOpenApiProject(swaggerDirectory: string | string[], endpointNameStrategy?: EndpointNameStrategy, endpointNamespace?: EndpointNamespaceConfig, serverUrlIndex?: number, enumStyle?: EnumStyle): Promise<ProjectModel>;

package/dist/core/read-openapi.js

@@ -5,6 +5,7 @@ import { ensureIdentifier, toPascalCase, uniqueName } from "./names.js";
 import { extractEndpointNamespace, validateEndpointNamespace } from "./endpoint-namespace.js";
 import { selectServerUrl, validateServerUrlIndex } from "./server-url.js";
 import { discoverSwaggerFiles } from "./swagger-files.js";
+import { EnumCollector, validateEnumStyle } from "./enums.js";
 const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
 /**
  * Reads selected OpenAPI JSON files and converts them to the generator project model.
@@ -13,10 +14,12 @@ const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "
  * @param endpointNameStrategy The strategy used to name generated endpoint constants.
  * @param endpointNamespace Configurable document field and optional namespace extraction regex.
  * @param serverUrlIndex Optional document server URL index to prefix endpoint paths with.
+ * @param enumStyle Emit literal unions (default) or named runtime enums.
  * @returns The normalized schemas and endpoints discovered in the OpenAPI files.
  * @throws Error when a JSON file cannot be read or parsed.
  */
-export async function readOpenApiProject(swaggerDirectory, endpointNameStrategy = "operationId", endpointNamespace, serverUrlIndex) {
+export async function readOpenApiProject(swaggerDirectory, endpointNameStrategy = "operationId", endpointNamespace, serverUrlIndex, enumStyle = "union") {
+    validateEnumStyle(enumStyle, String(swaggerDirectory));
     validateServerUrlIndex(serverUrlIndex, String(swaggerDirectory));
     if (endpointNameStrategy === "namespaceTagAndOperationId") {
         validateEndpointNamespace(endpointNamespace, String(swaggerDirectory));
@@ -26,19 +29,20 @@ export async function readOpenApiProject(swaggerDirectory, endpointNameStrategy
     const endpoints = [];
     const usedSchemaNames = new Set();
     const usedEndpointNames = new Set();
+    const enums = new EnumCollector(schemas, usedSchemaNames, enumStyle);
     for (const file of files) {
         const document = JSON.parse(await readFile(file, "utf8"));
         const sourceFile = relative(sourceDirectory, file);
         const serverUrl = selectServerUrl(document, serverUrlIndex, sourceFile);
-        const schemaNameMap = collectSchemas(document, schemas, usedSchemaNames);
+        const schemaNameMap = collectSchemas(document, enums, usedSchemaNames);
         const namespace = endpointNameStrategy === "namespaceTagAndOperationId"
             ? extractEndpointNamespace(document, endpointNamespace, sourceFile)
             : undefined;
-        endpoints.push(...collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy, namespace, serverUrl));
+        endpoints.push(...collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy, namespace, serverUrl, enums));
     }
     return { schemas, endpoints };
 }
-function collectSchemas(document, schemas, usedSchemaNames) {
+function collectSchemas(document, enums, usedSchemaNames) {
     const schemaNameMap = new Map();
     const sourceSchemas = document.components?.schemas ?? document.definitions ?? {};
     for (const rawName of Object.keys(sourceSchemas)) {
@@ -50,14 +54,11 @@ function collectSchemas(document, schemas, usedSchemaNames) {
         if (!generatedName) {
             continue;
         }
-        schemas.push({
-            name: generatedName,
-            schema: rewriteRefs(schema, schemaNameMap)
-        });
+        enums.addModel(generatedName, rewriteRefs(schema, schemaNameMap));
     }
     return schemaNameMap;
 }
-function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy, namespace, serverUrl = "") {
+function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames, endpointNameStrategy, namespace, serverUrl, enums) {
     const endpoints = [];
     for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
         if (!isRecord(pathItem)) {
@@ -76,11 +77,11 @@ function collectEndpoints(document, sourceFile, schemaNameMap, usedEndpointNames
                 path: serverUrl && path ? `${serverUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}` : serverUrl || path,
                 operationId,
                 sourceFile,
-                pathVariables: variablesFor(parameters, "path", schemaNameMap),
-                queryVariables: variablesFor(parameters, "query", schemaNameMap),
-                headerVariables: variablesFor(parameters, "header", schemaNameMap),
-                bodyType: requestBodyType(operation, schemaNameMap),
-                responseType: responseType(operation.responses, schemaNameMap)
+                pathVariables: variablesFor(parameters, "path", schemaNameMap, enums, endpointName),
+                queryVariables: variablesFor(parameters, "query", schemaNameMap, enums, endpointName),
+                headerVariables: variablesFor(parameters, "header", schemaNameMap, enums, endpointName),
+                bodyType: requestBodyType(operation, schemaNameMap, enums, endpointName),
+                responseType: responseType(operation.responses, schemaNameMap, enums, endpointName)
             });
         }
     }
@@ -101,26 +102,26 @@ function endpointNameForOperation(operation, operationId, strategy, namespace) {
     }
     return `${namespace}_${taggedName}`;
 }
-function variablesFor(parameters, location, schemaNameMap) {
+function variablesFor(parameters, location, schemaNameMap, enums, endpointName) {
     return parameters
         .filter((parameter) => parameter.in === location)
         .map((parameter) => ({
         name: parameter.name,
-        type: schemaToType(rewriteRefs(parameter.schema ?? { type: "string" }, schemaNameMap)),
+        type: schemaToType(enums.normalize(rewriteRefs(parameter.schema ?? { type: "string" }, schemaNameMap), `${toPascalCase(endpointName)}${toPascalCase(location)}${toPascalCase(parameter.name)}`)),
         required: parameter.required === true || location === "path"
     }));
 }
-function requestBodyType(operation, schemaNameMap) {
+function requestBodyType(operation, schemaNameMap, enums, endpointName) {
     const schema = preferredContentSchema(operation.requestBody?.content);
-    return schema ? schemaToType(rewriteRefs(schema, schemaNameMap)) : null;
+    return schema ? schemaToType(enums.normalize(rewriteRefs(schema, schemaNameMap), `${toPascalCase(endpointName)}Body`)) : null;
 }
-function responseType(responses, schemaNameMap) {
+function responseType(responses, schemaNameMap, enums, endpointName) {
     const response = responses?.["200"] ?? responses?.["201"] ?? responses?.["204"] ?? firstSuccessResponse(responses);
     const schema = preferredContentSchema(response?.content);
     if (!schema || response === responses?.["204"]) {
         return "void";
     }
-    return schemaToType(rewriteRefs(schema, schemaNameMap));
+    return schemaToType(enums.normalize(rewriteRefs(schema, schemaNameMap), `${toPascalCase(endpointName)}Response`));
 }
 function firstSuccessResponse(responses) {
     return Object.entries(responses ?? {}).find(([status]) => status.startsWith("2"))?.[1];

package/dist/core/schema-to-typescript.js

@@ -59,7 +59,7 @@ function schemaToNonNullableType(schema, fallback) {
         return (schema.oneOf ?? schema.anyOf ?? []).map((item) => schemaToType(item, fallback)).join(" | ") || fallback;
     }
     if (schema.type === "array") {
-        return `${schemaToType(schema.items, "unknown")}[]`;
+        return `Array<${schemaToType(schema.items, "unknown")}>`;
     }
     if (schema.type === "object" || schema.properties) {
         const entries = Object.entries(schema.properties ?? {});

package/dist/core/types.d.ts

@@ -1,4 +1,5 @@
 export type ClientKind = "angular" | "react";
+export type EnumStyle = "union" | "enum";
 export type EndpointNameStrategy = "operationId" | "tagAndOperationId" | "namespaceTagAndOperationId";
 export interface EndpointNamespaceConfig {
     /** JSON Pointer to a string in each OpenAPI document. */
@@ -8,6 +9,8 @@ export interface EndpointNamespaceConfig {
 }
 export interface SwaggerClientConfig {
     client: ClientKind;
+    /** Emit literal unions by default, or named runtime enums. */
+    "enum-style"?: EnumStyle;
     /** Directory, file glob, or include/exclude glob patterns, relative to the working directory. */
     "swaggers-directory": string | string[];
     "endpoint-name-strategy"?: EndpointNameStrategy;
@@ -27,6 +30,7 @@ export interface ProjectModel {
 export interface SchemaModel {
     name: string;
     schema: OpenApiSchema;
+    enumValues?: (string | number)[];
 }
 export interface EndpointModel {
     name: string;

package/dist/generators/endpoints.js

@@ -136,7 +136,11 @@ function propertyKey(name) {
     return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : quote(name);
 }
 function qualifyModelTypes(type, modelNames) {
-    return type.replace(/\b[A-Z][A-Za-z0-9_]*\b/g, (name) => {
+    return type.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|\b[A-Z][A-Za-z0-9_]*\b/g, (name, offset) => {
+        // Preserve string literals and property keys that happen to match model names.
+        if (name.startsWith('"') || name.startsWith("'") || /^\s*\??\s*:/.test(type.slice(offset + name.length))) {
+            return name;
+        }
         return modelNames.has(name) ? `ApiModels.${name}` : name;
     });
 }

package/dist/generators/models.js

@@ -1,4 +1,5 @@
 import { emitSchemaInterface } from "../core/schema-to-typescript.js";
+import { emitEnum } from "../core/enums.js";
 /**
  * Emits the generated TypeScript API model file.
  *
@@ -12,7 +13,9 @@ export function emitModels(project) {
         ""
     ];
     for (const schema of project.schemas) {
-        lines.push(emitSchemaInterface(schema.name, schema.schema), "");
+        lines.push(schema.enumValues
+            ? emitEnum(schema.name, schema.enumValues)
+            : emitSchemaInterface(schema.name, schema.schema), "");
     }
     return lines.join("\n");
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { ClientKind, EndpointNameStrategy, EndpointNamespaceConfig, EndpointModel, ProjectModel, SchemaModel, SwaggerClientConfig, VariableModel } from "./core/types.js";
+export type { ClientKind, EnumStyle, EndpointNameStrategy, EndpointNamespaceConfig, EndpointModel, ProjectModel, SchemaModel, SwaggerClientConfig, VariableModel } from "./core/types.js";
 export { generate } from "./core/generate.js";
 export { loadConfig } from "./core/load-config.js";
 export { readOpenApiProject } from "./core/read-openapi.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@let-aurn/swagger-client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Generate typed Angular and React clients from OpenAPI JSON files.",
   "type": "module",
   "bin": {