nuxt-openapi-hyperfetch 0.3.8-beta → 1.0.0

package/dist/generators/connectors/templates.js

@@ -0,0 +1,376 @@
+import { pascalCase, kebabCase } from 'change-case';
+// ─── File header ──────────────────────────────────────────────────────────────
+function generateFileHeader() {
+    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 */
+`;
+}
+// ─── Naming helpers ───────────────────────────────────────────────────────────
+function toAsyncDataName(operationId) {
+    return `useAsyncData${pascalCase(operationId)}`;
+}
+// ─── URL builder ─────────────────────────────────────────────────────────────
+/**
+ * Convert an OpenAPI path template into a JS arrow function string.
+ * '/pet/{petId}' + 'petId' → '(id: string | number) => `/pet/${id}`'
+ */
+function buildUrlFn(path, pathParam) {
+    if (!pathParam) {
+        return `'${path}'`;
+    }
+    const urlTemplate = path.replace(`{${pathParam}}`, '${id}');
+    return `(id: string | number) => \`${urlTemplate}\``;
+}
+// ─── Section builders ─────────────────────────────────────────────────────────
+function buildImports(resource, composablesRelDir, sdkRelDir, runtimeRelDir) {
+    const lines = [];
+    // zod — always needed for schema declarations
+    lines.push(`import { z } from 'zod';`);
+    lines.push('');
+    // connector-types — return type interfaces
+    const typeImports = ['GetAllConnectorReturn'];
+    if (resource.detailEndpoint) {
+        typeImports.push('GetConnectorReturn');
+    }
+    if (resource.createEndpoint) {
+        typeImports.push('CreateConnectorReturn');
+    }
+    if (resource.updateEndpoint) {
+        typeImports.push('UpdateConnectorReturn');
+    }
+    if (resource.deleteEndpoint) {
+        typeImports.push('DeleteConnectorReturn');
+    }
+    lines.push(`import type { ${typeImports.join(', ')} } from '${runtimeRelDir}/connector-types';`);
+    lines.push('');
+    // SDK model type -- import using the inferred item type name (from $ref) if available
+    const modelTypeName = resource.itemTypeName;
+    if (modelTypeName) {
+        lines.push(`import type { ${modelTypeName} } from '${sdkRelDir}';`);
+        lines.push('');
+    }
+    // SDK request type -- only when the list endpoint actually has query parameters
+    if (resource.listEndpoint && resource.listEndpoint.hasQueryParams) {
+        const requestTypeName = `${pascalCase(resource.listEndpoint.operationId)}Request`;
+        lines.push(`import type { ${requestTypeName} } from '${sdkRelDir}';`);
+        lines.push('');
+    }
+    // runtime connectors
+    const runtimeImports = ['useGetAllConnector'];
+    if (resource.detailEndpoint) {
+        runtimeImports.push('useGetConnector');
+    }
+    if (resource.createEndpoint) {
+        runtimeImports.push('useCreateConnector');
+    }
+    if (resource.updateEndpoint) {
+        runtimeImports.push('useUpdateConnector');
+    }
+    if (resource.deleteEndpoint) {
+        runtimeImports.push('useDeleteConnector');
+    }
+    for (const helper of runtimeImports) {
+        lines.push(`import { ${helper} } from '${runtimeRelDir}/${helper}';`);
+    }
+    lines.push('');
+    // useAsyncData composable — only needed for getAll (list endpoint)
+    if (resource.listEndpoint) {
+        const name = toAsyncDataName(resource.listEndpoint.operationId);
+        lines.push(`import { ${name} } from '${composablesRelDir}/${name}';`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function buildZodSchemas(resource) {
+    const lines = [];
+    const pascal = pascalCase(resource.name);
+    if (resource.zodSchemas.create) {
+        lines.push(`const ${pascal}CreateSchema = ${resource.zodSchemas.create};`);
+        lines.push('');
+    }
+    if (resource.zodSchemas.update) {
+        lines.push(`const ${pascal}UpdateSchema = ${resource.zodSchemas.update};`);
+        lines.push('');
+    }
+    if (resource.zodSchemas.create) {
+        lines.push(`type ${pascal}CreateInput = z.infer<typeof ${pascal}CreateSchema>;`);
+    }
+    if (resource.zodSchemas.update) {
+        lines.push(`type ${pascal}UpdateInput = z.infer<typeof ${pascal}UpdateSchema>;`);
+    }
+    return lines.join('\n');
+}
+function buildColumns(resource) {
+    if (!resource.columns || resource.columns.length === 0) {
+        return '';
+    }
+    const camel = resource.composableName
+        .replace(/^use/, '')
+        .replace(/Connector$/, '')
+        .replace(/^./, (c) => c.toLowerCase());
+    const varName = `${camel}Columns`;
+    const entries = resource.columns
+        .map((col) => `  { key: '${col.key}', label: '${col.label}', type: '${col.type}' }`)
+        .join(',\n');
+    return `const ${varName} = [\n${entries},\n];`;
+}
+function buildFields(resource) {
+    const fields = resource.formFields?.create ?? resource.formFields?.update;
+    if (!fields || fields.length === 0) {
+        return '';
+    }
+    const camel = resource.composableName
+        .replace(/^use/, '')
+        .replace(/Connector$/, '')
+        .replace(/^./, (c) => c.toLowerCase());
+    const varName = `${camel}Fields`;
+    const entries = fields
+        .map((f) => {
+        const opts = f.options
+            ? `, options: [${f.options.map((o) => `{ label: '${o.label}', value: '${o.value}' }`).join(', ')}]`
+            : '';
+        return `  { key: '${f.key}', label: '${f.label}', type: '${f.type}', required: ${f.required}${opts} }`;
+    })
+        .join(',\n');
+    return `const ${varName} = [\n${entries},\n];`;
+}
+function buildOptionsInterface(resource) {
+    const typeName = `${pascalCase(resource.composableName)}Options`;
+    const hasColumns = resource.columns && resource.columns.length > 0;
+    const fields = [];
+    if (resource.listEndpoint && hasColumns) {
+        fields.push(`  columnLabels?: Record<string, string>;`);
+        fields.push(`  columnLabel?: (key: string) => string;`);
+    }
+    if (resource.createEndpoint && resource.zodSchemas.create) {
+        const pascal = pascalCase(resource.name);
+        fields.push(`  createSchema?: z.ZodTypeAny | ((base: typeof ${pascal}CreateSchema) => z.ZodTypeAny);`);
+    }
+    if (resource.updateEndpoint && resource.zodSchemas.update) {
+        const pascal = pascalCase(resource.name);
+        fields.push(`  updateSchema?: z.ZodTypeAny | ((base: typeof ${pascal}UpdateSchema) => z.ZodTypeAny);`);
+    }
+    if (resource.createEndpoint || resource.updateEndpoint || resource.deleteEndpoint) {
+        fields.push(`  onRequest?: (ctx: any) => void | Promise<void> | Record<string, any>;`);
+        fields.push(`  onSuccess?: (data: any, ctx: { operation: string }) => void;`);
+        fields.push(`  onError?: (err: any, ctx: { operation: string }) => void;`);
+        fields.push(`  onFinish?: (ctx: any) => void;`);
+        fields.push(`  skipGlobalCallbacks?: boolean | Array<'onRequest' | 'onSuccess' | 'onError' | 'onFinish'>;`);
+    }
+    fields.push(`  baseURL?: string;`);
+    if (fields.length === 1) {
+        // only baseURL — minimal interface
+        return [`interface ${typeName} {`, ...fields, `}`].join('\n');
+    }
+    return [`interface ${typeName} {`, ...fields, `}`].join('\n');
+}
+function buildReturnType(resource) {
+    const pascal = resource.itemTypeName ?? pascalCase(resource.name);
+    const localPascal = pascalCase(resource.name);
+    const typeName = `${pascalCase(resource.composableName)}Return`;
+    const fields = [];
+    fields.push(`  getAll: GetAllConnectorReturn<${pascal}>;`);
+    if (resource.detailEndpoint) {
+        fields.push(`  get: GetConnectorReturn<${pascal}>;`);
+    }
+    if (resource.createEndpoint) {
+        const inputType = resource.zodSchemas.create
+            ? `${localPascal}CreateInput`
+            : `Record<string, unknown>`;
+        fields.push(`  create: CreateConnectorReturn<${inputType}>;`);
+    }
+    if (resource.updateEndpoint) {
+        const inputType = resource.zodSchemas.update
+            ? `${localPascal}UpdateInput`
+            : `Record<string, unknown>`;
+        fields.push(`  update: UpdateConnectorReturn<${inputType}>;`);
+    }
+    if (resource.deleteEndpoint) {
+        fields.push(`  del: DeleteConnectorReturn<${pascal}>;`);
+    }
+    return [`type ${typeName} = {`, ...fields, `};`].join('\n');
+}
+function buildFunctionBody(resource) {
+    const pascal = resource.itemTypeName ?? pascalCase(resource.name);
+    const localPascal = pascalCase(resource.name);
+    const hasColumns = resource.columns && resource.columns.length > 0;
+    const hasFields = !!(resource.formFields?.create?.length || resource.formFields?.update?.length);
+    const camel = resource.composableName
+        .replace(/^use/, '')
+        .replace(/Connector$/, '')
+        .replace(/^./, (c) => c.toLowerCase());
+    const columnsVar = `${camel}Columns`;
+    const fieldsVar = `${camel}Fields`;
+    const optionsTypeName = `${pascalCase(resource.composableName)}Options`;
+    const returnTypeName = `${pascalCase(resource.composableName)}Return`;
+    const hasMutations = !!(resource.createEndpoint ||
+        resource.updateEndpoint ||
+        resource.deleteEndpoint);
+    // Options destructure
+    const optionKeys = [];
+    if (resource.listEndpoint && hasColumns) {
+        optionKeys.push('columnLabels', 'columnLabel');
+    }
+    if (resource.createEndpoint && resource.zodSchemas.create) {
+        optionKeys.push('createSchema');
+    }
+    if (resource.updateEndpoint && resource.zodSchemas.update) {
+        optionKeys.push('updateSchema');
+    }
+    if (hasMutations) {
+        optionKeys.push('onRequest', 'onSuccess', 'onError', 'onFinish', 'skipGlobalCallbacks');
+    }
+    optionKeys.push('baseURL');
+    const optionsDestructure = `  const { ${optionKeys.join(', ')} } = options;\n`;
+    const lines = [];
+    // ── Function signature ─────────────────────────────────────────────────────
+    if (resource.listEndpoint) {
+        const hasQueryParams = resource.listEndpoint.hasQueryParams;
+        const listRequestTypeName = hasQueryParams
+            ? `${pascalCase(resource.listEndpoint.operationId)}Request`
+            : `Record<string, never>`;
+        lines.push(`export function ${resource.composableName}(source: () => unknown, options?: ${optionsTypeName}): ${returnTypeName};`, `export function ${resource.composableName}(params?: ${listRequestTypeName}, options?: ${optionsTypeName}): ${returnTypeName};`, `export function ${resource.composableName}(paramsOrSource?: ${listRequestTypeName} | (() => unknown), options: ${optionsTypeName} = {}): ${returnTypeName} {`);
+    }
+    else {
+        lines.push(`export function ${resource.composableName}(options: ${optionsTypeName} = {}): ${returnTypeName} {`);
+        lines.push(`  const paramsOrSource = undefined;`);
+    }
+    lines.push(optionsDestructure.trimEnd());
+    lines.push('');
+    // ── getAll ─────────────────────────────────────────────────────────────────
+    if (resource.listEndpoint) {
+        const fn = toAsyncDataName(resource.listEndpoint.operationId);
+        const hasQueryParams = resource.listEndpoint.hasQueryParams;
+        const listRequestTypeName = hasQueryParams
+            ? `${pascalCase(resource.listEndpoint.operationId)}Request`
+            : `Record<string, never>`;
+        const columnsArg = hasColumns ? `columns: ${columnsVar}` : '';
+        const labelArgs = hasColumns ? 'columnLabels, columnLabel' : '';
+        const allArgs = [columnsArg, labelArgs].filter(Boolean).join(', ');
+        const opts = allArgs ? `{ ${allArgs} }` : '{}';
+        lines.push(`  const isFactory = typeof paramsOrSource === 'function';`, `  const listFactory = isFactory`, `    ? (paramsOrSource as () => unknown)`, `    : () => ${fn}((paramsOrSource ?? {}) as ${listRequestTypeName});`, `  const getAll = useGetAllConnector(listFactory, ${opts}) as unknown as GetAllConnectorReturn<${pascal}>;`);
+    }
+    else {
+        lines.push(`  const getAll = useGetAllConnector(() => ({}), {}) as unknown as GetAllConnectorReturn<${pascal}>;`);
+    }
+    lines.push('');
+    // ── get ────────────────────────────────────────────────────────────────────
+    if (resource.detailEndpoint) {
+        const pathParam = resource.detailEndpoint.pathParams[0] ?? 'id';
+        const urlFn = buildUrlFn(resource.detailEndpoint.path, pathParam);
+        const fieldsArg = hasFields ? `fields: ${fieldsVar}` : '';
+        const args = [
+            'baseURL',
+            'onRequest',
+            'onSuccess',
+            'onError',
+            'onFinish',
+            'skipGlobalCallbacks',
+            fieldsArg,
+        ]
+            .filter(Boolean)
+            .join(', ');
+        lines.push(`  const get = useGetConnector(${urlFn}, { ${args} }) as unknown as GetConnectorReturn<${pascal}>;`);
+        lines.push('');
+    }
+    // ── create ─────────────────────────────────────────────────────────────────
+    if (resource.createEndpoint) {
+        const inputType = resource.zodSchemas.create
+            ? `${localPascal}CreateInput`
+            : `Record<string, unknown>`;
+        const schemaArg = resource.zodSchemas.create
+            ? `schema: ${localPascal}CreateSchema, schemaOverride: createSchema,`
+            : '';
+        const fieldsArg = hasFields ? `fields: ${fieldsVar},` : '';
+        const method = resource.createEndpoint.method;
+        lines.push(`  const create = useCreateConnector('${resource.createEndpoint.path}', {`, `    method: '${method}',`, ...(schemaArg ? [`    ${schemaArg}`] : []), ...(fieldsArg ? [`    ${fieldsArg}`] : []), `    onRequest, onSuccess, onError, onFinish,`, `    baseURL, skipGlobalCallbacks,`, `  }) as unknown as CreateConnectorReturn<${inputType}>;`);
+        lines.push('');
+    }
+    // ── update ─────────────────────────────────────────────────────────────────
+    if (resource.updateEndpoint) {
+        const inputType = resource.zodSchemas.update
+            ? `${localPascal}UpdateInput`
+            : `Record<string, unknown>`;
+        const pathParam = resource.updateEndpoint.pathParams[0]; // undefined when ID comes from body
+        const urlFn = buildUrlFn(resource.updateEndpoint.path, pathParam);
+        const schemaArg = resource.zodSchemas.update
+            ? `schema: ${localPascal}UpdateSchema, schemaOverride: updateSchema,`
+            : '';
+        const fieldsArg = hasFields ? `fields: ${fieldsVar},` : '';
+        const method = resource.updateEndpoint.method;
+        lines.push(`  const update = useUpdateConnector(${urlFn}, {`, `    method: '${method}',`, ...(schemaArg ? [`    ${schemaArg}`] : []), ...(fieldsArg ? [`    ${fieldsArg}`] : []), `    onRequest, onSuccess, onError, onFinish,`, `    baseURL, skipGlobalCallbacks,`, `  }) as unknown as UpdateConnectorReturn<${inputType}>;`);
+        lines.push('');
+    }
+    // ── del ────────────────────────────────────────────────────────────────────
+    if (resource.deleteEndpoint) {
+        const pathParam = resource.deleteEndpoint.pathParams[0];
+        const urlFn = buildUrlFn(resource.deleteEndpoint.path, pathParam);
+        // idFn: extract the ID from the staged item — try the path param name first, then .id
+        const idFn = pathParam
+            ? `(item: any) => item?.${pathParam} ?? item?.id ?? item`
+            : `(item: any) => item?.id ?? item`;
+        lines.push(`  const del = useDeleteConnector(`, `    ${idFn},`, `    ${urlFn},`, `    { onRequest, onSuccess, onError, onFinish, baseURL, skipGlobalCallbacks }`, `  ) as unknown as DeleteConnectorReturn<${pascal}>;`);
+        lines.push('');
+    }
+    // ── return ─────────────────────────────────────────────────────────────────
+    const returnKeys = ['getAll'];
+    if (resource.detailEndpoint) {
+        returnKeys.push('get');
+    }
+    if (resource.createEndpoint) {
+        returnKeys.push('create');
+    }
+    if (resource.updateEndpoint) {
+        returnKeys.push('update');
+    }
+    if (resource.deleteEndpoint) {
+        returnKeys.push('del');
+    }
+    lines.push(`  return { ${returnKeys.join(', ')} } as ${returnTypeName};`);
+    lines.push(`}`);
+    return lines.join('\n');
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+export function generateConnectorFile(resource, composablesRelDir, sdkRelDir = '../..', runtimeRelDir = '../../runtime') {
+    const header = generateFileHeader();
+    const imports = buildImports(resource, composablesRelDir, sdkRelDir, runtimeRelDir);
+    const schemas = buildZodSchemas(resource);
+    const columns = buildColumns(resource);
+    const fields = buildFields(resource);
+    const optionsInterface = buildOptionsInterface(resource);
+    const returnType = buildReturnType(resource);
+    const fn = buildFunctionBody(resource);
+    const parts = [header, imports];
+    if (schemas.trim()) {
+        parts.push(schemas);
+    }
+    if (columns.trim()) {
+        parts.push(columns);
+    }
+    if (fields.trim()) {
+        parts.push(fields);
+    }
+    parts.push(optionsInterface);
+    parts.push(returnType);
+    parts.push(fn);
+    return parts.join('\n') + '\n';
+}
+export function connectorFileName(composableName) {
+    return `${kebabCase(composableName)}.ts`;
+}
+export function generateConnectorIndexFile(composableNames) {
+    const header = generateFileHeader();
+    const exports = composableNames
+        .map((name) => `export { ${name} } from './${kebabCase(name)}';`)
+        .join('\n');
+    return `${header}${exports}\n`;
+}

package/dist/generators/connectors/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Types for the new Connector Generator.
+ *
+ * The Connector Generator reads the ResourceMap produced by the Schema Analyzer
+ * and writes one `use{Resource}Connector.ts` file per resource using $fetch for mutations.
+ */
+export interface ConnectorGeneratorOptions {
+    /** Absolute or relative path to the OpenAPI YAML/JSON spec */
+    inputSpec: string;
+    /** Directory where connector files will be written. E.g. ./composables/connectors */
+    outputDir: string;
+    /**
+     * Directory where the useAsyncData composables live (only used for getAll/list),
+     * expressed as a path relative to outputDir. Defaults to '../use-async-data/composables'.
+     */
+    composablesRelDir?: string;
+    /**
+     * Directory where runtime helpers will be copied to, expressed relative to
+     * outputDir. Defaults to '../runtime'.
+     */
+    runtimeRelDir?: string;
+    /**
+     * Base URL for API requests. If not provided, connectors will read from
+     * useRuntimeConfig().public.apiBaseUrl at runtime.
+     */
+    baseUrl?: string;
+}
+export interface ConnectorFileInfo {
+    /** PascalCase resource name. E.g. 'Pet' */
+    resourceName: string;
+    /** Generated composable function name. E.g. 'usePetsConnector' */
+    composableName: string;
+    /** Output filename (kebab-case). E.g. 'use-pets-connector.ts' */
+    fileName: string;
+    /** Formatted TypeScript source ready to be written to disk */
+    content: string;
+}

package/dist/generators/connectors/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for the new Connector Generator.
+ *
+ * The Connector Generator reads the ResourceMap produced by the Schema Analyzer
+ * and writes one `use{Resource}Connector.ts` file per resource using $fetch for mutations.
+ */
+export {};

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

@@ -53,8 +53,9 @@ export function useDeleteConnector(composableFn, options = {}) {
         try {
             // Pass the full target item; the generated composable extracts the id it needs
             const composable = composableFn(target.value);
-            if (composable.execute) {
-                await composable.execute();
+            // refresh() bypasses Nuxt SSR payload cache, forcing a real network request
+            if (composable.refresh) {
+                await composable.refresh();
             }
             const err = composable.error?.value;
             if (err) {
@@ -66,6 +67,7 @@ export function useDeleteConnector(composableFn, options = {}) {
             onSuccess.value?.(deletedItem);
         }
         catch (err) {
+            console.error('[useDeleteConnector] confirm error:', err);
             error.value = err;
             onError.value?.(err);
         }

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

@@ -10,5 +10,4 @@ export declare function useDetailConnector(composableFn: any, options?: {}): {
     load: (id: any) => Promise<void>;
     clear: () => void;
     _composable: any;
-    _idRef: any;
 };

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

@@ -9,39 +9,29 @@
  *
  * Copied to the user's project alongside the generated connectors.
  */
-import { ref, computed } from 'vue';
+import { computed } from 'vue';
 /**
  * @param composableFn  The generated useAsyncData composable, e.g. useAsyncDataGetPetById
  * @param options       Optional configuration
  */
 export function useDetailConnector(composableFn, options = {}) {
     const { fields = [] } = options;
-    // ── Reactive ID ref passed to the composable wrapper ──────────────────────
-    // The generated connector wraps the composable like:
-    //   (idRef, opts) => useAsyncDataGetPetById(computed(() => ({ petId: idRef.value })), opts)
-    // This lets us update idRef.value in load(id) so refresh() picks up the new value.
-    const idRef = ref(null);
-    // ── Execute the underlying composable ──────────────────────────────────────
-    // watch: false + immediate: false + lazy: true prevent any fetch until
-    // load(id) is called explicitly. The URL is only evaluated on refresh().
-    const composable = composableFn(idRef, {
-        watch: false,
-        immediate: false,
-        lazy: true,
-    });
+    // ── Execute the underlying composable lazily (only when load(id) is called) ─
+    // composableFn is a generated wrapper: (id) => { _idRef.value = id; return _composable }
+    // Calling it with null initializes the composable in setup context (safe — p.value is { param: null })
+    // Calling it in load(id) updates the ref before refresh()
+    const composable = composableFn(null);
     // ── Derived state ──────────────────────────────────────────────────────────
     const item = computed(() => composable.data?.value ?? null);
     const loading = computed(() => composable.pending?.value ?? false);
     const error = computed(() => composable.error?.value ?? null);
     // ── Actions ────────────────────────────────────────────────────────────────
     async function load(id) {
-        idRef.value = id;
+        composableFn(id); // updates the generated _detailIdRef
         await composable.refresh?.();
     }
     function clear() {
-        idRef.value = null;
-        if (composable.data)
-            composable.data.value = null;
+        composableFn(null);
     }
     return {
         // State
@@ -52,8 +42,7 @@ export function useDetailConnector(composableFn, options = {}) {
         // Actions
         load,
         clear,
-        // Expose composable for advanced use
+        // Expose composable for advanced use (e.g. useFormConnector loadWith)
         _composable: composable,
-        _idRef: idRef,
     };
 }

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

@@ -73,9 +73,9 @@ export function useFormConnector(composableFn, options = {}) {
         try {
             // The mutation composable accepts the model as its payload
             const composable = composableFn(model.value);
-            // Wait for the async data to resolve
-            if (composable.execute) {
-                await composable.execute();
+            // refresh() bypasses Nuxt SSR payload cache, forcing a real network request
+            if (composable.refresh) {
+                await composable.refresh();
             }
             const data = composable.data?.value;
             const err = composable.error?.value;
@@ -85,6 +85,7 @@ export function useFormConnector(composableFn, options = {}) {
             onSuccess.value?.(data);
         }
         catch (err) {
+            console.error('[useFormConnector] submit error:', err);
             submitError.value = err;
             onError.value?.(err);
         }

package/dist/generators/use-async-data/runtime/useApiAsyncData.js

@@ -16,7 +16,7 @@ import { getGlobalApiPagination, buildPaginationRequest, extractPaginationMetaFr
  * - Watch pattern for reactive parameters
  */
 export function useApiAsyncData(key, url, options) {
-    const { method = 'GET', body, headers = {}, params, baseURL, cacheKey, transform, pick, onRequest, onSuccess, onError, onFinish, skipGlobalCallbacks, immediate = true, lazy = false, server = true, dedupe = 'cancel', watch: watchOption = true, paginated, initialPage, initialPerPage, paginationConfig, ...restOptions } = options || {};
+    const { method = 'GET', body, headers = {}, params, baseURL, cacheKey, transform, pick, onRequest, onSuccess, onError, onFinish, skipGlobalCallbacks, immediate = true, lazy = false, server = true, dedupe = 'cancel', watch: watchOption = undefined, paginated, initialPage, initialPerPage, paginationConfig, ...restOptions } = options || {};
     // ---------------------------------------------------------------------------
     // Pagination setup
     // ---------------------------------------------------------------------------
@@ -34,9 +34,13 @@ export function useApiAsyncData(key, url, options) {
     if (!resolvedBaseURL) {
         console.warn('[nuxt-openapi-hyperfetch] No baseURL configured. Set runtimeConfig.public.apiBaseUrl in nuxt.config.ts or pass baseURL in options.');
     }
+    // For mutations (POST/PUT/PATCH/DELETE), auto-watch defaults to OFF unless explicitly enabled.
+    // For GET, auto-watch defaults to ON (reactive params, pagination).
+    const isMutation = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method.toUpperCase());
+    const effectiveWatchOption = watchOption !== undefined ? watchOption : !isMutation;
     // Create reactive watch sources — use refs/computeds directly so Vue can track them
-    // watchOption: false disables auto-refresh entirely
-    const watchSources = watchOption === false
+    // effectiveWatchOption: false disables auto-refresh entirely
+    const watchSources = effectiveWatchOption === false
         ? []
         : [
             ...(typeof url === 'function' ? [url] : []),
@@ -207,13 +211,18 @@ export function useApiAsyncData(key, url, options) {
             }
         }
     };
+    // For mutations: use a static UUID-based key to prevent reactive key tracking.
+    // A reactive key function causes Nuxt to re-fetch whenever any Ref accessed inside it changes
+    // (e.g. URL params), which triggers duplicate calls when combined with manual .refresh().
+    // GETs keep the reactive computedKey for proper per-params cache isolation.
+    const resolvedKey = isMutation ? `${key}-${crypto.randomUUID()}` : computedKey;
     // Use Nuxt's useAsyncData with a computed key for proper cache isolation per params
-    const result = useAsyncData(computedKey, fetchFn, {
+    const result = useAsyncData(resolvedKey, fetchFn, {
         immediate,
         lazy,
         server,
         dedupe,
-        watch: watchOption === false ? [] : watchSources,
+        watch: effectiveWatchOption === false ? [] : watchSources,
     });
     if (!paginated)
         return result;

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

@@ -13,7 +13,6 @@ function generateFileHeader() {
  */
 
 /* eslint-disable */
-// @ts-nocheck
 `;
 }
 /**
@@ -90,6 +89,17 @@ function generateImports(method, apiImportPath, isRaw) {
     else {
         imports += `import { useApiAsyncData, type ApiAsyncDataOptions } from '../runtime/useApiAsyncData';`;
     }
+    // Vue imports needed by the generated function body
+    const vueImports = ['shallowRef'];
+    if (method.requestType) {
+        vueImports.push('isRef');
+    }
+    if (method.hasBody || method.hasQueryParams || method.pathParams.length > 0) {
+        vueImports.push('computed');
+    }
+    const vueTypeImports = method.requestType ? ['Ref', 'ComputedRef'] : [];
+    const allVueImports = [...vueImports, ...vueTypeImports.map((t) => `type ${t}`)].join(', ');
+    imports += `\nimport { ${allVueImports} } from 'vue';`;
     return imports;
 }
 /**
@@ -124,24 +134,18 @@ function generateFunctionBody(method, isRaw, generateOptions) {
     const returnType = isRaw
         ? `ReturnType<typeof ${wrapperFunction}<${responseType}, DataT, PickT, Options>>`
         : `ReturnType<typeof ${wrapperFunction}<${responseType}, Options>>`;
-    const pInit = hasParams ? `\n  const p = shallowRef(params)` : '';
+    const pInit = hasParams ? `\n  const p = isRef(params) ? params : shallowRef(params)` : '';
     const argsExtraction = hasParams
         ? `  const _hasKey = typeof args[0] === 'string'\n  const params = _hasKey ? args[1] : args[0]\n  const options = _hasKey ? { cacheKey: args[0], ...args[2] } : args[1]`
         : `  const _hasKey = typeof args[0] === 'string'\n  const options = _hasKey ? { cacheKey: args[0], ...args[1] } : args[0]`;
-    return `${description}export function ${composableName}<
-  DataT = ${responseType},
-  PickT extends ReadonlyArray<string> | undefined = undefined,
-  Options extends ${optionsType} = ${optionsDefaultType}
->(key: string, ${args}): ${returnType}
-export function ${composableName}<
-  DataT = ${responseType},
-  PickT extends ReadonlyArray<string> | undefined = undefined,
-  Options extends ${optionsType} = ${optionsDefaultType}
->(${args}): ${returnType}
-export function ${composableName}(...args: any[]) {
-${argsExtraction}${pInit}
-  return ${wrapperCall}(${key}, ${url}, ${fetchOptions})
-}`;
+    const genericTypeParams = `<\n  DataT = ${responseType},\n  PickT extends ReadonlyArray<string> | undefined = undefined,\n  Options extends ${optionsType} = ${optionsDefaultType}\n>`;
+    const refParamsStr = hasParams
+        ? `params: Ref<${method.requestType}> | ComputedRef<${method.requestType}>, ${optionsArg}`
+        : '';
+    const refOverloads = hasParams
+        ? `\nexport function ${composableName}${genericTypeParams}(${refParamsStr}): ${returnType}\nexport function ${composableName}${genericTypeParams}(key: string, ${refParamsStr}): ${returnType}`
+        : '';
+    return `${description}export function ${composableName}${genericTypeParams}(${args}): ${returnType}\nexport function ${composableName}${genericTypeParams}(key: string, ${args}): ${returnType}${refOverloads}\nexport function ${composableName}(...args: any[]) {\n${argsExtraction}${pInit}\n  return ${wrapperCall}(${key}, ${url}, ${fetchOptions})\n}`;
 }
 /**
  * Generate URL (with path params if needed)

package/dist/generators/use-fetch/templates.js

@@ -94,7 +94,7 @@ function generateFunctionBody(method, options) {
     const url = generateUrl(method);
     const fetchOptions = generateFetchOptions(method, options);
     const description = method.description ? `/**\n * ${method.description}\n */\n` : '';
-    const pInit = hasParams ? `\n  const p = shallowRef(params)` : '';
+    const pInit = hasParams ? `\n  const p = isRef(params) ? params : shallowRef(params)` : '';
     return `${description}export const ${method.composableName} = <
   DataT = ${responseType},
   PickT extends ReadonlyArray<string> | undefined = undefined,