typed-openapi 2.2.3 → 2.2.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "typed-openapi",
   "type": "module",
-  "version": "2.2.3",
+  "version": "2.2.6",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "exports": {
@@ -18,27 +18,27 @@
     "directory": "packages/typed-openapi"
   },
   "dependencies": {
-    "@apidevtools/swagger-parser": "^10.1.1",
+    "@apidevtools/swagger-parser": "^12.1.0",
     "@sinclair/typebox-codegen": "^0.11.1",
-    "arktype": "2.1.20",
-    "cac": "^6.7.14",
-    "openapi3-ts": "^4.4.0",
+    "arktype": "2.2.0",
+    "cac": "7.0.0",
+    "openapi3-ts": "4.5.0",
+    "oxfmt": "0.45.0",
     "pastable": "^2.2.1",
-    "pathe": "^2.0.3",
-    "prettier": "3.5.3",
-    "ts-pattern": "^5.7.0"
+    "pathe": "2.0.3",
+    "ts-pattern": "^5.9.0"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.4",
-    "@tanstack/react-query": "5.85.0",
-    "@types/node": "^22.15.17",
-    "@types/prettier": "3.0.0",
-    "msw": "2.10.5",
-    "tstyche": "5.0.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.3",
-    "vitest": "^3.1.3",
-    "zod": "3.21.4"
+    "@changesets/cli": "^2.30.0",
+    "@tanstack/react-query": "5.99.0",
+    "@types/node": "^25.6.0",
+    "msw": "2.13.3",
+    "tstyche": "7.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vite": "7.3.2",
+    "vitest": "^4.1.4",
+    "zod": "4.3.6"
   },
   "files": [
     "src",
@@ -72,7 +72,7 @@
     "gen:runtime": "node bin.js ./tests/samples/petstore.yaml --output ./tmp/generated-client.ts --tanstack generated-tanstack.ts --default-fetcher",
     "test:runtime:run": "vitest run tests/integration-runtime-msw.test.ts",
     "test:runtime": "pnpm run gen:runtime && pnpm run test:runtime:run",
-    "fmt": "prettier --write src",
+    "fmt": "oxfmt --write src tests",
     "typecheck": "tsc -b ./tsconfig.build.json"
   }
 }

package/src/cli.ts

@@ -14,8 +14,12 @@ cli
     `Runtime to use for validation; defaults to \`none\`; available: ${allowedRuntimes.toString()}`,
     { default: "none" },
   )
+  .option("--format", "Format generated files with oxfmt (defaults to false)", { default: false })
   .option("--schemas-only", "Only generate schemas, skipping client generation (defaults to false)", { default: false })
   .option("--include-client", "Include API client types and implementation (defaults to true)", { default: true })
+  .option("--jsdoc", "Emit OpenAPI descriptions as JSDoc comments (defaults to false)", {
+    default: true,
+  })
   .option(
     "--success-status-codes <codes>",
     "Comma-separated list of success status codes (defaults to 2xx and 3xx ranges)",

package/src/format.ts

@@ -1,20 +1,75 @@
-import prettier, { type Options } from "prettier";
-import parserTypescript from "prettier/parser-typescript";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+type OxcFormatOptions = import("oxfmt").FormatConfig;
+
+export type PrettifyOptions = OxcFormatOptions & {
+  enabled?: boolean;
+  filePath?: string;
+};
+
+const defaultFilePath = "generated.ts";
+const require = createRequire(import.meta.url);
+
+async function formatWithBundledOxfmt(filePath: string, input: string, options?: OxcFormatOptions): Promise<string> {
+  const packageJsonPath = require.resolve("oxfmt/package.json");
+  const packageRoot = dirname(packageJsonPath);
+  const indexSource = await readFile(join(packageRoot, "dist", "index.js"), "utf8");
+  const match = indexSource.match(/from ["']\.\/(apis-[^"']+\.js)["']/);
+  const internalFile = match?.[1];
+
+  if (!internalFile) {
+    throw new Error("Unable to locate oxfmt's bundled JS formatter");
+  }
+
+  const internalUrl = pathToFileURL(join(packageRoot, "dist", internalFile)).href;
+  const { r: formatFile } = await import(internalUrl);
+
+  return formatFile({
+    code: input,
+    options: {
+      printWidth: 120,
+      trailingComma: "all",
+      ...options,
+      filepath: filePath,
+    },
+  });
+}
 
 /** @see https://github.dev/stephenh/ts-poet/blob/5ea0dbb3c9f1f4b0ee51a54abb2d758102eda4a2/src/Code.ts#L231 */
-function maybePretty(input: string, options?: Options | null) {
+async function maybePretty(input: string, options?: PrettifyOptions | null) {
+  const { enabled, filePath = defaultFilePath, ...formatOptions } = options ?? {};
+
+  if (enabled === false) {
+    return input;
+  }
+
   try {
-    return prettier.format(input, {
-      parser: "typescript",
-      plugins: [parserTypescript],
-      ...options,
+    const { format } = await import("oxfmt");
+    const result = await format(filePath, input, {
+      printWidth: 120,
+      trailingComma: "all",
+      ...formatOptions,
     });
-  } catch (err) {
-    console.warn("Failed to format code");
-    console.warn(err);
-    return input; // assume it's invalid syntax and ignore
+
+    if (result.errors.length > 0) {
+      console.warn(`Failed to format code in ${filePath}`);
+      console.warn(result.errors);
+      return input;
+    }
+
+    return result.code;
+  } catch {
+    try {
+      return await formatWithBundledOxfmt(filePath, input, formatOptions);
+    } catch (err) {
+      console.warn(`Failed to format code in ${filePath}`);
+      console.warn(err);
+      return input; // assume it's invalid syntax and ignore
+    }
   }
 }
 
-export const prettify = (str: string, options?: Options | null) =>
-  maybePretty(str, { printWidth: 120, trailingComma: "all", ...options });
+export const prettify = (str: string, options?: PrettifyOptions | null) => maybePretty(str, options);

package/src/generate-client-files.ts

@@ -30,6 +30,7 @@ async function ensureDir(dirPath: string): Promise<void> {
 export const optionsSchema = type({
   "output?": "string",
   runtime: allowedRuntimes,
+  "format?": "boolean | 'true' | 'false'",
   tanstack: "boolean | string",
   "defaultFetcher?": type({
     "envApiBaseUrl?": "string",
@@ -39,14 +40,27 @@ export const optionsSchema = type({
   }),
   schemasOnly: "boolean",
   "includeClient?": "boolean | 'true' | 'false'",
+  "jsdoc?": "boolean | 'true' | 'false'",
   "successStatusCodes?": "string",
   "errorStatusCodes?": "string",
 });
 
-type GenerateClientFilesOptions = typeof optionsSchema.infer & {
+export type GenerateClientFilesOptions = typeof optionsSchema.infer & {
   nameTransform?: NameTransformOptions;
 };
 
+function parseBooleanOption(value: boolean | "true" | "false" | undefined) {
+  if (value === "false") {
+    return false;
+  }
+
+  if (value === "true") {
+    return true;
+  }
+
+  return value;
+}
+
 export async function generateClientFiles(input: string, options: GenerateClientFilesOptions) {
   // TODO CLI option to save that file?
   const openApiDoc = (await SwaggerParser.bundle(input)) as OpenAPIObject;
@@ -65,8 +79,9 @@ export async function generateClientFiles(input: string, options: GenerateClient
     : undefined;
 
   // Convert string boolean to actual boolean
-  const includeClient =
-    options.includeClient === "false" ? false : options.includeClient === "true" ? true : options.includeClient;
+  const includeClient = parseBooleanOption(options.includeClient);
+  const jsdoc = parseBooleanOption(options.jsdoc) ?? true;
+  const shouldFormat = parseBooleanOption(options.format) ?? false;
 
   const generatorOptions: GeneratorOptions = {
     ...ctx,
@@ -74,25 +89,22 @@ export async function generateClientFiles(input: string, options: GenerateClient
     schemasOnly: options.schemasOnly,
     nameTransform: options.nameTransform,
     includeClient: includeClient ?? true,
+    jsdoc,
     successStatusCodes: successStatusCodes ?? DEFAULT_SUCCESS_STATUS_CODES,
     errorStatusCodes: errorStatusCodes ?? DEFAULT_ERROR_STATUS_CODES,
   };
 
-  const content = await prettify(generateFile(generatorOptions));
   const outputPath = join(
     cwd,
     options.output ?? input + `.${options.runtime === "none" ? "client" : options.runtime}.ts`,
   );
+  const content = await prettify(generateFile(generatorOptions), { enabled: shouldFormat, filePath: outputPath });
 
   console.log("Generating client...", outputPath);
   await ensureDir(dirname(outputPath));
   await writeFile(outputPath, content);
 
   if (options.tanstack) {
-    const tanstackContent = await generateTanstackQueryFile({
-      ...generatorOptions,
-      relativeApiClientPath: "./" + basename(outputPath),
-    });
     let tanstackOutputPath: string;
     if (typeof options.tanstack === "string" && isAbsolute(options.tanstack)) {
       tanstackOutputPath = options.tanstack;
@@ -102,6 +114,13 @@ export async function generateClientFiles(input: string, options: GenerateClient
         typeof options.tanstack === "string" ? options.tanstack : `tanstack.client.ts`,
       );
     }
+    const tanstackContent = await prettify(
+      await generateTanstackQueryFile({
+        ...generatorOptions,
+        relativeApiClientPath: "./" + basename(outputPath),
+      }),
+      { enabled: shouldFormat, filePath: tanstackOutputPath },
+    );
     console.log("Generating tanstack client...", tanstackOutputPath);
     await ensureDir(dirname(tanstackOutputPath));
     await writeFile(tanstackOutputPath, tanstackContent);
@@ -123,9 +142,13 @@ export async function generateClientFiles(input: string, options: GenerateClient
         typeof options.defaultFetcher === "string" ? options.defaultFetcher : `api.client.ts`,
       );
     }
+    const formattedDefaultFetcherContent = await prettify(defaultFetcherContent, {
+      enabled: shouldFormat,
+      filePath: defaultFetcherOutputPath,
+    });
     console.log("Generating default fetcher...", defaultFetcherOutputPath);
     await ensureDir(dirname(defaultFetcherOutputPath));
-    await writeFile(defaultFetcherOutputPath, defaultFetcherContent);
+    await writeFile(defaultFetcherOutputPath, formattedDefaultFetcherContent);
   }
 
   console.log(`Done in ${new Date().getTime() - now.getTime()}ms !`);

package/src/generator.ts

@@ -28,6 +28,7 @@ export type GeneratorOptions = ReturnType<typeof mapOpenApiEndpoints> & {
   successStatusCodes?: readonly number[];
   errorStatusCodes?: readonly number[];
   includeClient?: boolean;
+  jsdoc?: boolean;
 };
 type GeneratorContext = Required<GeneratorOptions>;
 
@@ -77,6 +78,30 @@ const replacerByRuntime = {
       ),
 };
 
+const shouldRenderDescriptionComments = (ctx: GeneratorContext) => ctx.jsdoc && ctx.runtime === "none";
+
+const escapeCommentText = (text: string) => text.replace(/\*\//g, "*\\/");
+
+const renderDescriptionComment = (description: string, indent = "") => {
+  const lines = description.trim().split(/\r?\n/);
+
+  return `${indent}/**\n${lines.map((line) => `${indent} * ${escapeCommentText(line)}`).join("\n")}\n${indent} */`;
+};
+
+const getSchemaDescription = (schema: Box<AnyBoxDef>["schema"]) => {
+  if (!schema || typeof schema !== "object") return undefined;
+  if ("description" in schema && typeof schema.description === "string") return schema.description;
+  return undefined;
+};
+
+const indentMultiline = (value: string, indent = "  ") =>
+  value.includes("\n")
+    ? value
+        .split("\n")
+        .map((line, index) => (index === 0 ? line : `${indent}${line}`))
+        .join("\n")
+    : value;
+
 export const generateFile = (options: GeneratorOptions) => {
   const ctx = {
     ...options,
@@ -84,6 +109,7 @@ export const generateFile = (options: GeneratorOptions) => {
     successStatusCodes: options.successStatusCodes ?? DEFAULT_SUCCESS_STATUS_CODES,
     errorStatusCodes: options.errorStatusCodes ?? DEFAULT_ERROR_STATUS_CODES,
     includeClient: options.includeClient ?? true,
+    jsdoc: options.jsdoc ?? false,
   } as GeneratorContext;
 
   const schemaList = generateSchemaList(ctx);
@@ -128,7 +154,8 @@ export const generateFile = (options: GeneratorOptions) => {
   return file;
 };
 
-const generateSchemaList = ({ refs, runtime }: GeneratorContext) => {
+const generateSchemaList = (ctx: GeneratorContext) => {
+  const { refs, runtime } = ctx;
   let file = `
   ${runtime === "none" ? "export namespace Schemas {" : ""}
     // <Schemas>
@@ -137,7 +164,13 @@ const generateSchemaList = ({ refs, runtime }: GeneratorContext) => {
     if (!infos?.name) return;
     if (infos.kind !== "schemas") return;
 
-    file += `export type ${infos.normalized} = ${schema.value}\n`;
+    const description = shouldRenderDescriptionComments(ctx) ? getSchemaDescription(schema.schema) : undefined;
+    const schemaValue =
+      shouldRenderDescriptionComments(ctx) && !Box.isReference(schema)
+        ? boxToString(schema, ctx, { prefixRefsWithSchemas: false })
+        : schema.value;
+
+    file += `${description ? `${renderDescriptionComment(description)}\n` : ""}export type ${infos.normalized} = ${schemaValue}\n`;
   });
 
   return (
@@ -149,31 +182,108 @@ const generateSchemaList = ({ refs, runtime }: GeneratorContext) => {
   );
 };
 
-const parameterObjectToString = (parameters: Box<AnyBoxDef> | Record<string, AnyBox>, ctx: GeneratorContext) => {
-  if (parameters instanceof Box) {
-    if (ctx.runtime === "none") {
-      return parameters.recompute((box) => {
-        if (Box.isReference(box) && !box.params.generics && box.value !== "null") {
-          box.value = `Schemas.${box.value}`;
-        }
-        return box;
-      }).value;
+const boxToString = (
+  box: Box<AnyBoxDef>,
+  ctx: GeneratorContext,
+  options: { prefixRefsWithSchemas?: boolean } = {},
+): string => {
+  const prefixRefsWithSchemas = options.prefixRefsWithSchemas ?? true;
+
+  if (ctx.runtime !== "none") {
+    return box.value;
+  }
+
+  const renderValue = (value: any): string => {
+    if (typeof value === "string") {
+      return value;
+    }
+
+    if (Box.isBox(value)) {
+      return boxToString(value, ctx, options);
+    }
+
+    return value.value;
+  };
+
+  if (Box.isUnion(box)) {
+    return `(${box.params.types.map((type) => renderValue(type)).join(" | ")})`;
+  }
+
+  if (Box.isIntersection(box)) {
+    return `(${box.params.types.map((type) => renderValue(type)).join(" & ")})`;
+  }
+
+  if (Box.isArray(box)) {
+    return `Array<${renderValue(box.params.type)}>`;
+  }
+
+  if (Box.isOptional(box)) {
+    return `${renderValue(box.params.type)} | undefined`;
+  }
+
+  if (Box.isObject(box)) {
+    const renderedProps = Object.entries(box.params.props).map(([prop, type]) => {
+      const isOptional = typeof type !== "string" && Box.isBox(type) && Box.isOptional(type);
+      const renderedValue = indentMultiline(renderValue(type));
+      const description =
+        shouldRenderDescriptionComments(ctx) && typeof type !== "string" && Box.isBox(type)
+          ? getSchemaDescription(type.schema)
+          : undefined;
+
+      return {
+        description,
+        line: `${wrapWithQuotesIfNeeded(prop)}${isOptional ? "?" : ""}: ${renderedValue};`,
+      };
+    });
+
+    const shouldRenderMultiline =
+      shouldRenderDescriptionComments(ctx) &&
+      renderedProps.some(({ description, line }) => description || line.includes("\n"));
+
+    if (!shouldRenderMultiline) {
+      const propsString = renderedProps.map(({ line }) => line.slice(0, -1)).join(", ");
+      return `{ ${propsString} }`;
     }
 
-    return parameters.value;
+    const propsString = renderedProps
+      .map(({ description, line }) => {
+        const comment = description ? `${renderDescriptionComment(description, "  ")}\n` : "";
+        return `${comment}  ${line}`;
+      })
+      .join("\n");
+
+    return `{
+${propsString}
+}`;
+  }
+
+  if (Box.isReference(box)) {
+    if (!box.params.generics) {
+      return box.value === "null" ? box.value : prefixRefsWithSchemas ? `Schemas.${box.value}` : box.value;
+    }
+
+    return `${box.params.name}<${box.params.generics.map((type) => renderValue(type)).join(", ")}>`;
+  }
+
+  return box.value;
+};
+
+const parameterObjectToString = (parameters: Box<AnyBoxDef> | Record<string, AnyBox>, ctx: GeneratorContext) => {
+  if (parameters instanceof Box) {
+    return boxToString(parameters, ctx);
   }
 
   let str = "{";
   for (const [key, box] of Object.entries(parameters)) {
-    str += `${wrapWithQuotesIfNeeded(key)}${box.type === "optional" ? "?" : ""}: ${box.value},\n`;
+    str += `${wrapWithQuotesIfNeeded(key)}${box.type === "optional" ? "?" : ""}: ${indentMultiline(boxToString(box, ctx))},\n`;
   }
   return str + "}";
 };
 
-const responseHeadersObjectToString = (responseHeaders: Record<string, Box<BoxObject>>) => {
+const responseHeadersObjectToString = (responseHeaders: Record<string, Box<BoxObject>>, ctx: GeneratorContext) => {
   let str = "{";
   for (const [key, responseHeader] of Object.entries(responseHeaders)) {
-    str += `${wrapWithQuotesIfNeeded(key.toLowerCase())}: ${responseHeader.value},\n`;
+    str += `${wrapWithQuotesIfNeeded(key.toLowerCase())}: ${indentMultiline(boxToString(responseHeader, ctx))},\n`;
   }
   return str + "}";
 };
@@ -181,16 +291,7 @@ const responseHeadersObjectToString = (responseHeaders: Record<string, Box<BoxOb
 const generateResponsesObject = (responses: Record<string, AnyBox>, ctx: GeneratorContext) => {
   let str = "{";
   for (const [statusCode, responseType] of Object.entries(responses)) {
-    const value =
-      ctx.runtime === "none"
-        ? responseType.recompute((box) => {
-            if (Box.isReference(box) && !box.params.generics && box.value !== "null") {
-              box.value = `Schemas.${box.value}`;
-            }
-
-            return box;
-          }).value
-        : responseType.value;
+    const value = indentMultiline(boxToString(responseType, ctx));
     str += `${wrapWithQuotesIfNeeded(statusCode)}: ${value},\n`;
   }
   return str + "}";
@@ -204,7 +305,9 @@ const generateEndpointSchemaList = (ctx: GeneratorContext) => {
   `;
   ctx.endpointList.map((endpoint) => {
     const parameters = endpoint.parameters ?? {};
-    file += `export type ${endpoint.meta.alias} = {
+    const description = shouldRenderDescriptionComments(ctx) ? endpoint.operation.description : undefined;
+
+    file += `${description ? `${renderDescriptionComment(description)}\n` : ""}export type ${endpoint.meta.alias} = {
       method: "${endpoint.method.toUpperCase()}",
       path: "${endpoint.path}",
       requestFormat: "${endpoint.requestFormat}",
@@ -214,26 +317,12 @@ const generateEndpointSchemaList = (ctx: GeneratorContext) => {
             ${parameters.query ? `query:  ${parameterObjectToString(parameters.query, ctx)},` : ""}
         ${parameters.path ? `path:  ${parameterObjectToString(parameters.path, ctx)},` : ""}
         ${parameters.header ? `header:  ${parameterObjectToString(parameters.header, ctx)},` : ""}
-        ${
-          parameters.body
-            ? `body:  ${parameterObjectToString(
-                ctx.runtime === "none"
-                  ? parameters.body.recompute((box) => {
-                      if (Box.isReference(box) && !box.params.generics) {
-                        box.value = `Schemas.${box.value}`;
-                      }
-                      return box;
-                    })
-                  : parameters.body,
-                ctx,
-              )},`
-            : ""
-        }
+        ${parameters.body ? `body:  ${parameterObjectToString(parameters.body, ctx)},` : ""}
           }`
           : "parameters: never,"
       }
       ${endpoint.responses ? `responses: ${generateResponsesObject(endpoint.responses, ctx)},` : ""}
-      ${endpoint.responseHeaders ? `responseHeaders: ${responseHeadersObjectToString(endpoint.responseHeaders)},` : ""}
+      ${endpoint.responseHeaders ? `responseHeaders: ${responseHeadersObjectToString(endpoint.responseHeaders, ctx)},` : ""}
     }\n`;
   });
 
@@ -327,7 +416,7 @@ export type Endpoint<TConfig extends DefaultEndpoint = DefaultEndpoint> = {
 
 export interface Fetcher {
     decodePathParams?: (path: string, pathParams: Record<string, string>) => string
-    encodeSearchParams?: (searchParams: Record<string, unknown> | undefined) => URLSearchParams
+  encodeSearchParams?: (searchParams: Record<string, unknown> | undefined) => URLSearchParams
     //
     fetch: (input: {
       method: Method;

package/src/node.export.ts

@@ -1 +1 @@
-export { generateClientFiles } from "./generate-client-files.ts";
+export { generateClientFiles, type GenerateClientFilesOptions } from "./generate-client-files.ts";

package/src/openapi-schema-to-ts.ts

@@ -123,13 +123,9 @@ export const openApiSchemaToTs = ({ schema, meta: _inheritedMeta, ctx }: Openapi
 
     if (schemaType === "object" || schema.properties || schema.additionalProperties) {
       if (!schema.properties) {
-        if (
-          schema.additionalProperties &&
-          !isReferenceObject(schema.additionalProperties) &&
-          typeof schema.additionalProperties !== "boolean"
-        ) {
+        if (schema.additionalProperties && typeof schema.additionalProperties !== "boolean") {
           const valueSchema = openApiSchemaToTs({ schema: schema.additionalProperties, ctx, meta });
-          return t.literal(`Record<string, ${valueSchema.value}>`);
+          return t.reference("Record", [t.string(), valueSchema]);
         }
 
         return t.literal("Record<string, unknown>");
@@ -151,9 +147,7 @@ export const openApiSchemaToTs = ({ schema, meta: _inheritedMeta, ctx }: Openapi
           });
         }
 
-        additionalProperties = t.literal(
-          `Record<string, ${additionalPropertiesType ? additionalPropertiesType.value : t.any().value}>`,
-        );
+        additionalProperties = t.reference("Record", [t.string(), additionalPropertiesType ?? t.any()]);
       }
 
       const hasRequiredArray = schema.required && schema.required.length > 0;
@@ -180,7 +174,15 @@ export const openApiSchemaToTs = ({ schema, meta: _inheritedMeta, ctx }: Openapi
       return isPartial ? t.reference("Partial", [objectType]) : objectType;
     }
 
-    if (!schemaType) return t.unknown();
+    if (!schemaType) {
+      const nullableKey = Object.keys(schema).filter((key) => !["nullable"].includes(key));
+
+      if (nullableKey.length === 0 && (schema as LibSchemaObject).nullable) {
+        return t.literal("null");
+      }
+
+      return t.unknown();
+    }
 
     throw new Error(`Unsupported schema type: ${schemaType}`);
   };
@@ -188,7 +190,7 @@ export const openApiSchemaToTs = ({ schema, meta: _inheritedMeta, ctx }: Openapi
   let output = getTs();
   if (!isReferenceObject(schema)) {
     // OpenAPI 3.1 does not have nullable, but OpenAPI 3.0 does
-    if ((schema as LibSchemaObject).nullable) {
+    if ((schema as LibSchemaObject).nullable && output.value !== "null") {
       output = t.union([output, t.literal("null")]);
     }
   }

package/src/ref-resolver.ts

@@ -52,18 +52,35 @@ export const createRefResolver = (
     const normalizedPath = path.replace("#/", "").replace("#", "").replaceAll("/", ".");
     const map = get(doc, normalizedPath) ?? ({} as any);
 
+    const existingInfo = byRef.get(correctRef);
+    if (existingInfo) {
+      return map[split[split.length - 1]!] as T;
+    }
+
     // "#/components/schemas/Something.jsonld" -> "Something.jsonld"
     const name = split[split.length - 1]!;
-    let normalized = normalizeString(name);
-    if (nameTransform?.transformSchemaName) {
-      normalized = nameTransform.transformSchemaName(normalized);
+    const kind = normalizedPath.split(".")[1] as RefInfo["kind"];
+    const baseNormalized = sanitizeName(
+      nameTransform?.transformSchemaName
+        ? nameTransform.transformSchemaName(normalizeString(name))
+        : normalizeString(name),
+      "schema",
+    );
+
+    let normalized = baseNormalized;
+    if (refByName.has(normalized) && refByName.get(normalized) !== correctRef) {
+      const kindSuffix = `${baseNormalized}_${kind}`;
+      normalized = kindSuffix;
+      let suffix = 2;
+      while (refByName.has(normalized) && refByName.get(normalized) !== correctRef) {
+        normalized = `${kindSuffix}_${suffix++}`;
+      }
     }
-    normalized = sanitizeName(normalized, "schema");
 
     nameByRef.set(correctRef, normalized);
     refByName.set(normalized, correctRef);
 
-    const infos = { ref: correctRef, name, normalized, kind: normalizedPath.split(".")[1] as RefInfo["kind"] };
+    const infos = { ref: correctRef, name, normalized, kind };
     byRef.set(infos.ref, infos);
     byNormalized.set(infos.normalized, infos);
 

package/src/string-utils.ts

@@ -13,10 +13,10 @@ export function normalizeString(text: string) {
     .replace(/--+/g, "-"); // Replace multiple - with single -
 }
 
-const onlyWordRegex = /^\w+$/;
+const barePropertyNameRegex = /^(?:[A-Za-z_]\w*|\d+)$/;
 export const wrapWithQuotesIfNeeded = (str: string) => {
   if (str[0] === '"' && str[str.length - 1] === '"') return str;
-  if (onlyWordRegex.test(str)) {
+  if (barePropertyNameRegex.test(str)) {
     return str;
   }
 

package/src/tanstack-query.generator.ts

@@ -1,5 +1,4 @@
 import { capitalize } from "pastable/server";
-import { prettify } from "./format.ts";
 import type { mapOpenApiEndpoints } from "./map-openapi-endpoints.ts";
 
 type GeneratorOptions = ReturnType<typeof mapOpenApiEndpoints>;
@@ -191,5 +190,5 @@ export const generateTanstackQueryFile = async (ctx: GeneratorContext & { relati
   }
 `;
 
-  return prettify(file);
+  return file;
 };