nuxt-openapi-hyperfetch 0.1.0-alpha.1

package/src/generators/use-async-data/runtime/useApiAsyncData.ts

@@ -0,0 +1,220 @@
+// @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;
+
+/**
+ * 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 function useApiAsyncData<T>(
+  key: string,
+  url: string | (() => string),
+  options?: ApiAsyncDataOptions<T>
+) {
+  const {
+    method = 'GET',
+    body,
+    headers = {},
+    params,
+    transform,
+    pick,
+    onRequest,
+    onSuccess,
+    onError,
+    onFinish,
+    skipGlobalCallbacks,
+    immediate = true,
+    lazy = false,
+    server = true,
+    dedupe = 'cancel',
+    watch: watchOption = true,
+    ...restOptions
+  } = options || {};
+
+  // Create reactive watch sources — use refs/computeds directly so Vue can track them
+  // watchOption: false disables auto-refresh entirely
+  const watchSources =
+    watchOption === false
+      ? []
+      : [
+          ...(typeof url === 'function' ? [url] : []),
+          ...(body ? (isRef(body) ? [body] : typeof body === 'object' ? [() => body] : []) : []),
+          ...(params
+            ? isRef(params)
+              ? [params]
+              : typeof params === 'object'
+                ? [() => params]
+                : []
+            : []),
+        ];
+
+  // Fetch function for useAsyncData
+  const fetchFn = async () => {
+    // Get URL value for merging callbacks
+    const finalUrl = typeof url === 'function' ? url() : url;
+
+    // Merge local and global callbacks
+    const mergedCallbacks = mergeCallbacks(
+      finalUrl,
+      { onRequest, onSuccess, onError, onFinish },
+      skipGlobalCallbacks
+    );
+
+    try {
+      // Get global headers
+      const globalHeaders = getGlobalHeaders();
+
+      // Prepare request context
+      const requestContext: RequestContext = {
+        url: finalUrl,
+        method: method as any,
+        headers: { ...globalHeaders, ...headers },
+        body,
+        params,
+      };
+
+      // Execute merged onRequest callback and potentially modify request
+      const modifiedContext = { ...requestContext };
+      if (mergedCallbacks.onRequest) {
+        const result = await mergedCallbacks.onRequest(requestContext);
+        // If onRequest returns modifications, apply them
+        if (result && typeof result === 'object') {
+          const modifications = result as ModifiedRequestContext;
+          if (modifications.body !== undefined) {
+            modifiedContext.body = modifications.body;
+          }
+          if (modifications.headers !== undefined) {
+            modifiedContext.headers = {
+              ...modifiedContext.headers,
+              ...modifications.headers,
+            };
+          }
+          if (modifications.params !== undefined) {
+            modifiedContext.params = {
+              ...modifiedContext.params,
+              ...modifications.params,
+            };
+          }
+        }
+      }
+
+      // Make the request with $fetch — toValue() unrefs any Ref/ComputedRef
+      let data = await $fetch<T>(modifiedContext.url, {
+        method: modifiedContext.method,
+        headers: modifiedContext.headers,
+        body: toValue(modifiedContext.body),
+        params: toValue(modifiedContext.params),
+        ...restOptions,
+      });
+
+      // Apply pick if provided
+      if (pick) {
+        data = applyPick(data, pick) as T;
+      }
+
+      // Apply transform if provided
+      if (transform) {
+        data = transform(data);
+      }
+
+      // Call merged onSuccess callback
+      if (mergedCallbacks.onSuccess) {
+        await mergedCallbacks.onSuccess(data, {
+          url: finalUrl,
+          method,
+          headers: modifiedContext.headers,
+        });
+      }
+
+      return data;
+    } catch (error: any) {
+      // Call merged onError callback
+      if (mergedCallbacks.onError) {
+        await mergedCallbacks.onError(error, { url: finalUrl, method, headers });
+      }
+      throw error;
+    } finally {
+      // Call merged onFinish callback
+      if (mergedCallbacks.onFinish) {
+        await mergedCallbacks.onFinish({
+          url: finalUrl,
+          method,
+          headers: { ...getGlobalHeaders(), ...headers },
+        });
+      }
+    }
+  };
+
+  // Use Nuxt's useAsyncData
+  const result = useAsyncData<MaybeTransformed<T, ApiAsyncDataOptions<T>>>(key, fetchFn, {
+    immediate,
+    lazy,
+    server,
+    dedupe,
+    watch: watchSources.length > 0 ? watchSources : undefined,
+  });
+
+  return result;
+}

package/src/generators/use-async-data/runtime/useApiAsyncDataRaw.ts

@@ -0,0 +1,236 @@
+// @ts-nocheck
+/**
+ * Nuxt Runtime Helper - This file is copied to the generated output
+ * It requires Nuxt 3 to be installed in the target project
+ *
+ * RAW VERSION: Returns full response including headers, status, and statusText
+ */
+import { watch } from 'vue';
+import {
+  getGlobalHeaders,
+  applyPick,
+  applyRequestModifications,
+  mergeCallbacks,
+  type RequestContext,
+  type ModifiedRequestContext,
+  type FinishContext,
+  type ApiRequestOptions as BaseApiRequestOptions,
+} from '../../shared/runtime/apiHelpers.js';
+
+/**
+ * Response structure for Raw version
+ * Includes data, headers, status, and statusText
+ */
+export interface RawResponse<T> {
+  data: T;
+  headers: Headers;
+  status: number;
+  statusText: string;
+}
+
+/**
+ * Helper type to infer transformed data type for Raw responses
+ * Transform only applies to the data property, not the entire response
+ */
+type MaybeTransformedRaw<T, Options> = Options extends { transform: (...args: any) => infer R }
+  ? RawResponse<R>
+  : Options extends { pick: ReadonlyArray<any> }
+    ? RawResponse<any> // With nested paths, type inference is complex
+    : RawResponse<T>;
+
+/**
+ * Extended options specific to useAsyncData Raw version
+ */
+export interface ApiAsyncDataRawOptions<T> extends Omit<BaseApiRequestOptions<T>, 'onSuccess'> {
+  /**
+   * Success callback that receives both data and full response
+   */
+  onSuccess?: (
+    data: T,
+    response: { headers: Headers; status: number; statusText: string; url: string }
+  ) => void | Promise<void>;
+
+  /**
+   * 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';
+}
+
+/**
+ * Generic wrapper for API calls using Nuxt's useAsyncData - RAW VERSION
+ * Returns full response with headers and status information
+ *
+ * Supports:
+ * - Lifecycle callbacks (onRequest, onSuccess with response, onError, onFinish)
+ * - Request modification via onRequest return value
+ * - Transform (applies only to data, not full response)
+ * - Pick operations (applies only to data)
+ * - Global headers from useApiHeaders or $getApiHeaders
+ * - Watch pattern for reactive parameters
+ */
+export function useApiAsyncDataRaw<T>(
+  key: string,
+  url: string | (() => string),
+  options?: ApiAsyncDataRawOptions<T>
+) {
+  const {
+    method = 'GET',
+    body,
+    headers = {},
+    params,
+    transform,
+    pick,
+    onRequest,
+    onSuccess,
+    onError,
+    onFinish,
+    skipGlobalCallbacks,
+    immediate = true,
+    lazy = false,
+    server = true,
+    dedupe = 'cancel',
+    ...restOptions
+  } = options || {};
+
+  // Create reactive watch sources for callbacks
+  const watchSources = [
+    ...(typeof url === 'function' ? [url] : []),
+    ...(body && typeof body === 'object' ? [() => body] : []),
+    ...(params && typeof params === 'object' ? [() => params] : []),
+  ];
+
+  // Fetch function for useAsyncData
+  const fetchFn = async (): Promise<RawResponse<T>> => {
+    // Get URL value for merging callbacks
+    const finalUrl = typeof url === 'function' ? url() : url;
+
+    // Merge local and global callbacks
+    const mergedCallbacks = mergeCallbacks(
+      finalUrl,
+      { onRequest, onSuccess, onError, onFinish },
+      skipGlobalCallbacks
+    );
+
+    try {
+      // Get global headers
+      const globalHeaders = getGlobalHeaders();
+
+      // Prepare request context
+      const requestContext: RequestContext = {
+        url: finalUrl,
+        method: method as any,
+        headers: { ...globalHeaders, ...headers },
+        body,
+        params,
+      };
+
+      // Execute merged onRequest callback and potentially modify request
+      const modifiedContext = { ...requestContext };
+      if (mergedCallbacks.onRequest) {
+        const result = await mergedCallbacks.onRequest(requestContext);
+        // If onRequest returns modifications, apply them
+        if (result && typeof result === 'object') {
+          const modifications = result as ModifiedRequestContext;
+          if (modifications.body !== undefined) {
+            modifiedContext.body = modifications.body;
+          }
+          if (modifications.headers !== undefined) {
+            modifiedContext.headers = {
+              ...modifiedContext.headers,
+              ...modifications.headers,
+            };
+          }
+          if (modifications.params !== undefined) {
+            modifiedContext.params = {
+              ...modifiedContext.params,
+              ...modifications.params,
+            };
+          }
+        }
+      }
+
+      // Make the request with $fetch.raw to get full response
+      const response = await $fetch.raw<T>(modifiedContext.url, {
+        method: modifiedContext.method,
+        headers: modifiedContext.headers,
+        body: modifiedContext.body,
+        params: modifiedContext.params,
+        ...restOptions,
+      });
+
+      // Extract data from response
+      let data = response._data as T;
+
+      // Apply pick if provided (only to data)
+      if (pick) {
+        data = applyPick(data, pick) as T;
+      }
+
+      // Apply transform if provided (only to data)
+      if (transform) {
+        data = transform(data);
+      }
+
+      // Construct the raw response object
+      const rawResponse: RawResponse<T> = {
+        data,
+        headers: response.headers,
+        status: response.status,
+        statusText: response.statusText,
+      };
+
+      // Call merged onSuccess callback with data and response context
+      if (mergedCallbacks.onSuccess) {
+        await mergedCallbacks.onSuccess(data, {
+          headers: response.headers,
+          status: response.status,
+          statusText: response.statusText,
+          url: finalUrl,
+        });
+      }
+
+      return rawResponse;
+    } catch (error: any) {
+      // Call merged onError callback
+      if (mergedCallbacks.onError) {
+        await mergedCallbacks.onError(error, { url: finalUrl, method, headers });
+      }
+      throw error;
+    } finally {
+      // Call merged onFinish callback
+      if (mergedCallbacks.onFinish) {
+        await mergedCallbacks.onFinish({
+          url: finalUrl,
+          method,
+          headers: { ...getGlobalHeaders(), ...headers },
+        });
+      }
+    }
+  };
+
+  // Use Nuxt's useAsyncData
+  const result = useAsyncData<MaybeTransformedRaw<T, ApiAsyncDataRawOptions<T>>>(key, fetchFn, {
+    immediate,
+    lazy,
+    server,
+    dedupe,
+    watch: watchSources.length > 0 ? watchSources : undefined,
+  });
+
+  return result;
+}

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

@@ -0,0 +1,250 @@
+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 useAsyncData composable function
+ */
+export function generateComposableFile(
+  method: MethodInfo,
+  apiImportPath: string,
+  options?: GenerateOptions
+): string {
+  const header = generateFileHeader();
+  const imports = generateImports(method, apiImportPath, false);
+  const functionBody = generateFunctionBody(method, false, options);
+
+  return `${header}${imports}\n\n${functionBody}\n`;
+}
+
+/**
+ * Generate a useAsyncData composable function (Raw version with headers)
+ */
+export function generateRawComposableFile(
+  method: MethodInfo,
+  apiImportPath: string,
+  options?: GenerateOptions
+): string {
+  const header = generateFileHeader();
+  const imports = generateImports(method, apiImportPath, true);
+  const functionBody = generateFunctionBody(method, true, 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, isRaw: boolean): 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 (normal or raw)
+  if (isRaw) {
+    imports += `import { useApiAsyncDataRaw, type ApiAsyncDataRawOptions, type RawResponse } from '../runtime/useApiAsyncDataRaw';`;
+  } else {
+    imports += `import { useApiAsyncData, type ApiAsyncDataOptions } from '../runtime/useApiAsyncData';`;
+  }
+
+  return imports;
+}
+
+/**
+ * Generate the composable function body
+ */
+function generateFunctionBody(
+  method: MethodInfo,
+  isRaw: boolean,
+  generateOptions?: GenerateOptions
+): string {
+  const hasParams = !!method.requestType;
+  const paramsArg = hasParams ? `params: MaybeRef<${method.requestType}>` : '';
+
+  // Determine the options type based on isRaw
+  const optionsType = isRaw
+    ? `ApiAsyncDataRawOptions<${method.responseType}>`
+    : `ApiAsyncDataOptions<${method.responseType}>`;
+  const optionsArg = `options?: ${optionsType}`;
+  const args = hasParams ? `${paramsArg}, ${optionsArg}` : optionsArg;
+
+  // Determine the response type generic
+  const responseTypeGeneric = method.responseType !== 'void' ? `<${method.responseType}>` : '';
+
+  // Generate unique key for useAsyncData
+  const composableName =
+    isRaw && method.rawMethodName
+      ? `useAsyncData${method.rawMethodName.replace(/Raw$/, '')}Raw`
+      : method.composableName.replace(/^useFetch/, 'useAsyncData');
+
+  const key = `'${composableName}'`;
+
+  const url = generateUrl(method);
+  const fetchOptions = generateFetchOptions(method, generateOptions);
+
+  const description = method.description ? `/**\n * ${method.description}\n */\n` : '';
+
+  // Choose the correct wrapper function
+  const wrapperFunction = isRaw ? 'useApiAsyncDataRaw' : 'useApiAsyncData';
+
+  const pInit = hasParams ? `\n  const p = isRef(params) ? params : shallowRef(params)` : '';
+
+  return `${description}export const ${composableName} = (${args}) => {${pInit}
+  return ${wrapperFunction}${responseTypeGeneric}(${key}, ${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 (renamed to 'params' for $fetch)
+  if (method.hasQueryParams) {
+    if (method.paramsShape === 'nested') {
+      options.push(`params: computed(() => p.value.query)`);
+    } else if (method.queryParams.length > 0) {
+      const queryObj = method.queryParams
+        .map((param) => `${param}: p.value.${param}`)
+        .join(',\n      ');
+      options.push(`params: 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-async-data/types.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export all types from shared types
+ */
+export * from '../shared/types.js';