nuxt-openapi-hyperfetch 0.1.0-alpha.1

package/src/generators/use-fetch/runtime/useApiRequest.ts

@@ -0,0 +1,223 @@
+// @ts-nocheck
+/**
+ * Nuxt Runtime Helper - This file is copied to the generated output
+ * It requires Nuxt 3 to be installed in the target project
+ */
+import { watch } from 'vue';
+import {
+  getGlobalHeaders,
+  applyPick,
+  applyRequestModifications,
+  mergeCallbacks,
+  type RequestContext,
+  type ModifiedRequestContext,
+  type FinishContext,
+  type ApiRequestOptions as BaseApiRequestOptions,
+} from '../../shared/runtime/apiHelpers.js';
+
+/**
+ * Helper type to infer transformed data type
+ * If transform is provided, infer its return type
+ * If pick is provided, return partial object (type inference for nested paths is complex)
+ * Otherwise, return original type
+ */
+type MaybeTransformed<T, Options> = Options extends { transform: (...args: any) => infer R }
+  ? R
+  : Options extends { pick: ReadonlyArray<any> }
+    ? any // With nested paths, type inference is complex, so we use any
+    : T;
+
+/**
+ * Options for useFetch API requests with lifecycle callbacks
+ * Extends base options with useFetch-specific options
+ */
+export interface ApiRequestOptions<T = any> extends BaseApiRequestOptions<T> {
+  /** All standard useFetch options */
+  [key: string]: any;
+}
+
+/**
+ * Enhanced useFetch wrapper with lifecycle callbacks and request interception
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const { data, error } = useApiRequest<Pet>('/api/pets', {
+ *   method: 'POST',
+ *   body: { name: 'Max' },
+ * });
+ *
+ * // With transform (type is inferred!)
+ * const { data } = useApiRequest<Pet>('/api/pets/1', {
+ *   transform: (pet) => ({ displayName: pet.name, available: pet.status === 'available' })
+ * });
+ * // data is Ref<{ displayName: string, available: boolean }>
+ *
+ * // With pick (simple fields)
+ * const { data } = useApiRequest<Pet>('/api/pets/1', {
+ *   pick: ['id', 'name'] as const
+ * });
+ *
+ * // With pick (nested dot notation)
+ * const { data } = useApiRequest('/api/user', {
+ *   pick: ['person.name', 'person.email', 'status']
+ * });
+ * // Result: { person: { name: '...', email: '...' }, status: '...' }
+ *
+ * // With callbacks
+ * const { data } = useApiRequest<Pet>('/api/pets', {
+ *   onRequest: (ctx) => ({ headers: { 'Authorization': `Bearer ${token}` } }),
+ *   onSuccess: (pet) => console.log('Got pet:', pet),
+ *   onError: (err) => console.error('Failed:', err),
+ * });
+ * ```
+ */
+export function useApiRequest<T = any, Options extends ApiRequestOptions<T> = ApiRequestOptions<T>>(
+  url: string | (() => string),
+  options?: Options
+) {
+  const {
+    onRequest,
+    onSuccess,
+    onError,
+    onFinish,
+    skipGlobalCallbacks,
+    transform,
+    pick,
+    ...fetchOptions
+  } = options || {};
+
+  // Prepare request context for onRequest interceptor
+  const urlValue = typeof url === 'function' ? url() : url;
+  const requestContext: RequestContext = {
+    url: urlValue,
+    method: fetchOptions.method || 'GET',
+    body: fetchOptions.body,
+    headers: fetchOptions.headers,
+    query: fetchOptions.query,
+  };
+
+  // Merge local and global callbacks
+  const mergedCallbacks = mergeCallbacks(
+    urlValue,
+    { onRequest, onSuccess, onError, onFinish },
+    skipGlobalCallbacks
+  );
+
+  // Apply global headers configuration (from composable or plugin)
+  const modifiedOptions = { ...fetchOptions };
+  const globalHeaders = getGlobalHeaders();
+  if (Object.keys(globalHeaders).length > 0) {
+    modifiedOptions.headers = {
+      ...globalHeaders,
+      ...modifiedOptions.headers, // User headers override global headers
+    };
+  }
+
+  // Execute merged onRequest interceptor and apply modifications
+  if (mergedCallbacks.onRequest) {
+    try {
+      const result = mergedCallbacks.onRequest(requestContext);
+
+      // Handle async onRequest
+      if (result && typeof result === 'object' && 'then' in result) {
+        result
+          .then((modifications) => {
+            if (modifications) {
+              applyRequestModifications(modifiedOptions, modifications);
+            }
+          })
+          .catch((error) => {
+            console.error('Error in merged onRequest callback:', error);
+          });
+      }
+      // Handle sync onRequest with return value
+      else if (result && typeof result === 'object') {
+        applyRequestModifications(modifiedOptions, result);
+      }
+    } catch (error) {
+      console.error('Error in merged onRequest callback:', error);
+    }
+  }
+
+  // Make the actual request using Nuxt's useFetch
+  const result = useFetch<T>(url, modifiedOptions);
+
+  // Create a ref for transformed data
+  type TransformedType = MaybeTransformed<T, Options>;
+  const transformedData = ref<TransformedType | null>(null);
+
+  // Track if callbacks have been executed to avoid duplicates
+  let successExecuted = false;
+  let errorExecuted = false;
+
+  // Watch for changes in data, error, and pending states
+  watch(
+    () => [result.data.value, result.error.value, result.pending.value] as const,
+    async ([data, error, pending], [prevData, prevError, prevPending]) => {
+      // Apply transformations when data arrives
+      if (data && data !== prevData) {
+        let processedData: any = data;
+
+        // Step 1: Apply pick if specified
+        if (pick) {
+          processedData = applyPick(processedData, pick);
+        }
+
+        // Step 2: Apply transform if specified
+        if (transform) {
+          try {
+            processedData = transform(processedData);
+          } catch (err) {
+            console.error('Error in transform function:', err);
+          }
+        }
+
+        // Update transformed data ref
+        transformedData.value = processedData as TransformedType;
+
+        // onSuccess - when data arrives and no error (using merged callback)
+        if (!error && !successExecuted && mergedCallbacks.onSuccess) {
+          successExecuted = true;
+          try {
+            await mergedCallbacks.onSuccess(processedData);
+          } catch (err) {
+            console.error('Error in merged onSuccess callback:', err);
+          }
+        }
+      }
+
+      // onError - when an error occurs (using merged callback)
+      if (error && error !== prevError && !errorExecuted && mergedCallbacks.onError) {
+        errorExecuted = true;
+        try {
+          await mergedCallbacks.onError(error);
+        } catch (err) {
+          console.error('Error in merged onError callback:', err);
+        }
+      }
+
+      // onFinish - when request completes (was pending, now not) (using merged callback)
+      if (prevPending && !pending && mergedCallbacks.onFinish) {
+        const finishContext: FinishContext<TransformedType> = {
+          data: transformedData.value || undefined,
+          error: error || undefined,
+          success: !!transformedData.value && !error,
+        };
+
+        try {
+          await mergedCallbacks.onFinish(finishContext);
+        } catch (err) {
+          console.error('Error in merged onFinish callback:', err);
+        }
+      }
+    },
+    { immediate: true }
+  );
+
+  // Return result with transformed data
+  return {
+    ...result,
+    data: transformedData as Ref<TransformedType | null>,
+  };
+}

package/src/generators/use-fetch/templates.ts

@@ -0,0 +1,214 @@
+import type { MethodInfo } from './types.js';
+
+/**
+ * Generate file header with auto-generation warning
+ */
+function generateFileHeader(): string {
+  return `/**
+ * ⚠️ AUTO-GENERATED FILE - DO NOT EDIT MANUALLY
+ *
+ * This file was automatically generated by nuxt-openapi-generator.
+ * Any manual changes will be overwritten on the next generation.
+ *
+ * @generated by nuxt-openapi-generator
+ * @see https://github.com/dmartindiaz/nuxt-openapi-hyperfetch
+ */
+
+/* eslint-disable */
+// @ts-nocheck
+`;
+}
+
+/**
+ * Options for code generation
+ */
+export interface GenerateOptions {
+  baseUrl?: string;
+  backend?: string;
+}
+
+/**
+ * Generate a useFetch composable function
+ */
+export function generateComposableFile(
+  method: MethodInfo,
+  apiImportPath: string,
+  options?: GenerateOptions
+): string {
+  const header = generateFileHeader();
+  const imports = generateImports(method, apiImportPath);
+  const functionBody = generateFunctionBody(method, options);
+
+  return `${header}${imports}\n\n${functionBody}\n`;
+}
+
+/**
+ * Extract base type names from a type string
+ * Examples:
+ *   Pet[] -> Pet
+ *   Array<Pet> -> Pet
+ *   Pet -> Pet
+ *   { [key: string]: Pet } -> (empty, it's anonymous)
+ */
+function extractBaseTypes(type: string): string[] {
+  if (!type) {
+    return [];
+  }
+
+  // Handle array syntax: Pet[]
+  const arrayMatch = type.match(/^(\w+)\[\]$/);
+  if (arrayMatch) {
+    return [arrayMatch[1]];
+  }
+
+  // Handle Array generic: Array<Pet>
+  const arrayGenericMatch = type.match(/^Array<(\w+)>$/);
+  if (arrayGenericMatch) {
+    return [arrayGenericMatch[1]];
+  }
+
+  // If it's a simple named type (single word, PascalCase), include it
+  if (/^[A-Z][a-zA-Z0-9]*$/.test(type)) {
+    return [type];
+  }
+
+  // For complex types, don't extract anything
+  return [];
+}
+
+/**
+ * Generate import statements
+ */
+function generateImports(method: MethodInfo, apiImportPath: string): string {
+  const typeNames = new Set<string>();
+
+  // Extract base types from request type
+  if (method.requestType) {
+    const extracted = extractBaseTypes(method.requestType);
+    extracted.forEach((t) => typeNames.add(t));
+  }
+
+  // Extract base types from response type
+  if (method.responseType && method.responseType !== 'void') {
+    const extracted = extractBaseTypes(method.responseType);
+    extracted.forEach((t) => typeNames.add(t));
+  }
+
+  let imports = '';
+
+  // Import types from API (only if we have named types to import)
+  if (typeNames.size > 0) {
+    imports += `import type { ${Array.from(typeNames).join(', ')} } from '${apiImportPath}';\n`;
+  }
+
+  // Import runtime helper
+  imports += `import { useApiRequest, type ApiRequestOptions } from '../runtime/useApiRequest';`;
+
+  return imports;
+}
+
+/**
+}
+
+/**
+ * Generate the composable function body
+ */
+function generateFunctionBody(method: MethodInfo, options?: GenerateOptions): string {
+  const hasParams = !!method.requestType;
+  const paramsArg = hasParams ? `params: MaybeRef<${method.requestType}>` : '';
+  const optionsType = `ApiRequestOptions<${method.responseType}>`;
+  const optionsArg = `options?: ${optionsType}`;
+  const args = hasParams ? `${paramsArg}, ${optionsArg}` : optionsArg;
+
+  const responseTypeGeneric = method.responseType !== 'void' ? `<${method.responseType}>` : '';
+
+  const url = generateUrl(method);
+  const fetchOptions = generateFetchOptions(method, options);
+
+  const description = method.description ? `/**\n * ${method.description}\n */\n` : '';
+
+  const pInit = hasParams ? `\n  const p = isRef(params) ? params : shallowRef(params)` : '';
+
+  return `${description}export const ${method.composableName} = (${args}) => {${pInit}
+  return useApiRequest${responseTypeGeneric}(${url}, ${fetchOptions})
+}`;
+}
+
+/**
+ * Generate URL (with path params if needed)
+ */
+function generateUrl(method: MethodInfo): string {
+  if (method.pathParams.length === 0) {
+    return `'${method.path}'`;
+  }
+
+  let url = method.path;
+  for (const param of method.pathParams) {
+    const accessor = method.paramsShape === 'nested' ? `p.value.path.${param}` : `p.value.${param}`;
+    url = url.replace(`{${param}}`, `\${${accessor}}`);
+  }
+
+  return `() => \`${url}\``;
+}
+
+/**
+ * Generate fetch options object
+ */
+function generateFetchOptions(method: MethodInfo, generateOptions?: GenerateOptions): string {
+  const options: string[] = [];
+
+  // Method
+  options.push(`method: '${method.httpMethod}'`);
+
+  // Base URL (if provided in config)
+  if (generateOptions?.baseUrl) {
+    options.push(`baseURL: '${generateOptions.baseUrl}'`);
+  }
+
+  // Body
+  if (method.hasBody) {
+    if (method.paramsShape === 'nested') {
+      options.push(`body: computed(() => p.value.body)`);
+    } else if (method.bodyField) {
+      options.push(`body: computed(() => p.value.${method.bodyField})`);
+    }
+  }
+
+  // Query params
+  if (method.hasQueryParams) {
+    if (method.paramsShape === 'nested') {
+      options.push(`query: computed(() => p.value.query)`);
+    } else if (method.queryParams.length > 0) {
+      const queryObj = method.queryParams
+        .map((param) => `${param}: p.value.${param}`)
+        .join(',\n      ');
+      options.push(`query: computed(() => ({\n      ${queryObj}\n    }))`);
+    }
+  }
+
+  // Headers
+  if (Object.keys(method.headers).length > 0) {
+    const headersEntries = Object.entries(method.headers)
+      .map(([key, value]) => `'${key}': '${value}'`)
+      .join(',\n      ');
+    options.push(`headers: {\n      ${headersEntries},\n      ...options?.headers\n    }`);
+  }
+
+  // Spread options
+  options.push('...options');
+
+  const optionsStr = options.join(',\n    ');
+  return `{\n    ${optionsStr}\n  }`;
+}
+
+/**
+ * Generate index.ts that exports all composables
+ */
+export function generateIndexFile(composableNames: string[]): string {
+  const header = generateFileHeader();
+  const exports = composableNames
+    .map((name) => `export { ${name} } from './composables/${name}'`)
+    .join('\n');
+
+  return `${header}${exports}\n`;
+}

package/src/generators/use-fetch/types.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-export shared types
+ * This allows use-fetch generator to use the same types as other generators
+ */
+export * from '../shared/types.js';

package/src/index.ts

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import * as p from '@clack/prompts';
+import { generateOpenApiFiles, generateHeyApiFiles, checkJavaInstalled } from './generate.js';
+import { generateUseFetchComposables } from './generators/use-fetch/generator.js';
+import { generateUseAsyncDataComposables } from './generators/use-async-data/generator.js';
+import { generateNuxtServerRoutes } from './generators/nuxt-server/generator.js';
+import {
+  promptInitialInputs,
+  promptInputPath,
+  promptComposablesSelection,
+  promptServerRoutePath,
+  promptBffConfig,
+  promptGeneratorBackend,
+} from './cli/prompts.js';
+import { MESSAGES } from './cli/messages.js';
+import { displayLogo } from './cli/logo.js';
+import { loadConfig, mergeConfig, parseTags, parseGenerators } from './cli/config.js';
+
+const program = new Command();
+
+program.name('nxh').description('Nuxt OpenAPI Hyperfetch generator').version('1.0.0');
+
+interface GenerateOptions {
+  input?: string;
+  output?: string;
+  baseUrl?: string;
+  mode?: 'client' | 'server';
+  tags?: string;
+  excludeTags?: string;
+  overwrite?: boolean;
+  dryRun?: boolean;
+  verbose?: boolean;
+  watch?: boolean;
+  generators?: string;
+  serverRoutePath?: string;
+  enableBff?: boolean;
+  backend?: string;
+}
+
+program
+  .command('generate')
+  .description('Generate all nuxt files and composables from OpenAPI spec')
+  .option('-i, --input <path>', 'OpenAPI file path or URL')
+  .option('-o, --output <path>', 'Output directory')
+  .option('--base-url <url>', 'Base URL for API requests')
+  .option('--mode <mode>', 'Generation mode: client or server', 'client')
+  .option('--tags <tags>', 'Generate only specific tags (comma-separated)')
+  .option('--exclude-tags <tags>', 'Exclude specific tags (comma-separated)')
+  .option('--overwrite', 'Overwrite existing files without prompting', false)
+  .option('--dry-run', 'Preview changes without writing files', false)
+  .option('-v, --verbose', 'Enable verbose logging', false)
+  .option('--watch', 'Watch mode - regenerate on file changes', false)
+  .option('--generators <types>', 'Generators to use: useFetch,useAsyncData,nuxtServer')
+  .option('--server-route-path <path>', 'Server route path (for nuxtServer mode)')
+  .option('--enable-bff', 'Enable BFF pattern (for nuxtServer mode)', false)
+  .option('--backend <type>', 'Generator backend: official (Java) or heyapi (Node.js)')
+  .action(async (options: GenerateOptions) => {
+    try {
+      // Load config file
+      const fileConfig = await loadConfig();
+
+      if (options.verbose && fileConfig) {
+        p.log.info('Loaded configuration from file');
+      }
+
+      // Parse and merge configuration
+      const config = mergeConfig(fileConfig, {
+        input: options.input,
+        output: options.output,
+        baseUrl: options.baseUrl,
+        mode: options.mode,
+        tags: parseTags(options.tags),
+        excludeTags: parseTags(options.excludeTags),
+        overwrite: options.overwrite,
+        dryRun: options.dryRun,
+        verbose: options.verbose,
+        watch: options.watch,
+        generators: parseGenerators(options.generators),
+        serverRoutePath: options.serverRoutePath,
+        enableBff: options.enableBff,
+        backend:
+          options.backend === 'official' || options.backend === 'heyapi'
+            ? options.backend
+            : undefined,
+      });
+
+      if (config.verbose) {
+        console.log('Configuration:', config);
+      }
+
+      // Show logo and intro
+      displayLogo();
+      p.intro(MESSAGES.intro);
+
+      if (config.dryRun) {
+        p.log.warn('🔍 DRY RUN MODE - No files will be written');
+      }
+
+      // 0. Select generator engine (first question)
+      // Resolve engine from config.generator (user-facing) or config.backend (CLI flag)
+      // config.generator: 'openapi' | 'heyapi'  →  map 'openapi' to internal 'official'
+      const resolvedBackend =
+        config.generator === 'openapi'
+          ? 'official'
+          : config.generator === 'heyapi'
+            ? 'heyapi'
+            : config.backend;
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const backend = await promptGeneratorBackend(resolvedBackend);
+
+      // Check Java availability when official backend is selected
+      if (backend === 'official' && !checkJavaInstalled()) {
+        p.log.error(
+          'Java not found. The OpenAPI Generator requires Java 11 or higher.\n' +
+            'Install it from: https://adoptium.net\n' +
+            'Or switch to @hey-api/openapi-ts which requires no Java.'
+        );
+        p.outro('Aborted.');
+        process.exit(1);
+      }
+
+      // 1. Determine composables to generate FIRST
+      let composables: ('useFetch' | 'useAsyncData' | 'nuxtServer')[];
+
+      if (config.generators) {
+        composables = config.generators;
+        if (config.verbose) {
+          console.log(`Using generators from config: ${composables.join(', ')}`);
+        }
+      } else {
+        const result = await promptComposablesSelection();
+        composables = result.composables;
+      }
+
+      if (composables.length === 0) {
+        p.outro(MESSAGES.outro.noComposables);
+        return;
+      }
+
+      // 2. Ask for paths based on which generators were selected
+      const needsComposables = composables.some((c) => c === 'useFetch' || c === 'useAsyncData');
+      const needsNuxtServer = composables.includes('nuxtServer');
+
+      let inputPath: string;
+      let outputPath: string;
+
+      if (needsComposables) {
+        // useFetch/useAsyncData: ask for both input (OpenAPI spec) and output (composables dir)
+        const inputs = await promptInitialInputs(config.input, config.output);
+        inputPath = inputs.inputPath;
+        outputPath = inputs.outputPath;
+      } else {
+        // nuxtServer only: ask just for the OpenAPI spec, use default/config for output
+        inputPath = await promptInputPath(config.input);
+        outputPath = config.output ?? './swagger';
+      }
+
+      // 3. Ask for server route path if nuxtServer is selected
+      let serverRoutePath = config.serverRoutePath || '';
+      let enableBff = config.enableBff || false;
+
+      if (needsNuxtServer && !config.serverRoutePath) {
+        serverRoutePath = await promptServerRoutePath();
+        const bffConfig = await promptBffConfig();
+        enableBff = bffConfig.enableBff;
+      }
+
+      // Generate OpenAPI files
+      const s = p.spinner();
+      s.start(MESSAGES.steps.generatingOpenApi);
+
+      if (!config.dryRun) {
+        if (backend === 'heyapi') {
+          await generateHeyApiFiles(inputPath, outputPath);
+        } else {
+          generateOpenApiFiles(inputPath, outputPath);
+        }
+        s.stop('OpenAPI files generated');
+      } else {
+        s.stop('Would generate OpenAPI files (skipped in dry-run)');
+      }
+
+      // Generate selected composables
+      const composablesOutputDir = `${outputPath}/composables`;
+
+      for (const composable of composables) {
+        const spinner = p.spinner();
+        spinner.start(`Generating ${composable}...`);
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const generateOptions = { baseUrl: config.baseUrl, backend };
+
+        try {
+          switch (composable) {
+            case 'useFetch':
+              if (!config.dryRun) {
+                await generateUseFetchComposables(
+                  outputPath,
+                  `${composablesOutputDir}/use-fetch`,
+                  generateOptions
+                );
+                spinner.stop(`✓ Generated useFetch composables`);
+              } else {
+                spinner.stop(`Would generate useFetch composables (dry-run)`);
+              }
+              break;
+            case 'useAsyncData':
+              if (!config.dryRun) {
+                await generateUseAsyncDataComposables(
+                  outputPath,
+                  `${composablesOutputDir}/use-async-data`,
+                  generateOptions
+                );
+                spinner.stop(`✓ Generated useAsyncData composables`);
+              } else {
+                spinner.stop(`Would generate useAsyncData composables (dry-run)`);
+              }
+              break;
+            case 'nuxtServer':
+              if (!config.dryRun) {
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                await generateNuxtServerRoutes(outputPath, serverRoutePath, { enableBff, backend });
+                spinner.stop(`✓ Generated Nuxt server routes`);
+              } else {
+                spinner.stop(`Would generate Nuxt server routes (dry-run)`);
+              }
+              break;
+          }
+        } catch (error) {
+          spinner.stop(`✗ Failed to generate ${composable}`);
+          throw error;
+        }
+      }
+
+      if (config.dryRun) {
+        p.outro('🔍 Dry run complete - no files were modified');
+      } else {
+        p.outro(MESSAGES.outro.success);
+      }
+    } catch (error) {
+      p.log.error(`Error: ${String(error)}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('use-fetch')
+  .description('Generate Nuxt useFetch composables from OpenAPI generated files')
+  .option('-i, --input <path>', 'OpenAPI generated files directory')
+  .option('-o, --output <path>', 'Output directory for composables')
+  .action(async (options: { input?: string; output?: string }) => {
+    if (!options.input || !options.output) {
+      p.log.error('Error: You must provide both --input and --output');
+      process.exit(1);
+    }
+    try {
+      await generateUseFetchComposables(options.input, options.output);
+    } catch (error) {
+      p.log.error(`Error: ${String(error)}`);
+      process.exit(1);
+    }
+  });
+
+program.parse();