nuxt-openapi-hyperfetch 0.1.0-alpha.1

package/dist/generators/shared/parsers/heyapi-parser.d.ts

@@ -0,0 +1,11 @@
+import type { ApiClassInfo } from '../types.js';
+/**
+ * Get Hey API generated files from the output directory.
+ * Returns the sdk.gen.ts path — the single entry point for all operations.
+ */
+export declare function getApiFiles(inputDir: string): string[];
+/**
+ * Parse Hey API generated files and return all operations as ApiClassInfo.
+ * Reads both sdk.gen.ts (for HTTP method + description) and types.gen.ts (for param/response types).
+ */
+export declare function parseApiFile(sdkFilePath: string): ApiClassInfo;

package/dist/generators/shared/parsers/heyapi-parser.js

@@ -0,0 +1,248 @@
+import { Project, SyntaxKind } from 'ts-morph';
+import * as path from 'path';
+import { existsSync, readFileSync } from 'node:fs';
+import { pascalCase } from 'change-case';
+import { p } from '../../../cli/logger.js';
+/**
+ * Get Hey API generated files from the output directory.
+ * Returns the sdk.gen.ts path — the single entry point for all operations.
+ */
+export function getApiFiles(inputDir) {
+    const sdkFile = path.join(inputDir, 'sdk.gen.ts');
+    if (!existsSync(sdkFile)) {
+        throw new Error(`Hey API output not found: ${sdkFile}\nMake sure to run @hey-api/openapi-ts before generating composables.`);
+    }
+    return [sdkFile];
+}
+/**
+ * Parse Hey API generated files and return all operations as ApiClassInfo.
+ * Reads both sdk.gen.ts (for HTTP method + description) and types.gen.ts (for param/response types).
+ */
+export function parseApiFile(sdkFilePath) {
+    const inputDir = path.dirname(sdkFilePath);
+    const typesFilePath = path.join(inputDir, 'types.gen.ts');
+    if (!existsSync(typesFilePath)) {
+        throw new Error(`types.gen.ts not found in ${inputDir}`);
+    }
+    // Parse types.gen.ts with ts-morph to read type declarations
+    const project = new Project({ skipAddingFilesFromTsConfig: true });
+    const typesFile = project.addSourceFileAtPath(typesFilePath);
+    // Build operation info map from sdk.gen.ts using text parsing
+    const sdkText = readFileSync(sdkFilePath, 'utf-8');
+    const opMap = buildOperationMap(sdkText);
+    const methodInfos = [];
+    // Iterate over all *Data type aliases — each represents one API operation
+    for (const typeAlias of typesFile.getTypeAliases()) {
+        const name = typeAlias.getName();
+        // Skip non-operation types (ClientOptions, etc.)
+        if (!name.endsWith('Data') || name === 'ClientOptions') {
+            continue;
+        }
+        const baseName = name.slice(0, -4); // 'AddPetData' → 'AddPet'
+        const opName = baseName.charAt(0).toLowerCase() + baseName.slice(1); // 'addPet'
+        try {
+            const methodInfo = extractMethodInfo(typeAlias, typesFile, baseName, opName, opMap);
+            if (methodInfo) {
+                methodInfos.push(methodInfo);
+            }
+        }
+        catch (error) {
+            p.log.warn(`Could not parse Hey API operation "${opName}": ${String(error)}`);
+        }
+    }
+    return { className: 'Api', methods: methodInfos };
+}
+/**
+ * Build a map of operation name → SdkOpInfo by text-parsing sdk.gen.ts.
+ * Extracts HTTP method, JSDoc description, and Content-Type header.
+ */
+function buildOperationMap(sdkText) {
+    const map = new Map();
+    const lines = sdkText.split('\n');
+    let jsDocLines = [];
+    let inJsDoc = false;
+    let pendingDescription;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed === '/**') {
+            inJsDoc = true;
+            jsDocLines = [line];
+            continue;
+        }
+        if (inJsDoc) {
+            jsDocLines.push(line);
+            if (trimmed === '*/') {
+                inJsDoc = false;
+                pendingDescription = parseJsDocDescription(jsDocLines.join('\n'));
+            }
+            continue;
+        }
+        // Match: export const funcName =
+        const funcMatch = line.match(/^export const (\w+) =/);
+        if (funcMatch) {
+            const funcName = funcMatch[1];
+            // Scan ahead a few lines to find the HTTP method call
+            const snippet = lines.slice(i, Math.min(i + 8, lines.length)).join('\n');
+            const methodMatch = snippet.match(/\.(post|get|put|delete|patch)</i);
+            const httpMethod = methodMatch ? methodMatch[1].toUpperCase() : 'GET';
+            // Detect Content-Type header
+            const headers = {};
+            if (snippet.includes("'Content-Type': 'application/json'")) {
+                headers['Content-Type'] = 'application/json';
+            }
+            else if (snippet.includes("'Content-Type': 'application/octet-stream'")) {
+                headers['Content-Type'] = 'application/octet-stream';
+            }
+            map.set(funcName, { httpMethod, description: pendingDescription, headers });
+            pendingDescription = undefined;
+            jsDocLines = [];
+        }
+    }
+    return map;
+}
+/**
+ * Extract the first meaningful line from a JSDoc comment block.
+ */
+function parseJsDocDescription(jsDoc) {
+    for (const line of jsDoc.split('\n')) {
+        const cleaned = line.replace(/^\s*[/*]+\s?/, '').trim();
+        if (cleaned && !cleaned.startsWith('@')) {
+            return cleaned;
+        }
+    }
+    return undefined;
+}
+/**
+ * Convert a *Data TypeAliasDeclaration into a MethodInfo object.
+ */
+function extractMethodInfo(typeAlias, typesFile, baseName, opName, opMap) {
+    const dataTypeName = typeAlias.getName(); // e.g. 'AddPetData'
+    const opInfo = opMap.get(opName);
+    if (!opInfo) {
+        p.log.warn(`Operation "${opName}" not found in sdk.gen.ts — skipping`);
+        return null;
+    }
+    const typeNode = typeAlias.getTypeNode();
+    if (!typeNode || typeNode.getKind() !== SyntaxKind.TypeLiteral) {
+        return null;
+    }
+    const typeLiteral = typeNode.asKind(SyntaxKind.TypeLiteral);
+    if (!typeLiteral) {
+        return null;
+    }
+    let urlPath = '';
+    let hasBody = false;
+    let pathParams = [];
+    let queryParams = [];
+    let hasQueryParams = false;
+    for (const member of typeLiteral.getMembers()) {
+        if (member.getKind() !== SyntaxKind.PropertySignature) {
+            continue;
+        }
+        const propSig = member.asKind(SyntaxKind.PropertySignature);
+        if (!propSig) {
+            continue;
+        }
+        const propName = propSig.getName();
+        const typeNodeText = propSig.getTypeNode()?.getText() ?? '';
+        switch (propName) {
+            case 'url':
+                // String literal type: "'/pet'" → strip quotes → '/pet'
+                urlPath = typeNodeText.replace(/^['"`]|['"`]$/g, '');
+                break;
+            case 'body':
+                if (typeNodeText !== 'never') {
+                    hasBody = true;
+                }
+                break;
+            case 'path': {
+                if (typeNodeText !== 'never') {
+                    const pathTypeNode = propSig.getTypeNode();
+                    if (pathTypeNode && pathTypeNode.getKind() === SyntaxKind.TypeLiteral) {
+                        const innerLiteral = pathTypeNode.asKind(SyntaxKind.TypeLiteral);
+                        if (innerLiteral) {
+                            pathParams = innerLiteral
+                                .getMembers()
+                                .filter((m) => m.getKind() === SyntaxKind.PropertySignature)
+                                .map((m) => m.asKind(SyntaxKind.PropertySignature).getName());
+                        }
+                    }
+                }
+                break;
+            }
+            case 'query': {
+                if (typeNodeText !== 'never') {
+                    const queryTypeNode = propSig.getTypeNode();
+                    if (queryTypeNode && queryTypeNode.getKind() === SyntaxKind.TypeLiteral) {
+                        const innerLiteral = queryTypeNode.asKind(SyntaxKind.TypeLiteral);
+                        if (innerLiteral) {
+                            queryParams = innerLiteral
+                                .getMembers()
+                                .filter((m) => m.getKind() === SyntaxKind.PropertySignature)
+                                .map((m) => m.asKind(SyntaxKind.PropertySignature).getName());
+                            hasQueryParams = queryParams.length > 0;
+                        }
+                    }
+                }
+                break;
+            }
+        }
+    }
+    if (!urlPath) {
+        return null;
+    }
+    // Extract response type from the matching *Responses type alias
+    const responsesAlias = typesFile.getTypeAlias(`${baseName}Responses`);
+    const responseType = responsesAlias ? extractResponseType(responsesAlias) : 'void';
+    // Only set requestType if the operation actually requires input params
+    const hasParams = hasBody || pathParams.length > 0 || hasQueryParams;
+    const requestType = hasParams ? dataTypeName : undefined;
+    return {
+        name: opName,
+        composableName: `useFetch${pascalCase(opName)}`,
+        requestType,
+        responseType,
+        httpMethod: opInfo.httpMethod,
+        path: urlPath,
+        hasBody,
+        bodyField: hasBody ? 'body' : undefined,
+        hasQueryParams,
+        queryParams,
+        pathParams,
+        headers: opInfo.headers,
+        description: opInfo.description,
+        hasRawMethod: false,
+        rawMethodName: undefined,
+        paramsShape: 'nested',
+    };
+}
+/**
+ * Extract the success (2xx) response type from a *Responses type alias.
+ * Maps `unknown` to `void` for operations with no meaningful response body.
+ */
+function extractResponseType(responsesAlias) {
+    const typeNode = responsesAlias.getTypeNode();
+    if (!typeNode || typeNode.getKind() !== SyntaxKind.TypeLiteral) {
+        return 'void';
+    }
+    const typeLiteral = typeNode.asKind(SyntaxKind.TypeLiteral);
+    if (!typeLiteral) {
+        return 'void';
+    }
+    for (const member of typeLiteral.getMembers()) {
+        if (member.getKind() !== SyntaxKind.PropertySignature) {
+            continue;
+        }
+        const propSig = member.asKind(SyntaxKind.PropertySignature);
+        if (!propSig) {
+            continue;
+        }
+        const memberName = propSig.getName();
+        if (memberName === '200' || memberName === '201' || memberName === '202') {
+            const typeText = propSig.getTypeNode()?.getText() ?? '';
+            return typeText === 'unknown' || typeText === '' ? 'void' : typeText;
+        }
+    }
+    return 'void';
+}

package/dist/generators/shared/parsers/official-parser.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Official OpenAPI Generator parser (typescript-fetch output)
+ * Re-exports the existing parser — no changes needed here.
+ */
+export * from '../../use-fetch/parser.js';

package/dist/generators/shared/parsers/official-parser.js

@@ -0,0 +1,5 @@
+/**
+ * Official OpenAPI Generator parser (typescript-fetch output)
+ * Re-exports the existing parser — no changes needed here.
+ */
+export * from '../../use-fetch/parser.js';

package/dist/generators/shared/runtime/apiHelpers.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Shared API Helpers - Used by both useFetch and useAsyncData wrappers
+ * This file contains common logic for callbacks, transforms, and global configuration
+ */
+/**
+ * Context provided to onRequest interceptor
+ */
+export interface RequestContext {
+    /** Request URL */
+    url: string;
+    /** HTTP method */
+    method: string;
+    /** Request body (if any) */
+    body?: any;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Query parameters */
+    query?: Record<string, any>;
+}
+/**
+ * Modified context that can be returned from onRequest
+ */
+export interface ModifiedRequestContext {
+    /** Modified request body */
+    body?: any;
+    /** Modified request headers */
+    headers?: Record<string, string>;
+    /** Modified query parameters */
+    query?: Record<string, any>;
+}
+/**
+ * Result context provided to onFinish callback
+ */
+export interface FinishContext<T> {
+    /** Response data (if successful) */
+    data?: T;
+    /** Error (if failed) */
+    error?: any;
+    /** Whether the request was successful */
+    success: boolean;
+}
+/**
+ * Global callbacks configuration
+ * Can be provided via Nuxt plugin: $getGlobalApiCallbacks
+ */
+export interface GlobalCallbacksConfig {
+    /**
+     * Optional URL patterns to match (Opción 3)
+     * Only apply global callbacks to URLs matching these patterns
+     * Supports wildcards: '/api/**', '/api/public/*', etc.
+     * If omitted, callbacks apply to all requests
+     */
+    patterns?: string[];
+    /**
+     * Called before every request matching patterns
+     * Return false to prevent local callback execution (Opción 2)
+     * Return modified context to change request
+     */
+    onRequest?: (context: RequestContext) => void | Promise<void> | ModifiedRequestContext | Promise<ModifiedRequestContext> | boolean | Promise<boolean>;
+    /**
+     * Called when request succeeds
+     * Return false to prevent local callback execution (Opción 2)
+     */
+    onSuccess?: (data: any, context?: any) => void | Promise<void> | boolean | Promise<boolean>;
+    /**
+     * Called when request fails
+     * Return false to prevent local callback execution (Opción 2)
+     */
+    onError?: (error: any, context?: any) => void | Promise<void> | boolean | Promise<boolean>;
+    /**
+     * Called when request finishes (success or error)
+     * Return false to prevent local callback execution (Opción 2)
+     */
+    onFinish?: (context: FinishContext<any>) => void | Promise<void> | boolean | Promise<boolean>;
+}
+/**
+ * Type for skipGlobalCallbacks option (Opción 1)
+ * - true: skip all global callbacks
+ * - array: skip specific callbacks by name
+ */
+export type SkipGlobalCallbacks = boolean | Array<'onRequest' | 'onSuccess' | 'onError' | 'onFinish'>;
+/**
+ * Base options for API requests with lifecycle callbacks
+ * This is extended by specific wrapper options (useFetch, useAsyncData)
+ */
+export interface ApiRequestOptions<T = any> {
+    /**
+     * Called before the request is sent - can be used as an interceptor
+     * Return modified body/headers to transform the request
+     */
+    onRequest?: (context: RequestContext) => void | Promise<void> | ModifiedRequestContext | Promise<ModifiedRequestContext>;
+    /** Called when the request succeeds with data (after transform/pick if provided) */
+    onSuccess?: (data: any) => void | Promise<void>;
+    /** Called when the request fails with an error */
+    onError?: (error: any) => void | Promise<void>;
+    /** Called when the request finishes (success or error) with result context */
+    onFinish?: (context: FinishContext<any>) => void | Promise<void>;
+    /**
+     * Skip global callbacks for this specific request (Opción 1)
+     * - true: skip all global callbacks
+     * - ['onSuccess', 'onError']: skip specific callbacks
+     * - false/undefined: use global callbacks (default)
+     * @example
+     * skipGlobalCallbacks: true // Skip all global callbacks
+     * skipGlobalCallbacks: ['onSuccess'] // Skip only global onSuccess
+     */
+    skipGlobalCallbacks?: SkipGlobalCallbacks;
+    /**
+     * Transform the response data
+     * @example
+     * transform: (pet) => ({ displayName: pet.name, isAvailable: pet.status === 'available' })
+     */
+    transform?: (data: T) => any;
+    /**
+     * Pick specific keys from the response (applied before transform)
+     * Supports dot notation for nested paths
+     * @example
+     * pick: ['id', 'name'] as const
+     * pick: ['person.name', 'person.email', 'status']
+     */
+    pick?: ReadonlyArray<string>;
+}
+/**
+ * Helper function to apply request modifications from onRequest interceptor
+ */
+export declare function applyRequestModifications(options: Record<string, any>, modifications: ModifiedRequestContext): void;
+/**
+ * Helper function to pick specific keys from an object
+ * Supports dot notation for nested paths (e.g., 'person.name')
+ */
+export declare function applyPick<T>(data: T, paths: ReadonlyArray<string>): any;
+/**
+ * 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 declare function getGlobalHeaders(): Record<string, string>;
+/**
+ * Helper function to get global callbacks from user configuration
+ * Uses Nuxt plugin provide: plugins/api-callbacks.ts with $getGlobalApiCallbacks
+ */
+export declare function getGlobalCallbacks(): GlobalCallbacksConfig;
+/**
+ * Check if a global callback should be applied to a specific request
+ * Implements Opción 1 (skipGlobalCallbacks) and Opción 3 (pattern matching)
+ */
+export declare function shouldApplyGlobalCallback(url: string, callbackName: 'onRequest' | 'onSuccess' | 'onError' | 'onFinish', patterns?: string[], skipConfig?: SkipGlobalCallbacks): boolean;
+/**
+ * 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 declare function mergeCallbacks(url: string, localCallbacks: {
+    onRequest?: Function;
+    onSuccess?: Function;
+    onError?: Function;
+    onFinish?: Function;
+}, skipConfig?: SkipGlobalCallbacks): {
+    /**
+     * Merged onRequest callback
+     * Executes global first, then local
+     * Global can return modifications or false to cancel local
+     */
+    onRequest: (ctx: RequestContext) => Promise<any>;
+    /**
+     * Merged onSuccess callback
+     * Executes global first, then local (if global doesn't return false)
+     */
+    onSuccess: (data: any, context?: any) => Promise<void>;
+    /**
+     * Merged onError callback
+     * Executes global first, then local (if global doesn't return false)
+     */
+    onError: (error: any, context?: any) => Promise<void>;
+    /**
+     * Merged onFinish callback
+     * Executes global first, then local (if global doesn't return false)
+     */
+    onFinish: (context: any) => Promise<void>;
+};