nuxt-openapi-hyperfetch 0.3.8-beta → 1.0.0

package/src/generators/connectors/templates.ts

@@ -0,0 +1,481 @@
+import { pascalCase, kebabCase } from 'change-case';
+import type { ResourceInfo } from '../components/schema-analyzer/types.js';
+
+// ─── File header ──────────────────────────────────────────────────────────────
+
+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 */
+`;
+}
+
+// ─── Naming helpers ───────────────────────────────────────────────────────────
+
+function toAsyncDataName(operationId: string): string {
+  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: string, pathParam?: string): string {
+  if (!pathParam) {
+    return `'${path}'`;
+  }
+  const urlTemplate = path.replace(`{${pathParam}}`, '${id}');
+  return `(id: string | number) => \`${urlTemplate}\``;
+}
+
+// ─── Section builders ─────────────────────────────────────────────────────────
+
+function buildImports(
+  resource: ResourceInfo,
+  composablesRelDir: string,
+  sdkRelDir: string,
+  runtimeRelDir: string
+): string {
+  const lines: string[] = [];
+
+  // zod — always needed for schema declarations
+  lines.push(`import { z } from 'zod';`);
+  lines.push('');
+
+  // connector-types — return type interfaces
+  const typeImports: string[] = ['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: string[] = ['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: ResourceInfo): string {
+  const lines: string[] = [];
+  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: ResourceInfo): string {
+  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: ResourceInfo): string {
+  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: ResourceInfo): string {
+  const typeName = `${pascalCase(resource.composableName)}Options`;
+  const hasColumns = resource.columns && resource.columns.length > 0;
+  const fields: string[] = [];
+
+  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: ResourceInfo): string {
+  const pascal = resource.itemTypeName ?? pascalCase(resource.name);
+  const localPascal = pascalCase(resource.name);
+  const typeName = `${pascalCase(resource.composableName)}Return`;
+  const fields: string[] = [];
+
+  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: ResourceInfo): string {
+  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: string[] = [];
+  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: string[] = [];
+
+  // ── 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: string[] = ['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: ResourceInfo,
+  composablesRelDir: string,
+  sdkRelDir = '../..',
+  runtimeRelDir = '../../runtime'
+): string {
+  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: string[] = [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: string): string {
+  return `${kebabCase(composableName)}.ts`;
+}
+
+export function generateConnectorIndexFile(composableNames: string[]): string {
+  const header = generateFileHeader();
+  const exports = composableNames
+    .map((name) => `export { ${name} } from './${kebabCase(name)}';`)
+    .join('\n');
+  return `${header}${exports}\n`;
+}

package/src/generators/connectors/types.ts

@@ -0,0 +1,39 @@
+/**
+ * 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/src/generators/shared/runtime/useDeleteConnector.ts

@@ -63,8 +63,9 @@ export function useDeleteConnector(composableFn, options = {}) {
       // 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;
@@ -78,6 +79,7 @@ export function useDeleteConnector(composableFn, options = {}) {
 
       onSuccess.value?.(deletedItem);
     } catch (err) {
+      console.error('[useDeleteConnector] confirm error:', err);
       error.value = err;
       onError.value?.(err);
     } finally {

package/src/generators/shared/runtime/useDetailConnector.ts

@@ -18,20 +18,11 @@ import { ref, computed } from 'vue';
 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 ──────────────────────────────────────────────────────────
 
@@ -42,13 +33,12 @@ export function useDetailConnector(composableFn, options = {}) {
   // ── 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 {
@@ -62,8 +52,7 @@ export function useDetailConnector(composableFn, options = {}) {
     load,
     clear,
 
-    // Expose composable for advanced use
+    // Expose composable for advanced use (e.g. useFormConnector loadWith)
     _composable: composable,
-    _idRef: idRef,
   };
 }

package/src/generators/shared/runtime/useFormConnector.ts

@@ -94,9 +94,9 @@ export function useFormConnector(composableFn, options = {}) {
       // 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;
@@ -108,6 +108,7 @@ export function useFormConnector(composableFn, options = {}) {
 
       onSuccess.value?.(data);
     } catch (err) {
+      console.error('[useFormConnector] submit error:', err);
       submitError.value = err;
       onError.value?.(err);
     } finally {

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

@@ -112,7 +112,7 @@ export function useApiAsyncData<
     lazy = false,
     server = true,
     dedupe = 'cancel',
-    watch: watchOption = true,
+    watch: watchOption = undefined,
     paginated,
     initialPage,
     initialPerPage,
@@ -142,10 +142,15 @@ export function useApiAsyncData<
     );
   }
 
+  // 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 as string).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
+  // effectiveWatchOption: false disables auto-refresh entirely
   const watchSources =
-    watchOption === false
+    effectiveWatchOption === false
       ? []
       : [
           ...(typeof url === 'function' ? [url] : []),
@@ -322,13 +327,19 @@ export function useApiAsyncData<
     }
   };
 
+  // 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<InferData<T, Options>>(computedKey, fetchFn, {
+  const result = useAsyncData<InferData<T, Options>>(resolvedKey, fetchFn, {
     immediate,
     lazy,
     server,
     dedupe,
-    watch: watchOption === false ? [] : watchSources,
+    watch: effectiveWatchOption === false ? [] : watchSources,
   });
 
   if (!paginated) return result;