react-query-lightbase-codegen 2.5.11 → 3.1.0

package/src/generator/schemaGenerator.ts

@@ -1,9 +1,27 @@
 import type { OpenAPIV3 } from "openapi-types";
-import { getTypeFromSchema, pascalCase, sanitizePropertyName, sanitizeTypeName } from "../utils";
+import {
+	getContentSchema,
+	getTypeFromSchema,
+	pascalCase,
+	sanitizePropertyName,
+	sanitizeTypeName,
+} from "../utils";
 
-interface SchemaContext {
-	schemas: { [key: string]: OpenAPIV3.SchemaObject };
-	generatedTypes: Set<string>;
+/**
+ * Formats a parameter as a TypeScript property string with optional JSDoc.
+ */
+function formatParamProperty(param: OpenAPIV3.ParameterObject, forceRequired = false): string {
+	const safeName = sanitizePropertyName(param.name);
+	const isDeprecated = param.deprecated;
+	const hasDescription = param.description;
+	const isOptional = forceRequired ? false : !param.required;
+
+	const desc =
+		hasDescription || isDeprecated
+			? `/**${hasDescription ? `\n * ${param.description}` : ""}${isDeprecated ? "\n * @deprecated" : ""}\n */\n`
+			: "";
+
+	return `${desc}${safeName}${isOptional ? "?" : ""}: ${getTypeFromSchema(param.schema)}`;
 }
 
 function generateTypeDefinition(
@@ -26,18 +44,16 @@ function generateTypeDefinition(
  * Generates TypeScript interface definitions from OpenAPI schemas
  */
 export function generateTypeDefinitions(spec: OpenAPIV3.Document): string {
-	const context: SchemaContext = {
-		schemas: (spec.components?.schemas as { [key: string]: OpenAPIV3.SchemaObject }) || {},
-		generatedTypes: new Set(),
-	};
+	const schemas = (spec.components?.schemas as { [key: string]: OpenAPIV3.SchemaObject }) || {};
+	const generatedTypes = new Set<string>();
 
 	let output = "/* Generated TypeScript Definitions */\n\n";
 
 	// Generate types for all schema definitions
-	for (const [name, schema] of Object.entries(context.schemas)) {
-		if (context.generatedTypes.has(name)) continue;
+	for (const [name, schema] of Object.entries(schemas)) {
+		if (generatedTypes.has(name)) continue;
 		output += generateTypeDefinition(name, schema);
-		context.generatedTypes.add(name);
+		generatedTypes.add(name);
 	}
 
 	// Generate request/response types
@@ -54,34 +70,36 @@ export function generateTypeDefinitions(spec: OpenAPIV3.Document): string {
 				// Generate request body type
 				if (requestBody) {
 					const content = (requestBody as OpenAPIV3.RequestBodyObject).content;
-					const jsonContent =
-						content["application/ld+json"] ??
-						content["application/json"] ??
-						content["multipart/form-data"] ??
-						content["application/octet-stream"] ??
-						content["application/json;charset=UTF-8"];
-					if (jsonContent?.schema) {
+					const requestSchema = getContentSchema(content);
+					if (requestSchema) {
 						const typeName = `${operationId}Request`;
-						output += generateTypeDefinition(typeName, jsonContent.schema as OpenAPIV3.SchemaObject);
+						output += generateTypeDefinition(typeName, requestSchema as OpenAPIV3.SchemaObject);
 					}
 				}
 
 				// Generate response types
+				const errorTypes: string[] = [];
 				if (responses) {
 					for (const [code, response] of Object.entries(responses)) {
 						const responseObj = response as OpenAPIV3.ResponseObject;
-						const content =
-							responseObj.content?.["application/ld+json"] ??
-							responseObj.content?.["application/json"] ??
-							responseObj.content?.["application/octet-stream"] ??
-							responseObj.content?.["application/json;charset=UTF-8"];
-						if (content?.schema) {
+						const responseSchema = getContentSchema(responseObj.content);
+						if (responseSchema) {
 							const typeName = `${operationId}Response${code}`;
-							output += generateTypeDefinition(typeName, content.schema as OpenAPIV3.SchemaObject);
+							output += generateTypeDefinition(typeName, responseSchema as OpenAPIV3.SchemaObject);
+
+							// Track non-2xx responses for error union type
+							if (!code.startsWith("2")) {
+								errorTypes.push(typeName);
+							}
 						}
 					}
 				}
 
+				// Generate error union type if there are error responses
+				if (errorTypes.length > 0) {
+					output += `export type ${pascalCase(operationId)}Error = ${errorTypes.join(" | ")};\n\n`;
+				}
+
 				// Build data type parts
 				const dataProps: string[] = [];
 
@@ -91,43 +109,14 @@ export function generateTypeDefinitions(spec: OpenAPIV3.Document): string {
 					[]) as OpenAPIV3.ParameterObject[];
 				const headerParams = (parameters?.filter((p) => "in" in p && p.in === "header") ||
 					[]) as OpenAPIV3.ParameterObject[];
+				const cookieParams = (parameters?.filter((p) => "in" in p && p.in === "cookie") ||
+					[]) as OpenAPIV3.ParameterObject[];
 
-				// Add path and query parameters
-				urlParams.forEach((p) => {
-					const safeName = sanitizePropertyName(p.name);
-					const isDeprecated = "deprecated" in p && p.deprecated;
-					const hasDescription = "description" in p && p.description;
-					const desc =
-						hasDescription || isDeprecated
-							? `/**${hasDescription ? `\n* ${p.description}` : ""}${isDeprecated ? "\n* @deprecated" : ""}
-							*/\n`
-							: "";
-					dataProps.push(`${desc}${safeName}: ${getTypeFromSchema(p.schema)}`);
-				});
-
-				queryParams.forEach((p) => {
-					const safeName = sanitizePropertyName(p.name);
-					const isDeprecated = "deprecated" in p && p.deprecated;
-					const hasDescription = "description" in p && p.description;
-					const desc =
-						hasDescription || isDeprecated
-							? `\n/**${hasDescription ? `\n* ${p.description}` : ""}${isDeprecated ? "\n* @deprecated" : ""}
-							*/\n`
-							: "";
-					dataProps.push(`${desc}${safeName}${p.required ? "" : "?"}: ${getTypeFromSchema(p.schema)}`);
-				});
-
-				headerParams.forEach((p) => {
-					const safeName = sanitizePropertyName(p.name);
-					const isDeprecated = "deprecated" in p && p.deprecated;
-					const hasDescription = "description" in p && p.description;
-					const desc =
-						hasDescription || isDeprecated
-							? `\n/**${hasDescription ? `\n* ${p.description}` : ""}${isDeprecated ? "\n* @deprecated" : ""}
-							*/\n`
-							: "";
-					dataProps.push(`${desc}${safeName}${p.required ? "" : "?"}: ${getTypeFromSchema(p.schema)}`);
-				});
+				// Add path, query, header, and cookie parameters
+				urlParams.forEach((p) => dataProps.push(formatParamProperty(p, true))); // Path params always required
+				queryParams.forEach((p) => dataProps.push(formatParamProperty(p)));
+				headerParams.forEach((p) => dataProps.push(formatParamProperty(p)));
+				cookieParams.forEach((p) => dataProps.push(formatParamProperty(p)));
 
 				// Add request body type if it exists
 				const hasData = (parameters && parameters.length > 0) || requestBody;

package/src/utils.ts

@@ -1,5 +1,118 @@
 import type { OpenAPIV3 } from "openapi-types";
 
+/**
+ * Supported content types in order of preference
+ */
+export const CONTENT_TYPES = [
+	"application/ld+json",
+	"application/json",
+	"text/plain",
+	"multipart/form-data",
+	"application/octet-stream",
+	"application/json;charset=UTF-8",
+] as const;
+
+/**
+ * Resolves a schema reference to its actual schema object.
+ * If the schema is already a concrete schema (not a $ref), returns it as-is.
+ */
+export function resolveSchema(
+	schema: OpenAPIV3.ReferenceObject | OpenAPIV3.SchemaObject | undefined,
+	spec: OpenAPIV3.Document
+): OpenAPIV3.SchemaObject | undefined {
+	if (!schema) return undefined;
+	if ("$ref" in schema) {
+		const index = schema.$ref.split("/").pop();
+		return spec.components?.schemas?.[index as string] as OpenAPIV3.SchemaObject;
+	}
+	return schema;
+}
+
+/**
+ * Extracts the schema from a content object, checking supported content types in order.
+ */
+export function getContentSchema(
+	content: { [media: string]: OpenAPIV3.MediaTypeObject } | undefined
+): OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined {
+	if (!content) return undefined;
+	for (const type of CONTENT_TYPES) {
+		if (content[type]?.schema) {
+			return content[type].schema;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Operation info extracted from OpenAPI paths
+ */
+export interface OperationInfo {
+	method: string;
+	path: string;
+	operationId: string;
+	summary?: string;
+	description?: string;
+	deprecated?: boolean;
+	parameters: OpenAPIV3.ParameterObject[];
+	requestBody?: OpenAPIV3.RequestBodyObject;
+	responses: OpenAPIV3.ResponsesObject;
+}
+
+const HTTP_METHODS = ["get", "post", "put", "delete", "patch"] as const;
+
+/**
+ * Collects all operations from an OpenAPI spec, resolving parameter and request body references.
+ */
+export function collectOperations(spec: OpenAPIV3.Document): OperationInfo[] {
+	const operations: OperationInfo[] = [];
+
+	const resolveParameters = (
+		parameters: (OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject)[]
+	): OpenAPIV3.ParameterObject[] => {
+		return parameters.map((p) => {
+			if ("$ref" in p) {
+				const index = p.$ref.split("/").pop();
+				return spec.components?.parameters?.[index as string] as OpenAPIV3.ParameterObject;
+			}
+			return p;
+		});
+	};
+
+	const resolveRequestBody = (
+		requestBody: OpenAPIV3.RequestBodyObject | OpenAPIV3.ReferenceObject | undefined
+	): OpenAPIV3.RequestBodyObject | undefined => {
+		if (!requestBody) return undefined;
+		if ("$ref" in requestBody) {
+			const index = requestBody.$ref.split("/").pop();
+			return spec.components?.requestBodies?.[index as string] as OpenAPIV3.RequestBodyObject;
+		}
+		return requestBody;
+	};
+
+	Object.entries(spec.paths || {}).forEach(([path, pathItem]) => {
+		if (!pathItem) return;
+
+		HTTP_METHODS.forEach((method) => {
+			const operation = pathItem[method] as OpenAPIV3.OperationObject | undefined;
+			if (!operation) return;
+
+			operations.push({
+				method,
+				path,
+				operationId: sanitizeTypeName(operation.operationId || path.replace(/\W+/g, "_")),
+				summary: operation.summary,
+				description: operation.description,
+				deprecated: operation.deprecated,
+				parameters: resolveParameters([...(pathItem.parameters || []), ...(operation.parameters || [])]),
+				requestBody: resolveRequestBody(operation.requestBody),
+				responses: operation.responses,
+			});
+		});
+	});
+
+	return operations;
+}
+
 export function camelCase(str: string): string {
 	return str
 		.replace(/[^a-zA-Z0-9]+(.)/g, (_, chr) => chr.toUpperCase())
@@ -63,6 +176,7 @@ export function specTitle(spec: OpenAPIV3.Document): string {
  * Handles:
  * - References ($ref) by extracting the type name
  * - Nullable types by appending "| null"
+ * - Composition types (allOf → intersection, oneOf/anyOf → union)
  * - Enums by creating union types of the values
  * - OneOf schemas as union types
  * - Basic types (string, number, boolean)
@@ -72,7 +186,7 @@ export function specTitle(spec: OpenAPIV3.Document): string {
  * - Objects with additionalProperties as Records
  * - Fallback to "any" for unknown types
  *
- * @param param - The OpenAPI schema/parameter object to convert
+ * @param schema - The OpenAPI schema/parameter object to convert
  * @returns The TypeScript type as a string
  */
 export function getTypeFromSchema(
@@ -88,6 +202,30 @@ export function getTypeFromSchema(
 	// Add "| null" for nullable types
 	const nullable = "nullable" in schema && schema.nullable ? " | null" : "";
 
+	// Handle allOf (intersection types)
+	if ("allOf" in schema && schema.allOf) {
+		const types = schema.allOf.map((s) => getTypeFromSchema(s)).filter(Boolean) as string[];
+		if (types.length === 0) return "unknown";
+		const result = types.length === 1 ? types[0] : `(${types.join(" & ")})`;
+		return `${result}${nullable}`;
+	}
+
+	// Handle oneOf (union types - exactly one)
+	if ("oneOf" in schema && schema.oneOf) {
+		const types = schema.oneOf.map((s) => getTypeFromSchema(s)).filter(Boolean) as string[];
+		if (types.length === 0) return "unknown";
+		const result = types.length === 1 ? types[0] : `(${types.join(" | ")})`;
+		return `${result}${nullable}`;
+	}
+
+	// Handle anyOf (union types - one or more)
+	if ("anyOf" in schema && schema.anyOf) {
+		const types = schema.anyOf.map((s) => getTypeFromSchema(s)).filter(Boolean) as string[];
+		if (types.length === 0) return "unknown";
+		const result = types.length === 1 ? types[0] : `(${types.join(" | ")})`;
+		return `${result}${nullable}`;
+	}
+
 	// Handle enums as union types
 	if ("enum" in schema && schema.enum) {
 		if (Object.values(schema.enum)?.length > 0) {
@@ -100,14 +238,6 @@ export function getTypeFromSchema(
 		return schema.enum.map((e) => (typeof e === "string" ? `'${e}'` : e)).join(" | ") + nullable;
 	}
 
-	// Handle oneOf as union types
-	if ("oneOf" in schema && schema.oneOf) {
-		const unionTypes = schema.oneOf
-			.map((subSchema) => getTypeFromSchema(subSchema))
-			.filter((type): type is string => type !== undefined);
-		return unionTypes.length > 0 ? `${unionTypes.join(" | ")}${nullable}` : `any${nullable}`;
-	}
-
 	// Handle types based on the "type" property
 	if ("type" in schema) {
 		switch (schema.type) {
@@ -143,8 +273,7 @@ export function getTypeFromSchema(
 							const hasDescription = "description" in prop && prop.description;
 							const desc =
 								hasDescription || isDeprecated
-									? `/**${hasDescription ? `\n* ${prop.description}` : ""}${isDeprecated ? "\n* @deprecated" : ""}
-									*/\n`
+									? `/**${hasDescription ? `\n * ${prop.description}` : ""}${isDeprecated ? "\n * @deprecated" : ""}\n */\n`
 									: "";
 							return `${desc}${safeName}${isRequired ? "" : "?"}: ${propertyType};`;
 						})
@@ -156,19 +285,19 @@ export function getTypeFromSchema(
 				if (schema.additionalProperties) {
 					const valueType =
 						typeof schema.additionalProperties === "boolean"
-							? "any"
+							? "unknown"
 							: getTypeFromSchema(schema.additionalProperties);
 					return `Record<string, ${valueType}>${nullable}`;
 				}
 
 				// Default object type when no properties specified
-				return `Record<string, any>${nullable}`;
+				return `Record<string, unknown>${nullable}`;
 
 			default:
-				return `any${nullable}`;
+				return `unknown${nullable}`;
 		}
 	}
 
 	// Fallback for schemas without a type
-	return "any";
+	return "unknown";
 }