nuxt-openapi-hyperfetch 0.1.0-alpha.1

package/dist/generators/shared/templates/api-callbacks-plugin.js

@@ -0,0 +1,338 @@
+// @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/dist/generators/shared/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared types used by multiple generators
+ */
+export interface MethodInfo {
+    name: string;
+    composableName: string;
+    requestType?: string;
+    responseType: string;
+    httpMethod: string;
+    path: string;
+    hasBody: boolean;
+    bodyField?: string;
+    hasQueryParams: boolean;
+    queryParams: string[];
+    pathParams: string[];
+    headers: Record<string, string>;
+    description?: string;
+    hasRawMethod: boolean;
+    rawMethodName?: string;
+    paramsShape?: 'flat' | 'nested';
+}
+export interface ApiClassInfo {
+    className: string;
+    methods: MethodInfo[];
+}

package/dist/generators/shared/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types used by multiple generators
+ */
+export {};

package/dist/generators/tanstack-query/generator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Placeholder for TanStack Query composables generator
+ * TODO: Implement TanStack Query generation
+ */
+export declare function generateTanstackQueryComposables(inputDir: string, outputDir: string): void;

package/dist/generators/tanstack-query/generator.js

@@ -0,0 +1,11 @@
+/**
+ * Placeholder for TanStack Query composables generator
+ * TODO: Implement TanStack Query generation
+ */
+export function generateTanstackQueryComposables(inputDir, outputDir) {
+    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/dist/generators/use-async-data/generator.d.ts

@@ -0,0 +1,5 @@
+import { type GenerateOptions } from './templates.js';
+/**
+ * Main function to generate useAsyncData composables
+ */
+export declare function generateUseAsyncDataComposables(inputDir: string, outputDir: string, options?: GenerateOptions): Promise<void>;

package/dist/generators/use-async-data/generator.js

@@ -0,0 +1,156 @@
+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, } from './templates.js';
+import { p, logSuccess, logError } from '../../cli/logger.js';
+/**
+ * Main function to generate useAsyncData composables
+ */
+export async function generateUseAsyncDataComposables(inputDir, outputDir, options) {
+    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 = [];
+    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 = [];
+    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, inputDir) {
+    // 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) {
+    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/dist/generators/use-async-data/parser.d.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';

package/dist/generators/use-async-data/parser.js

@@ -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';

package/dist/generators/use-async-data/runtime/useApiAsyncData.d.ts

@@ -0,0 +1,38 @@
+import { type ApiRequestOptions as BaseApiRequestOptions } from '../../shared/runtime/apiHelpers.js';
+/**
+ * Extended options specific to useAsyncData
+ */
+export interface ApiAsyncDataOptions<T> extends BaseApiRequestOptions<T> {
+    /**
+     * Whether to fetch data immediately on mount (default: true)
+     */
+    immediate?: boolean;
+    /**
+     * Lazy mode: don't block navigation (default: false)
+     */
+    lazy?: boolean;
+    /**
+     * Server-side rendering mode (default: true)
+     */
+    server?: boolean;
+    /**
+     * Deduplicate requests with the same key (default: 'cancel')
+     */
+    dedupe?: 'cancel' | 'defer';
+    /**
+     * Disable automatic refresh when reactive params change.
+     * Set to false to prevent re-fetching when params/url refs update.
+     * @default true
+     */
+    watch?: boolean;
+}
+/**
+ * Generic wrapper for API calls using Nuxt's useAsyncData
+ * Supports:
+ * - Lifecycle callbacks (onRequest, onSuccess, onError, onFinish)
+ * - Request modification via onRequest return value
+ * - Transform and pick operations
+ * - Global headers from useApiHeaders or $getApiHeaders
+ * - Watch pattern for reactive parameters
+ */
+export declare function useApiAsyncData<T>(key: string, url: string | (() => string), options?: ApiAsyncDataOptions<T>): any;