nuxt-openapi-hyperfetch 0.1.0-alpha.1

package/dist/generators/shared/runtime/apiHelpers.js

@@ -0,0 +1,268 @@
+// @ts-nocheck - This file runs in user's Nuxt project with different TypeScript config
+/**
+ * Shared API Helpers - Used by both useFetch and useAsyncData wrappers
+ * This file contains common logic for callbacks, transforms, and global configuration
+ */
+/**
+ * Helper function to apply request modifications from onRequest interceptor
+ */
+export function applyRequestModifications(options, modifications) {
+    if (modifications.body !== undefined) {
+        options.body = modifications.body;
+    }
+    if (modifications.headers !== undefined) {
+        options.headers = {
+            ...options.headers,
+            ...modifications.headers,
+        };
+    }
+    if (modifications.query !== undefined) {
+        options.query = {
+            ...options.query,
+            ...modifications.query,
+        };
+    }
+}
+/**
+ * Helper function to pick specific keys from an object
+ * Supports dot notation for nested paths (e.g., 'person.name')
+ */
+export function applyPick(data, paths) {
+    const result = {};
+    for (const path of paths) {
+        const keys = path.split('.');
+        // Navigate to the nested value
+        let value = data;
+        let exists = true;
+        for (const key of keys) {
+            if (value && typeof value === 'object' && key in value) {
+                value = value[key];
+            }
+            else {
+                exists = false;
+                break;
+            }
+        }
+        // Set the value in the result, maintaining nested structure
+        if (exists) {
+            let current = result;
+            for (let i = 0; i < keys.length - 1; i++) {
+                const key = keys[i];
+                if (!(key in current)) {
+                    current[key] = {};
+                }
+                current = current[key];
+            }
+            current[keys[keys.length - 1]] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Helper function to get global headers from user configuration
+ * Supports two methods:
+ * 1. Auto-imported composable: composables/useApiHeaders.ts
+ * 2. Nuxt plugin provide: plugins/api-config.ts with $getApiHeaders
+ */
+export function getGlobalHeaders() {
+    let headers = {};
+    // Method 1: Try to use auto-imported composable (useApiHeaders)
+    try {
+        // @ts-ignore - useApiHeaders may or may not exist (user-defined)
+        if (typeof useApiHeaders !== 'undefined') {
+            // @ts-ignore
+            const getHeaders = useApiHeaders();
+            if (getHeaders) {
+                const h = typeof getHeaders === 'function' ? getHeaders() : getHeaders;
+                if (h && typeof h === 'object') {
+                    headers = { ...headers, ...h };
+                }
+            }
+        }
+    }
+    catch (e) {
+        // useApiHeaders doesn't exist or failed, that's OK
+    }
+    // Method 2: Try to use Nuxt App plugin ($getApiHeaders)
+    try {
+        const nuxtApp = useNuxtApp();
+        // @ts-ignore - $getApiHeaders may or may not exist (user-defined)
+        if (nuxtApp.$getApiHeaders) {
+            // @ts-ignore
+            const h = nuxtApp.$getApiHeaders();
+            if (h && typeof h === 'object') {
+                headers = { ...headers, ...h };
+            }
+        }
+    }
+    catch (e) {
+        // useNuxtApp not available or plugin not configured, that's OK
+    }
+    return headers;
+}
+/**
+ * Helper function to get global callbacks from user configuration
+ * Uses Nuxt plugin provide: plugins/api-callbacks.ts with $getGlobalApiCallbacks
+ */
+export function getGlobalCallbacks() {
+    try {
+        const nuxtApp = useNuxtApp();
+        // @ts-ignore - $getGlobalApiCallbacks may or may not exist (user-defined)
+        if (nuxtApp.$getGlobalApiCallbacks) {
+            // @ts-ignore
+            const callbacks = nuxtApp.$getGlobalApiCallbacks();
+            if (callbacks && typeof callbacks === 'object') {
+                return callbacks;
+            }
+        }
+    }
+    catch (e) {
+        // useNuxtApp not available or plugin not configured, that's OK
+    }
+    return {};
+}
+/**
+ * Check if a global callback should be applied to a specific request
+ * Implements Opción 1 (skipGlobalCallbacks) and Opción 3 (pattern matching)
+ */
+export function shouldApplyGlobalCallback(url, callbackName, patterns, skipConfig) {
+    // Opción 1: Check if callback is skipped via skipGlobalCallbacks
+    if (skipConfig === true) {
+        return false; // Skip all global callbacks
+    }
+    if (Array.isArray(skipConfig) && skipConfig.includes(callbackName)) {
+        return false; // Skip this specific callback
+    }
+    // Opción 3: Check pattern matching
+    if (patterns && patterns.length > 0) {
+        return patterns.some((pattern) => {
+            // Convert glob pattern to regex
+            // ** matches any characters including /
+            // * matches any characters except /
+            const regexPattern = pattern
+                .replace(/\*\*/g, '@@DOUBLE_STAR@@')
+                .replace(/\*/g, '[^/]*')
+                .replace(/@@DOUBLE_STAR@@/g, '.*');
+            const regex = new RegExp('^' + regexPattern + '$');
+            return regex.test(url);
+        });
+    }
+    // By default, apply global callback
+    return true;
+}
+/**
+ * Merge local and global callbacks with proper execution order
+ * Implements all 3 options:
+ * - Opción 1: skipGlobalCallbacks to disable global callbacks
+ * - Opción 2: global callbacks can return false to prevent local execution
+ * - Opción 3: pattern matching to apply callbacks only to matching URLs
+ */
+export function mergeCallbacks(url, localCallbacks, skipConfig) {
+    const global = getGlobalCallbacks();
+    return {
+        /**
+         * Merged onRequest callback
+         * Executes global first, then local
+         * Global can return modifications or false to cancel local
+         */
+        onRequest: async (ctx) => {
+            // Execute global onRequest
+            if (shouldApplyGlobalCallback(url, 'onRequest', global.patterns, skipConfig) &&
+                global.onRequest) {
+                try {
+                    const result = await global.onRequest(ctx);
+                    // Opción 2: If global returns false, don't execute local
+                    if (result === false) {
+                        return;
+                    }
+                    // If global returns modified context, use it
+                    if (result && typeof result === 'object' && !('then' in result)) {
+                        return result;
+                    }
+                }
+                catch (error) {
+                    console.error('Error in global onRequest callback:', error);
+                }
+            }
+            // Execute local onRequest
+            if (localCallbacks.onRequest) {
+                return await localCallbacks.onRequest(ctx);
+            }
+        },
+        /**
+         * Merged onSuccess callback
+         * Executes global first, then local (if global doesn't return false)
+         */
+        onSuccess: async (data, context) => {
+            let continueLocal = true;
+            // Execute global onSuccess
+            if (shouldApplyGlobalCallback(url, 'onSuccess', global.patterns, skipConfig) &&
+                global.onSuccess) {
+                try {
+                    const result = await global.onSuccess(data, context);
+                    // Opción 2: If global returns false, don't execute local
+                    if (result === false) {
+                        continueLocal = false;
+                    }
+                }
+                catch (error) {
+                    console.error('Error in global onSuccess callback:', error);
+                }
+            }
+            // Execute local onSuccess (if not cancelled)
+            if (continueLocal && localCallbacks.onSuccess) {
+                await localCallbacks.onSuccess(data, context);
+            }
+        },
+        /**
+         * Merged onError callback
+         * Executes global first, then local (if global doesn't return false)
+         */
+        onError: async (error, context) => {
+            let continueLocal = true;
+            // Execute global onError
+            if (shouldApplyGlobalCallback(url, 'onError', global.patterns, skipConfig) &&
+                global.onError) {
+                try {
+                    const result = await global.onError(error, context);
+                    // Opción 2: If global returns false, don't execute local
+                    if (result === false) {
+                        continueLocal = false;
+                    }
+                }
+                catch (error) {
+                    console.error('Error in global onError callback:', error);
+                }
+            }
+            // Execute local onError (if not cancelled)
+            if (continueLocal && localCallbacks.onError) {
+                await localCallbacks.onError(error, context);
+            }
+        },
+        /**
+         * Merged onFinish callback
+         * Executes global first, then local (if global doesn't return false)
+         */
+        onFinish: async (context) => {
+            let continueLocal = true;
+            // Execute global onFinish
+            if (shouldApplyGlobalCallback(url, 'onFinish', global.patterns, skipConfig) &&
+                global.onFinish) {
+                try {
+                    const result = await global.onFinish(context);
+                    // Opción 2: If global returns false, don't execute local
+                    if (result === false) {
+                        continueLocal = false;
+                    }
+                }
+                catch (error) {
+                    console.error('Error in global onFinish callback:', error);
+                }
+            }
+            // Execute local onFinish (if not cancelled)
+            if (continueLocal && localCallbacks.onFinish) {
+                await localCallbacks.onFinish(context);
+            }
+        },
+    };
+}

package/dist/generators/shared/templates/api-callbacks-plugin.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 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/*']
+ */
+declare const _default: any;
+export default _default;
+/**
+ * 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);
+ *   }
+ * });
+ */
+/**
+ * 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();
+ *   }
+ * };
+ */