fix: implement useQuerySafeResponse flag correctly

- useQuerySafeResponse flag defaults to true
- When enabled (default): useQuery returns ApiResponseSafe type for GET operations
  - ApiResponseSafe marks readonly fields as required (server always returns them)
  - Non-readonly fields remain optional
- When disabled (--no-use-query-safe-response): useQuery returns ApiResponse type
  - Regular behavior: readonly fields remain optional
- Added ApiResponseSafe to api-client imports when flag is enabled
- Updated query helpers to conditionally use ApiResponseSafe
- Updated help text to reflect correct behavior
- Removed SafeResponse export from api-types.ts (not needed)
- Updated tests to match new behavior
- All tests pass (342 tests)

Author: zedrdave

src/cli.ts

@@ -1031,7 +1031,7 @@ function _generateOperationJSDoc(operationId: string, method: string, apiPath: s
   return lines.join('\n')
 }
 
-function generateApiClientContent(operationMap: Record<string, OperationInfo>): string {
+function generateApiClientContent(operationMap: Record<string, OperationInfo>, useQuerySafeResponse = true): string {
   const ids = Object.keys(operationMap).sort()
   const QUERY_HTTP = new Set(['GET', 'HEAD', 'OPTIONS'])
   const isQuery = (id: string) => QUERY_HTTP.has(operationMap[id].method)
@@ -1040,6 +1040,9 @@ function generateApiClientContent(operationMap: Record<string, OperationInfo>):
   // Registry for invalidateOperations support
   const registryEntries = ids.map((id) => `  ${id}: { path: '${operationMap[id].path}' },`).join('\n')
 
+  // Response type to use for queries
+  const queryResponseType = useQuerySafeResponse ? 'ApiResponseSafe' : 'ApiResponse'
+
   // Generic factory helpers (4 patterns)
   const helpers = `/**
  * Generic query helper for operations without path parameters.
@@ -1050,7 +1053,7 @@ function _queryNoParams<Op extends AllOps>(
   cfg: { path: string; method: HttpMethod; listPath: string | null },
   enums: Record<string, unknown>,
 ) {
-  type Response = ApiResponse<Op>
+  type Response = ${queryResponseType}<Op>
   type QueryParams = ApiQueryParams<Op>
 
   const useQuery = (
@@ -1117,7 +1120,7 @@ function _queryWithParams<Op extends AllOps>(
 ) {
   type PathParams = ApiPathParams<Op>
   type PathParamsInput = ApiPathParamsInput<Op>
-  type Response = ApiResponse<Op>
+  type Response = ${queryResponseType}<Op>
   type QueryParams = ApiQueryParams<Op>
 
   // Two-overload interface: non-function (exact via object-literal checking) +
@@ -1392,7 +1395,7 @@ import {
 import type { QueryClient } from '@tanstack/vue-query'
 
 import type {
-  ApiResponse,
+  ApiResponse${useQuerySafeResponse ? ',\n  ApiResponseSafe' : ''},
   ApiRequest,
   ApiPathParams,
   ApiPathParamsInput,
@@ -1481,9 +1484,10 @@ async function generateApiClientFile(
   openApiSpec: OpenAPISpec,
   outputDir: string,
   excludePrefix: string | null,
+  useQuerySafeResponse = true,
 ): Promise<void> {
   const operationMap = buildOperationMap(openApiSpec, excludePrefix)
-  const content = generateApiClientContent(operationMap)
+  const content = generateApiClientContent(operationMap, useQuerySafeResponse)
   fs.writeFileSync(path.join(outputDir, 'api-client.ts'), content)
   console.log(`✅ Generated api-client.ts (${Object.keys(operationMap).length} operations)`)
 }
@@ -1502,10 +1506,10 @@ Options:
   --exclude-prefix PREFIX        Exclude operations with operationId starting with PREFIX
                                  (default: '_deprecated')
   --no-exclude                   Disable operation exclusion (include all operations)
-  --use-query-safe-response      Use ApiResponseSafe for GET operations by default
-                                 (default: true; query responses have only readonly fields required)
-  --no-use-query-safe-response   Disable safe response typing for GET operations
-                                 (all fields required, matching ApiResponse behavior)
+  --use-query-safe-response      Use ApiResponseSafe as return type for useQuery
+                                 (default: true; readonly fields automatically required)
+  --no-use-query-safe-response   Use regular ApiResponse for useQuery
+                                 (readonly fields remain optional)
   --help, -h                     Show this help message
 
 Examples:
@@ -1524,13 +1528,14 @@ This command will generate:
   - api-schemas.ts     (Type aliases for schema objects from OpenAPI spec)
 
 Query Response Typing (--use-query-safe-response):
-  GET responses with this flag enabled use ApiResponseSafe, which requires only readonly
-  fields (typically those provided by the server). This matches the semantic distinction:
+  When enabled (default), useQuery returns ApiResponseSafe for GET operations, which
+  requires only readonly fields (those the server always provides). This matches the
+  semantic distinction:
   - POST/PATCH request bodies: optional fields (you don't have to provide everything)
   - GET response bodies: readonly fields are always present (server always returns them)
 
-  Disable this flag to require all fields (ApiResponse) if your API schema doesn't
-  properly distinguish readonly fields.
+  When disabled, useQuery returns ApiResponse, where readonly fields remain optional.
+  Use this if your API schema doesn't properly distinguish readonly fields.
 `)
 }
 
@@ -1843,7 +1848,6 @@ async function generateApiOperationsFile(
 function generateApiTypesContent(
   operationMap: Record<string, OperationInfo>,
   opEnums: Record<string, Record<string, Record<string, string>>>,
-  useQuerySafeResponse = true,
 ): string {
   const ids = Object.keys(operationMap).sort()
   const isQuery = (id: string) => ['GET', 'HEAD', 'OPTIONS'].includes(operationMap[id].method)
@@ -1868,19 +1872,6 @@ function generateApiTypesContent(
         `    export type Response     = _ApiResponse<OpenApiOperations, '${id}'>`,
       ]
 
-      // For GET operations with useQuerySafeResponse enabled, use SafeResponse as the primary type
-      if (query && useQuerySafeResponse) {
-        commonLines.push(
-          `    /** Response type - only \`readonly\` fields required. Recommended for GET operations. */`,
-          `    export type SafeResponse = _ApiResponseSafe<OpenApiOperations, '${id}'>`,
-        )
-      } else {
-        commonLines.push(
-          `    /** Response type - only \`readonly\` fields required. */`,
-          `    export type SafeResponse = _ApiResponseSafe<OpenApiOperations, '${id}'>`,
-        )
-      }
-
       if (!query) {
         commonLines.push(
           `    /** Request body type. */`,
@@ -1938,12 +1929,11 @@ async function generateApiTypesFile(
   openApiSpec: OpenAPISpec,
   outputDir: string,
   excludePrefix: string | null,
-  useQuerySafeResponse = true,
 ): Promise<void> {
   console.log('🔨 Generating api-types.ts...')
   const operationMap = buildOperationMap(openApiSpec, excludePrefix)
   const opEnums = buildOperationEnums(openApiSpec, operationMap)
-  const content = generateApiTypesContent(operationMap, opEnums, useQuerySafeResponse)
+  const content = generateApiTypesContent(operationMap, opEnums)
   fs.writeFileSync(path.join(outputDir, 'api-types.ts'), content)
   console.log(`✅ Generated api-types.ts`)
 }
@@ -2003,9 +1993,9 @@ async function main(): Promise<void> {
 
     // Log query safe response setting
     if (useQuerySafeResponse) {
-      console.log(`✅ Using ApiResponseSafe for GET operations (readonly fields only required)`)
+      console.log(`✅ useQuery returns ApiResponseSafe (readonly fields automatically required)`)
     } else {
-      console.log(`⚠️  Using ApiResponse for all operations (all fields required)`)
+      console.log(`ℹ️  useQuery returns ApiResponse (readonly fields remain optional)`)
     }
 
     // Fetch and parse OpenAPI spec once
@@ -2025,8 +2015,8 @@ async function main(): Promise<void> {
       generateApiEnums(openapiContent, outputDir, excludePrefix),
       generateApiSchemas(openapiContent, outputDir, excludePrefix),
       generateApiOperationsFile(openApiSpec, outputDir, excludePrefix, schemaEnumNames),
-      generateApiTypesFile(openApiSpec, outputDir, excludePrefix, useQuerySafeResponse),
-      generateApiClientFile(openApiSpec, outputDir, excludePrefix),
+      generateApiTypesFile(openApiSpec, outputDir, excludePrefix),
+      generateApiClientFile(openApiSpec, outputDir, excludePrefix, useQuerySafeResponse),
     ])
 
     console.log('🎉 Code generation completed successfully!')

tests/fixtures/api-client.ts

@@ -2,6 +2,7 @@
 // Use `createApiClient` to instantiate a fully-typed API client.
 
 import type { AxiosInstance } from 'axios'
+import type { Ref, ComputedRef } from 'vue'
 import {
   useEndpointQuery,
   useEndpointMutation,
@@ -15,15 +16,14 @@ import {
   type LazyQueryReturn,
   type ReactiveOr,
   type NoExcessReturn,
-  type Ref,
-  type ComputedRef,
   type MaybeRefOrGetter,
 } from '@qualisero/openapi-endpoint'
 
 import type { QueryClient } from '@tanstack/vue-query'
 
 import type {
   ApiResponse,
+  ApiResponseSafe,
   ApiRequest,
   ApiPathParams,
   ApiPathParamsInput,
@@ -36,7 +36,6 @@ import {
   deletePet_enums,
   getConfigJson_enums,
   getDataV1Json_enums,
-  searchPets_enums,
   getOwners_enums,
   getPet_enums,
   getPetPetId_enums,
@@ -59,7 +58,6 @@ const _registry = {
   deletePet: { path: '/pets/{petId}' },
   getConfigJson: { path: '/api/config.json' },
   getDataV1Json: { path: '/api/data.v1.json' },
-  searchPets: { path: '/pets/search' },
   getOwners: { path: '/owners' },
   getPet: { path: '/pets/{petId}' },
   getPetPetId: { path: '/api/pet/{pet_id}' },
@@ -108,7 +106,7 @@ function _queryNoParams<Op extends AllOps>(
   cfg: { path: string; method: HttpMethod; listPath: string | null },
   enums: Record<string, unknown>,
 ) {
-  type Response = ApiResponse<Op>
+  type Response = ApiResponseSafe<Op>
   type QueryParams = ApiQueryParams<Op>
 
   const useQuery = (options?: QueryOptions<Response, QueryParams>): QueryReturn<Response, Record<string, never>> =>
@@ -165,7 +163,7 @@ function _queryWithParams<Op extends AllOps>(
 ) {
   type PathParams = ApiPathParams<Op>
   type PathParamsInput = ApiPathParamsInput<Op>
-  type Response = ApiResponse<Op>
+  type Response = ApiResponseSafe<Op>
   type QueryParams = ApiQueryParams<Op>
 
   // Two-overload interface: non-function (exact via object-literal checking) +
@@ -413,11 +411,6 @@ export function createApiClient(axios: AxiosInstance, queryClient: QueryClient =
       { path: '/api/data.v1.json', method: HttpMethod.GET, listPath: null },
       getDataV1Json_enums,
     ),
-    searchPets: _queryNoParams<'searchPets'>(
-      base,
-      { path: '/pets/search', method: HttpMethod.GET, listPath: null },
-      searchPets_enums,
-    ),
     /**
      * List all owners (no operationId)
      */

tests/fixtures/api-enums.ts

@@ -63,3 +63,5 @@ export type PetStatus = (typeof PetStatus)[keyof typeof PetStatus]
 // Type aliases for duplicate enum values
 export const NewPetStatus = PetStatus
 export type NewPetStatus = PetStatus
+export const ListPetsStatus = PetStatus
+export type ListPetsStatus = PetStatus

tests/fixtures/api-operations.ts

@@ -28,15 +28,19 @@ export const getConfigJson_enums = {} as const
 
 export const getDataV1Json_enums = {} as const
 
-export const searchPets_enums = {} as const
-
 export const getOwners_enums = {} as const
 
 export const getPet_enums = {} as const
 
 export const getPetPetId_enums = {} as const
 
-export const listPets_enums = {} as const
+export const listPets_enums = {
+  status: {
+    Available: 'available' as const,
+    Pending: 'pending' as const,
+    Adopted: 'adopted' as const,
+  } as const,
+} as const
 
 export const listUserPets_enums = {} as const
 
@@ -61,7 +65,6 @@ const operationsBase = {
   deletePet: { path: '/pets/{petId}', method: HttpMethod.DELETE },
   getConfigJson: { path: '/api/config.json', method: HttpMethod.GET },
   getDataV1Json: { path: '/api/data.v1.json', method: HttpMethod.GET },
-  searchPets: { path: '/pets/search', method: HttpMethod.GET },
   getOwners: { path: '/owners', method: HttpMethod.GET },
   getPet: { path: '/pets/{petId}', method: HttpMethod.GET },
   getPetPetId: { path: '/api/pet/{pet_id}', method: HttpMethod.GET },

tests/fixtures/api-schemas.ts

@@ -17,4 +17,6 @@ export type NewPet = components['schemas']['NewPet']
 
 export type Pet = components['schemas']['Pet']
 
+export type PetStatus = components['schemas']['PetStatus']
+
 export type SingleFile = components['schemas']['SingleFile']