nuxt-openapi-hyperfetch 0.1.0-alpha.1

package/src/generators/shared/templates/api-callbacks-plugin.ts

@@ -0,0 +1,352 @@
+// @ts-nocheck
+/**
+ * Global API Callbacks Plugin
+ *
+ * ⚠️ IMPORTANT: This file is NEVER regenerated - your changes are safe!
+ *
+ * This plugin allows you to configure global callbacks for all API requests
+ * made with useFetch* and useAsyncData* composables.
+ *
+ * 📚 Three ways to control global callbacks:
+ *
+ * 1️⃣ OPTION 1: skipGlobalCallbacks (disable from the call)
+ *    Skip global callbacks for specific requests
+ *    Example:
+ *      useFetchGetPets({ skipGlobalCallbacks: true })
+ *      useFetchGetPets({ skipGlobalCallbacks: ['onSuccess'] })
+ *
+ * 2️⃣ OPTION 2: return false (disable from the plugin)
+ *    Global callbacks can return false to prevent local callback execution
+ *    Example:
+ *      onError: (error) => {
+ *        if (error.statusCode === 401) {
+ *          navigateTo('/login');
+ *          return false; // Don't execute local onError
+ *        }
+ *      }
+ *
+ * 3️⃣ OPTION 3: patterns (URL matching)
+ *    Only apply callbacks to URLs matching specific patterns
+ *    Example:
+ *      patterns: ['/api/**', '/api/v2/*']
+ */
+
+export default defineNuxtPlugin(() => {
+  // Uncomment and customize the callbacks you need
+  const globalCallbacks = {
+    // ========================================================================
+    // OPTION 3: URL Pattern Matching (OPTIONAL)
+    // ========================================================================
+    // Only apply global callbacks to URLs matching these patterns
+    // Use ** to match any path (including nested), * to match single segment
+    // If omitted or empty, callbacks apply to ALL requests
+    // patterns: ['/api/**'],  // Only internal APIs
+    // patterns: ['/api/v1/**', '/api/v2/**'],  // Multiple API versions
+    // patterns: ['**/public/**'],  // All public endpoints
+    // ========================================================================
+    // onRequest: Called before every request
+    // ========================================================================
+    // Use cases:
+    // - Add authentication headers globally
+    // - Log all API calls
+    // - Add request timestamps
+    // - Modify request body/headers/params
+    // onRequest: (context) => {
+    //   console.log(`[API] ${context.method} ${context.url}`);
+    //
+    //   // Example 1: Add auth token to all requests
+    //   // const token = useCookie('auth-token').value;
+    //   // if (token) {
+    //   //   return {
+    //   //     headers: { 'Authorization': `Bearer ${token}` }
+    //   //   };
+    //   // }
+    //
+    //   // Example 2: Add request timestamp
+    //   // return {
+    //   //   headers: { 'X-Request-Time': new Date().toISOString() }
+    //   // };
+    //
+    //   // Example 3: Block local onRequest (OPTION 2)
+    //   // return false;
+    // },
+    // ========================================================================
+    // onSuccess: Called when request succeeds
+    // ========================================================================
+    // Use cases:
+    // - Show success notifications/toasts
+    // - Track successful operations
+    // - Update analytics
+    // - Cache responses
+    // onSuccess: (data, context) => {
+    //   // Example 1: Success notification
+    //   // const { $toast } = useNuxtApp();
+    //   // $toast?.success('✅ Operation successful');
+    //
+    //   // Example 2: Track analytics
+    //   // trackEvent('api_success', { url: context?.url });
+    //
+    //   // Example 3: Log response data (development only)
+    //   // if (process.dev) {
+    //   //   console.log('API Response:', data);
+    //   // }
+    //
+    //   // Example 4: Cache specific responses
+    //   // if (context?.url.includes('/api/config')) {
+    //   //   localStorage.setItem('app-config', JSON.stringify(data));
+    //   // }
+    //
+    //   // Example 5: Block local onSuccess for certain cases (OPTION 2)
+    //   // if (data.status === 'pending_approval') {
+    //   //   $toast?.info('⏳ Awaiting approval');
+    //   //   return false; // Don't execute local onSuccess
+    //   // }
+    // },
+    // ========================================================================
+    // onError: Called when request fails
+    // ========================================================================
+    // Use cases:
+    // - Handle authentication errors globally (401, 403)
+    // - Show error notifications
+    // - Log errors to monitoring service
+    // - Handle network errors
+    // - Retry logic
+    // onError: (error, context) => {
+    //   console.error('[API Error]', error);
+    //   const { $toast } = useNuxtApp();
+    //
+    //   // Example 1: Handle authentication errors (OPTION 2)
+    //   if (error.statusCode === 401) {
+    //     $toast?.warning('⚠️ Session expired - redirecting to login...');
+    //     navigateTo('/login');
+    //     return false; // Don't execute local onError (avoiding duplicate messages)
+    //   }
+    //
+    //   // Example 2: Handle forbidden errors
+    //   // if (error.statusCode === 403) {
+    //   //   $toast?.error('❌ Access denied');
+    //   //   navigateTo('/');
+    //   //   return false;
+    //   // }
+    //
+    //   // Example 3: Handle server errors
+    //   // if (error.statusCode >= 500) {
+    //   //   $toast?.error('❌ Server error - please try again later');
+    //   //   // Log to monitoring service
+    //   //   // logErrorToSentry(error);
+    //   // }
+    //
+    //   // Example 4: Handle rate limiting
+    //   // if (error.statusCode === 429) {
+    //   //   const retryAfter = error.data?.retryAfter || 60;
+    //   //   $toast?.warning(`⏳ Too many requests - retry in ${retryAfter}s`);
+    //   //   return false; // Don't show duplicate error in component
+    //   // }
+    //
+    //   // Example 5: Handle network errors
+    //   // if (error.message === 'Network request failed') {
+    //   //   $toast?.error('❌ Network error - check your connection');
+    //   // }
+    //
+    //   // Example 6: Generic error notification
+    //   // $toast?.error(`❌ ${error.message || 'An error occurred'}`);
+    //
+    //   // Allow local onError to execute (return true or don't return)
+    // },
+    // ========================================================================
+    // onFinish: Called when request completes (success or error)
+    // ========================================================================
+    // Use cases:
+    // - Hide loading indicators
+    // - Track request completion
+    // - Clean up resources
+    // - Update request counters
+    // onFinish: (context) => {
+    //   // Example 1: Track API call completion
+    //   // const duration = Date.now() - context.startTime;
+    //   // trackMetric('api_call_duration', duration, { url: context.url });
+    //
+    //   // Example 2: Log request completion
+    //   // console.log(
+    //   //   `[API] ${context.url} - ${context.success ? '✅ Success' : '❌ Failed'}`
+    //   // );
+    //
+    //   // Example 3: Update request counter
+    //   // const store = useRequestStore();
+    //   // store.decrementPendingRequests();
+    //
+    //   // Example 4: Clean up global loading state
+    //   // const { $loading } = useNuxtApp();
+    //   // $loading?.hide();
+    // },
+  };
+
+  return {
+    provide: {
+      getGlobalApiCallbacks: () => globalCallbacks,
+    },
+  };
+});
+
+// ============================================================================
+// USAGE EXAMPLES
+// ============================================================================
+
+/**
+ * Example 1: Use global callbacks (default behavior)
+ *
+ * const { data, error } = useFetchGetPets();
+ * // ✅ All global callbacks execute automatically
+ */
+
+/**
+ * Example 2: Skip ALL global callbacks (OPTION 1)
+ *
+ * const { data, error } = useFetchGetPets({
+ *   skipGlobalCallbacks: true,
+ * });
+ * // ❌ No global callbacks execute
+ */
+
+/**
+ * Example 3: Skip SPECIFIC global callbacks (OPTION 1)
+ *
+ * const { data, error } = useFetchUpdatePet(id, pet, {
+ *   skipGlobalCallbacks: ['onSuccess'], // Skip global onSuccess only
+ *   onSuccess: (data) => {
+ *     // Only this local callback executes
+ *     console.log('Pet updated:', data);
+ *   }
+ * });
+ * // ✅ Global onError still executes
+ * // ❌ Global onSuccess skipped
+ * // ✅ Local onSuccess executes
+ */
+
+/**
+ * Example 4: Global callback prevents local execution (OPTION 2)
+ *
+ * // In plugin:
+ * onError: (error) => {
+ *   if (error.statusCode === 401) {
+ *     navigateTo('/login');
+ *     return false; // Don't execute local onError
+ *   }
+ * }
+ *
+ * // In component:
+ * const { data, error } = useFetchGetPets({
+ *   onError: (error) => {
+ *     // ❌ This won't execute for 401 errors (global returned false)
+ *     // ✅ This executes for other errors (404, 500, etc.)
+ *     console.error('Failed to load pets:', error);
+ *   }
+ * });
+ */
+
+/**
+ * Example 5: URL pattern matching (OPTION 3)
+ *
+ * // In plugin:
+ * patterns: ['/api/public/**']
+ *
+ * // In components:
+ * useFetchGetPets();          // URL: /api/public/pets   ✅ Global callbacks execute
+ * useFetchGetUser();          // URL: /api/users/me      ❌ Global callbacks skipped
+ * useFetchGetPublicConfig();  // URL: /api/public/config ✅ Global callbacks execute
+ */
+
+/**
+ * Example 6: Combine all options
+ *
+ * // In plugin:
+ * patterns: ['/api/**'],
+ * onError: (error) => {
+ *   if (error.statusCode === 401) return false;
+ * }
+ *
+ * // In component:
+ * const { data } = useFetchCreatePet(pet, {
+ *   skipGlobalCallbacks: ['onSuccess'], // Skip global success toast
+ *   onSuccess: (pet) => {
+ *     // Show custom success message
+ *     toast.success(`🐕 ${pet.name} added successfully!`);
+ *   },
+ *   onError: (error) => {
+ *     // This won't execute for 401 (global returns false)
+ *     // This executes for other errors
+ *     console.error('Failed to create pet:', error);
+ *   }
+ * });
+ */
+
+// ============================================================================
+// COMMON PATTERNS
+// ============================================================================
+
+/**
+ * Pattern 1: Toast notifications for all operations
+ *
+ * const globalCallbacks = {
+ *   onSuccess: () => {
+ *     useNuxtApp().$toast?.success('✅ Success');
+ *   },
+ *   onError: (error) => {
+ *     if (error.statusCode === 401) {
+ *       navigateTo('/login');
+ *       return false;
+ *     }
+ *     useNuxtApp().$toast?.error(`❌ ${error.message}`);
+ *   }
+ * };
+ */
+
+/**
+ * Pattern 2: Authentication + logging
+ *
+ * const globalCallbacks = {
+ *   onRequest: (context) => {
+ *     console.log(`[API] ${context.method} ${context.url}`);
+ *     const token = useCookie('auth-token').value;
+ *     if (token) {
+ *       return { headers: { 'Authorization': `Bearer ${token}` } };
+ *     }
+ *   },
+ *   onError: (error) => {
+ *     if (error.statusCode === 401) {
+ *       useCookie('auth-token').value = null;
+ *       navigateTo('/login');
+ *       return false;
+ *     }
+ *   }
+ * };
+ */
+
+/**
+ * Pattern 3: Analytics tracking
+ *
+ * const globalCallbacks = {
+ *   onSuccess: (data, context) => {
+ *     trackEvent('api_success', { endpoint: context?.url });
+ *   },
+ *   onError: (error, context) => {
+ *     trackEvent('api_error', {
+ *       endpoint: context?.url,
+ *       statusCode: error.statusCode
+ *     });
+ *   }
+ * };
+ */
+
+/**
+ * Pattern 4: Loading states
+ *
+ * const globalCallbacks = {
+ *   onRequest: () => {
+ *     useLoadingStore().increment();
+ *   },
+ *   onFinish: () => {
+ *     useLoadingStore().decrement();
+ *   }
+ * };
+ */

package/src/generators/shared/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared types used by multiple generators
+ */
+
+export interface MethodInfo {
+  name: string; // 'addPet'
+  composableName: string; // 'useFetchAddPet' or 'useAsyncDataAddPet'
+  requestType?: string; // 'AddPetRequest'
+  responseType: string; // 'Pet'
+  httpMethod: string; // 'POST' | 'GET' | 'PUT' | 'DELETE' | 'PATCH'
+  path: string; // '/pet' or '/pet/{petId}'
+  hasBody: boolean; // true if method uses body
+  bodyField?: string; // 'pet' (from params.pet)
+  hasQueryParams: boolean; // true if has query parameters
+  queryParams: string[]; // ['status', 'tags']
+  pathParams: string[]; // ['petId']
+  headers: Record<string, string>; // Default headers
+  description?: string; // Method description from comments
+  hasRawMethod: boolean; // true if xxxRaw method exists
+  rawMethodName?: string; // 'addPetRaw'
+  paramsShape?: 'flat' | 'nested'; // 'flat' for official generator, 'nested' for Hey API
+}
+
+export interface ApiClassInfo {
+  className: string; // 'PetApi'
+  methods: MethodInfo[];
+}

package/src/generators/tanstack-query/generator.ts

@@ -0,0 +1,11 @@
+/**
+ * Placeholder for TanStack Query composables generator
+ * TODO: Implement TanStack Query generation
+ */
+export function generateTanstackQueryComposables(inputDir: string, outputDir: string): void {
+  console.log('\n📦 @tanstack/vue-query generator\n');
+  console.log(`   Input: ${inputDir}`);
+  console.log(`   Output: ${outputDir}`);
+  console.log('\n⚠️  This generator is not yet implemented.');
+  console.log('   Coming soon!\n');
+}

package/src/generators/use-async-data/generator.ts

@@ -0,0 +1,204 @@
+import * as path from 'path';
+import fs from 'fs-extra';
+import { fileURLToPath } from 'url';
+import { format } from 'prettier';
+import {
+  getApiFiles as getApiFilesOfficial,
+  parseApiFile as parseApiFileOfficial,
+} from './parser.js';
+import {
+  getApiFiles as getApiFilesHeyApi,
+  parseApiFile as parseApiFileHeyApi,
+} from '../shared/parsers/heyapi-parser.js';
+import {
+  generateComposableFile,
+  generateRawComposableFile,
+  generateIndexFile,
+  type GenerateOptions,
+} from './templates.js';
+import type { MethodInfo } from './types.js';
+import { p, logSuccess, logError } from '../../cli/logger.js';
+
+/**
+ * Main function to generate useAsyncData composables
+ */
+export async function generateUseAsyncDataComposables(
+  inputDir: string,
+  outputDir: string,
+  options?: GenerateOptions
+): Promise<void> {
+  const mainSpinner = p.spinner();
+
+  // Select parser based on chosen backend
+  const getApiFiles = options?.backend === 'heyapi' ? getApiFilesHeyApi : getApiFilesOfficial;
+  const parseApiFile = options?.backend === 'heyapi' ? parseApiFileHeyApi : parseApiFileOfficial;
+
+  // 1. Get all API files
+  mainSpinner.start('Scanning API files');
+  const apiFiles = getApiFiles(inputDir);
+  mainSpinner.stop(`Found ${apiFiles.length} API file(s)`);
+
+  if (apiFiles.length === 0) {
+    throw new Error('No API files found in the input directory');
+  }
+
+  // 2. Parse each API file
+  mainSpinner.start('Parsing API files');
+  const allMethods: MethodInfo[] = [];
+
+  for (const file of apiFiles) {
+    const fileName = path.basename(file);
+    try {
+      const apiInfo = parseApiFile(file);
+      allMethods.push(...apiInfo.methods);
+    } catch (error) {
+      logError(`Error parsing ${fileName}: ${error}`);
+    }
+  }
+
+  mainSpinner.stop(`Found ${allMethods.length} methods to generate`);
+
+  if (allMethods.length === 0) {
+    p.log.warn('No methods found to generate');
+    return;
+  }
+
+  // 3. Clean and create output directories
+  mainSpinner.start('Preparing output directories');
+  const composablesDir = path.join(outputDir, 'composables');
+  const runtimeDir = path.join(outputDir, 'runtime');
+  const sharedRuntimeDir = path.join(outputDir, 'shared', 'runtime');
+  await fs.emptyDir(composablesDir);
+  await fs.ensureDir(runtimeDir);
+  await fs.ensureDir(sharedRuntimeDir);
+  mainSpinner.stop('Output directories ready');
+
+  // 4. Copy runtime helpers
+  mainSpinner.start('Copying runtime files');
+  // Derive __dirname equivalent for ESM
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  // When compiled, __dirname points to dist/generators/use-async-data/
+  // We need to go back to src/ to get the original .ts files
+
+  // Copy useApiAsyncData.ts
+  const runtimeSource = path.resolve(
+    __dirname,
+    '../../../src/generators/use-async-data/runtime/useApiAsyncData.ts'
+  );
+  const runtimeDest = path.join(runtimeDir, 'useApiAsyncData.ts');
+  await fs.copyFile(runtimeSource, runtimeDest);
+
+  // Copy useApiAsyncDataRaw.ts
+  const runtimeRawSource = path.resolve(
+    __dirname,
+    '../../../src/generators/use-async-data/runtime/useApiAsyncDataRaw.ts'
+  );
+  const runtimeRawDest = path.join(runtimeDir, 'useApiAsyncDataRaw.ts');
+  await fs.copyFile(runtimeRawSource, runtimeRawDest);
+
+  // Copy shared apiHelpers.ts
+  const sharedHelpersSource = path.resolve(
+    __dirname,
+    '../../../src/generators/shared/runtime/apiHelpers.ts'
+  );
+  const sharedHelpersDest = path.join(sharedRuntimeDir, 'apiHelpers.ts');
+  await fs.copyFile(sharedHelpersSource, sharedHelpersDest);
+  mainSpinner.stop('Runtime files copied');
+
+  // 5. Calculate relative import path from composables to APIs
+  const relativePath = calculateRelativeImportPath(composablesDir, inputDir);
+
+  // 6. Generate each composable (normal + Raw if available)
+  mainSpinner.start('Generating composables');
+  let successCount = 0;
+  let errorCount = 0;
+  const generatedComposableNames: string[] = [];
+
+  for (const method of allMethods) {
+    // Generate normal version
+    try {
+      const code = generateComposableFile(method, relativePath, options);
+      const formattedCode = await formatCode(code);
+      const composableName = method.composableName.replace(/^useFetch/, 'useAsyncData');
+      const fileName = `${composableName}.ts`;
+      const filePath = path.join(composablesDir, fileName);
+
+      await fs.writeFile(filePath, formattedCode, 'utf-8');
+      generatedComposableNames.push(composableName);
+      successCount++;
+    } catch (error) {
+      logError(`Error generating ${method.composableName}: ${error}`);
+      errorCount++;
+    }
+
+    // Generate Raw version if available
+    if (method.hasRawMethod && method.rawMethodName) {
+      try {
+        const code = generateRawComposableFile(method, relativePath, options);
+        const formattedCode = await formatCode(code);
+        const composableName = `useAsyncData${method.rawMethodName.replace(/Raw$/, '')}Raw`;
+        const fileName = `${composableName}.ts`;
+        const filePath = path.join(composablesDir, fileName);
+
+        await fs.writeFile(filePath, formattedCode, 'utf-8');
+        generatedComposableNames.push(composableName);
+        successCount++;
+      } catch (error) {
+        logError(`Error generating ${method.composableName} (Raw): ${error}`);
+        errorCount++;
+      }
+    }
+  }
+
+  // 7. Generate index.ts
+  const indexCode = generateIndexFile(generatedComposableNames);
+  const formattedIndex = await formatCode(indexCode);
+  await fs.writeFile(path.join(outputDir, 'index.ts'), formattedIndex, 'utf-8');
+  mainSpinner.stop(`Generated ${successCount} composables`);
+
+  // 8. Summary
+  if (errorCount > 0) {
+    p.log.warn(`Completed with ${errorCount} error(s)`);
+  }
+  logSuccess(`Generated ${successCount} useAsyncData composable(s) in ${outputDir}`);
+}
+
+/**
+ * Calculate relative import path from composables to APIs
+ */
+function calculateRelativeImportPath(composablesDir: string, inputDir: string): string {
+  // Import from the root index.ts which exports apis, models, and runtime
+  let relativePath = path.relative(composablesDir, inputDir);
+
+  // Convert Windows paths to Unix-style
+  relativePath = relativePath.replace(/\\/g, '/');
+
+  // Ensure it starts with './' or '../'
+  if (!relativePath.startsWith('.')) {
+    relativePath = './' + relativePath;
+  }
+
+  // Remove .ts extension and trailing /
+  relativePath = relativePath.replace(/\.ts$/, '').replace(/\/$/, '');
+
+  return relativePath;
+}
+
+/**
+ * Format code with Prettier
+ */
+async function formatCode(code: string): Promise<string> {
+  try {
+    return await format(code, {
+      parser: 'typescript',
+      semi: true,
+      singleQuote: true,
+      trailingComma: 'es5',
+      printWidth: 80,
+      tabWidth: 2,
+    });
+  } catch {
+    p.log.warn('Could not format code with Prettier');
+    return code;
+  }
+}

package/src/generators/use-async-data/parser.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-export all parser functionality from use-fetch
+ * The parsing logic is the same for both generators
+ */
+export * from '../use-fetch/parser.js';